Skip to content
Back to search

citadel-local

MarketplaceWorks with Claude CodeGitHub

Local Citadel plugin marketplace

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/SethGammon/Citadel with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/SethGammon/Citadel'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sethgammon-citadel/badge.svg)](/listings/sethgammon-citadel)

HTML

<a href="/listings/sethgammon-citadel"><img src="/api/listings/sethgammon-citadel/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

Citadel is installed through the plugin marketplace already built into your coding agent. The commands below pin the complete `v1.4.5` release; if that tag is not present on [GitHub Releases](https://github.com/SethGammon/Citadel/releases), do not substitute floating `main`.

**Verified release · Project-local activation · Removable · No npm package**

OpenAI Codex

Run these commands from the repository you want Citadel to manage:

codex plugin marketplace add SethGammon/Citadel --ref v1.4.5
codex plugin add citadel@citadel-local

Start a new Codex task, review Citadel through `/hooks`, then give it a real request such as `/do review README.md`.

Claude Code

Run these commands from the repository you want Citadel to manage:

claude plugin marketplace add SethGammon/Citadel@v1.4.5 --scope local
claude plugin install citadel@citadel-local --scope local

Run `/reload-plugins` if Claude Code is already open, then give Citadel a real request such as `/do review README.md`.

Prefer to have your agent install it?

Paste this into Claude Code or Codex. It explains both what Citadel is and the boundary the installer must preserve:

Citadel is an open-source operating layer for Claude Code and OpenAI Codex. It
adds one /do entry point, repository-local state that survives sessions,
guarded multi-step workflows, and reviewable evidence with explicit Needs You
and Resume boundaries.

Install Citadel v1.4.5 from https://github.com/SethGammon/Citadel using this
runtime's native plugin marketplace, then enable it for this repository. Use
project-local defaults and preserve removal evidence for every change. Do not clone main or change shared
configuration, sandbox settings, permissions, or user-wide settings without
asking me.

Only interrupt me for a platform-required trust or reload action, or for a real
configuration conflict. Verify the result, then tell me the single next action.

The platform owns plugin acquisition and executable-code trust. Citadel owns bounded project state and recovery. Plans, digests, receipts, and doctor checks remain available as evidence, but are not user chores on the normal path.

<details> <summary><strong>Manual, offline, and high-assurance installation</strong></summary>

<br>

1. Open the [GitHub Releases](https://github.com/SethGammon/Citadel/releases) page and choose an explicit `vX.Y.Z` release. 2. Download `citadel-vX.Y.Z.tar.gz`, its `.manifest.json`, and its `.sha256` sidecar into one directory. 3. Compare the archive's SHA-256 with both published values before extraction. A missing asset or mismatch is a blocked install. 4. Extract the archive, then use its single `citadel-X.Y.Z/` directory as the immutable source for the governed adoption plan.

From the target repository, with `CITADEL_ROOT` pointing at that extracted directory, the compact Linux/macOS form is below. Windows users should use the quoted `$env:CITADEL_ROOT` PowerShell path in [Installation](INSTALL.md).

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

Use `--project-runtime claude` for Claude Code or `both` only when both runtime projections are intentional. Runtime-specific enable steps are in [Installation](INSTALL.md).

Keep every saved plan outside the target repository. Writing the plan inside the target changes the preflight snapshot and causes apply to reject `TARGET_DRIFT`.

</details>

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "citadel-local",
  3. "description": "Local Citadel plugin marketplace",
  4. "owner": {
  5. "name": "SethGammon",
  6. "email": "noreply@github.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "citadel",
  11. "description": "Route requests, preserve run state, enforce hooks, and surface reviewable evidence in Claude Code",
  12. "version": "1.4.5",
  13. "source": "./",
  14. "author": {
  15. "name": "SethGammon",
  16. "email": "noreply@github.com"
  17. }
  18. }
  19. ]
  20. }
