README.md

June 1, 2026 · View on GitHub

Citadel - The Operating System for Autonomous Engineering

Stop re-explaining your codebase every session. Start compounding what your agents learn.

Follow on X for updates · Join the discussion

What Is Citadel

Citadel is an agent orchestration harness for Claude Code and OpenAI Codex. It gives your coding agent durable project memory, installable skills, safety hooks, and parallel campaign coordination.

In practice, that means:

/do routes plain-English requests to the right workflow.
Campaign state survives new sessions and context resets.
Fleet mode can split large work across isolated worktrees.
Hooks enforce quality, safety, telemetry, and handoff rules automatically.

Without Citadel, every agent session starts from zero. You re-explain architecture decisions. You re-discover that the auth module is fragile. You copy-paste the same review checklist. When a task is too big for one agent, you manually split it and lose context between the pieces. Your agents never get better at your codebase — you just get better at prompting them.

With Citadel, sessions resume where they left off. A /do review runs a structured 5-pass review that remembers what broke last time. A /do overhaul the API layer spawns parallel agents in isolated worktrees, shares discoveries between them, and merges the results. Skills you build once compound across every future session. The system learns from its own mistakes through campaign persistence and telemetry.

The difference: CLAUDE.md and AGENTS.md tell the runtime about your project. Citadel gives the runtime the infrastructure to work autonomously — routing, memory, safety hooks, and coordination that a single guidance file can't provide.

Quick Install

Prerequisites: Claude Code or OpenAI Codex already installed, plus Node.js 18+.

Open your target project in your agent and paste this message:

Install Citadel in this repository.

Use https://github.com/SethGammon/Citadel as the source. If a local clone
already exists, reuse it or update it. Detect whether this session is running
in OpenAI Codex or Claude Code. From this project's root, run the matching
Citadel installer and follow any printed plugin enable step.

After Citadel is enabled in a fresh thread, run:

/do setup --express

Use the current repository as the target project. Do not require placeholder
path edits.

The agent will clone or update Citadel, install it for the current runtime, use the current repo as the target, and tell you if a plugin approval step is required.

Want to install it yourself instead? Read INSTALL.md. That page has the manual Codex and Claude Code commands, dry-run commands, and verification steps.

After setup, try:

/do review src/main.ts

What gets checked: plugin manifest, local marketplace, skill paths, hook bundle, MCP config, project guidance, runtime shell or sandbox settings, and readiness evidence under .planning/verification/.

How It Works

Say what you want. /do routes it to the lightest workflow that can handle it.

/do fix the typo on line 42        # Direct edit, no model call
/do review the auth module         # 5-pass structured code review
/do why is the API returning 500   # Root cause analysis
/do build a caching layer          # Multi-step orchestrated build
/do overhaul all three services    # Parallel fleet with isolated worktrees

Classification runs across four tiers:

Pattern match — catches trivial commands with regex. Zero tokens, zero model calls, instant.
Session state — checks if you're mid-campaign and resumes it. Still zero tokens.
Keyword lookup — scans your input against installed skill keywords ("review", "test", "refactor") and routes directly. Still zero tokens.
LLM classification — only when tiers 1-3 don't match, a structured complexity analysis (~500 tokens) determines whether you need a single-step Marshal, a multi-session Archon, or a parallel Fleet.

Most requests resolve at tiers 1-3 for free. Tier 4 is the exception, not the default. You never have to choose the tool.

See it route live

The Orchestration Ladder

Four tiers. Use the lightest one that fits.

Skill: direct domain workflow for focused tasks.
Marshal: single-session commander for multi-step work.
Archon: multi-session campaign planner and executor.
Fleet: parallel agents in isolated worktrees with shared discoveries.

What You Get

Cost transparency. Citadel reads runtime-native session artifacts and computes real cost from API pricing. Use /cost for a breakdown or /dashboard for the overview.

Safety hooks. 32 hooks across 29 lifecycle events guard file access, external actions, protected branches, secrets, and repeated tool failures. Project policy lives in harness.json.

Campaign persistence. Multi-session work survives context compression and session boundaries. /do continue resumes saved state, decisions, and progress.

Parallel coordination. Fleet mode spawns multiple agents in isolated git worktrees, shares discoveries between them, and keeps merge work organized.

Autonomous quality improvement. /evolve scores a target against a rubric, validates improvement hypotheses, runs focused cycles, and records reusable lessons for later sessions.

FAQ

Is this for me? If you're running Claude Code or Codex on a real codebase and finding that agents lose context, repeat mistakes, or can't work in parallel, yes. If you're still exploring either runtime for the first time, Citadel is most useful once you have a real repository and repeat workflows.

How is this different from CLAUDE.md or AGENTS.md? Those files tell the runtime about your project. Citadel tells the runtime how to work: durable state, intelligent routing, automated safety, and native parallelism — the infrastructure layer those files assume someone else built.

Do I need to learn all 45 skills? No. Just use /do and describe what you want in plain English. The router picks the right skill. You can go months without ever typing a skill name directly.

What if /do routes to the wrong tool? Tell it "wrong tool" or invoke the skill directly: /review, /archon, /fleet, and so on. The router is a convenience, not a gate.

How much does it cost in tokens? Citadel adds ~2.5% overhead to your session cost. Skills cost zero when not loaded. The /do router costs ~500 tokens only at Tier 4. Use /cost to see real token data and exact spend for any session or campaign.

How is this different from CrewAI, LangChain, or Aider? Those are agent frameworks: they give you primitives for building agents from scratch. Citadel is an operating system for an existing coding agent. You install a plugin and get routing, persistence, parallelism, and safety hooks on top of the agent you already use.

Does it work with Claude Code? Yes. Citadel ships a Claude Code marketplace and plugin manifest, and scripts/claude-install.js --install --scope local validates the marketplace, installs the plugin into the target project scope, and writes resolved hook paths before you run /do setup.

Does it work with OpenAI Codex? Yes. Citadel ships as a Codex plugin with bundled skills, hooks, MCP config, and install-surface metadata. scripts/codex-install.js prepares the local marketplace and verifies the target project so the remaining Codex app step is the normal Add to Codex install click.

Does this work on Windows? Yes. All hooks and scripts run on Node.js. The Codex installer also runs the Windows sandbox/shell readiness check when it runs on Windows.

Learn More

Interactive routing demo — type any task, watch the tier cascade animate
Install — manual setup for Codex or Claude Code
Quickstart — first-run paths for both runtimes
Skills reference — all 45 skills with invocation and examples
Hooks reference — 29 lifecycle events, 32 hooks, what each one enforces
Campaign guide — persistent state, phases, AI amnesia prevention
Fleet guide — parallel agents, worktree isolation, discovery relay
Security model — path traversal, shell injection, and defensive measures
Contributing — how to submit issues, PRs, and new skills

Community

X / Twitter — follow for updates and what's being built
GitHub Discussions — use cases, questions, requests, show and tell

Have a use case, a bug, or a workflow you want optimized? Open a Discussion. If you're using this in production, say so — it helps prioritize what gets built next.

Roadmap

Multi-runtime support (Claude Code + Codex CLI)
Fleet mode with worktree isolation
Campaign persistence across sessions
Desktop app for campaign management
Autonomous quality improvement engine (/evolve — research-driven multi-cycle director)
Governance layer (3-tier policy constitution, policy-enforcer agent, immutable audit log)
Campaign recovery and rollback
Web dashboard (Citadel Cloud)
Team collaboration features

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to:

Submit issues with bug reports or feature requests
Create pull requests for skills, hooks, or docs
Share your use cases and workflows

License

MIT