Reasonbook

What Reasonbook MCP server does

The Reasonbook MCP server maintains one project record for decisions, reasons, lessons, constraints, and unfinished work. The record is stored locally in a SQLite file under rbook/db/rbook.sqlite, keeping project context available after an AI session ends and when work moves to another client.

A new record can be initialized as a Ledger with the CLI. The first review produces a project digest containing recorded decisions, lessons, and open work. Planner and Builder workflows can add next steps, sprints, and missions. Records can also represent proposals, including drafts that still need approval, and decisions can be superseded when circumstances change.

How it works

The server exposes 15 typed tools through MCP. In Codex, calls use the working folder supplied by the client, so a project can call rbook_review() without supplying a path. Projects outside that folder can be addressed through a registered rbook:// address returned by rbook_project(action="list"), using the projectRoot argument. Unknown or ambiguous addresses are rejected.

Reasonbook can be installed through the Claude Code or Codex plugin systems, which provide the server and, depending on the plugin, skills and lifecycle hooks. The developer-oriented Codex plugin includes five hooks; the chat plugin has no hooks. Supported hooks can bring the project record into a session automatically and can retain a proposed decision as a draft for later approval.

Setup and configuration

Node.js 20 or newer is required. The standalone setup installs the pinned CLI package, runs reasonbook init --level ledger from the project directory, and reads the result with reasonbook review --format=context.

Claude Code installation uses the Reasonbook marketplace plugin. Codex provides separate reasonbook and reasonbook-chat plugins for development and conversation-focused workflows. After a first installation, a new session may be needed once the server finishes installing. Local development uses an absolute checkout path.

The Codex developer plugin can forward supported settings such as RBOOK_CONFIG_DIR; shared roots must be absolute. RBOOK_CHECKPOINT_SYNC=off disables automatic checkpoint uploads, but does not disable explicitly requested network actions or shared-collaboration pushes.

Tools and capabilities

• Read a project digest with rbook_review.
• List or select registered project addresses with rbook_project.
• Initialize a project record with the reasonbook init CLI command.
• Review decisions, lessons, and open work with the reasonbook review command.
• List pending proposals with reasonbook drafts list.
• Capture decisions, lessons, constraints, and next steps through the MCP tool set.
• Use lifecycle hooks and skills supplied by the Claude Code and Codex plugins.

Limitations and notes

Claude Code and Codex are the verified clients. Claude Desktop, Cursor, Zed, VS Code, and Windsurf are identified as untested. Chat-only approval is not independently verified by Reasonbook, so it does not claim hook-verified approval for those records.

The Reasonbook MCP server keeps the main record on the local machine, but configured session and sprint closes can upload the entire SQLite file, including pending and declined proposals. Registered-project writes may also schedule an upload after a quiet or continuous-write interval. Automatic checkpoint synchronization can be disabled with RBOOK_CHECKPOINT_SYNC=off, while implicit process-exit closes do not upload.

A project has one record, and changing tools does not automatically change the record's content. When replacing older CMOS installations, duplicate servers and old hook registrations need to be removed or handled according to the migration instructions.