Citadel for Claude Code and Codex: A Project-Local Operating Layer

What Citadel solves for people who run coding agents across many sessions

The README frames Citadel as an operating layer for two specific runtimes: Claude Code and OpenAI Codex. The problem it names is not code generation. It is everything around generation that a chat session forgets: which workflow was chosen, what was already decided, what a previous session handed off, and whether a risky multi-step change was actually approved before it ran. Citadel's own table of use cases lists repeated setup and lost context, unclear workflow choice, risky or multi-step changes, several agents or branches, and work interrupted between sessions.

That list also defines the audience. If your work fits inside one prompt, the README says your coding agent may already be enough. The tool is aimed at repositories where agent work stretches over days and where a second session needs to pick up where the first stopped. The five public states describe that loop: Request, Run, Evidence, Needs You, Resume. Only one of those is about doing the work. The other four are about knowing what happened and what comes next.

One boundary is stated plainly enough to repeat: Citadel does not replace CLAUDE.md, AGENTS.md, branch protection, or human review. It sits around the agent you already use rather than substituting for it.

How /do routing, repo-local state and hooks fit together

There is one entry point. You describe an outcome through /do, and Citadel decides what to run. The routing has three tiers visible in the README. Exact commands resolve only when the normalized whole request matches, so a stray word changes the outcome. The project commands /do test, /do build and /do typecheck carry an extra condition: the corresponding non-empty script must exist in the target package.json. Anything larger collects generated candidates and then requires runtime semantic classification.

That third tier is where the interesting limitation lives. /do preview shares only the exact-command and built-in candidate preflight. It does not inspect active state, does not discover project-local skills, and does not run the runtime LLM classifier. The README states that every natural-language preview is non-executable: selected and command are null, canRunNow is false, and the boundary is semantic-classification-required. So preview tells you the request was understood as a candidate, not that it will run.

If you already know the destination, there is a validated override, /do --route /test-gen -- generate tests for the changed files. The README describes this as skipping routing, not as skipping activation or safety boundaries. State lives in the repository. The top-level layout includes .citadel/, .planning/, .agents/, hooks/, hooks_src/, core/, runtimes/, skills/, and mcp-servers/citadel-state/, which is consistent with a design where memory, hooks and coordination are files in the project rather than a hosted service. The README does not describe a server component, and the install commands are all project-local.

Installing Citadel through the Codex or Claude Code plugin marketplace

Citadel is not an npm package. The README says install goes through the plugin marketplace built into your coding agent, and the commands pin the complete v1.3.5 release. Requirements are Claude Code or OpenAI Codex, Node.js 22 or newer, and a git repository. Run the commands from the repository you want Citadel to manage.

For OpenAI Codex, two commands add the marketplace at the pinned tag and then add the plugin:

codex plugin marketplace add SethGammon/Citadel --ref v1.3.5
codex plugin add citadel@citadel-local

Start a new Codex task afterward, review Citadel through /hooks, then issue a real request. The README's example is /do review README.md. For Claude Code the shape is the same but the scope flag is explicit:

claude plugin marketplace add SethGammon/[email protected] --scope local
claude plugin install citadel@citadel-local --scope local

If Claude Code is already open, run /reload-plugins before trying /do. The README warns against substituting floating main if the v1.3.5 tag is missing from GitHub Releases. There is also a manual path for offline or high-assurance installs: download citadel-vX.Y.Z.tar.gz, its .manifest.json and its .sha256 sidecar, compare the archive's SHA-256 against both published values, and treat a missing asset or mismatch as a blocked install. The adoption script then runs in three steps:

node "$CITADEL_ROOT/scripts/adopt.js" plan "$CITADEL_ROOT" \
  --target . --project-runtime codex \
  --out ../citadel-adoption.plan.json --json
node "$CITADEL_ROOT/scripts/adopt.js" apply ../citadel-adoption.plan.json \
  --confirm <plan-token> --json
node "$CITADEL_ROOT/scripts/adopt.js" doctor --target . --json

Keep the saved plan outside the target repository. The README states that writing the plan inside the target changes the preflight snapshot and causes apply to reject TARGET_DRIFT. Use --project-runtime claude for Claude Code, or both only when both runtime projections are intentional.

