consistorium

# Consistorium [](https://github.com/Renaissance-AI-Solutions/consistorium/actions/workflows/ci.yml) [](LICENSE) <p align="center"> <img src="assets/ConsistoriumGraphic.png" alt="Consistorium — the command layer for agent coordination" width="100%"> </p> > **Your strategist AI can't see your codebase. Fix that.** Consistorium is a local-first MCP server that gives any conversational model — ChatGPT included — grounded, current intelligence about the repositories your coding agents are actually working in: live git state, allowlisted documents, durable tasks, and agent-to-agent handoffs. **Use your best reasoning model as the general. Save coding agents for code.** Coding-agent time is scarce — metered in five-hour windows, weekly caps, and credit packs — yet much of it is spent re-discovering what already exists: repo structure, branch state, decisions made yesterday. Consistorium reverses the flow: your conversational strategist reads live project state on demand, decides what should happen next, and hands coding agents work so precise they never have to explore. No more pasting `git log` output into chat. No more stale summaries. Your coding agents do the work; Consistorium lets your best reasoning model see it.  ## The problem Multi-model development has a structural gap: - **Coding agents** (Claude Code, Codex, Cursor, Hermes) hold the repository. - **Strategic reasoning** often happens elsewhere — a long-running ChatGPT conversation that knows your goals but not your code. - Today the only bridge is copy-paste: git output, file excerpts, hand-written status reports — all stale the moment they're pasted. Consistorium closes the gap in the other direction: instead of dragging your strategist into the terminal, it exposes **bounded, read-only project intelligence** to any MCP client — with every claim labeled as either `live_observation` (git facts read right now) or `agent_record` (what a previous agent claimed when it left). Generated memory never masquerades as ground truth. ## 30-second quickstart > Requires Node.js 20+ and `git` on `PATH`. ```bash npm install -g consistorium # Allowlist a project (this is the only thing the server can ever inspect) consistorium init --path ~/dev/my-project --name my-project --yes consistorium doctor # verifies config + smokes a live briefing ``` `init` prints a ready-to-paste `mcpServers` snippet (with your absolute config path) and the one-line `claude mcp add` equivalent — copy whichever matches your client, restart it, done. If npm returns `E404` before the first registry release, use the source-install fallback in [docs/install.md](docs/install.md). Do not confuse `npm install` inside a checkout (dependencies only) with `npm install -g .` (installs the CLI). Point any stdio MCP client at it: ```json { "mcpServers": { "consistorium": { "command": "consistorium", "args": ["serve"], "env": { "CONSISTORIUM_CONFIG": "~/.config/consistorium/config.yaml" } } } } ``` Works with Claude Desktop, Claude Code, Codex, Cursor, Windsurf, Hermes, and any other MCP-compatible client. For **ChatGPT** (which connects over the network rather than stdio), see [docs/chatgpt-setup.md](docs/chatgpt-setup.md). Full walkthrough for every client, troubleshooting, and uninstall: **[docs/install.md](docs/install.md)**. Want an agent to do it? Give a coding agent the appropriate copy-paste handoff in **[docs/agent-install.md](docs/agent-install.md)** — or the one-liner above. It installs, preserves existing configuration, registers the MCP server, and must prove success with a real tool call. For ChatGPT, the only unavoidable human actions are approving the restricted OpenAI runtime key, copying it to the local clipboard, and—when browser policy requires it—pressing **Send** on the staged verification prompt. Then ask your client: > *What changed in my-project today, what remains before release, and what should I ask my coding agent to do next?* A grounded answer comes back citing live branch state and allowlisted docs — separating observed facts from anything an agent recorded. If the model answers without calling a tool, it's guessing. ## One-prompt setup for AI agents Don't want to touch a terminal? Paste this short handoff into a coding agent with terminal access: ```text Open https://github.com/Renaissance-AI-Solutions/consistorium/blob/main/docs/agent-install.md. Use Prompt A to install Consistorium for this repository and your own MCP client. Perform the steps instead of returning a tutorial, preserve existing configuration, and do not claim success until context_list_projects and context_project_briefing work through the client. ``` For ChatGPT as the planning agent, use **Prompt B** in [docs/agent-install.md](docs/agent-install.md). If an existing Project Context card is visible but not callable, use **Prompt C** before deleting anything or rotating a key. ## What it does | Tool | Use when | |---|---| | `context_project_briefing` | **The hero call** — live git + docs + open tasks + latest handoffs + blockers + next actions, provenance-labeled | | `context_project_snapshot` | Live repo/worktree/session detail | | `context_list_worktrees` / `context_worktree_snapshot` | Parallel worktrees and multi-agent activity | | `context_recent_changes` / `context_compare` | History and branch divergence | | `context_search` | Bounded text search across allowlisted roots; optional `excludeGlobs` and `includeIgnored` narrow or widen the file filter without relaxing secret exclusions | | `context_read_context_document` | Read only explicitly allowlisted documents | | `context_task_*` / `context_handoff_*` | Durable task records and structured agent handoffs | The continuity model: an execution agent calls `context_task_upsert` when it starts work and `context_handoff_create` when it leaves — objective, decisions, evidence, blockers, canonical-vs-asserted git state, and a requested next action. A **fresh** agent with no conversation history calls `context_project_briefing` and continues without the human reconstructing anything. ## Why not just give the model repo access? Claude Code and Codex already *have* the repository — that's not the gap. The gap is the model that *doesn't*: your strategist, reviewer, or planner sitting outside the harness. Cloning the repo into a chat session copies megabytes of context you don't control and can't bound. Consistorium is the deliberate, read-only, allowlisted pipe for exactly the intelligence a strategist needs — nothing more. And unlike "give ChatGPT your terminal" bridges, Consistorium executes no commands, mutates nothing, and cannot widen its own access. See the [security model](#security-model). ## Security model Private repository text must never become a public endpoint. - **Explicit allowlist** — only configured project roots are ever inspected (`realpath`-canonicalized; traversal and symlink escapes denied) - **Secret denylist** — `.env`, keys, `.ssh/`, `.aws/`, credential-named files are refused even if globs would match - **Read-only git** — hardened `execFile` invocations only; no shell, no checkout/commit/push, ever - **Bounded outputs** — capped reads, diffs, search results, and record sizes; truncation is flagged, never silent - **Loopback-only HTTP by default** — Streamable HTTP binds `127.0.0.1`, requires a bearer token, refuses anonymous non-loopback binds, and hides write tools unless explicitly enabled - **Provenance labels** — `live_observation` vs `agent_record`, so agent claims can be checked against git reality - **No telemetry** — nothing leaves your machine except what your own MCP client sends Full details: [THREAT_MODEL.md](THREAT_MODEL.md) · [SECURITY.md](SECURITY.md) ## Connecting clients ### Claude Desktop / Claude Code / Cursor / Codex / Windsurf Use the JSON snippet above. After editing, restart the client. ### Hermes ```bash hermes mcp add consistorium \ --command consistorium \ --args serve \ --env CONSISTORIUM_CONFIG=$HOME/.config/consistorium/config.yaml ``` ### ChatGPT ChatGPT connects through OpenAI's Secure MCP Tunnel. The recommended setup lets the tunnel client launch Consistorium over stdio, leaving only one long-lived runtime to supervise. The complete walkthrough — tunnel installation, runtime key scoping, developer-mode connector setup, and troubleshooting — lives in [docs/chatgpt-setup.md](docs/chatgpt-setup.md). Short version: ```bash tunnel-client runtimes connect \ --alias consistorium \ --tunnel-id tunnel_YOUR_ID \ --runtime-api-key file:/ABSOLUTE/PATH/TO/runtime-key \ --mcp-command "consistorium serve --read-only" ``` Never paste the runtime key into chat or command text. The tunnel ID identifies the connection; it is not the key. Secure MCP Tunnel is for a private developer-mode connection and must remain running for discovery and tool calls. It does not make Consistorium a public Plugin Directory listing; that would require a separate hosted HTTPS service and per-user authentication. ## Environment variables | Variable | Purpose | |---|---| | `CONSISTORIUM_CONFIG` | Config file path | | `CONSISTORIUM_STATE_DIR` | Task/handoff state directory (kept outside project roots by default) | | `CONSISTORIUM_TOKEN` | Bearer token for Streamable HTTP | | `CONSISTORIUM_HTTP_WRITES=1` | Allow task/handoff writes on HTTP (off by default) | Upgrading from v0.3 or earlier? The pre-0.4 `CONTEXT_BRIDGE_*` variable names and the `~/.config/context-bridge/`, `~/.local/state/context-bridge/`, and `./context-bridge.yaml` locations are still honored automatically — nothing breaks, and `consistorium init` writes to the new defaults from now on. Records are written `0600` under a `0700` state directory; filenames are hashes, IDs never become paths. ## Testing ```bash npm test # 125+ tests: security boundaries, transports, Agent A→B continuity e2e npm run typecheck consistorium doctor ``` Tests run against synthetic temporary repositories — no private checkouts required. ## The story Consistorium was built and battle-tested while operating [Corpus](https://corpuslaw.us) — an AI-native legal platform that compiles US law into a free public library and forms companies in all 50 states. Every strategic decision on Corpus runs through this exact loop: coding agents implement, Consistorium reconstructs project state, and a conversational strategist reasons over live engineering reality instead of pasted summaries. The tool exists because we needed it daily. ## Documentation - [docs/install.md](docs/install.md) — complete installation guide for every client - [docs/agent-install.md](docs/agent-install.md) — prompts that let an AI agent install and verify it - [docs/chatgpt-setup.md](docs/chatgpt-setup.md) — ChatGPT connection via Secure MCP Tunnel - [docs/release-checklist.md](docs/release-checklist.md) — launch gates and clean-machine tests - [DESIGN.md](DESIGN.md) — architecture and data flow - [THREAT_MODEL.md](THREAT_MODEL.md) — assets, adversaries, mitigations - [SECURITY.md](SECURITY.md) — reporting policy and safe usage - [ROADMAP.md](ROADMAP.md) — shipped vs designed vs explicitly not planned - [CONTRIBUTING.md](CONTRIBUTING.md) — ground rules and development setup - [CHANGELOG.md](CHANGELOG.md) ## License Apache-2.0 — see [LICENSE](LICENSE). --- ## Built in public Follow along: [@TritiumAISol](https://x.com/TritiumAISol) (founder — build-in-public receipts) · [@AnAIRenaissance](https://x.com/AnAIRenaissance) (announcements + demos) · [The AI Renaissance on YouTube](https://www.youtube.com/@TheAIRenaissance) <p align="center"> <img src="assets/ConsistoriumBanner.png" alt="Consistorium — the command layer for agent coordination" width="100%"> </p>