One command routes the work. The repository remembers what happened.

Citadel is the open-source operating layer for Claude Code and OpenAI Codex. It adds durable project memory, cheap intent routing, verification evidence, cost telemetry, and coordinated agents in isolated git worktrees.

If CLAUDE.md and AGENTS.md tell the runtime what your project is, Citadel tells the runtime how to operate on it.

Install · See the operating loop · Inspect the proof · How it works · Help test 1.1

---

See the operating loop

The animation summarizes a real contract: route the request, run the lightest capable workflow, verify the result, write the handoff, and preserve the next action in the repository. Run the copyable workflow to reproduce it in your own project.

After installing, try this from your project root:

/do setup --express
/do next
/do review README.md
/do generate tests for the changed files
/cost

Proof, not promises

Proof	Result	Inspect it
Serialized landing lane	15 of 15 PRs merged and deployed, 14 branch updates, 59 CI waits, 0 repair tasks	Public proof repository
Hosted operating journey	30 of 30 deterministic Claude Code and Codex journeys across Windows, Linux, and macOS	Golden path
Missing evidence	Absent telemetry stays unknown instead of becoming a green check	Dashboard contract
Fresh-process continuity	Campaign state and the next action reload from repository files	Campaigns

These are bounded claims. Deterministic fixtures are not human adoption, clone operations are not retained users, and Citadel does not replace review.

What Is Citadel?

Citadel turns one-off coding-agent chats into repeatable engineering workflows. Claude Code and Codex are strong at local reasoning and code edits, but each session still needs project context, safe operating rules, task routing, and a way to continue work after context resets. Citadel is that harness layer.

	Claude Code / Codex alone	With Citadel
Project context	Re-explained every session	Compiled memory in repo-local .planning/ files
Choosing a workflow	You pick review vs. debug vs. refactor	/do routes plain English to the lightest capable tool
Long-running work	Dies with the context window	Campaigns persist, resume, and hand off across sessions
Parallel work	Manual branch juggling	Fleet agents in isolated worktrees with shared discoveries
Safety rules	Prompt discipline, re-stated by hand	Lifecycle hooks enforce file protection and quality gates
Token spend	Guesswork	/cost and /dashboard from runtime-native telemetry

Quick Install

Prerequisites: Claude Code or OpenAI Codex, Node.js 18+, and a git repository you want Citadel to manage.

Open your project in Claude Code or Codex and paste this install prompt:

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.

Important

After the installer finishes, start a fresh session if the runtime asks for one, then run /do setup --express. That is the command that matters: it auto-detects the project, installs hooks, scaffolds Citadel state, and gets you to a working /do without a tour.

Manual install (run the installer yourself)

Clone Citadel once:

git clone https://github.com/SethGammon/Citadel.git ~/Citadel

Then run exactly one installer from the target project root.

For OpenAI Codex:

node ~/Citadel/scripts/install.js --runtime codex --add-marketplace

For Claude Code:

node ~/Citadel/scripts/install.js --runtime claude --install --scope local

Then start a fresh session in the same project and run:

/do setup --express

Tip

For a copyable first-run walkthrough, see DEMO.md. For runtime-specific details, dry runs, and troubleshooting, see INSTALL.md.

How It Works

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

Classification cascades through four tiers, cheapest first:

• Tier 0 · Pattern match - catches trivial commands with regex. Zero tokens, under a millisecond.
• Tier 1 · Active state - checks whether you are mid-campaign and resumes it.
• Tier 2 · Keyword table - routes known task language to installed skills. Still zero tokens.
• Tier 3 · LLM classifier - only when tiers 0-2 miss: analyzes complexity and picks Skill, Marshal, Archon, or Fleet.

Most requests resolve before Tier 3. Whatever runs, the same loop closes around it:

Orchestration Ladder

Four tiers let Citadel scale from a one-line edit to a multi-session campaign. You never pick one; the router does.

Core Features

Capability	What you get	Docs
Durable memory	Campaigns, discoveries, intake, and telemetry live in .planning/, so work resumes after a fresh thread or context reset	Campaigns
/do routing	Describe the task once; pattern, state, and keyword tiers resolve most requests for zero tokens	Routing preview
Safety hooks	35 Node hook scripts across 29 lifecycle events protect files, gate risky actions, and record handoffs	Hooks
Cost telemetry	/cost and /dashboard show real token usage and session spend instead of guesses	Reports
Product evidence	Local activation stages and authenticated GitHub traffic snapshots separate attention and discovery sources from verified use without hosted analytics	Activation metrics
Golden-path verification	A hosted 30/30 Claude/Codex × Windows/Linux/macOS fixture grid proves install, setup, route, verification, handoff, resume, and exact rollback while labeling human evidence separately	Golden path
Read-only dashboard	Nine schema-1 views expose needs-you, campaign, fleet, loop, hook, handoff, cost, and activation state; missing data stays unknown, never false green	Dashboard spec
Product benchmark	Ten frozen bare-versus-harnessed scenarios preserve symmetric inputs, raw runs, negative results, and an explicit open utility gate	Benchmark
Skill interoperability	A digested external SKILL.md fixture installs unchanged under Claude and Codex projections, routes, verifies, emits local telemetry, hands off, and rolls back	Interoperability
Operator console	/do next is a decision-first cockpit: current state, next action, risk boundary, verification profile	Operating loop
Parallel fleets	Broad work decomposes across agents in isolated worktrees, with discoveries shared between waves	Fleet
Skills	49 built-in skills covering review, refactor, tests, QA, telemetry, and setup; write your own in one file	Skills
Repeatable setup	Runtime-specific installers plus /do setup --express produce the same project state on Codex and Claude Code	Install

