# Install Rationale and connect your agents · Rationale

> How to install the Rationale client on macOS and Linux, what rationale init sets up, how Claude Code and Codex capture decisions, how to connect Claude, ChatGPT and Cursor over MCP, and exactly what leaves your machine.

Source: https://rationalehq.com/docs
Language: en

Documentation

# Install Rationale and connect your agents

Everything a team needs to run Rationale, in the order it happens: install the client on each laptop, sign in, let it capture, connect the assistants that speak MCP, and know what leaves your machines. Written for the client as it ships today.

Updated October 2026 · client 0.9.0

On this page

1.  [How the pieces fit](#overview)
2.  [Before you start](#requirements)
3.  [Install the client](#install)
4.  [Sign in and set up: rationale init](#init)
5.  [What happens while you work](#day)
6.  [Commands](#commands)
7.  [Connect Claude, ChatGPT, Cursor and other assistants (MCP)](#mcp)
8.  [Connect GitHub and Jira](#connectors)
9.  [What leaves your machine, and what never does](#data)
10.  [Updates, rollback, uninstall](#updates)
11.  [When something does not look right](#troubleshooting)

## 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

Command

What it does

`rationale init [--url URL]`

Sign in (browser), check this repository, install the hooks and the watcher

`rationale login [--url URL]`

Sign in to another workspace, or renew a sign-in

`rationale status`

Sign-ins, this repository's workspace, hooks, watcher, latest session

`rationale anchors check PATH`

Which decisions would warn an agent on this file, their gist, and how far the file moved since

`rationale capture --task HANDLE`

Capture now, for a task; `--dry-run --print-delta` shows what would be sent

`rationale record --title "..." < thread.txt`

A pasted thread or notes through the extractor, recorded as one turn

`rationale deploy production [--ref REF]`

Tell Rationale what went live from this machine: sha, branch, commits

`rationale digest`

Summarize the projects that are due, with your own agent: status, topics, where tasks stand

`rationale pause codex [--hours N]`

Stop extracting with your Codex for a while; `rationale resume codex` resumes. Hooks keep warning.

`rationale update [--rollback]`

Check the signed release now and install it, or put the previous one back

`rationale uninstall`

Remove the hooks and the watcher; then revoke the device in the app

## 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

Leaves the machine

Never leaves

The extracted decisions, with short quotes of the person's own words

The transcript of the session

Session id, turn numbers, repository remote, branch, commit, time, and the equivalent cost of the extraction

Your repository's files: Rationale stores paths, never content

The paths of files an agent reads or changes, to ask which decisions apply

The content matched against a decision's identifiers (read locally, 512 KB at most)

A handoff and a project digest, written by your agent

Secret values: refused in what people and agents write, redacted from quotes

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.

Anything else: [support@rationalehq.com](mailto:support@rationalehq.com)