README.md · README · 289 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. [![Tests](https://github.com/SethGammon/Citadel/actions/workflows/tests.yml/badge.svg)](https://github.com/SethGammon/Citadel/actions/workflows/tests.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  4. ![Node.js 22+](https://img.shields.io/badge/Node.js-22%2B-green.svg)
  5. [![Interactive demo](https://img.shields.io/badge/Interactive_demo-00d2ff.svg)](https://sethgammon.github.io/Citadel/)
  6. # Citadel
  7. **An open-source operating layer for Claude Code and OpenAI Codex.**
  8. Citadel routes requests, preserves repository state between sessions,
  9. coordinates parallel work, applies repository safeguards, and records evidence
  10. and handoffs around the coding agent you already use.
  11. [Install](#install) · [Start using it](#start-using-it) · [Trust boundary](#trust-boundary) · [Documentation](#documentation)
  12. </div>
  13. ## Install
  14. **Requires:** Claude Code or OpenAI Codex, Node.js 22+, and a git repository.
  15. Citadel is installed through the plugin marketplace already built into your
  16. coding agent. The commands below pin the complete `v1.4.5` release; if that tag
  17. is not present on [GitHub Releases](https://github.com/SethGammon/Citadel/releases),
  18. do not substitute floating `main`.
  19. **Verified release · Project-local activation · Removable · No npm package**
  20. ### OpenAI Codex
  21. Run these commands from the repository you want Citadel to manage:
  22. ```bash
  23. codex plugin marketplace add SethGammon/Citadel --ref v1.4.5
  24. codex plugin add citadel@citadel-local
  25. ```
  26. Start a new Codex task, review Citadel through `/hooks`, then give it a real
  27. request such as `/do review README.md`.
  28. ### Claude Code
  29. Run these commands from the repository you want Citadel to manage:
  30. ```bash
  31. claude plugin marketplace add SethGammon/Citadel@v1.4.5 --scope local
  32. claude plugin install citadel@citadel-local --scope local
  33. ```
  34. Run `/reload-plugins` if Claude Code is already open, then give Citadel a real
  35. request such as `/do review README.md`.
  36. ### Prefer to have your agent install it?
  37. Paste this into Claude Code or Codex. It explains both what Citadel is and the
  38. boundary the installer must preserve:
  39. ```text
  40. Citadel is an open-source operating layer for Claude Code and OpenAI Codex. It
  41. adds one /do entry point, repository-local state that survives sessions,
  42. guarded multi-step workflows, and reviewable evidence with explicit Needs You
  43. and Resume boundaries.
  44. Install Citadel v1.4.5 from https://github.com/SethGammon/Citadel using this
  45. runtime's native plugin marketplace, then enable it for this repository. Use
  46. project-local defaults and preserve removal evidence for every change. Do not clone main or change shared
  47. configuration, sandbox settings, permissions, or user-wide settings without
  48. asking me.
  49. Only interrupt me for a platform-required trust or reload action, or for a real
  50. configuration conflict. Verify the result, then tell me the single next action.
  51. ```
  52. The platform owns plugin acquisition and executable-code trust. Citadel owns
  53. bounded project state and recovery. Plans, digests, receipts, and doctor checks
  54. remain available as evidence, but are not user chores on the normal path.
  55. <details>
  56. <summary><strong>Manual, offline, and high-assurance installation</strong></summary>
  57. <br>
  58. 1. Open the [GitHub Releases](https://github.com/SethGammon/Citadel/releases)
  59. page and choose an explicit `vX.Y.Z` release.
  60. 2. Download `citadel-vX.Y.Z.tar.gz`, its `.manifest.json`, and its `.sha256`
  61. sidecar into one directory.
  62. 3. Compare the archive's SHA-256 with both published values before extraction.
  63. A missing asset or mismatch is a blocked install.
  64. 4. Extract the archive, then use its single `citadel-X.Y.Z/` directory as the
  65. immutable source for the governed adoption plan.
  66. From the target repository, with `CITADEL_ROOT` pointing at that extracted
  67. directory, the compact Linux/macOS form is below. Windows users should use the
  68. quoted `$env:CITADEL_ROOT` PowerShell path in [Installation](INSTALL.md).
  69. ```bash
  70. node "$CITADEL_ROOT/scripts/adopt.js" plan "$CITADEL_ROOT" \
  71. --target . --project-runtime codex \
  72. --out ../citadel-adoption.plan.json --json
  73. node "$CITADEL_ROOT/scripts/adopt.js" apply ../citadel-adoption.plan.json \
  74. --confirm <plan-token> --json
  75. node "$CITADEL_ROOT/scripts/adopt.js" doctor --target . --json
  76. ```
  77. Use `--project-runtime claude` for Claude Code or `both` only when both runtime
  78. projections are intentional. Runtime-specific enable steps are in
  79. [Installation](INSTALL.md).
  80. Keep every saved plan outside the target repository. Writing the plan inside
  81. the target changes the preflight snapshot and causes apply to reject
  82. `TARGET_DRIFT`.
  83. </details>
  84. For contributor testing only, a source checkout may use
  85. `git clone --branch main https://github.com/SethGammon/Citadel.git`. That path
  86. is development-only: it has no release trio or immutable version boundary and
  87. must not be presented as a stable install.
  88. See [Installation](INSTALL.md) for platform-specific checksum commands,
  89. runtime enable steps, rollback, and uninstall. See [Releases](docs/RELEASES.md)
  90. for the artifact and provenance contract.
  91. ## Start using it
  92. <img src="assets/terminal-demo.svg" width="100%" alt="An illustrative live Citadel runtime session moving from request through run and evidence to resume" />
  93. Start with `/do` and describe the outcome:
  94. ```text
  95. /do review README.md
  96. /do generate tests for the changed files
  97. /do preview build a caching layer
  98. /do next
  99. ```
  100. Exact commands resolve only when the normalized whole request matches. The
  101. project commands `/do test`, `/do build`, and `/do typecheck` additionally
  102. require the corresponding non-empty target `package.json` script. Larger
  103. requests collect generated candidates and then require runtime semantic
  104. classification.
  105. `/do preview` shares only the exact-command and built-in candidate preflight.
  106. It does not inspect active state, discover project-local skills, or run the
  107. runtime LLM classifier. Every natural-language preview is non-executable:
  108. `selected` and `command` are null, `canRunNow` is false, and the boundary is
  109. `semantic-classification-required`.
  110. If you already know the destination, a validated override is available without
  111. bypassing activation or safety boundaries:
  112. ```text
  113. /do --route /test-gen -- generate tests for the changed files
  114. ```
  115. The operating loop uses five public states:
  116. | State | What it means |
  117. |---|---|
  118. | **Request** | You describe the outcome through `/do` or a known skill. |
  119. | **Run** | The selected workflow acts within runtime, repository, and approval boundaries. |
  120. | **Evidence** | Checks and artifacts report `passed`, `failed`, `blocked`, or `unknown`. |
  121. | **Needs You** | Citadel stops with the exact approval, conflict, or missing evidence required. |
  122. | **Resume** | Repo-local state names the next useful action for a fresh session. |
  123. ## When Citadel is useful
  124. Citadel is most useful when coding-agent work extends beyond one prompt:
  125. | You are dealing with... | Citadel adds... |
  126. |---|---|
  127. | Repeated setup and lost context | Repo-local decisions, discoveries, and handoffs |
  128. | Unclear workflow choice | One natural-language entry point through `/do` |
  129. | Risky or multi-step changes | Approval boundaries and explicit verification |
  130. | Several agents or branches | Isolated worktrees, ownership, and shared discoveries |
  131. | Work interrupted between sessions | Durable state and a concrete resume action |
  132. For a short one-off edit, your coding agent may already be enough. Citadel does
  133. not replace `CLAUDE.md`, `AGENTS.md`, branch protection, or human review.
  134. ## What Citadel can prove
  135. Citadel publishes positive and negative outcomes from the same evidence
  136. contract. Its v1 experiment does not support a savings claim: one matched
  137. baseline timeout drove the aggregate advantage, and excluding that pair
  138. reversed the economic direction. A later capability-profile run preserved the
  139. verified rate but used more measured GPU energy. A representative fixture
  140. shakedown reached 6/12 verified cells with zero false passes, but missed its
  141. frozen energy gate. The [research site](https://sethgammon.github.io/Citadel/research.html)
  142. publishes the bounded results and limitations together.
  143. ### Source-only proof program
  144. The full source checkout retains a broader, reproducible proof program. These
  145. maintainer instruments and their detailed artifacts are not included in the
  146. slim GitHub Release.
  147. | Evidence | Result | Boundary |
  148. |---|---|---|
  149. | Outside-authored public holdout | 24 distinct repositories, sealed routes, and 32 official verdicts. The controller verified 3/16 tasks versus 2/16 for direct Claude at 1.26% lower comparison cost. | Direct Claude verified only 12.5%, so the baseline was invalid. This is a diagnostic, not proof of reliability or savings. |
  150. | Bounded hybrid pilot | Both policies verified 12/12 synthetic tasks. A local Qwen 3B support route used 38.7% less comparison cost than always-Claude. | One model pair, one machine, and author-selected tasks. Actual subscription cash and production generalization remain unknown. |
  151. | Offline evidence replay | In a full source checkout, `npm run grant:verify` checks signed artifacts, source bindings, receipt chains, reports, and public claims without calling a model. | This maintainer command is source-only. Artifact integrity does not prove that an agent produced good work. |
  152. | Deterministic recovery and safety comparisons | Journaled recovery produced 0 duplicate effects versus 3 for naive restart across six injected boundaries. Safety gates achieved 100% malicious recall and 0% benign false positives across 12 matched decisions. | Local deterministic fixtures only. No process-kill, power-loss, real exploit, or cross-OS claim. |
  153. | Leased deploy-steward state machine | Across three 15-PR batches per arm, independent loops produced 315 stale-head race attempts; the leased steward produced 0. | Fake provider only. This is not GitHub, Actions, branch protection, or real-deployment evidence. |
  154. | Protected GitHub deploy-steward comparison | Across three valid matched public runs, both policies merged 45/45 PRs through strict Actions checks and recorded exactly one successful GitHub Deployment per merge SHA. Independent loops incurred 106 failed merge races, 315 stale updates, and 421 interventions; the steward incurred 0 of each. | Six disposable public repositories under one account, plus one disclosed invalid run. Deployments are GitHub API records, not production releases. No speed, cost, human-utility, or broad reliability claim. |
  155. | Historical npm-pack profile | At source commit `9bebf1a`, the private source package measured 9,123,375 packed bytes and 1,888 files, 5.7385% and 66 files below its frozen baseline. | Native marketplaces consume an exact GitHub release tag; the release trio remains the manual and offline assurance path. This frozen source-only measurement is not a current release-size or public-package claim. |
  156. The public claim is deliberately narrow: Citadel can make agent evaluations
  157. inspectable, reproducible, and fail-honest. Comparative real-user utility
  158. remains open.
  159. - [Evaluator start here](docs/grants/EVALUATOR_START_HERE.md)
  160. - [Generated evidence manifest](docs/EVIDENCE_MANIFEST.md)
  161. - [Experiment results, boundaries, and reproduction commands](docs/EXPERIMENTS.md)
  162. - [Deploy-steward public case study](docs/CASE_STUDY_DEPLOY_STEWARD.md)
  163. - [Public deploy control](https://github.com/SethGammon/citadel-steward-proof-20260804-control) and [steward treatment](https://github.com/SethGammon/citadel-steward-proof-20260804-treatment)
  164. - [Outside-authored holdout](benchmarks/public-holdout-pilot/REPORT.md)
  165. - [Bounded hybrid pilot](benchmarks/hybrid-economic-pilot-v2/published-run/REPORT.md)
  166. ## Trust boundary
  167. - Citadel runs with the permissions of Claude Code or Codex. It is not a
  168. sandbox and does not replace code review or branch protection.
  169. - Verification reports `passed`, `failed`, `blocked`, or `unknown`. Missing
  170. evidence is not promoted to success.
  171. - Project state and telemetry stay local by default. Citadel does not commit,
  172. push, or transmit them automatically.
  173. - The automated suite validates Citadel's contracts and fixtures. It does not
  174. guarantee the quality of agent-written code.
  175. Read [Security](SECURITY.md) and [Privacy](PRIVACY.md) before enabling Citadel in
  176. a sensitive repository.
  177. ## Documentation
  178. The stable release intentionally ships a small public documentation surface:
  179. | Goal | Document |
  180. |---|---|
  181. | Acquire, install, update, roll back, or remove Citadel | [Installation](INSTALL.md) |
  182. | Verify release archives and provenance | [Releases](docs/RELEASES.md) |
  183. | Understand exact commands, candidates, and preview limits | [Routing Preview](docs/ROUTING_PREVIEW.md) |
  184. | Understand runtime, state, and orchestration boundaries | [Architecture](docs/ARCHITECTURE.md) |
  185. | Use package commands and supported flags | [CLI reference](docs/CLI.md) |
  186. | Review shipped changes | [Changelog](CHANGELOG.md) |
  187. The extracted release includes <!-- GENERATED: skill-count -->48<!-- /GENERATED --> skills and <!-- GENERATED: hook-script-count -->36<!-- /GENERATED --> hook scripts across <!-- GENERATED: hook-event-count -->29<!-- /GENERATED --> lifecycle events. They are an internal catalog, not a prerequisite checklist.
  188. Citadel keeps operational state separate from application code:
  189. ```text
  190. .planning/ Campaigns, runs, evidence, handoffs, and telemetry
  191. .citadel/scripts/ Project-local coordination and reporting utilities
  192. .claude/agent-context/ Rules supplied to delegated agents
  193. .claude/harness.json Project configuration generated by setup
  194. ```
  195. ## Common questions
  196. **Does Citadel work on Windows?**
  197. Yes. Hooks and scripts run on Node.js, and the Codex installer includes Windows
  198. readiness checks.
  199. **Can I choose which model each agent uses?**
  200. Yes. Codex agent models and reasoning effort are project configuration, not
  201. hardcoded internals. Citadel ships current Sol, Terra, and Luna defaults and
  202. supports per-family or per-agent overrides, including `max` and `ultra` where
  203. the selected Codex model supports them. See
  204. [Agent model configuration](docs/CLI.md#agent-model-configuration).
  205. **How do I remove it?**
  206. Use `/unharness` to create a receipt-owned leave plan, review the exact
  207. footprint, and apply it with the plan token. Legacy installs are inventoried
  208. first and cannot claim exact removal. See [Installation](INSTALL.md).
  209. **Where should I report a problem?**
  210. Use [GitHub Discussions](https://github.com/SethGammon/Citadel/discussions) for
  211. questions or [GitHub Issues](https://github.com/SethGammon/Citadel/issues) for
  212. reproducible defects.
  213. [MIT License](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.