Why Citadel Exists

Claude Code and Codex made local agentic development practical. The next problem is operational: making those agents reliable across real projects, repeated sessions, and larger tasks. Without a harness, you keep solving the same coordination problems by hand:

• Re-explaining architecture and project conventions in every session.
• Choosing between review, debugging, refactor, test generation, or planning workflows yourself.
• Losing decisions and discoveries when context compresses or a session ends.
• Manually splitting large tasks across branches or worktrees.
• Rebuilding safety rules, cost checks, and handoff discipline in prompts.

Citadel adds the missing layer around the runtime: persistent state, intent routing, lifecycle enforcement, telemetry, and coordinated multi-agent execution. The priority is reliability over novelty: easier to install, easier to verify, harder to misuse.

Built in the Open

Everything described above ships in this repository:

• 49 skills under [`skills/`](skills/), hook source under [`hooks_src/`](hooks_src/), runtime adapters under [`runtimes/`](runtimes/), installers and verification under [`scripts/`](scripts/).
• Trust boundaries are documented in SECURITY.md and THREAT_MODEL.md: local automation risk, generated state, hooks, approval gates, and public-artifact review.
• The loop contract makes repeated agent workflows inspectable, with shared budgets, verifiers, and stop conditions.
• CI runs the full local verification suite on every push. Run it yourself from a clone:

npm test

Roadmap

The full plan with exit criteria lives in docs/ROADMAP.md. The arc: make the harness visible, prove it with numbers, then make it steerable.

• See It: the read-only local dashboard now projects nine versioned views with explicit source health. Its 1,000-file CI gate enforces <1 second cold start, <500 ms updates, <64 MB complete RSS, and <10 MB dashboard overhead. Pixel baselines and stranger comprehension remain open gates. See docs/DASHBOARD_SPEC.md.
• Prove It: the reproducible benchmark contract now freezes ten symmetric bare-versus-harnessed scenarios and publishes its negative fixture result. Actual runs and external scenario selection remain open. See docs/BENCHMARK.md.
• Drive It: approvals, steering, and a loop builder in the browser, through the same file contracts the terminal uses.
• Harden It: teams-native fleet GA, sandboxed execution profiles, threat model v2, release integrity.
• Multiply It: team workflows, a community skill and loop registry, and a third runtime adapter.

Learn More

• Install and first run - setup, first-run paths, and troubleshooting for both runtimes
• Demo workflow - copyable operating-loop demo for a real repo
• Interactive routing demo - watch the tier cascade animate
• Lab report: 103 days in - the real numbers, what the platforms absorbed, and what survived
• Routing preview guide - compare Skill, Marshal, Archon, and Fleet before heavier work
• Skills reference - all built-in skills with invocation and examples
• Hooks reference - lifecycle events and enforcement behavior
• Campaign guide - persistent state, phases, and handoffs
• Fleet guide - parallel agents, worktree isolation, discovery relay
• Operating loop proof - evidence checklist for demos and PRs
• Activation and acquisition metrics - local funnel privacy, GitHub traffic history, and honest interpretation
• Golden path verification - deterministic runtime fixtures, cross-OS matrix rules, and human-proof boundaries
• Product benchmark - frozen methodology, raw fixture evidence, negative results, and remaining real-run gates
• Independent product-proof trial - privacy-minimal recruitment, cohort, benchmark-selection, and 14-day return-use protocol
• Interoperability - external skill compatibility, provenance limits, and remote registry boundaries
• Citadel 1.1 product-proof scorecard - what is locally proven, CI-proven, human-proven, and still blocked
• Skill and memory visibility - inspect available skills and compiled project memory
• Public positioning - how to describe Citadel without overclaiming
• Security model - path traversal, shell injection, and defensive measures
• Contributing - issues, PRs, skills, and docs

FAQ

Is this for me?

If you use Claude Code or Codex on a real repository and keep hitting context loss, repeated setup, weak handoffs, or manual coordination overhead, yes. Citadel is most useful once you have repeated workflows.

How is this different from CLAUDE.md or AGENTS.md?

Those files describe your project. Citadel adds the operating layer around the agent: routing, memory, hooks, telemetry, and parallel coordination.

Do I need to learn all 49 skills?

No. Use /do and describe what you want. Direct skill commands are available when you want explicit control.

How much token overhead does it add?

Skills cost zero when not loaded. Router tiers 0-2 are local checks; Tier 3 uses a small LLM classification only when needed. Use /cost to inspect real usage.

Does it work on Windows?

Yes. Hooks and scripts run on Node.js, and the Codex installer includes Windows readiness checks.

Community

• Help test Citadel 1.1 - independent benchmark review, first-time-user trials, and return-use evidence
• GitHub Discussions - questions, use cases, bugs, and workflow requests
• X / Twitter - project updates

Star History

Contributors

License

MIT