← Docs

Quickstart

Get Precedent governing an agent's work in about a minute. Precedent is a decision layer, not a notes app: every decision your agents make is recorded with its authority, retrieved before the next change, and enforced at the merge gate.

1. Install into any repo

One command wires Precedent into every agent you run — Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini, and any AGENTS.md-aware agent — without overwriting your existing rules:

cd /path/to/your-repo
npx precedent-cli init            # vendors the engine + AGENTS.md/CLAUDE.md/skill/MCP/CI gate
export OPENROUTER_API_KEY=...     # only the semantic steps need a key; the gate is deterministic

Requires Python 3.9+ on PATH (the engine is stdlib-only for the hot path — no pip deps). Prefer source? git clone https://github.com/bbiangul/precedent && cd precedent && python3 src/init.py /path/to/your-repo.

2. Retrieve before you decide

The agent asks Precedent before making a non-trivial choice:

npx precedent-cli retrieve "add a caching layer to the dashboard"

── Precedent decision packet ──
 • E2 [guardrail] Redux is banned for server-state caching; use React Query
     why: two teams built divergent cache-invalidation layers on Redux
 recommendation: follow the decisions above; guardrail-authority ones override your own judgment.

If nothing applies, it says so — that's a new decision to record.

3. Govern before you merge

Get an autonomy verdict for a concrete change. A guardrail conflict is blocked, not just flagged:

npx precedent-cli govern --paths web/store.ts --title "Add Redux for dashboard server-state caching"

⛔ BLOCK — denied: violates a guardrail (E2)

The same check runs in CI (the Precedent gate) on every PR.

4. Record after you decide

npx precedent-cli record \
  "situation: picking a styling approach; decided Tailwind for all styling; because no runtime cost + RSC-safe; scope web/**"

New decisions enter as unconfirmed — they're still retrieved and can govern, but a human makes them authoritative (policy/guardrail) by promoting them in the cloud console (the Decisions tab → Promote). This admission control means an agent can propose a rule but can't unilaterally grant it guardrail authority.

IDs like E2 and C-001 below are examples — use the id shown by retrieve/record in your store (fresh repos start at C-001; the seeded demo uses E-prefixed ids).

5. Retire what's wrong (lifecycle)

Decisions go stale. An agent can propose retiring one; a human confirms — you can't silently drop a guardrail:

npx precedent-cli deprecate E2 --reason "moved to React Query" --superseded-by E9   # proposes
npx precedent-cli confirm-deprecation E2                                            # human confirms

A retired decision stops being retrieved and stops being enforced.

Use the cloud (optional)

The engine stays in your repos; the cloud is the shared registry + natural-language console. An agent can self-serve:

# create a team (returns a team_token + an invite link for a human)
curl -X POST https://precedent-cloud.vercel.app/api/teams \
     -H "Authorization: Bearer <user_jwt>" -d '{"name":"Acme Platform"}'

# push a repo's decisions
python3 .precedent/engine/sync.py            # uses PRECEDENT_CLOUD_URL + PRECEDENT_TEAM_TOKEN

# ask in natural language, scoped to the team
curl -X POST https://precedent-cloud.vercel.app/api/ask \
     -H "Authorization: Bearer <user_jwt>" \
     -d '{"question":"which guardrails cover payments?","teamId":"...","locale":"en"}'

Next