Reasonbook

Reasonbook — decisions that survive the session

Reasonbook keeps a local record of your project's decisions, reasons and lessons so the next agent session can pick up where you left off. You make the decisions; agents handle the bookkeeping. No dashboard account is required.

A 65-second replay of recorded runs. Read the demo's receipts and what Reasonbook sends and stores.

Try it

Choose a plugin below, or install the CLI with npm. Your first ten minutes takes you from installation to recording a choice and finding its reason in another session.

Commit the generated agent instructions, rbook/.gitignore and your project documents; keep the SQLite store, WAL/SHM files and snapshots out of Git.

Install it in Claude Code

Install the plugin once for all your projects:

claude plugin marketplace add kneelinghorse/reasonbook

claude plugin install reasonbook@reasonbook

Start a new Claude Code session after installation, then ask it to start a Reasonbook Ledger for this project. If the first session says Reasonbook is installing, start another once it finishes.

Get a project digest in three steps

Requires Node.js 20 or newer.

1. Install the pinned CLI:

   npm install -g @aquex/reasonbook@4.12.0

Ensure the global npm bin directory is on your PATH. If the former package is installed globally, run npm uninstall -g @aquex/cmos-mcp first. Version 4 provides only the reasonbook command; update scripts and MCP configurations that use the old command.

1. In the project folder you want to track, start a Ledger:

   cd /absolute/path/to/your/project

reasonbook init --level ledger

1. Read its first digest:

   reasonbook review --format=context

The digest names this project and shows its decisions, lessons and open work. A new Ledger starts empty. Planner adds next steps; Builder adds sprints and missions.

Commit the generated AGENTS.md, CLAUDE.md, rbook/.gitignore and the project documents you maintain. A new record's ignore file keeps the SQLite store, its WAL/SHM files and snapshots out of Git. Init preserves an existing ignore file. Shared records require the store to remain untracked; exchange those records through Reasonbook's sharing commands.

A plugin installation does not put reasonbook on your terminal PATH. Plugin-only users can replace reasonbook in these commands with npx --prefer-offline -y @aquex/reasonbook@4.12.0, for example npx --prefer-offline -y @aquex/reasonbook@4.12.0 review --format=context.

Codex plugins

codex plugin marketplace add kneelinghorse/reasonbook

codex plugin add reasonbook@reasonbook

For chat workflows, use codex plugin add reasonbook-chat@reasonbook instead. See Codex setup and verification limits.

Upgrading from CMOS

Use reasonbook doctor to inspect what needs changing and reasonbook migrate to preview a record move. Follow the migration guide to upgrade clients before moving their records.

Propose a decision, then approve it

When a choice needs your approval, the agent ends its reply with one concrete line:

Would record: Use a weekly review because it keeps the reading list useful without daily upkeep.

With the developer hooks enabled and linked to that conversation, the Stop hook keeps this as a draft. Your next reply can approve it, decline it, ask a question or amend the wording. The agent records an approved draft with its returned P id; a draft is not yet a decision. In the same live conversation, an answer more than two hours later can still address an unexpired draft. Late approvals record as agent-judged; late declines persist. Constraint, rule and profile drafts need to be proposed again for plain approval. Inspect drafts from the project folder with:

reasonbook drafts list

reasonbook-chat makes a direct record of the choice and reasons you request or approve. It states that you approved it in the conversation without quoting the conversation or using the draft runtime. An explicit approval already given for the exact wording counts, so the agent need not ask again.

The method

• One project, one record of decisions, lessons, constraints and next steps.
• Start from that record; supported hooks bring it into the session automatically.
• Record decisions deliberately, with reasons. Supersede a changed decision.
• Make expiry and supersession visible; closing a sprint keeps records active by default.
• Keep the record with the project so it survives a change of tools.

The method gives the five lines in full, what Reasonbook does at each level, and how to move up; the starter templates hold the files each level starts with.

What leaves your machine

The record stays in your project's SQLite file. With a stored user-scoped key or legacy environment credentials, explicit session and sprint closes attempt a background upload of the whole file, including pending and declined proposals. For a registered project, MCP tool writes also schedule an upload after 5 quiet minutes or 30 minutes of continuous writes; the next poll starts it within 60 seconds when no upload lease or failure backoff blocks it. Transfer time follows. See the timing and failure details under Optional: hosted dashboard. RBOOK_CHECKPOINT_SYNC=off stops automatic uploads and manual rbook_db(action="backfill") uploads. Other requested network actions and shared-record exchanges remain available. Logging out leaves project keys valid for other requested dashboard calls, but closes and manual backfill also require a stored user-scoped key or environment credentials. Implicit process-exit closes do not upload. A project shared through reasonbook.ai keeps uploading its whole file until the share hands its record to the dashboard's referee copy, then sends the shared record's changes until it is moved back. The client also supports a member uploading a scrubbed SQLite copy when reasonbook.ai begins hosted recovery. The owner reviews and confirms the recovery plan on the Shared record page. Either RBOOK_SHARED_SYNC=off or RBOOK_DASHBOARD_SHARING=off stops recovery contributions, including during an explicit sync. Full network and data disclosure.

