An open-source operating layer for Claude Code and OpenAI Codex.

Citadel helps coding agents work reliably across real repositories. It routes requests, preserves project state between sessions, coordinates parallel work, applies repository safeguards, and records verification and handoffs.

Quick install | Start using it | Is it a fit? | Portable operations | Documentation

Quick install

Requires: Claude Code or OpenAI Codex, Node.js 18+, and a git repository.

Open the repository you want Citadel to manage, then paste this into your coding agent:

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 report any plugin-enable or restart step it prints.

Use the current repository as the target. Do not require placeholder paths.

Follow any printed enable step, start a fresh session if prompted, then run:

/do setup --express

Setup installs the project hooks and creates the repo-local state Citadel uses to resume work later.

Manual installation

Clone Citadel once:

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

From the repository you want Citadel to manage, run the installer for your runtime.

OpenAI Codex

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

Claude Code

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

Start a fresh session in the same repository and run /do setup --express.

Dry runs, generated paths, runtime-specific setup, and rollback are documented in Installation.

Start using it

You do not need to learn the skill catalog. Start with /do and describe the outcome:

/do review README.md
/do generate tests for the changed files
/do next

Command	What it gives you
/do <request>	Selects and runs the appropriate workflow
/do next	Shows active work, risks, and the next useful action
/dashboard	Opens Mission Control for campaigns, agents, operations, hooks, and handoffs
/cost	Reports token use and session cost from available local telemetry

For a copyable walkthrough in a real repository, use the demo workflow.

When Citadel is useful

Citadel is most useful when coding-agent work extends beyond a single prompt:

You are dealing with...	Citadel adds...
Repeated setup and lost context	Repo-local campaigns, decisions, discoveries, and handoffs
Unclear workflow choice	One natural-language entry point through /do
Risky or multi-step changes	Approval boundaries, lifecycle hooks, and explicit verification
Several agents or branches	Isolated worktrees, ownership, and shared discoveries
Work that must survive interruption	Durable state, recovery, and a concrete next action

For a short, one-off edit, your coding agent may already be enough. Citadel becomes valuable when the operating discipline around the agent is the hard part.

Citadel does not replace CLAUDE.md or AGENTS.md. Those files describe the project and its rules. Citadel supplies the workflows and state used to carry them out consistently.

One operating loop

1. Route: /do chooses a focused skill, a coordinated session, a persistent campaign, or a parallel fleet.
2. Execute and verify: hooks apply repository rules, gate consequential actions, and capture required checks.
3. Record and resume: Citadel writes the result, handoff, and next action to the repository for the next session.

The repository remains the source of truth. Citadel adds an operating layer around the coding agent rather than replacing its runtime.

Portable operations

Portable operations are optional. They are for work that needs a stable contract, durable recovery, comparable executors, or a verifiable receipt. Ordinary repository work still begins with /do.

If you need to...	Start here
Run the same objective through isolated Claude Code and Codex branches	Operation Fork
Package a repeatable result with permissions, checks, and stopping conditions	Outcome Packs
Inspect or control a running operation	Mission Control

The underlying Operations Protocol defines the runtime-neutral contracts for operations, attempts, intents, evidence, and receipts. Most users do not need those internals to use Citadel.

Trust and scope

• Citadel runs with the permissions of Claude Code or Codex. It does not replace code review, branch protection, or repository-specific checks.
• Verification artifacts report passed, failed, blocked, or unknown. Missing evidence is not promoted to success.
• Project state and telemetry stay local by default. Nothing is transmitted automatically.
• The automated suite validates Citadel's contracts and supported fixtures. It does not guarantee the quality of an agent's code.

Read Security, the threat model, and golden-path verification for the full boundaries.

Choose your documentation

Goal	Recommended path
Install or evaluate Citadel	Installation, Demo, Choosing Citadel
Operate day to day	Campaigns, Fleet, Hooks, Mission Control
Use portable operations	Operation Fork, Outcome Packs, Recovery
Integrate or verify	CLI reference, Interoperability, Reports

The complete reference is in docs/.

Project footprint

The current package includes 49 workflows and 35 hook scripts across 29 lifecycle events. /do selects among them; they are not a prerequisite checklist.

Citadel keeps operational state separate from application code:

.planning/                 Campaigns, operations, fleet sessions, intake, and telemetry
.citadel/scripts/          Project-local coordination and reporting utilities
.claude/agent-context/     Rules supplied to delegated agents
.claude/harness.json       Project configuration generated by setup

Runtime adapters may add Claude Code or Codex configuration files. Installation lists every generated path and its rollback procedure.

Common questions

Do I need to learn every skill or operation command?

No. Start with /do. Operation commands are only for work that needs durable contracts, receipts, recovery, or runtime comparison.

Does Citadel work on Windows?

Yes. The hooks and scripts run on Node.js, and the Codex installer includes Windows-specific readiness checks.

How do I remove it?

Use /unharness to export useful state and remove Citadel-managed project files. Installation also documents the exact rollback paths.

Community

• GitHub Discussions for questions, use cases, and workflow requests
• Contributing for issues, pull requests, skills, and documentation
• MIT License