Decision context for coding agents / local-first

Stop repeating your business rules to the AI.

Rationale saves the decisions behind your code so a new conversation can retrieve them before it changes anything important.

Install Rationale Quick start

Git + Codebase Memory · No account · Human-approved

Live change / synthetic demonstrationrevision 2f6d1e4

prepare_change

Constraints, risks, evidence and authority before the edit.

READY

Change

The agent changes code with the why still visible.

OBSERVED

finalize_change

Observed facts are captured. No decision is approved here.

WAITING

Human approval

A person approves, corrects, disputes, revokes or supersedes.

HUMAN

The packet travels with the change. The approval boundary stays visible.

The failure mode

You explained the rule. The next chat never heard it.

“Do not send while the upload is still running.”

It works in Monday’s conversation. Three days later, a fresh agent sees only the code, removes the guard, and confidently calls the change an improvement.

Rationale keeps the rule next to the code it governs.

Three systems / one clearer boundary

Structure tells you where. Git tells you what. Rationale protects why.

Install Codebase Memory first for structural coverage. Rationale is optional, local, and honest when that provider is unavailable.

01 / GIT

Git

What changed, when, and in which revision?

02 / STRUCTURE

Codebase Memory ↗

Where is it, and how is it connected?

03 / CAUSAL

Rationale

Why does it exist, what must survive, and who approved it?

The dispatch rail

The agent gets context before it gets clever.

Locate with Codebase Memory, preflight with Rationale, make the change, capture what happened, and leave approval with a person.

Prepare

Capture the why before code moves.

Change

Make the edit with constraints in view.

Finalize

Bundle the diff and observed facts.

Review

Confirm the decision with explicit authority.

$ rationale prepare src/retry/policy.ts → packet ready

The artifact

Make the context impossible to lose.

A compact packet gives the agent the decision, the trade-offs and the evidence before it reaches for a simplification.

.rationale/subjects/retry-policy.yaml

Exponential backoff for outbound retries

human-approved

why_it_matters: Reduces cascading failures under transient upstream errors.
decision: Use exponential backoff with jitter. Cap at 30s, 5 attempts.
trade-offs: Higher tail latency vs. improved success rate and stability.
authority: platform / human review
evidence: ADR-042 · incident-2024-04-11

observed · bound to src/retry/policy.ts · reviewed 2024-05-17

src/retry/policy.ts

+48 / −17

Synthetic demonstration

The change is legible beside the reason it exists.

export function retry(request) {
- return send(request, RETRY_DELAY_MS)
+ return sendWithBackoff(request, jitter)
+ // see: .rationale/records/retry-policy.yaml

+ export const MAX_ATTEMPTS = 5

+ export const BASE_DELAY_MS = 250

− export const RETRY_DELAY_MS = 500

Where context pays for itself

Four ordinary moments. One less thing to explain.

01 / ONBOARDING

Start a new agent conversation

The rules your team already settled survive the chat you opened today.

02 / REFACTOR

Refactor without removing the fence

A strange branch gets an explanation before an agent turns it into a regression.

03 / REVIEW

Review the change with its why attached

See the constraint, evidence, authority and revision instead of reconstructing the story from memory.

04 / TEAM

Keep business rules with the code

The reason remains versioned, reviewable and available after the person who explained it changes teams.

Quick start / by agent

Choose your agent and start with one concrete action.

Claude Code gets commands installed by Rationale. In Codex, ask for the same intent in writing: MCP tools do the work and approval remains human.

Open agents and MCP docs →

Claude Code

Installed slash commands

6 ACTIONS

/rationale-preflight <target> <intent>/rationale-explain <target>/rationale-capture [statement]/rationale-health/rationale-protocol/rationale-review

`/rationale-review` is intentionally human-only: the agent cannot self-approve.

Codex

Ask in plain language

MCP

“Prepare this change with Rationale for `<target>` with intent `<intent>`.”

“Explain `<target>` before changing it.”

“Capture and finalize this change with Rationale.”

“Check Rationale health.”

No fictional slash commands: Codex reads `AGENTS.md` and calls the available MCP tools.

Documentation / start with the work

Everything you need to verify the claim.

Use the landing to orient yourself; use the repository docs to inspect the real behavior, limits and evidence.

Start Five-minute quickstart Install, initialize a project, inspect health and run the first preflight.01 UnderstandFactual architecture See the real modules and the prepare → capture → review flow.02 OperateAgents and MCP Connect the tools without handing approval to the protocol.03 VerifyDogfood and pilot evidence Read the evidence with its coverage, gates and uncertainty attached.04

Trust is a product behavior

Local by default. Explicit about uncertainty.

CANON / LOCAL

What stays local

The `.rationale/` canon is versioned with the project. Logs stay local. Derived SQLite/FTS can be rebuilt and is never the only copy.

BOUNDARY / HUMAN

What stays human

MCP can prepare and capture. It cannot approve, revoke, supersede or change authority. Those actions require `rationale review`.

Release truth

Useful now, honest about what is still open.

public beta / latest

Rationale is in public beta. The core and full capture/review cycle are functional; platform coverage, pilot gates and human review remain visible work.

✓ Current public release: latest

! Open: platform matrix, provider coverage and pilot gates.

Install / then initialize

Protect the why before the next change.

The installer places the binary locally. `rationale init` creates the project canon and detects the agent configuration.

Companion / structural coverage

Install Codebase Memory first.

Codebase Memory maps where and how the code connects; Rationale carries why. The full path uses both. Rationale can still run alone with degraded coverage.

Open Codebase Memory ↗

macOS + Linux

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

01 / Install Rationale · macOS + Linux

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Ragosorio/Rationale/releases/latest/download/rationale-installer.sh | sh

Then, inside the repository:

rationale init

Check the project health:

rationale health

04 / Restart the agent. In Claude Code run `/rationale-health`; in Codex ask “Check Rationale health.”