Citadel

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

GitHub Releases are the only supported stable acquisition channel. Choose an explicit version and use its complete archive, external manifest, and SHA-256 sidecar. The public npm package named citadel is unrelated to this project, and floating main is development source rather than a stable install.

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

Install Citadel in this repository from a tagged GitHub Release at
https://github.com/SethGammon/Citadel/releases.

Choose an explicit vX.Y.Z release. Download all three matching assets:
citadel-vX.Y.Z.tar.gz, citadel-vX.Y.Z.tar.gz.manifest.json, and
citadel-vX.Y.Z.tar.gz.sha256. Verify that the archive SHA-256 agrees with both
the sidecar and external manifest before extracting it. Do not use npm and do
not install from floating main.

Detect whether this session is running in OpenAI Codex or Claude Code. Use the
extracted citadel-X.Y.Z directory as the source and this repository as the
target. Create a governed adoption plan for that runtime. Show me the exact
footprint, unknown external registrations, plan digest, and confirmation token
before applying anything. After I approve the saved plan, apply it and run
adoption doctor.

After adoption is healthy and Citadel is enabled in a fresh thread, run:

/do setup --express

The agent must stop at the saved adoption plan until you approve its exact confirmation token. Follow any external plugin-enable step still reported as unknown, start a fresh session if prompted, then run /do setup --express.

node "$CITADEL_ROOT/scripts/adopt.js" plan "$CITADEL_ROOT" \
  --target . --project-runtime codex \
  --out ../citadel-adoption.plan.json --json

node "$CITADEL_ROOT/scripts/adopt.js" apply ../citadel-adoption.plan.json \
  --confirm <plan-token> --json

node "$CITADEL_ROOT/scripts/adopt.js" doctor --target . --json

For contributor testing only, a source checkout may use git clone --branch main https://github.com/SethGammon/Citadel.git. That path is development-only: it has no release trio or immutable version boundary and must not be presented as a stable install.

See Installation for platform-specific checksum commands, runtime enable steps, rollback, and uninstall. See Releases for the artifact and provenance contract.

Start with /do and describe the outcome:

/do review README.md
/do generate tests for the changed files
/do preview build a caching layer
/do next

Exact commands resolve only when the normalized whole request matches. The project commands /do test, /do build, and /do typecheck additionally require the corresponding non-empty target package.json script. Larger requests collect generated candidates and then require runtime semantic classification.

/do preview shares only the exact-command and built-in candidate preflight. It does not inspect active state, discover project-local skills, or run the runtime LLM classifier. Every natural-language preview is non-executable: selected and command are null, canRunNow is false, and the boundary is semantic-classification-required.

If you already know the destination, a validated override is available without bypassing activation or safety boundaries:

/do --route /test-gen -- generate tests for the changed files

The operating loop uses five public states:

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

For a short one-off edit, your coding agent may already be enough. Citadel does not replace CLAUDE.md, AGENTS.md, branch protection, or human review.

Citadel publishes positive and negative outcomes from the same evidence contract. Its v1 experiment does not support a savings claim: one matched baseline timeout drove the aggregate advantage, and excluding that pair reversed the economic direction. A later capability-profile run preserved the verified rate but used more measured GPU energy. A representative fixture shakedown reached 6/12 verified cells with zero false passes, but missed its frozen energy gate. The research site publishes the bounded results and limitations together.

The full source checkout retains a broader, reproducible proof program. These maintainer instruments and their detailed artifacts are not included in the slim GitHub Release.

The public claim is deliberately narrow: Citadel can make agent evaluations inspectable, reproducible, and fail-honest. Comparative real-user utility remains open.

• Evaluator start here
• Generated evidence manifest
• Experiment results, boundaries, and reproduction commands
• Deploy-steward public case study
• Public deploy control and steward treatment
• Outside-authored holdout
• Bounded hybrid pilot

• Citadel runs with the permissions of Claude Code or Codex. It is not a sandbox and does not replace code review or branch protection.
• Verification reports passed, failed, blocked, or unknown. Missing evidence is not promoted to success.
• Project state and telemetry stay local by default. Citadel does not commit, push, or transmit them automatically.
• The automated suite validates Citadel's contracts and fixtures. It does not guarantee the quality of agent-written code.

Read Security and Privacy before enabling Citadel in a sensitive repository.

The stable release intentionally ships a small public documentation surface:

The extracted release includes 48 skills and 35 hook scripts across 29 lifecycle events. They are an internal catalog, not a prerequisite checklist.

Citadel keeps operational state separate from application code:

.planning/                 Campaigns, runs, evidence, handoffs, 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

Does Citadel work on Windows?

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

How do I remove it?

Use /unharness to create a receipt-owned leave plan, review the exact footprint, and apply it with the plan token. Legacy installs are inventoried first and cannot claim exact removal. See Installation.

Where should I report a problem?

Use GitHub Discussions for questions or GitHub Issues for reproducible defects.

MIT License