README.md

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 from https://github.com/SethGammon/Citadel into this repository.
Detect whether I am using Codex or Claude Code, show me what will change before
applying it, use the current repository as the target, and run Citadel doctor.

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.

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

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 or operation internals. Start with /do and describe the outcome:

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

Citadel reveals more machinery only when the work needs it:

Most users can stay at Levels 1 and 2. Advanced levels do not replace or complicate /do.

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:

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.

Evidence status

Citadel publishes positive and negative results from the same evidence contract. V1 recorded 27/36 verified cells versus 24/36 and a frozen aggregate with 9.9% less measured GPU energy, but one same-route 60-second baseline timeout drove that appearance. Excluding the matched pair reverses the economic direction to 3.5% more GPU energy and 5.4% more modeled GPU cost, so Citadel makes no v1 savings claim.

A distinct capability-profile follow-up then preserved the always-7B verified rate (24/36 versus 24/36) but used 15.7% more measured GPU energy after 12 verification escalations. Citadel publishes that regression because detecting a plausible policy that is economically worse is part of the product.

The latest representative fixture shakedown moved verification from exact answers to repository artifacts. Both policies verified 6/12 cells with zero false passes and path violations; Citadel's 7.1% energy reduction missed the frozen 20% gate and is published as failed.

• Evaluator start here
• Generated evidence manifest
• Prospective local comparison
• Capability-profile follow-up
• Representative repository-operation shakedown
• Research site

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.

If you regularly delete clones, opt into cross-clone repository memory on Node.js 22.13+ with citadel memory enable. Citadel then keeps completed campaigns, postmortems, research, discoveries, backlog, and project context in a user-level SQLite database and restores missing files in another clone of the same remote. Its default path is outside the checkout, and Citadel never commits, pushes, or transmits it.

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.

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.

For reviewers who want evidence instead of architecture claims, Operation Control includes a frozen 120-cell real-workload import and a preregistered real-runtime integration result. Both preserve failed and unknown outcomes and state what they do not prove.

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

The complete reference is in docs/.

.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

Common questions

Community

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