The Precedent handbook
Automatic reminders
Connect your assistant first. Optional reminders can then surface related decisions when you send a prompt, without blocking your work.
Start with the standard connection
The recommended installation includes MCP and the decision-librarian skill. It does not install hooks or capture transcripts. Use it to retrieve and cite a real decision before adding automation.
Enable reminders in a local project
After installing the native plugin and linking your project, ask your assistant:
Use Precedent’s enable-reminders skill to enable decision reminders in this project.
The skill checks your assistant’s native mcp_tool hook support, validates the project choices, and uses the exact name of the plugin’s connected MCP server. It preserves unrelated settings and checks for duplicate reminders. Review and trust the hook in your assistant, then start a fresh session.
This requires a supported Codex or Claude Code release and local project files. Chat-only assistants can use decision-librarian without local hooks. A disconnected server supplies no reminders and does not start a second login. See the Claude hook reference and Codex hook reference.
What is configured
Claude Code reads .claude/settings.json. Codex reads .codex/hooks.json. The skill adds one project-level UserPromptSubmit reminder calling get_agent_context with the submitted prompt and the validated .precedent.json object, and, on request, one SessionStart hook that calls get_project_brief. It does not edit account-wide hooks without a separate request.
Plugin server names differ from manual connection names. Claude Code normally uses plugin:precedent:precedent; the skill reads the actual connected name before configuring either assistant. Do not copy a bare precedent server name from an older manual installation.
The read-only tool returns a short payload using your existing permissions. Warnings come first: expired or expiring exceptions, superseded decisions and overdue reviews in the checked Areas or named in the prompt, each with its reason, link and what to do instead. These are recorded facts, never search matches. Related decisions follow as active decision refs, summaries and links. No separate token, executable hook script, or model key is needed. Blocking checks and transcript capture are omitted. A SessionStart hook is added only on request (see Session brief).
Session brief
Use Precedent’s enable-reminders skill to reload the project brief after a clear or a compaction in this project.
This optional hook calls get_project_brief with the project's .precedent.json and adds the brief of its decisions in force to your assistant's context. It sends no prompt text. The skill installs it only when you ask, in the same file as the reminder, and you can ask for it without a reminder.
Claude Code runs the hook after /clear and after a compaction, when the session has lost the brief. It never runs it at startup, because its MCP servers are not ready yet. Codex runs it at startup as well, but there it can run before the server is ready. When the hook has not run, the decision-librarian skill loads the brief on your first request.
The Claude Code entry in .claude/settings.json:
{
"matcher": "clear|compact",
"hooks": [
{
"type": "mcp_tool",
"server": "plugin:precedent:precedent",
"tool": "get_project_brief",
"input": {
"project": {
"version": 2,
"deployment": "https://app.example.com",
"workspaceId": "…",
"recordAreaId": "…",
"checkAreaIds": ["…"]
},
"format": "hook",
"maxChars": 8000
},
"timeout": 10
}
]
}The Codex entry in .codex/hooks.json also runs at startup and asks for less text:
{
"matcher": "startup|clear|compact",
"hooks": [
{
"type": "mcp_tool",
"server": "EXACT_CONNECTED_SERVER_NAME",
"tool": "get_project_brief",
"input": {
"project": {
"version": 2,
"deployment": "https://app.example.com",
"workspaceId": "…",
"recordAreaId": "…",
"checkAreaIds": ["…"]
},
"format": "hook",
"maxChars": 6000
},
"timeout": 10
}
]
}In Codex the skill reads the server's name from your configuration. Claude Code accepts up to 10,000 characters of added context and Codex about 2,500 tokens by default, so the entries stay under each limit.
Cursor and GitHub Copilot cannot run this hook, because their hooks cannot call an MCP tool.
Disable or remove reminders
Ask the enable-reminders skill to remove this project’s Precedent reminder, its session brief hook, or both, or disable them in your assistant’s hook settings. Remove them before uninstalling the plugin. Unrelated hooks and settings must be preserved.
Existing Python-managed direct installations can continue using --preset reminders and remove their managed hook with --uninstall, using the original client, scope and area options. Do not run both that reminder and a plugin reminder.
Project checking and recording context
When you link a project, the skill updates an existing project reminder to pass the same .precedent.json values to get_agent_context. It updates the session brief hook's project values in the same way. Reminders search the project's checking Areas (checkAreaIds, up to three), deduplicating shared guidance. The recording Area is searched only when it is one of them. Linking does not enable reminders or change account-wide hooks. If your assistant cannot update the project hook, it should say so; an unchanged account reminder still uses its connection context.
Moving from the older shell hooks
Older installations wrote scripts and a separate OAuth connection under ~/.precedent. The plugin does not reuse that connection or automatically delete those files. Remove the old Precedent hook entries from your project and user settings before enabling native reminders, so both do not run.
Once no assistants use those scripts, revoke the precedent-hooks connection under Settings → Assistants. Keep any unrelated files and configuration. The older push and Stop scripts block on a related search result, even when a decision has already been cited; they do not verify compliance.
Older transcript capture invokes Claude separately and files drafts using its own connection. It is not part of the standard setup or native reminders. Keep it only if you intentionally want that behaviour.
When you need a merge policy
Hooks execute at deterministic points, but relevance search is not a policy verdict. If a team needs an acknowledgement before merging, define what evidence is required and enforce that through its review process. See validating assistant work and the CI example.