▸ BICAMERAL
  ┌───────────────────────────────────────────────┐
  │  what your team decided  ↔  what the AI built │
  └───────────────────────────────────────────────┘

Bicameral MCP

Bicameral eliminates redundant rework in the software development lifecycle (SDLC) by building the compliance layer between product decisions and code output.

Bicameral is a local-first MCP server that ingests your meeting transcripts, PRDs, and Slack threads, maps every decision to the code that implements it, and automatically surfaces alignment gaps — before they become bugs.

Compliance posture

bicameral-mcp's compliance stance is documented in six policy files:

• docs/policies/host-trust-model.md — MCP host UX dependency declaration (closes OWASP LLM-07 / MCP-01 gap)
• docs/policies/acceptable-use.md — intended purpose + prohibited uses (NIST AI RMF MAP-3.1 + EU AI Act Annex III)
• docs/policies/install-trust-model.md — install + update supply-chain trust model (closes OWASP-03 + OWASP-05)
• docs/policies/audit-log.md — structured audit-log emission for self-hosted operators (closes SOC2-06 + OWASP-06 fold)
• docs/policies/diagnose-output.md — bicameral-mcp diagnose output allowlist + privacy posture (#252 Layer 3)
• docs/sla.md — availability stance (operator-run-only; no hosted SLA)

The full compliance audit is at docs/research-brief-compliance-audit-2026-05-06.md. Per-release change-control evidence procedure: docs/RELEASE_EVIDENCE_PROCEDURE.md.

The Problem

Engineering teams make hundreds of product decisions per week. A tiny fraction end up in tickets. None are linked to the code that implements them.

When you build with an AI coding assistant, this disconnect accelerates:

• The agent has no memory of the sprint planning where you decided on the rate limit
• It implements checkout without knowing the compliance rule from last week's Slack thread
• By the time someone notices, the gap has compounded across three PRs

Bicameral solves spec-alignment friction. It acts as a persistent, auditable memory layer between your product decisions and your codebase — so your AI agent always has the right context before writing a line of code.

  meeting transcript       PRD / Slack thread       inline answer
         │                        │                       │
         └────────────────────────┼───────────────────────┘
                                  ▼
                          bicameral.ingest
                                  │
                    ┌─────────────▼──────────────┐
                    │       Decision Ledger        │
                    │   what was said  ↔  code    │
                    │  status:  reflected | drifted │
                    │           pending | ungrounded│
                    │  signoff: proposed | ratified │
                    └─────────────────────────────┘
                                  │
              ┌───────────────────┼───────────────────┐
              ▼                   ▼                   ▼
       preflight fires      dashboard shows      drift detected
     before you code        full picture        at review time

How It Feels

Before implementing a feature, your agent runs bicameral.preflight and surfaces:

(bicameral surfaced — checking Stripe webhook context)

📌 3 prior decisions in scope:
  ✓ Idempotency via Redis SETNX with 24h TTL
    src/middleware/idempotency.ts:checkIdempotencyKey:42-67
    Source: Sprint 14 planning · Ian, 2026-03-12

  ⚠ DRIFTED: Trust Stripe event.created, not server time
    src/handlers/webhook.ts:processEvent:80-92
    Drift evidence: switched to Date.now() in PR #287

~ 1 AI-surfaced question (no human source yet):
  • Should we deduplicate by event.id or (account_id, event.id)?
    Source: Slack #payments 2026-03-20

At any time, the dashboard gives you the full picture:

Quickstart

The fastest path is uv. If you don't have uv yet, the official installer is one line:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then:

uv tool install bicameral-mcp
bicameral-mcp setup

Prefer pipx? That works too:

pipx install bicameral-mcp
bicameral-mcp setup

The setup wizard detects your repo, installs the MCP server config into Claude Code, adds a git hook that automatically syncs the ledger after every commit, and adds a session-end hook that captures any design decisions you stated mid-session but didn't explicitly ingest. Restart Claude Code and you're done.

Verify it works:

bicameral-mcp --smoke-test

Don't have pipx?

macOS

brew install pipx
pipx ensurepath

Linux

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Windows

python -m pip install --user pipx
python -m pipx ensurepath

Then restart your terminal and re-run the install command above.

Core Concepts

Two Orthogonal Axes

Every decision carries two independent signals:

Status — what the codebase says (derived at query time, never stored):

Signoff — what humans decided (stored explicitly):

The two axes are independent. The most important combination to watch for is proposed × reflected: the code already implements this decision cleanly, but a human hasn't signed off yet. That's the hero case for the dashboard — the PM sees it, ratifies, and drift tracking activates.

Status is immune to rebase, squash, and cherry-pick because it's derived fresh at query time from content hashes, not stored as a flag.

When Does link_commit Run?

link_commit syncs a commit's changes into the ledger — it recomputes content hashes and re-evaluates drift for every bound decision.

It fires automatically in three ways:

1. After every bicameral.ingest — auto-chained by the server
2. After git commits/merges/pulls — via the PostToolUse hook installed by setup
3. Before every bicameral.preflight — lazy catch-up if HEAD has advanced since the last sync

If you commit outside of Claude Code (e.g., from a terminal), the next preflight call will sync the ledger before surfacing context.

Collaboration Modes

In team mode, a PM ingests a PRD; when a dev pulls, preflight surfaces those decisions as coding context and the dashboard shows what still needs implementation.

.bicameral/
├── events/                ← committed to git (shared decisions)
│   ├── [email protected]    ← PM's ingested PRDs and transcripts
│   └── [email protected]   ← developer's commit syncs
├── config.yaml            ← committed (mode, guided flag)
└── local/                 ← gitignored (materialized state, DB)

What setup Installs

Running bicameral-mcp setup writes these files to your repo:

Removing Bicameral

To fully uninstall from a repo:

# 1. Remove the MCP server
claude mcp remove bicameral --scope project

# 2. Remove data and config
rm -rf .bicameral/

# 3. Remove skills
rm -rf .claude/skills/bicameral-*/

# 4. Remove the git hook (if installed)
#    Open .claude/settings.json and delete the PostToolUse entry
#    with "bicameral" in the command field.

# 5. Remove the .gitignore entry
#    Delete the "# Bicameral MCP" block from .gitignore.

Slash Commands

After setup, Claude Code gets these slash commands:

The agent also fires these automatically — preflight before any code change, ingest when you paste a document.

MCP Tools Reference

Decision Ledger

Code Locator

The server exposes deterministic primitives only. Callers use their own
tools (Grep/Read/Glob) for code search and pass resolved file paths /
symbol names back to the server.

Configuration

All data stays local. The embedded SurrealDB instance runs in-process — no separate server.

Local Development

git clone https://github.com/BicameralAI/bicameral-mcp.git
cd bicameral-mcp
pip install -e "pilot/mcp[test]"
cd pilot/mcp && pytest tests/ -v

Tests use real adapters with SURREAL_URL=memory:// — no external services required. CI runs on PRs to main via GitHub Actions.

Telemetry

Bicameral collects anonymous usage statistics to improve reliability and prioritize development. No code, decision content, file paths, or personally identifiable information is ever collected.

What is collected:

• Tool name (e.g. bicameral.ingest)
• Server version
• Call duration (milliseconds)
• Error flag (boolean)
• Aggregate counts (e.g. number of decisions grounded per ingest call — integers only)

What is never collected: decision descriptions, transcript content, search queries, file paths, repo names, or any user-supplied text.

Opt out at any time:

export BICAMERAL_TELEMETRY=0

or add BICAMERAL_TELEMETRY=0 to the env block in your .mcp.json.

Collaborator access

Telemetry data is stored in a private PostHog project. If you are a design partner, contributor, or researcher who needs access to the usage dashboard, reach out directly at [email protected].

Contributing

Contributions welcome. Please open an issue before submitting large changes.

License

MIT