Install Rationale and connect your agents

How the pieces fit

Rationale has three parts. A client on each person's machine: one binary, no runtime, that listens to the person's agent sessions. The app at app.rationalehq.com, where decisions, tasks and audit logs live and where the team signs in. And a remote MCP server at mcp.rationalehq.com, through which assistants such as Claude, ChatGPT and Cursor read and record decisions.

The client extracts decisions with the agent the person already has signed in (claude -p for Claude Code, codex exec for Codex), on that machine. Rationale receives the extracted decisions, short quotes and metadata: session id, turn numbers, repository, branch, time. The transcript never leaves the machine, except to the agent's own provider, as it always did.

Before you start

• macOS (one universal binary) or Linux on x86_64 or arm64. Windows is not supported yet: the installer says so and stops.
• Claude Code or Codex signed in on the machine. The client uses that CLI to extract decisions, on the person's own plan; it never needs an API key of its own.
• A Rationale workspace. We are in early access: request access and we set the workspace up with you within a working day.
• A project in the workspace that lists the git remote of each repository you want captured. The client routes every session by that remote; a repository no project lists is never captured.
• curl or wget, and sha256sum or shasum, which every macOS and Linux has.

Install the client

One command, no sudo:

curl -fsSL https://rationalehq.com/install.sh | sh

The installer puts one binary at ~/.local/bin/rationale. It downloads next to the binary, checks size and sha256 against the release manifest, runs rationale --version and renames it into place. It never edits your shell files: if ~/.local/bin is not on your PATH, it prints the line to add. It signs nothing in and installs no hooks; that is rationale init, next.

With Homebrew instead:

brew tap rationalehq/tap https://github.com/jorgebasilio/homebrew-tap
brew install rationalehq/tap/rationale

The first install trusts TLS to the file host, like every curl | sh. Every later update is verified by the client itself against a signed release manifest (see Updates, rollback, uninstall).

Sign in and set up: rationale init

Run it once per machine, inside a repository your workspace lists:

rationale init

1. Sign-in. It opens the browser with a short code (the device flow). You sign in to Rationale and the machine gets its own token, kept in ~/.config/rationale/config.json (mode 600). One sign-in per workspace; rationale login adds another.
2. Repository check. It asks which of your workspaces has a project listing this repository's git remote. Exactly one: captured there. None: not captured, and it says so. Two: not captured, and rationale status names both. It never guesses.
3. Hooks. For Claude Code it writes four entries to ~/.claude/settings.json (a backup is kept, your own entries are untouched): Stop, UserPromptSubmit, SessionStart and PostToolUse. For Codex it adds four entries to ~/.codex/hooks.json; Codex runs a hook only after you trust it (/hooks in the CLI, or Review hooks in the app), and init and status tell you until that is done.
4. Watcher. On macOS a launchd job (~/Library/LaunchAgents/com.rationalehq.client.watcher.plist), on Linux a systemd user timer (rationale-watcher.timer), every minute: captures, handoffs, digests and updates. Without a systemd user session, init says so, and the hooks still capture every turn.

rationale status shows the sign-ins, this repository's workspace, the hooks, the watcher and the latest session, any time.

What happens while you work

• Capture. When a session ends (Claude Code's Stop hook, or the watcher for Codex), the client builds a compact delta of the new turns, without tool output or thinking, and asks your agent to pick out the decisions: question, choice, criteria, what was ruled out, when to revisit it, the files and the task they are about, and the person's own words that confirm, correct or retire an earlier one. A failed extraction is retried later and never blocks the agent.
• Warnings before the edit. When the agent reads or is about to change a file a decision is anchored to, the hook asks Rationale for those decisions within a two-second budget and shows them to the agent before the edit: who decided, the gist, and how many commits touched the file since. If the server is slow, the agent gets the gist from a local index instead. A decision that names a class, a table or a ticket key is matched inside the file's content on your machine; that content never leaves it.
• Context for a task. Type a task's #handle in a prompt and the agent starts with what was decided on it, who is on it and the open pull requests.
• Notes at session start. Your notes for the repository, the workspace and the project reach the agent when a session starts.
• Handoffs. A session with decisions that goes quiet for 30 minutes gets a handoff written for whoever picks the task up: summary, next steps, open questions.
• Never in the way. A hook that fails exits silently and lets the agent continue. Nothing waits on the network except the warning, which has its budget.

Commands

Connect Claude, ChatGPT, Cursor and other assistants (MCP)

Assistants that speak the Model Context Protocol read your team's decisions and record new ones through the remote server at https://mcp.rationalehq.com/mcp. It uses OAuth 2.1: paste the URL, sign in once in the browser, and allow your workspaces. Each tool says whether it reads or writes: context_for, list_tasks, record_decision, record_handoff, record_note, pull_request_for and a few more.

• Claude Code: claude mcp add --scope user --transport http rationale https://mcp.rationalehq.com/mcp, then the browser sign-in Claude Code opens.
• Codex: codex mcp add rationale --url https://mcp.rationalehq.com/mcp, then codex mcp login rationale.
• Claude (claude.ai and the desktop app): Settings → Connectors → Add custom connector, with the URL above. Sign in when Claude asks.
• ChatGPT: Settings → Connectors → Create, with the URL above (custom connectors need a plan that allows them). Sign in when ChatGPT asks.
• Cursor and other MCP clients: add a server with that URL in the client's MCP settings (for Cursor, ~/.cursor/mcp.json) and sign in when prompted.

A project can pin its workspace with ?workspace=slug on the URL. The Get started page in the app shows the same commands with your details filled in.

Connect GitHub and Jira

In the app, Settings → Connectors. GitHub installs as a GitHub App on the organizations you choose; Jira connects with OAuth to your Atlassian site. Both are per member: each person sees in Rationale only the repositories, pull requests, tickets and projects their own account can see.

Pull requests, reviews and issues link to the decisions that govern the files they change. Jira tickets and epics become tasks, and decisions follow the ticket. Without a tracker, tasks live in Rationale and agents open them when asked.

What leaves your machine, and what never does

Extraction, handoffs and digests run with your own agent on your own plan, so the cost stays on your side and visible: each capture carries its equivalent cost. The client reports the result of an update (ok, bad signature, rolled back) as a code with its next request, never a log.

Updates, rollback, uninstall

The watcher, never a hook, checks the signed release manifest at most every six hours and swaps the binary in place, keeping the previous one. Two minisign public keys are compiled into every binary: a release key that signs every manifest, and an offline backup key used only to rotate the first. A manifest neither key signed is refused; so is a replayed one. Homebrew installs only say a newer version exists.

rationale update
rationale update --rollback

To leave: rationale uninstall removes the hooks and the watcher; then revoke the device on the Devices page of the app, which invalidates its token. The config stays in ~/.config/rationale/ and the state in ~/.local/state/rationale/ until you delete them.

When something does not look right

• rationale: command not found: ~/.local/bin is not on your PATH; the installer printed the line to add to your shell profile.
• Sessions are not captured: run rationale status. The repository's remote must be listed by exactly one project in one of your workspaces; two workspaces claiming it stop capture until one drops it. Codex hooks capture only once you trust them.
• Warnings do not appear: the hook has a two-second budget and gives up quietly on a slow network; the next one tries again. rationale anchors check PATH shows what a hook would say for a file.
• Corporate proxy: the client uses your platform's certificate store, so a proxy with its own root certificate works without configuration.
• Anything else: support@rationalehq.com, with the output of rationale status. It contains no transcript and no decision text.