Before an agent changes your code, Rationale hands it the rules, decisions and relationships that govern that code. After the change, what stays true is written back to your repository automatically, and the rules you pin stay out of any agent's reach.
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Ragosorio/Rationale/releases/latest/download/rationale-installer.sh | sh
It works in Monday’s conversation. On Thursday a fresh agent sees only the code, removes the guard and calls it a cleanup.
“Never retry a payment that already reached the bank.”
Rationale keeps the rule next to the code it governs and hands it to every agent before that code is touched.
There is no approval queue. Agents capture what they learn; you keep authority over what must not move.
Find the symbol, its callers and the files around it.
prepare_changeGoverning rules, explained relationships, the structural neighborhood and the target’s code, within a token ceiling.
The smallest change consistent with that context.
finalize_changeDurable knowledge becomes canonical Records in the same call. Noise and duplicates are discarded with a reason.
rationale pinFix the rules no agent may replace. Any attempt becomes a conflict only you resolve.
Install once per machine, initialize once per repository, then keep working the way you already do. Updating or uninstalling never touches .rationale/.
1Install Codebase Memory (recommended)
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
2Install Rationale on macOS or Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Ragosorio/Rationale/releases/latest/download/rationale-installer.sh | sh
The installer verifies checksums, uses the stable channel and registers the MCP server for the agents it finds.
3Initialize your repository
rationale init
Creates the canon in .rationale/ and writes the protocol into CLAUDE.md, AGENTS.md or the Cursor rule.
4Restart your agent and check the connection
In Claude Code run /rationale-health. In Codex ask “Check Rationale health.”
5Ask for a real change
“Make payment retries stop after three attempts.”
You don’t have to mention Rationale. The agent prepares the change, makes it, and captures what stays true.
6Watch it live, and pin what must not move
rationale ui
rationale pin <record-id>
The protocol in CLAUDE.md and AGENTS.md tells an agent to prepare and capture. The rationale skill shows it how. A short router loads only the playbook for the operation at hand, so the depth costs nothing until a task needs it.
/rationale capture or $rationale explain <target> call it by name.finalize_change.| Operation | When the agent uses it |
|---|---|
preflight | Before it changes, moves or deletes non-trivial code |
explain | When code looks redundant or odd, or you ask why it exists |
capture | When a change is done and tested |
conflicts | When a candidate collides with a pinned rule |
health | When tools are missing or results look degraded |
adopt | When setting Rationale up and seeding the first Records |
maintain | When bindings go stale or rationale doctor reports findings |
For any other agent that reads skills
npx skills add Ragosorio/Rationale
rationale init and install-agent already install it for Claude Code and Codex.
A bounded packet compiled for one target and one intent. Governing knowledge is never truncated, and the budget is a ceiling, not a goal.
{ "operation_id": "op_7f3c…", "critical_constraints": [{ "id": "constraint.payments-idempotent", "authority": "pinned", "provenance": "human_stated" }], "decisions": [{ "id": "decision.charge-after-reservation", "authority": "normal", "provenance": "agent_asserted" }], "relationships": [ { "edge": "charge → bank_client", "state": "observed" }, { "edge": "retry_worker → charge", "state": "indirect" } ], "structure": { "nodes": "12 / 52", "edges": "11 / 51" }, "estimated_tokens": 1707, // ≤ 2400 "known_unknowns": ["refunds → charge: orphaned"] }
Each panel shows a call and an abridged response. Switch panels with the arrow keys; where a panel has steps, step through them.
Simulated example. An invented shipping project from Rationale's evaluation, run with the development binary. No customer data, and no numbers here are customer results.
On Monday an agent learned that a cancellation must wait for the carrier and captured it. On Thursday a fresh session is asked to cancel locally when the carrier is down.
It receives Monday’s decision with its reason, bound to the exact function, and owes a verdict before editing.
prepare_change(target="src/shipping/service.ts::cancelShipment", intent="Allow cancelling locally when the carrier API is down") { "retrieval": { "status": "found", "scope": "symbol" }, "decisions": [{ "id": "decision.cancel-requires-carrier-ack", "statement": "A shipment is cancelled only after the carrier acknowledges the cancellation.", "rationale": "Cancelling locally … left paid labels in transit with no record.", "provenance": "agent_asserted", "why": "bound to this symbol" }], "intent_conflicts": [{ "record_id": "decision.cancel-requires-carrier-ack", "detection": "governs-target" }], "governance_verdict_required": true }
The quote cache once kept prices for five minutes; a later decision cut it to sixty seconds.
The five-minute rule is history, with its replacement named. It is never served as current next to the rule that replaced it.
explain_target(target="src/shipping/rates.ts::quoteRate") { "governing_records": [{ "id": "decision.rate-cache-ttl-60s", "statement": "Carrier rate quotes are cached for 60 seconds per route and weight.", "replaces": ["decision.rate-cache-ttl-5m"] }], "history": [{ "id": "decision.rate-cache-ttl-5m", "status": "superseded", "replaced_by": "decision.rate-cache-ttl-60s" }] }
explain_target(target="src/shipping/rates.ts::quoteRate", include_history=true) { "history": [{ "id": "decision.rate-cache-ttl-5m", "status": "superseded", "statement": "Carrier rate quotes are cached for 5 minutes per route and weight.", "rationale": "Carrier APIs rate-limit quote calls; five minutes kept us under the limit at launch." }] }
After an incident, a person pinned “money is integer cents” on the shipping helper. Billing never bound it, but it calls that helper.
The pinned invariant arrives as an inherited constraint, with the observed call that brought it. Similarity never brings one.
prepare_change(target="src/billing/invoice.ts::issueInvoice", intent="Sum invoice lines as floats and round once at the end") { "decisions": [{ "id": "decision.invoice-rounding-bankers", "why": "bound to this symbol" }], "inherited_constraints": [{ "id": "constraint.money-in-integer-cents", "statement": "Monetary amounts are integers in cents from quote to invoice; never store, sum or compare floating-point currency.", "authority": "pinned", "provenance": "human_stated", "severity": "critical", "via": "issueInvoice calls toCents" }] }
A small budget leaves out the structure; the packet names what it left out and how to get it back.
Governing knowledge is never cut. What did not fit is listed, with the call that returns it.
prepare_change(target="src/shipping/service.ts::cancelShipment", max_tokens=800) { "decisions": [{ "id": "decision.cancel-requires-carrier-ack", … }], "omitted": [{ "section": "structure", "count": 1, "expand": "raise max_tokens" }], "budget": { "max_tokens": 800, "estimated_tokens": 754, "estimator": "upper-bound" } }
prepare_change(target="src/shipping/service.ts::cancelShipment", max_tokens=2400) { "decisions": [{ "id": "decision.cancel-requires-carrier-ack", … }], "structure": { "nodes": ["cancelShipment", …], "considered_nodes": 4 }, "relevant_code": { "file_path": "src/shipping/service.ts", "start_line": 10, … }, "budget": { "max_tokens": 2400, "estimated_tokens": 1037, "estimator": "upper-bound" } }
An agent prepares a change, explores, and decides not to make it.
The Claude Code Stop hook asks once; the agent closes the operation without memory and without claiming a change.
prepare_change(target="src/shipping/rates.ts::applySurcharge", intent="Make the remote surcharge a percentage") { "operation_id": "op_1a13b671…", "packet": { … } }
Stop hook → the agent tries to stop without closing it { "decision": "block", "reason": "Rationale: this session prepared 1 change(s) that are still open: op_1a13b671… If you did not change the code, call finalize_change(operation_id, abandon=true, summary=\"why\"). Do not finalize as done a change that did not happen." }
finalize_change(operation_id="op_1a13b671…", abandon=true, summary="Only explored; the surcharge stays flat.") { "state": "abandoned", "memory_written": false }
Ships in the release after v1.1.0. With v1.1.0 today, prepare and capture work as described in the loop above.What changes, and the evidence
rationale ui opens a local, read-only Control Room: the working subgraph in 3D, the memory that explains it, and every session’s activity as it streams.
Served on 127.0.0.1 only, GET requests only, embedded in the binary.Control Room docs
Every Record carries where it came from and how far it can move. The capture gate enforces that boundary.
provenancepinnedconflictsHuman-only commands: they require an interactive terminal and declared authority.
A Record can explain a relationship. On every call Rationale re-derives its state from the provider, and it never deletes the explanation.
| State | Edge | What it means |
|---|---|---|
observed | The direct relationship exists in the current index. | |
indirect | No longer direct, but a bounded path still connects both ends. | |
orphaned | It can’t be located. The explanation may be stale, so it is flagged and never deleted. | |
unknown | The provider couldn’t verify it. Absence is not proof. |
Agents reach the canon only through the capture gate, and the Control Room only reads. This is the binary’s real wiring, drawn from its own call graph.
The installer registers one MCP server per agent with its absolute path; install-agent writes the protocol into your project. Remove it all with uninstall-agent.
Claude Code
/rationale [operation]/rationale-preflight <target> <intent>/rationale-explain <target>/rationale-capture [statement]/rationale-conflicts/rationale-healthThe agent picks the skill on its own; the shortcuts are for you. /rationale-conflicts hands the decision to you.
Codex
<target> with intent <intent>.”<target> before changing it.”Codex reads the protocol from AGENTS.md, calls the MCP tools and loads the skill from .agents/skills/. $rationale calls it by name.
Cursor
Cursor gets .cursor/rules/rationale.mdc in the project and a user-scoped MCP server that works from the Dock.
.rationale/ is plain YAML, reviewed in the same pull request as the code.5 MCP tools · 6 MCP prompts · 1 skill with 7 operations · 3 supported agents · 5 platforms · no accounts, no telemetry
The full loop has been implemented, tested and used on Rationale’s own repository since 1.0, and 1.1 adds the rationale skill.