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.

Self-hosted or cloud?

Self-hosted (this page) Cloud
Setup npx precedent-cli init a 6-line GitHub Action + one secret
Engine vendored into your repo (.precedent/engine) hosted — nothing in your repo
Model key you bring OPENROUTER_API_KEY ours — no key in your repo
Store local .precedent/ (optional sync to cloud) the shared team registry
Best for OSS / air-gapped / full control teams who want zero infra

The self-hosted quickstart is below. For cloud, add the precedent-gate Action with your team token (from the Teams tab) — no engine, no model key:

# .github/workflows/precedent.yml
on: pull_request
permissions: { contents: read, pull-requests: write }
jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: bbiangul/precedent-gate@v1
        with: { team-token: ${{ secrets.PRECEDENT_TEAM_TOKEN }} }

1. Install into any repo (self-hosted)

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