What it is

Reasonbook is the protocol + client. It runs locally on your machine, owns a SQLite database under rbook/db/rbook.sqlite, and exposes 15 typed tools over MCP. Claude Code and Codex are verified (see the harness guide); other MCP clients, such as Claude Desktop, Cursor, Zed, VS Code and Windsurf, are untested.

Out of the box you get:

• Sprint and mission state machines with auditable transitions
• Session capture for decisions, learnings, constraints, next-steps
• Strategic context that condenses across sprints, with FTS5 retrieval
• Full-text search across decisions, learnings, missions, sessions
• Database snapshots on demand; backup attempts around sprint closes; required backups before a restore or a snapshot prune with selected rows
• Per-project credential store and device-code auth (RFC 8628)

The dashboard at reasonbook.ai is optional. You can run Reasonbook standalone forever — sign-up unlocks dashboard uploads (SQLite → Postgres mirror), the project registry (rbook://you/* addresses), and cross-project messaging. Without it, every other tool still works locally.

Install

Recommended: a global install of this release. The server then starts from disk, with no registry lookup on launch:

npm install -g @aquex/reasonbook@4.12.0

If the former package is installed globally, run npm uninstall -g @aquex/cmos-mcp first. Version 4 provides only the reasonbook command; update scripts and MCP configurations that use the old command.

Or run it on demand with npx. Pin the version and prefer the local cache: an unpinned npx -y can look the package up again on every launch.

npx --prefer-offline -y @aquex/reasonbook@4.12.0

Semantic (vector) search is optional. Without it, retrieval is keyword-only, and the install is about 45 MB instead of about 306 MB. To add a vector term to retrieval, install @xenova/transformers next to Reasonbook. rbook_db(action="health") reports whether it is on.

Requires Node.js 20 or newer.

Configure your MCP client

Claude Code and Codex are verified; the other blocks follow each client's own MCP configuration and are untested with Reasonbook. Each example below runs a pinned version through npx, preferring the local cache; to upgrade, change the version. With the global install, use "command": "reasonbook" and drop the npx arguments (keep --project-root where an example has it).

Claude Code

claude mcp add-json rbook '{"command":"npx","args":["--prefer-offline","-y","@aquex/reasonbook@4.12.0"]}'

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows/Linux:

{

"mcpServers": { "rbook": { "command": "npx", "args": [ "--prefer-offline", "-y", "@aquex/reasonbook@4.12.0", "--project-root", "/absolute/path/to/your/project" ] } } }

Claude Desktop is expected to start servers with no project context (on macOS, from / with no workspace roots; untested with Reasonbook), so name the project in the config. --project-root applies only to this server entry, and only to calls with no project context: no projectRoot, no workspace roots, and a working directory of /, your home directory or the server's install directory. A client that starts the server from any other folder should pass projectRoot instead.

Cursor

Add to ~/.cursor/mcp.json:

{

"mcpServers": { "rbook": { "command": "npx", "args": ["--prefer-offline", "-y", "@aquex/reasonbook@4.12.0"] } } }

Zed

{

"context_servers": { "rbook": { "command": "npx", "args": ["--prefer-offline", "-y", "@aquex/reasonbook@4.12.0"] } } }

VS Code (Claude extension)

Use the Claude Code command above from the integrated terminal, or add the server through /mcp in the Claude panel. The extension and CLI share MCP configuration; start a new conversation after changing it. The extension does not add claude to your terminal PATH, so the terminal route needs the standalone Claude CLI. Claude Code in VS Code

Windsurf

{

"mcpServers": { "rbook": { "command": "npx", "args": ["--prefer-offline", "-y", "@aquex/reasonbook@4.12.0"] } } }

First call

Project tools work on a folder that has a Reasonbook database, so a new project starts with init:

rbook_project(action="init", projectRoot="/absolute/path/to/your/project")

init creates rbook/db/rbook.sqlite, the seed files, an AGENTS.md and a CLAUDE.md that imports it at the project root (keeping either file if it already exists). In a folder without that database, the tools that read or write a proj