Citadel
installs/mo · npmstarsforks
How to install Citadel?
sethgammon/citadel
$git clone https://github.com/SethGammon/CitadelAn open-source operating layer for Claude Code and OpenAI Codex.
README.md
| 1 | <img src="assets/citadel-hero.svg" width="100%" alt="Citadel, an operating layer for Claude Code and OpenAI Codex" /> |
| 2 | |
| 3 | <div align="center"> |
| 4 | |
| 5 | [](https://github.com/SethGammon/Citadel/actions/workflows/tests.yml) |
| 6 | [](LICENSE) |
| 7 |  |
| 8 | [](https://sethgammon.github.io/Citadel/) |
| 9 | |
| 10 | **An open-source operating layer for Claude Code and OpenAI Codex.** |
| 11 | |
| 12 | 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. |
| 13 | |
| 14 | [Quick install](#quick-install) | [Start using it](#start-using-it) | [Is it a fit?](#when-citadel-is-useful) | [Portable operations](#portable-operations) | [Documentation](#choose-your-documentation) |
| 15 | |
| 16 | </div> |
| 17 | |
| 18 | ## Quick install |
| 19 | |
| 20 | **Requires:** Claude Code or OpenAI Codex, Node.js 18+, and a git repository. |
| 21 | |
| 22 | Open the repository you want Citadel to manage, then paste this into your coding agent: |
| 23 | |
| 24 | ```text |
| 25 | Install Citadel in this repository. |
| 26 | |
| 27 | Use https://github.com/SethGammon/Citadel as the source. If a local clone |
| 28 | already exists, reuse it or update it. Detect whether this session is running |
| 29 | in OpenAI Codex or Claude Code. From this project's root, run the matching |
| 30 | Citadel installer and report any plugin-enable or restart step it prints. |
| 31 | |
| 32 | Use the current repository as the target. Do not require placeholder paths. |
| 33 | ``` |
| 34 | |
| 35 | Follow any printed enable step, start a fresh session if prompted, then run: |
| 36 | |
| 37 | ```text |
| 38 | /do setup --express |
| 39 | ``` |
| 40 | |
| 41 | Setup installs the project hooks and creates the repo-local state Citadel uses to resume work later. |
| 42 | |
| 43 | <details> |
| 44 | <summary><strong>Manual installation</strong></summary> |
| 45 | |
| 46 | <br> |
| 47 | |
| 48 | Clone Citadel once: |
| 49 | |
| 50 | ```bash |
| 51 | git clone https://github.com/SethGammon/Citadel.git ~/Citadel |
| 52 | ``` |
| 53 | |
| 54 | From the repository you want Citadel to manage, run the installer for your runtime. |
| 55 | |
| 56 | **OpenAI Codex** |
| 57 | |
| 58 | ```bash |
| 59 | node ~/Citadel/scripts/install.js --runtime codex --add-marketplace |
| 60 | ``` |
| 61 | |
| 62 | **Claude Code** |
| 63 | |
| 64 | ```bash |
| 65 | node ~/Citadel/scripts/install.js --runtime claude --install --scope local |
| 66 | ``` |
| 67 | |
| 68 | Start a fresh session in the same repository and run `/do setup --express`. |
| 69 | |
| 70 | </details> |
| 71 | |
| 72 | Dry runs, generated paths, runtime-specific setup, and rollback are documented in [Installation](INSTALL.md). |
| 73 | |
| 74 | ## Start using it |
| 75 | |
| 76 | <img src="assets/terminal-demo.svg" width="100%" alt="A Citadel terminal session routing a request, running checks, and writing a handoff" /> |
| 77 | |
| 78 | You do not need to learn the skill catalog. Start with `/do` and describe the outcome: |
| 79 | |
| 80 | ```text |
| 81 | /do review README.md |
| 82 | /do generate tests for the changed files |
| 83 | /do next |
| 84 | ``` |
| 85 | |
| 86 | | Command | What it gives you | |
| 87 | |---|---| |
| 88 | | `/do <request>` | Selects and runs the appropriate workflow | |
| 89 | | `/do next` | Shows active work, risks, and the next useful action | |
| 90 | | `/dashboard` | Opens Mission Control for campaigns, agents, operations, hooks, and handoffs | |
| 91 | | `/cost` | Reports token use and session cost from available local telemetry | |
| 92 | |
| 93 | For a copyable walkthrough in a real repository, use the [demo workflow](DEMO.md). |
| 94 | |
| 95 | ## When Citadel is useful |
| 96 | |
| 97 | Citadel is most useful when coding-agent work extends beyond a single prompt: |
| 98 | |
| 99 | | You are dealing with... | Citadel adds... | |
| 100 | |---|---| |
| 101 | | Repeated setup and lost context | Repo-local campaigns, decisions, discoveries, and handoffs | |
| 102 | | Unclear workflow choice | One natural-language entry point through `/do` | |
| 103 | | Risky or multi-step changes | Approval boundaries, lifecycle hooks, and explicit verification | |
| 104 | | Several agents or branches | Isolated worktrees, ownership, and shared discoveries | |
| 105 | | Work that must survive interruption | Durable state, recovery, and a concrete next action | |
| 106 | |
| 107 | For a short, one-off edit, your coding agent may already |
People who liked this also viewed
6 picksType
- fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!MCP ServersNov 2025
- lean-lsp-mcpLean Theorem Prover MCPMCP ServersJul 2026
- rulesyncA Utility CLI for AI Coding AgentsMCP ServersJul 2026
- FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.MCP ServersJul 2026
- repomix📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.MCP ServersJul 2026
- mcp-serverMCP server for AI-assisted development of CAP applicationsMCP ServersJul 2026
