citadel

---

See It Run

[!NOTE] The session above is illustrative, but every step in it is real behavior: the tier cascade, the marshal step chain, the .planning/ handoff, and /cost telemetry. Watch the router animate in the interactive demo, or run the copyable demo workflow in your own repo.

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

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.

<strong>Manual install</strong> (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:

flowchart LR
    A["you: /do &lt;task&gt;"] --> R{"router<br/>tiers 0-3"}
    R --> S["skill<br/>focused task"]
    R --> M["marshal<br/>multi-step"]
    R --> C["archon<br/>multi-session"]
    R --> F["fleet<br/>parallel worktrees"]
    S --> H["lifecycle hooks<br/>protect · verify · record"]
    M --> H
    C --> H
    F --> H
    H --> P[(".planning/ memory<br/>state · telemetry · handoffs")]
    P -.->|"next session resumes"| R

Orchestration Ladder

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

<table> <tr> <td width="50%"></td> <td width="50%"></td> </tr> <tr> <td width="50%"></td> <td width="50%"></td> </tr> </table>

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
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	46 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:

• 46 skills under skills/, hook source under hooks_src/, runtime adapters under runtimes/, installers and verification under 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: a local dashboard over .planning/ state: campaigns, fleet, loops, hooks, and dual-mode cost (dollars for API users, plan-window burn for subscribers). Spec in docs/DASHBOARD_SPEC.md.
• Prove It: a public, reproducible benchmark page: completion rate and cost on long tasks, bare agent vs harnessed.
• 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
• 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
• 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

<strong>Is this for me?</strong>

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.

<strong>How is this different from <code>CLAUDE.md</code> or <code>AGENTS.md</code>?</strong>

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

<strong>Do I need to learn all 46 skills?</strong>

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

<strong>How much token overhead does it add?</strong>

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.

<strong>Does it work on Windows?</strong>

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

Community

• GitHub Discussions - questions, use cases, bugs, and workflow requests
• X / Twitter - project updates

Star History

[

![Star history chart for SethGammon/Citadel](https://api.star-history.com/svg?repos=SethGammon/Citadel&type=Date)

](https://www.star-history.com/#SethGammon/Citadel&Date)

Contributors

License

MIT