← Docs

Precedent for AI agents

You (an AI coding agent) can install and operate Precedent yourself. This page is written for you.

The loop

Retrieve before you choose. Govern before you merge. Record after you choose. Every time.

  1. Before a non-trivial choice — a library, a data store, an error/retry pattern, touching payments/checkout/auth, adding an endpoint, a migration, or reusing-vs-rebuilding a capability — retrieve the applicable decisions:

    python3 src/precedent.py retrieve "<what you're deciding + files involved>"

    Follow anything at guardrail authority (it overrides your judgment). If it says the action is irreversible or a human must decide, stop and ask.

  2. Before you merge/deploy — get the verdict on the concrete change. Pass the real diff, not just a title (a title can't reveal whether your new endpoint applies mandated audit logging):

    python3 src/govern_cli.py --paths <files> --title "<what + why>" --diff <patch-file-or-->

    act_silently / act_and_flag → proceed. require_review / escalate / deny → stop, a human decides. In-session, call the MCP govern tool instead.

  3. After you decide — record it, so the next agent inherits it instead of re-deciding. This is the step agents skip; don't:

    python3 src/precedent.py record "situation: <...>; decided <X>; because <why>; scope <paths>"

    Always record when you set a new pattern, pick a canonical source of truth ("consume the onboarding output, don't re-parse"), or ban/standardize an approach. Records enter as unconfirmed until a human promotes them — so record liberally.

Wire Precedent into a repo (copy-paste)

To set Precedent up in the repository you're working in, run one command from the repo root:

# from the repo root
npx precedent-cli init

init vendors the engine into .precedent/engine/, creates .precedent/ (an empty decision store + the risk policy + the autonomy matrix), and wires every harness without overwriting your existing rules — appending a marked block to AGENTS.md / CLAUDE.md / GEMINI.md / .github/copilot-instructions.md, writing .cursor/rules / .windsurf/rules / the Claude Code skill, merging the precedent MCP server into .mcp.json / .cursor/mcp.json, and adding the .github/workflows/precedent-gate.yml CI gate. Then seed the store from the repo's existing decisions:

python3 .precedent/engine/extract/extract_decisions.py .        # from ADRs/RFCs/convention docs
python3 .precedent/engine/extract/mine_enforcements.py          # from PR review history (needs `gh`)

Wire the CI gate — you (the agent) do this, autonomously

init already writes .github/workflows/precedent-gate.yml. To finish wiring it on GitHub, run — you can do this yourself with the gh CLI:

npx precedent-cli init --github

This detects the repo and enforces the govern status check on the default branch (a failing gate then blocks merge). It deliberately leaves the human exactly one step — sharing the model key as a repo secret, which you must not handle yourself:

gh secret set OPENROUTER_API_KEY        # the human pastes the key; https://openrouter.ai/keys

That is the whole division of labor: the agent wires everything; the human shares one secret. (Branch protection on private repos needs a paid plan; if it can't be set automatically, --github prints the exact gh api command to run.)

MCP setup

.mcp.json registers the server for Claude Code (project scope). For other harnesses:

Tools exposed: retrieve_precedent, govern, record_precedent.

Rules of thumb