Where Citadel gets in the way, and when it is the wrong tool

The exact-command tier is stricter than it first appears. Because resolution requires the normalized whole request to match, near-misses fall through to candidate collection and semantic classification, which needs the runtime LLM classifier. In a runtime where that classifier is unavailable, the fallback is not a guess; the README's preview contract shows the failure shape, with canRunNow false and a boundary string explaining why. That is honest, but it means a request phrased slightly differently may not run at all.

The preview behavior is the other sharp edge. A developer who reads a preview as confirmation will be wrong, because preview deliberately does not look at active state or project-local skills. It answers a narrower question than most people expect from the word preview.

Citadel is also the wrong tool for a single small edit. The README says so directly. The install itself is a commitment: a pinned tag, a project-local plugin scope, and for the manual path a checksum verification and a plan file that must live outside the repository. If your work never spans sessions, that overhead buys nothing. The README does not document rollback or uninstall steps in the main body; it points to INSTALL.md for rollback and uninstall, so that file is where you should look before adopting rather than after.

Citadel compared with plain CLAUDE.md and AGENTS.md conventions

The obvious alternative is doing nothing beyond the convention files your runtime already reads. A CLAUDE.md or AGENTS.md file is static guidance: it is read at the start of a session and it does not change based on what happened in the last one. Citadel's difference is that its state is written during work. The README describes repo-local decisions, discoveries and handoffs, and a Resume state that names the next useful action for a fresh session. A convention file cannot produce that, because nothing in it is aware of the previous run.

The second difference is routing. With convention files, choosing the workflow is your job every time. Citadel puts one /do entry point in front of that choice and resolves it against exact commands, built-in candidates, and then semantic classification. The trade-off is that you inherit a resolution contract: exact matches only, a package.json script requirement for test, build and typecheck, and a preview mode that intentionally stops short of execution.

A third difference is where the tool draws its trust boundary. The README says the platform owns plugin acquisition and executable-code trust, while Citadel owns bounded project state and recovery. That split is a design decision worth weighing. It means Citadel is not trying to be a sandbox or a permission system; it is trying to be the memory and the approval checkpoints around one.

Cost, licence and what upgrading Citadel actually involves

Citadel is MIT licensed, and package.json marks the package private with a bin entry at bin/citadel.js, so there is no registry distribution to track. Licence questions beyond that are for your own counsel; the practical implication is that the MIT terms are the ones in the LICENSE file at the repository root.

The upgrade cost is mostly version discipline. The install commands pin v1.3.5, and the README explicitly says not to substitute floating main if that tag is absent from GitHub Releases. The manual path has the same property: you pick an explicit vX.Y.Z release and verify the archive against both the manifest and the SHA-256 sidecar before extraction. That means upgrades are deliberate re-installs at a new tag rather than a background update, and the release artifacts are what you audit. The recent release history shows three releases on 2026-08-13, v1.3.3, v1.3.4 and v1.3.5, while the last push to the repository was also on 2026-08-13. The repository is not archived. The README points to docs/RELEASES.md for the artifact and provenance contract, which is the file to read if you need to justify a specific version internally.

One packaging detail is worth noting because it affects what you receive: package.json excludes several files from the published set, including core/skills/noop-calibration.json, core/skills/noop-detect.js, core/telemetry/activation-cohort.js, core/telemetry/github-traffic.js and hooks_src/smoke-test.js. Those are development-side files, and their absence from the distributed set is consistent with the release-trio model rather than a gap.

Editorial conclusion

Adopt Citadel if you run Claude Code or Codex across many sessions in one git repository and keep losing decisions, workflow choice or handoff state between them. Skip it for short one-off edits, and skip it if you expect it to replace CLAUDE.md, AGENTS.md, branch protection or human review, because the README says it does not. Before adopting, verify the v1.3.5 tag exists on the GitHub Releases page, confirm your Node.js is 22 or newer, and run the install with --scope local so nothing outside the target repository is changed. Then check the manual path's checksum sidecar, because the README treats a missing asset or a mismatch as a blocked install.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes