An open-source operating layer for Claude Code and OpenAI Codex.
Citadel helps coding agents work reliably across real repositories. It routes requests, preserves project state between sessions, coordinates parallel work, applies repository safeguards, and records verification and handoffs.
Quick install | Start using it | Is it a fit? | Portable operations | Documentation
Quick install
Requires: Claude Code or OpenAI Codex, Node.js 18+, and a git repository.
Open the repository you want Citadel to manage, then paste this into your coding agent:
Install Citadel from https://github.com/SethGammon/Citadel into this repository.
Detect whether I am using Codex or Claude Code, show me what will change before
applying it, use the current repository as the target, and run Citadel doctor.
Follow any printed enable step, start a fresh session if prompted, then run:
/do setup --express
Setup installs the project hooks and creates the repo-local state Citadel uses to resume work later.
Clone Citadel once:
git clone https://github.com/SethGammon/Citadel.git ~/Citadel
From the repository you want Citadel to manage, run the installer for your runtime.
OpenAI Codex
node ~/Citadel/scripts/install.js --runtime codex --add-marketplace
Claude Code
node ~/Citadel/scripts/install.js --runtime claude --install --scope local
Start a fresh session in the same repository and run /do setup --express.
Dry runs, generated paths, runtime-specific setup, and rollback are documented in Installation.
Start using it
You do not need to learn the skill catalog or operation internals. Start with /do and describe the outcome:
/do review README.md
/do generate tests for the changed files
/do next
Citadel reveals more machinery only when the work needs it:
| Level | Start here | What it gives you |
|---|
| 1. Do the work | /do <request> | Selects a proportional workflow and verifies the result |
| 2. Keep going | /do next or /do continue | Preserves and resumes work across sessions |
| 3. Coordinate | /dashboard, campaigns, or Fleet | Makes longer and parallel work visible and recoverable |
| 4. Control an operation | citadel operation ... | Adds explicit quality, privacy, tool, time, model-fallback, and cost constraints |
Most users can stay at Levels 1 and 2. Advanced levels do not replace or complicate /do.
For a copyable walkthrough in a real repository, use the demo workflow.
When Citadel is useful
Citadel is most useful when coding-agent work extends beyond a single prompt:
| You are dealing with... | Citadel adds... |
|---|
| Repeated setup and lost context | Repo-local campaigns, decisions, discoveries, and handoffs |
| Unclear workflow choice | One natural-language entry point through /do |
| Risky or multi-step changes | Approval boundaries, lifecycle hooks, and explicit verification |
| Several agents or branches | Isolated worktrees, ownership, and shared discoveries |
| Work that must survive interruption | Durable state, recovery, and a concrete next action |
For a short, one-off edit, your coding agent may already be enough. Citadel becomes valuable when the operating discipline around the agent is the hard part.
Citadel does not replace CLAUDE.md or AGENTS.md. Those files describe the project and its rules. Citadel supplies the workflows and state used to carry them out consistently.
Evidence status
Citadel publishes positive and negative results from the same evidence
contract. V1 recorded 27/36 verified cells versus 24/36 and a frozen aggregate
with 9.9% less measured GPU energy, but one same-route 60-second baseline
timeout drove that appearance. Excluding the matched pair reverses the
economic direction to 3.5% more GPU energy and 5.4% more modeled GPU cost, so
Citadel makes no v1 savings claim.
A distinct capability-profile follow-up then preserved the always-7B verified
rate (24/36 versus 24/36) but used 15.7% more measured GPU energy after 12
verification escalations. Citadel publishes that regression because detecting
a plausible policy that is economically worse is part of the product.
The latest representative fixture shakedown moved verification from exact
answers to repository artifacts. Both policies verified 6/12 cells with zero
false passes and path violations; Citadel's 7.1% energy reduction missed the
frozen 20% gate and is published as failed.
One operating loop
- Route:
/do chooses a focused skill, a coordinated session, a persistent campaign, or a parallel fleet.
- Execute and verify: hooks apply repository rules, gate consequential actions, and capture required checks.
- Record and resume: Citadel writes the result, handoff, and next action to the repository for the next session.
The repository remains the source of truth. Citadel adds an operating layer around the coding agent rather than replacing its runtime.
If you regularly delete clones, opt into cross-clone repository memory
on Node.js 22.13+ with citadel memory enable. Citadel then keeps completed
campaigns, postmortems, research, discoveries, backlog, and project context in
a user-level SQLite database and restores missing files in another clone of the
same remote. Its default path is outside the checkout, and Citadel never commits,
pushes, or transmits it.
Portable operations
Portable operations are optional. They are for work that needs a stable contract, durable recovery, comparable executors, or a verifiable receipt. Ordinary repository work still begins with /do.
| If you need to... | Start here |
|---|
| Run the same objective through isolated Claude Code and Codex branches | Operation Fork |
| Package a repeatable result with permissions, checks, and stopping conditions | Outcome Packs |
| Inspect or control a running operation | Mission Control |
| Choose and escalate a model/tool/topology path under explicit constraints | Operation Control |
| Adopt Citadel reversibly, activate only the needed product, or connect an external control plane | Governed lifecycle |
The underlying Operations Protocol defines the runtime-neutral contracts for operations, attempts, intents, evidence, and receipts. Most users do not need those internals to use Citadel.
For reviewers who want evidence instead of architecture claims, Operation
Control includes a frozen 120-cell real-workload import
and a preregistered real-runtime integration result.
Both preserve failed and unknown outcomes and state what they do not prove.
Trust and scope
- Citadel runs with the permissions of Claude Code or Codex. It does not replace code review, branch protection, or repository-specific checks.
- Verification artifacts report
passed, failed, blocked, or unknown. Missing evidence is not promoted to success.
- Project state and telemetry stay local by default. Nothing is transmitted automatically.
- The automated suite validates Citadel's contracts and supported fixtures. It does not guarantee the quality of an agent's code.
Read Security, the threat model, and golden-path verification for the full boundaries.
Choose your documentation
| Goal | Recommended path |
|---|
| Install or evaluate Citadel | Installation, Demo, Choosing Citadel |
| Operate day to day | Campaigns, Fleet, Hooks, Mission Control |
| Use portable operations | Operation Control, Operation Fork, Outcome Packs, Recovery |
| Govern adoption, activation, evidence, or external control | Governed lifecycle, Real User Proof v2 |
| Integrate or verify | CLI reference, Interoperability, Reports |
The complete reference is in docs/.
The current package includes 49 workflows and 35 hook scripts across 29 lifecycle events. /do selects among them; they are not a prerequisite checklist.
Citadel keeps operational state separate from application code:
.planning/ Campaigns, operations, fleet sessions, intake, and telemetry
.citadel/scripts/ Project-local coordination and reporting utilities
.claude/agent-context/ Rules supplied to delegated agents
.claude/harness.json Project configuration generated by setup
Runtime adapters may add Claude Code or Codex configuration files. Installation lists every generated path and its rollback procedure.
Common questions
Yes, if you enable cross-clone memory first with citadel memory enable on
Node.js 22.13+. It syncs only durable knowledge to a local user-level SQLite store.
A new clone with the same origin restores missing knowledge automatically
after Citadel is installed. Existing divergent files are never overwritten
automatically. See Cross-clone repository memory.
No. Start with /do. Operation commands are only for work that needs durable contracts, receipts, recovery, or runtime comparison.
Yes. The hooks and scripts run on Node.js, and the Codex installer includes Windows-specific readiness checks.
Use /unharness to create a receipt-owned leave plan, review the exact
footprint, and apply it with the plan token. Legacy installs are inventoried
first and cannot claim exact removal. Installation documents the
rollback and compatibility paths.
Community
