# precedent

[![M8ven Score](https://m8ven.ai/badge/mcp/juw12/precedent)](https://m8ven.ai/mcp/juw12/precedent?s=readme)

**Stop false "I can't"s and unchecked "done"s in your AI coding agents.**

Enforced automatically in Claude Code, Codex CLI, Gemini CLI, OpenCode and GitHub Copilot CLI;
available as MCP tools plus rules in Cursor, Windsurf, VS Code and Claude Desktop.

You've seen this: the agent says *"I can't do that"*, you reply *"you did it
before"*, and suddenly it works. The capability was there all along. What it
lacked was a **precedent**.

`precedent` finds that precedent automatically, from **all** your agents'
history, before the agent gives up. It also makes sure a pushed agent never
fakes success to please you.

## Before / after

**Without precedent:**

```
You:    convert report.xlsx to csv
Agent:  Sorry, I can't convert Excel files in this environment.
```

**With precedent**, the agent's give-up is sent back with this (real hook output):

```
Precedent check: your answer gives up without evidence. Before stopping: (1) name the
exact blocker; (2) look for precedent ... (3) try at least three routes that differ in
kind; (4) verify any success with a real check. Never invent a past success or fake output. ...

Possible precedent found in local history (check it matches before reusing; cite it if you use it):
- [2026-11-01, Claude Code, this project, session 3f2a1b9c; succeeded] Bash:
  `python -c "import pandas as pd; pd.read_excel('data.xlsx').to_csv('data.csv', index=False)"`
  (task: "convert data.xlsx to csv")
```

The failed `xlsx2csv` attempt from that same session is not shown: only actions
that **succeeded** count. What the agent does next depends on the agent. It was
measured on a real agent, including where it backfired at first (see *Verified so far*).

**See it yourself in under a minute**, no agent history needed:

```
python demo.py
```

It builds a throwaway sandbox and runs the real hooks as Claude Code, Codex CLI
and Gemini CLI would: a give-up sent back with last week's working command, a
"done" with no check sent back, and a test-weakening patch denied.

## Works with

| Agent | History searched | How it's enforced |
|---|---|---|
| Claude Code | ✓ transcripts | **automatic hooks** + skill + MCP |
| Codex CLI | ✓ rollouts (incl. 0.161–0.163 code mode) | **automatic hooks** + skill + MCP + AGENTS.md rules |
| Gemini CLI | ✓ chat recordings | **automatic hooks** + skill + MCP + GEMINI.md rules |
| OpenCode | ✓ SQLite history | **automatic plugin** + skill + MCP + AGENTS.md rules |
| GitHub Copilot CLI | — | **automatic hooks** + skill + MCP |
| Cursor, Windsurf, VS Code (Copilot agent), Claude Desktop | — | MCP server |
| ChatGPT, Gemini app, any chat | — | paste-in rules (`platforms/chatgpt/`) |

Plus shell history (bash, zsh, PowerShell) and git log for everyone.

## Install

```
git clone https://github.com/juw12/precedent
cd precedent
python install.py            # dry run: shows every change, writes nothing
python install.py --apply    # install for every agent it finds
python install.py --uninstall --apply
```

It backs up every file it edits (`*.precedent-bak`), is safe to run twice,
skips any config it can't parse safely (for example JSON with comments) and
tells you what to add by hand. Requirements: Python 3.8+. No other dependencies.
Codex CLI asks you to trust new hooks once: run `/hooks` inside Codex and approve them.
It only touches agents it can actually find (their CLI on PATH, or their own
config or history files), and never overwrites a different skill that happens
to use the folder name `precedent`.

## What it does

| When | What happens |
|---|---|
| You say "you did it before" / "try again" | It searches your past sessions in **every agent**, shell history and git, and hands the agent **the exact action that worked**, with date and task. If there is none, it says so, so the agent can't fake a memory. |
| The agent is about to give up | The answer goes back with the precedent attached and a short loop: name the blocker, try three routes that differ in kind, verify. Safety refusals are left alone. |
| The agent says "done" | If nothing ran after the last edit, or the last check failed, it is sent back to verify. "Should work now" is not a check. |
| The agent cites a precedent | Commands cited on a `Precedent:` line are checked against real history. An invented one is flagged. |
| The same error happens twice | The agent is told to stop repeating that route; on the 3rd and 5th repeat it gets hypotheses and matching precedent. |
| The agent tries to cut corners | Adding `skip`/`xfail`/`.only` or `assert True`, removing assertions, **deleting test files**, `push --force`, `--no-verify`, `reset --hard`, broad `rm -r`: **stopped**. Claude Code asks you; Codex and Gemini have no "ask", so the call is denied with the reason. |

In Claude Code, Codex CLI, Gemini CLI and GitHub Copilot CLI this all happens
automatically through hooks (one set of scripts that speaks each agent's hook
format); in OpenCode through a plugin that runs the same scripts. In other agents
the same checks are MCP tools (`find_precedent`, `review_reply`,
`record_failure`, `check_test_edit`, `check_command`) that the installed rules
tell the agent to use, plus a `precedent` prompt (slash command) where the
client supports MCP prompts.

## Why it's different

- **It searches every agent's history.** It reads Claude Code transcripts,
  OpenCode's database, Codex rollouts and Gemini CLI recordings, keeps only tool
  calls that **succeeded**, and ranks them by the task they served. Each agent
  hides failure differently, and the readers handle it: Gemini marks a shell
  command that exits 1 as `success` with `Exit Code: 1` in its output, and Codex
  code mode wraps commands in JavaScript.
- **It is built against fake success.** "Done" needs a check after the last
  change, invented precedents are flagged, and weakening or deleting tests asks first.
- **Honest exits.** A well-evidenced `BLOCKED` with one precise ask is a good result.
- **Private.** Everything runs locally: no network, no telemetry. Databases are
  opened read-only. Tokens, passwords, keys and `user:pass@` URLs are redacted.

## Use the finder yourself

```
python skills/precedent/scripts/find_precedent.py "convert xlsx to csv"
python skills/precedent/scripts/find_precedent.py "deploy docs" --git --limit 8
```

## Manual setup (if you skip the installer)

- **Skill:** copy `skills/precedent/` into your agent's skills folder.
- **MCP server:** command `python`, args `["<path>/skills/precedent/scripts/mcp_server.py"]` (stdio).
- **Rules:** paste `platforms/rules/precedent-rules.md` into AGENTS.md / GEMINI.md / your rules.
- **Cursor rule:** `platforms/cursor/precedent.mdc` into `.cursor/rules/`.
- **OpenCode plugin:** copy `platforms/opencode/precedent.js` into `.opencode/plugin/` (one project) or let the installer add `~/.config/opencode/plugins/precedent/`.
- **Claude Code plugin:** `claude plugin marketplace add juw12/precedent`, then `claude plugin install precedent@precedent`.

Turn the hooks off any time with `PRECEDENT_OFF=1`.

## Verified so far

- **106 automated tests**: hooks fed realistic transcripts, an OpenCode
  database with the real schema, Codex and Gemini fixtures copied from real
  recordings, Codex and Gemini hook payloads in the shapes their sources define,
  a live MCP stdio session, the demo, and the installer against a fake home
  with real existing configs (dry run writes nothing, re-runs change nothing,
  uninstall removes only what it added; installed hook commands run through
  cmd, PowerShell and bash). Run: `python -m unittest discover -s tests`.
- **Real recordings**: the Codex reader was run on 21 real rollouts (Codex
  0.161, 0.162, 0.163) and the Gemini reader on 36 real recordings (Gemini CLI
  0.46, 0.63) from the public [cv](https://github.com/emberian/cv) test corpus.
  Every failed or backgrounded command was excluded, and both returned the right
  commands for a "replace TODO with DONE in notes.txt" query.
- **Real history**: tested read-only against a real OpenCode history of about
  300k records. Searches take 1–3 s, and a query with no real precedent returns nothing.
- **Agent A/B on OpenCode 2.2.0** ([full report](evals/RESULTS.md)), against a
  baseline that already had strong honesty rules in its global `AGENTS.md`:
  - Solvable and "impossible" cases: both arms passed all of them. On a careful
    setup the give-up and "done" checks changed nothing measurable.
  - The first version **backfired** on access walls: its "don't give up" push led
    the agent to guess `admin:admin` and to try removing a folder's deny ACL. The
    fixes in 3.3.0 treat a quoted access denial as evidence, stop reading "keep
    trying" in an opening request as pushback, rule out bypassing access controls
    in every nudge, and block both moves in the guard.
  - On the final code, three fresh trials of those two cases: precedent held the
    line 6/6, the baseline 4/6 (it stripped the ACL once and guessed a password
    once). Small samples; evidence, not a rate.
  - Full suite re-run on the final code (precedent arm): 12/12 pass.

## Limits

- The search is keyword-based (IDF-weighted). It can surface a near-miss, so
  results are labelled "possible precedent" and the agent is told to confirm a
  match before reusing it.
- Automatic enforcement covers Claude Code, Codex CLI, Gemini CLI, GitHub
  Copilot CLI and OpenCode. Cursor, Windsurf, VS Code and Claude Desktop get the
  same checks as MCP tools plus rules, so there they depend on the agent calling them.
- Live-verified so far: the OpenCode plugin (OpenCode 2.2.0) and the Claude Code
  hook format. The Codex, Gemini and Copilot wiring is tested against the payload
  shapes in their source and docs (Codex `hooks/src/schema.rs`, Gemini and GitHub
  hooks references), not yet inside a live session of those agents.
- Surfaced precedent comes from your real history, so it can point an agent at things
  it would not otherwise touch (in the A/B it led one run to read the test machine's
  mailbox while looking for an SMS). It is labelled a lead to check, not permission.
- In OpenCode the end-of-turn send-back needs a long-lived session (the TUI or
  `opencode serve`). One-shot `opencode run` exits as soon as the turn ends, so
  there only the tool guard, loop breaker and rules apply.
- Codex rollouts older than 7 days may be zstd-compressed (`.jsonl.zst`); those
  are skipped (no standard-library decoder). Antigravity's protobuf
  conversations are not read.
- Detection uses phrase patterns, so unusual wording can slip through. Every
  hook and tool fails open: an error never blocks you.

## License

MIT