Citadel: A Stateful Operating Layer for Claude Code and Codex

What Citadel Adds to Your Coding Agent

Citadel solves a specific problem: coding agents like Claude Code and Codex are stateless across sessions. Each new prompt starts from scratch, and multi-step work loses context, decisions, and handoffs. Citadel is an operating layer that preserves repository state between sessions, routes requests through a single /do entry point, and applies safety hooks around the agent's actions. It is for teams and individuals who use these agents for work that extends beyond one prompt: repeated setup, risky multi-step changes, multiple agents or branches, and work that gets interrupted. The README is explicit that Citadel does not replace CLAUDE.md, AGENTS.md, branch protection, or human review. It adds a layer on top, not a substitute.

The Five-State Operating Loop

The core mechanism is a five-state loop that Citadel uses to manage work. The states are Request, Run, Evidence, Needs You, and Resume. You start with a Request through /do, describing an outcome like '/do review README.md'. Citadel selects a workflow and runs it within runtime, repository, and approval boundaries. Checks and artifacts then report evidence as passed, failed, blocked, or unknown. If something needs human input, Citadel stops at Needs You with the exact approval, conflict, or missing evidence required. Finally, Resume uses repo-local state to name the next useful action for a fresh session. This loop is not just a workflow engine; it is a state machine that persists between sessions, which is the key difference from a plain plugin that only intercepts commands.

Installation: Plugin Marketplace and Verified Releases

Installation is through the native plugin marketplace of each runtime. For OpenAI Codex, you run 'codex plugin marketplace add SethGammon/Citadel --ref v1.3.5' and then 'codex plugin add citadel@citadel-local'. For Claude Code, the commands are 'claude plugin marketplace add SethGammon/Citadel@v1.3.5 --scope local' and 'claude plugin install citadel@citadel-local --scope local'. The README stresses pinning the complete v1.3.5 release, not floating main. If the tag is not present on GitHub Releases, you should not substitute main. For manual or offline installation, you download the release tarball, its manifest, and a SHA-256 sidecar, verify checksums, and extract to an immutable directory. Then you run 'node scripts/adopt.js plan', 'apply', and 'doctor' with CITADEL_ROOT pointing at that directory. The plan must be kept outside the target repository, because writing it inside changes the preflight snapshot and causes apply to reject with TARGET_DRIFT.

Routing and the /do Entry Point

The /do command is the single entry point for all work. Exact commands resolve only when the normalized whole request matches. For example, '/do test', '/do build', and '/do typecheck' require the corresponding non-empty target package.json script. Larger requests collect generated candidates and then require runtime semantic classification. This means Citadel does not guess: it either matches an exact command or uses the LLM classifier to decide. There is also a validated override: '/do --route /test-gen -- generate tests for the changed files' lets you specify a destination without bypassing activation or safety boundaries. The '/do preview' command shares only the exact-command and built-in candidate preflight. It does not inspect active state, discover project-local skills, or run the classifier, so every natural-language preview is non-executable: 'selected' and 'command' are null, 'canRunNow' is false, and the boundary is 'semantic-classification-required'. This is a deliberate design to prevent accidental execution.

Trust Boundary and Safety Hooks

Citadel defines a clear trust boundary. The platform (Claude Code or Codex) owns plugin acquisition and executable-code trust. Citadel owns bounded project state and recovery. Plans, digests, receipts, and doctor checks remain available as evidence, but they are not user chores on the normal path. The README includes an installer prompt that tells the agent to preserve removal evidence for every change and not to change shared configuration, sandbox settings, permissions, or user-wide settings without asking. This is a safety hook: Citadel is designed to constrain the agent, not to give it more power. However, the trust boundary is only as strong as the runtime's plugin isolation. If the runtime allows a plugin to modify its own sandbox, the boundary is weaker than it appears. The README does not detail how Citadel enforces these boundaries beyond stating them, so you should verify that in practice.

Limitations and When It Is the Wrong Tool

Citadel is not for everyone. The README states that for a short one-off edit, your coding agent may already be enough. Citadel adds overhead: installation, state management, and the /do routing layer. The exact-command matching is strict, and larger requests depend on the runtime LLM classifier, which can be slow or unpredictable. The manual installation process is complex, with checksum verification and plan tokens. If you do not need persistent state or multi-step coordination, this is the wrong tool. Another limitation is that Citadel does not replace existing project documentation or review processes. It is an additional layer, and if your team already has robust workflows for context and handoffs, Citadel may duplicate effort without clear benefit. The README also notes that the source checkout on main is development-only and must not be used as a stable install, so you cannot simply clone and run.

Alternatives and Maintenance Cost

The obvious alternative is to rely on the built-in memory features of Claude Code and Codex, such as CLAUDE.md and AGENTS.md files. Those are static documentation that the agent reads at the start of each session. Citadel goes further by maintaining dynamic state across sessions, but the alternative is simpler and requires no plugin. Another alternative is a custom script that saves and restores context, but that lacks the routing, safety hooks, and evidence tracking. The maintenance cost of Citadel includes keeping up with releases (v1.3.5 is the latest, with v1.3.4 and v1.3.3 released on the same day, suggesting active development), verifying checksums on each upgrade, and ensuring that the plugin remains compatible with the runtime's marketplace. The license is MIT, so there are no permissive-use restrictions, but you must manage the release artifacts yourself. The README does not describe an upgrade path beyond reinstalling a new release, so plan for manual upgrades.

Editorial conclusion

Adopt Citadel if your coding-agent work routinely spans multiple sessions, involves risky multi-step changes, or needs parallel agents with isolated worktrees. Do not adopt it for one-off edits or if you expect it to replace CLAUDE.md, AGENTS.md, or branch protection. Before adopting, verify that the v1.3.5 release assets (the tarball, manifest, and SHA-256 sidecar) are present on GitHub Releases, and confirm that your runtime supports the plugin marketplace commands shown in the README. Also test the /do route override on a non-critical repository, because the exact-command matching and semantic classification behavior will determine whether the overhead is worth it for your team.

Official sources

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