Skip to content

Connect your AI assistant

Your coding assistant (Claude Code, Cursor, or any other that speaks MCP) can ask CORE about your project instead of guessing, check its own change before it commits, and submit it to CORE as a proposal that only you can approve. CORE answers from your project's law and decision history, with sources, and says plainly what it did not check.

The server runs locally, started by the assistant itself. The read tools need no database, no API and no other service: pip install core-runtime is enough. Submitting a change needs a running CORE (see Run the full runtime).

What the assistant gets

Tool Question it answers
law_rules Which rules are in force (optionally one pack or id prefix), how strict each is, and what checks it?
law_rule What does this rule say, how is it enforced, and where is it declared?
law_can_write May I write this path? What the law says, and what actually enforces it.
decision_adr What did this architecture decision record (ADR) decide?
decision_adrs Which ADRs exist (optionally only the accepted ones)?
change_verdict Does my current change break a blocking rule?
validate_change Does my patch pass CORE's full checks? (starts a check run; a few minutes)
submit_change If it passed, record it as a pending proposal for the governor.

Six tools only read. Two, validate_change and submit_change, ask CORE to check a change and to record it as a pending proposal. None can approve, waive, or act as the governor.

Which path a change takes: with a plain pip install (no running CORE), the assistant calls change_verdict and commits only if it is not BLOCKED; the full audit then runs on the pull request through CORE's GitHub Action (core-admin project init sets it up). Only a project that runs CORE (its API) uses validate_change and submit_change, which turn the change into a proposal you approve instead of a direct commit.

The same answers are available from the shell, which is the quickest way to see what the assistant will see:

core-admin law list
core-admin law show governance.constitution.read_only
core-admin law check .intent/rules/example.json
core-admin decisions list --status accepted
core-admin code verify

What you need

Claude Code

From your project's root:

claude mcp add --scope project core -- core-admin mcp run

This writes a .mcp.json file at the project root; commit it, so everyone who works on the repository gets the same setup. Its content is equivalent to this (your Claude Code version may lay it out differently, for example with "env": {} added):

{
  "mcpServers": {
    "core": {
      "type": "stdio",
      "command": "core-admin",
      "args": ["mcp", "run"]
    }
  }
}

The next time you start claude in the project, it asks once whether to trust the core server. That approval is yours to give; claude mcp list shows the server as pending until you do. To use it only yourself, leave out --scope project: Claude Code then keeps the entry in your own settings.

Non-interactive runs (claude -p, scripts, CI) cannot answer a permission prompt, so each core tool is refused until you allow it. Put the prompt directly after -p and the list after it:

claude -p "Run change_verdict on my current change before I commit." \
  --allowedTools "mcp__core__law_rules,mcp__core__law_rule,mcp__core__law_can_write,mcp__core__decision_adr,mcp__core__decision_adrs,mcp__core__change_verdict"

This list leaves out validate_change and submit_change, so a non-interactive run cannot submit a change unless you add them.

Other assistants

Any MCP client can start the server over stdio. Configure:

  • command: core-admin
  • arguments: mcp run --repo /path/to/your/project

--repo names the project to serve. Without it, the server serves the project around its working directory, which is enough for assistants that start it in the project root.

Propose a change

With a running CORE, the assistant can submit a change in two steps: validate_change runs CORE's full checks on the patch (a few minutes); submit_change then records it as a pending proposal, naming who produced it and why (an issue, an ADR or your request). Nothing lands until you run core proposals approve <id> from your own account, over CORE's Unix socket (CORE_API_URL=unix:///run/core/api/api.sock), and type the short id at a terminal. The assistant's account is refused (403). The commit names the assistant as author and CORE as committer.

What the answers mean

  • Sources and limits. Every law and decision answer names the files it came from and states what it does not establish. A rule or ADR that does not exist is answered as unknown, never guessed.
  • The verdict is feedback, not a pass. change_verdict judges the changed files against the per-file rules and answers BLOCKED, CLEAR_IN_SCOPE, NO_CHANGES or NOT_EVALUATED (nothing could be judged, for example a project with no rules yet). It lists every rule it did not evaluate, such as whole-repository checks. It never says PASS: only the full audit (core-admin code audit, in your commit hook or CI) does.
  • Detected, not prevented. CORE does not stop an assistant from editing files directly. law_can_write says so for protected paths: CORE refuses such writes on its own write path and detects them in every audit, and a protected branch with required checks keeps them from landing.