Citadel
An operating layer that makes multi-step Claude Code and Codex repository work recoverable, verifiable, and coordinated.
- Source repo
- SethGammon/Citadel
- Stars
- ★ 927
- Last updated
- 1d ago
- License
- MIT
- Primary language
- JavaScript
- FA score
- 60/100 · Some gaps
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
- Source review
- 60/100 · Some gaps
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 | 60 · Some gaps | Agent plugin / skillFree + model costs | ★ 927 | 1d ago | JavaScript | Codex · Claude Code |
| dmux | 69 · Some gaps | CLIFree + model costs | ★ 1.8k | 2mo ago | HTML | Codex · Claude Code · OpenAI API |
| Agent Deck | 76 · Good | CLIFree + model costs | ★ 1.2k | today | Go | Codex · Claude Code |
| Archon Workflow Factory | 64 · Some gaps | CLIFree + model costs | ★ 24k | 1d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows least-privilege design: local state by default, no automatic transmission, .env protection, path checks, external action gates. User confirmation exists (approval gates, explicit consent). Data flow transparency documented (SECURITY.md, THREAT_MODEL.md). Sensitive data handling protected (.env protection, private state guidance). Dependency security partial: dependency pinning in GitHub Actions, but no dependency audit or vulnerability scan evidence. External effects controlled (prohibits push, publish, etc.). Rollback documented (INSTALL.md, /unharness). Source attribution: author identity unverified, but license and repo metadata present. Deductions: dependency security evidence thin, source attribution limited by unverified publisher.
Self-consistency: README, SECURITY.md, package.json align; features match docs. Dependency availability: Node.js 18+ requirement clear, but no lockfile or integrity checks. Failure messages: error handling documented (stderr mirroring, block reasons). Deduction: dependency availability evidence thin.
Audience and scenarios: clearly targets Claude Code and Codex users, multiple use cases. Capability boundaries: docs explicitly state it does not replace code review, branch protection, etc. Trigger precision: /do command has clear routing logic. Environment fit: supports Windows, Node.js 18+, runtime adapters. Deduction: none significant.
Information architecture: clear docs structure, docs/ directory. Install notes: detailed, quick and manual install. Naming stability: version 1.3.0, but no naming stability guarantee. Examples and FAQ: DEMO.md and common questions. Known limitations: SECURITY.md and THREAT_MODEL.md outline boundaries. License: MIT explicit. Versioning and changelog: CHANGELOG.md present. Maintenance responsibility: author unverified, but contributing guide exists. Deductions: naming stability evidence thin, maintenance responsibility limited by unverified publisher.
Output usability: CLI, docs, demos provided. Marginal value: clearly states when useful, when not. Cost-benefit: benchmark reports exist, but unverified. Deduction: cost-benefit evidence based on unverified benchmarks.
Claim traceability: evidence manifest and benchmark reports. Cross-source corroboration: multiple benchmark reports, but not independently verified. Fact-inference separation: clearly distinguishes verification results from inferences. Deduction: cross-source corroboration thin.
- Publisher identity unverified; assess supply chain risk carefully.
- Dependency security evidence thin; check dependency locking and vulnerability scanning.
- Benchmark results not independently verified; treat cost-benefit claims with caution.
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.