Citadel
An operating layer that makes multi-step Claude Code and Codex repository work recoverable, verifiable, and coordinated.
- Source repo
- SethGammon/Citadel
- Stars
- ★ 929
- Last updated
- 5d ago
- License
- MIT
- Primary language
- JavaScript
- FA score
- 84/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Claude Code maintainer resuming a refactor across sessions and needing
/do continueto surface the recorded next action. - Not a fit if
- Users who only need a one-off edit and no cross-session state
- Teams not using Claude Code or OpenAI Codex
- Teams needing a sandbox or a replacement for code review and branch protection
- Website
- sethgammon.github.io/Citadel ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-05latest release v1.4.5 (2026-11-04)
- Source review
- 84/100 · Good
What does this agent do, and when should you use it?
Citadel is an open-source operating layer for Claude Code and OpenAI Codex, not a replacement coding runtime. Its /do entry point routes a request to a focused workflow, coordinated session, persistent campaign, or parallel Fleet. Repository-local state records campaigns, discoveries, handoffs, next actions, and telemetry so work can resume in later sessions. Lifecycle hooks, verification records, and receipts add operational controls around consequential work. Installation adapts an existing Git repository with runtime-specific configuration and local state; optional cross-clone memory uses a user-level SQLite database.
After /do <request>, Citadel routes the request to a focused skill, coordinated session, campaign, or Fleet. Its hooks apply repository rules, gate consequential actions, and capture required checks; it then writes the result, handoff, and next action into repository state for /do next or /do continue. citadel operation ... adds explicit quality, privacy, tool, time, model-fallback, and cost constraints, using the Operations Protocol’s operations, attempts, intents, evidence, and receipts. Operation Fork runs one objective in isolated Claude Code and Codex worktrees. On Node.js 22.13+, citadel memory enable stores durable cross-clone knowledge in a user-level SQLite database.
- A Claude Code maintainer resuming a refactor across sessions and needing
/do continueto surface the recorded next action. - An OpenAI Codex user making a risky, multi-step repository change that needs hooks and explicit verification.
- An engineering team coordinating several agents or branches with isolated worktrees, ownership, and shared discoveries.
- An evaluator comparing Claude Code and Codex on the same objective through isolated branches with Operation Fork.
- An operator packaging a repeatable outcome with permissions, checks, stopping conditions, and a verifiable receipt.
How do you install or deploy this agent?
Requires Claude Code or OpenAI Codex, Node.js 18+, and a Git repository. In the target repository, install Citadel through your coding agent, follow any printed enable step, start a fresh session if prompted, and run /do setup --express. For manual installation, run git clone https://github.com/SethGammon/Citadel.git ~/Citadel; for Codex run node ~/Citadel/scripts/install.js --runtime codex --add-marketplace, or for Claude Code run node ~/Citadel/scripts/install.js --runtime claude --install --scope local. Start a fresh session in that repository and run /do setup --express.
How do you use this agent?
After setup, begin with a request such as /do review README.md or /do generate tests for the changed files; /do is Citadel’s natural-language entry point. Citadel routes the request to a focused workflow, coordinated session, persistent campaign, or parallel Fleet. During the work, repository-local state records results, discoveries, handoffs, and next actions. Use /do next to surface the recorded next action, or /do continue to resume the work in a later session. When a repeatable operation requires explicit quality, privacy, tool, time, model-fallback, or cost constraints, use citadel operation ...; its Operations Protocol records operations, attempts, intents, evidence, and receipts. Operation Fork can run the same objective in isolated Claude Code and Codex worktrees. On Node.js 22.13+, run citadel memory enable to opt into durable cross-clone repository memory stored in a user-level SQLite database.
What are this agent's strengths and limitations?
- Directly supports both Claude Code and OpenAI Codex with runtime-specific installation paths.
- Preserves campaigns, discoveries, handoffs, and next actions for interruption recovery across sessions.
- Uses hooks, verification states, and receipts; absent evidence is not promoted to success.
- Operation Fork can execute the same objective in isolated Claude Code and Codex worktrees.
- Requires a Git repository, Node.js 18+, and either Claude Code or OpenAI Codex; it is not a standalone coding runtime.
- Runs with the permissions of its host runtime and does not replace code review, branch protection, or repository-specific checks.
- Cross-clone memory requires Node.js 22.13+ and uses a user-level SQLite store.
- Its published representative shakedown missed the frozen 20% energy gate, which the project reports as failed.
How does this agent compare with similar options?
Citadel complements rather than replaces CLAUDE.md or AGENTS.md: those files describe project rules, while Citadel supplies workflows and state for carrying them out. A short one-off edit may already be handled by the coding runtime alone; Citadel targets cases where recovery, coordination, and verification are the harder problems.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Citadel This agent | 84 · Good | Agent plugin / skillFree + model costs | ★ 929 | 5d ago | JavaScript | Codex · Claude Code |
| dmux | 55 · Major gaps | CLIFree + model costs | ★ 1.8k | 2mo ago | HTML | Codex · Claude Code · OpenAI API |
| Atris Project Workbench | 47 · Major gaps | CLIFreemium | ★ 71 | 1d ago | JavaScript | Codex · Claude Code |
| Agent Deck | 74 · Some gaps | CLIFree + model costs | ★ 1.2k | 1d ago | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The trust-boundary, security, and installation material says the product inherits host-runtime permissions and provides protected-file checks, external-action gates, explicit approvals, plan tokens, receipts, and rollback paths; this supports strong scores for confirmation, data-flow transparency, sensitive-data handling, and rollback. Least privilege is also addressed, but deducted because Citadel is not a sandbox and arbitrary shell child processes can exceed direct-tool boundaries; some automation can leave OS tasks that require manual removal. Release instructions describe version pinning and checksums, and CI actions shown are commit-pinned, but the sample is insufficient to assess the full dependency closure, so dependency security is partial. Attribution is traceable to a named author, repository, and license, but publisher identity is unverified and maintenance responsibility is not fully established.
The documentation specifies blocked or unknown outcomes and discloses silent opencode load failure, non-blocking hooks, and platform boundaries, supporting a high failure-message score. Deductions reflect the large multi-runtime product being represented by a partial sample whose installation, version, and cross-runtime claims cannot all be reconciled here; availability also depends on host platforms and external tools.
README and skill instructions give concrete use and non-use scenarios, approval boundaries, and routing limits. Skill metadata uses explicit trigger keywords with auto-trigger disabled, and preview is clearly non-executable, supporting strong adaptability and trigger precision. Deductions reflect runtime differences: the sampled docs say Codex, Claude Code, and opencode capabilities are not equivalent, with platform-specific requirements and configuration.
The repository presents a clear information structure, documentation index, installation and removal instructions, FAQ, known limitations, MIT license, and versioned acquisition paths. Deductions reflect naming and component variation across Claude, Codex, and opencode; while changelog and release versioning are referenced, the sample does not establish equally clear maintenance ownership, support, and update responsibility across the product.
Output states, evidence, handoffs, and recovery actions have concrete formats and examples. Reported evaluation results include limits rather than claiming general savings. Deductions reflect that comparative benefits are bounded by an invalid baseline, small samples, or local fixtures; a full operating layer may not repay its overhead for short one-off tasks, and real-user net benefit remains unproven.
README bounds its experimental claims, while security and installation documents give traceable commands, versions, and evidence types and distinguish recorded results, product boundaries, and unknowns. Deductions reflect that most support is repository-authored; this static sample provides no independent review and omits parts of the source, tests, and release artifacts, limiting cross-source corroboration.
- Citadel inherits the permissions of Claude Code, Codex, or its other host runtime. It is not an OS sandbox; shells, scripts, and child processes can bypass direct-tool checks.
- Before enabling it, review the target repository's instructions, scripts, and hooks, and verify the pinned release manifest and checksums. Do not treat bounded local or benchmark results as proof of production reliability or cost savings.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.4.5 Citadel v1.4.5
Release notes excerpt
Citadel v1.4.5 packages the reliability and security fixes merged since v1.4.4. Security and upgrade notes Repository-configured typechecks and loop trigger/verifier commands require machine-local approval for the exact project and command. Review the displayed approval command and run it interactively; hooks and agents cannot approve their own commands. Session-end cleanup and archive destinations are contained within the project, including paths with symlinked ancestors. Fixes and improvements - Include all shared utilities so installed hooks can load frontmatter dependencies. …View on GitHub ↗ -
v1.4.4 Citadel v1.4.4
Release notes excerpt
What's Changed * chore(deps): bump actions/setup-node from 7.0.0 to 7.1.0 by @dependabot[bot] in https://github.com/SethGammon/Citadel/pull/350 * chore(deps): bump actions/upload-artifact from 7.0.1 to 7.0.2 by @dependabot[bot] in https://github.com/SethGammon/Citadel/pull/349 * chore(deps): bump actions/download-artifact from 8.0.1 to 8.0.2 by @dependabot[bot] in https://github.com/SethGammon/Citadel/pull/351 * chore(deps): bump hashgraph-online/ai-plugin-scanner-action from 1.2.767 to 1.2.786 by @dependabot[bot] in https://github.com/SethGammon/Citadel/pull/352 …View on GitHub ↗ -
v1.4.3 Citadel v1.4.3
Release notes excerpt
What's Changed * fix: repair plugin MCP paths and security boundary by @SethGammon in https://github.com/SethGammon/Citadel/pull/302 * fix: bind config recovery commands to project root by @SethGammon in https://github.com/SethGammon/Citadel/pull/304 * chore(deps): bump hashgraph-online/ai-plugin-scanner-action from 1.2.640 to 1.2.683 by @dependabot[bot] in https://github.com/SethGammon/Citadel/pull/305 * fix(codex): repair MCP plugin startup by @brandstaetter in https://github.com/SethGammon/Citadel/pull/312 …View on GitHub ↗
FAQ
Does Citadel automatically transmit project state or telemetry?
Does it guarantee the quality of an agent’s code?
What happens when verification evidence is missing?
passed, failed, blocked, or unknown; missing evidence is not promoted to success.How can it be removed?
/unharness to create a receipt-owned leave plan, review the footprint, then apply it with the plan token. Legacy installs are inventoried first and cannot claim exact removal.Is Citadel free?
Is Citadel open source?
Is Citadel safe to use?
Is Citadel still maintained?
Who makes Citadel?
What is Citadel's official website?
Thanks — we use this to improve the page.