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.

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.

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

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

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

/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.

Core Features

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/`](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: 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

Community

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

Star History

Contributors

License

MIT