Reasonbook README

Reasonbook — decisions that survive the session

Reasonbook, formerly CMOS, is the project record your agents keep: what was decided, why, what was learned, and what remains. The next session can pick up from that record, even in another tool. You make the decisions; agents handle the bookkeeping. No dashboard account is required.

See it work in a 75-second replay of recorded runs in Claude Code and Codex, and read what it sends and stores.

Install it in Claude Code

Install the plugin once for all your projects:

claude plugin marketplace add kneelinghorse/reasonbook
claude plugin install reasonbook@reasonbook

Upgrading from cmos@cmos? Uninstall it before refreshing the marketplace, using claude plugin uninstall cmos@cmos --scope user (or its original project or local scope), then install reasonbook@reasonbook. For a local installation, run the command from that project. If the marketplace already refreshed and uninstall says “not found”, use the tested recovery steps. Upgrade every client before moving an existing record.

For candidate testing, replace kneelinghorse/reasonbook with this checkout's absolute path. Start a new Claude Code session after installation. The plugin supplies the MCP server, hooks and commands; its first cold session may report that Reasonbook is installing and load the record from the next session. Use /reasonbook:init for a new record, /reasonbook:start to read it, /reasonbook:close-out to finish work, /reasonbook:plan to plan, and /reasonbook:build to execute. Plugin installation. Other tools use the harness adapters and coverage guide.

Get a project digest in three steps

Requires Node.js 20 or newer.

1. Install the pinned CLI:

   TerminalCopy

   npm install -g @aquex/reasonbook@4.0.2
   

   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.

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

   shCopy

   cd /absolute/path/to/your/project
   reasonbook init --level ledger
   

3. Read its first digest:

   shCopy

   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.

Codex plugins — 4.0.2

The developer plugin reasonbook supplies the server, seven skills and five lifecycle hooks. The conversation-focused reasonbook-chat supplies the same server and six distinct chat skills, with no hooks. Plugin loading, installation and project calls are verified in the bundled Codex CLI and app-server. ChatGPT Work remains unverified; this is not a hosted plugin for ChatGPT web or phone.

Install the developer plugin:

codex plugin marketplace add kneelinghorse/reasonbook
codex plugin add reasonbook@reasonbook

If the plugin is installed under its former name, remove it first, because both plugins answer as the same server: codex plugin remove cmos@cmos, and codex plugin remove cmos-chat@cmos for the chat plugin.

For chat workflows, install reasonbook-chat@reasonbook instead:

codex plugin add reasonbook-chat@reasonbook

For local development, replace the marketplace repository with this checkout's absolute path. Both plugins can be enabled together: Codex loads one server named rbook, and both sets of skills remain visible. Choose the developer plugin for building; choose the chat plugin for setup, catch-up, recall, proposing decisions, capturing notes and discussing next steps.

Node.js 20 or newer is required. The plugins install their exact Reasonbook version into ~/.config/rbook/plugins, with legacy config fallback for existing installations. On a first install, Reasonbook connects with an installing message; start a new session when installation finishes to load the project tools. The developer hooks share that runtime. The developer plugin requests forwarding of supported settings, including RBOOK_CONFIG_DIR; the portable chat plugin uses the environment inherited from its host. Use an absolute path, because empty or relative shared roots are refused. Environment forwarding depends on the client's plugin loader. If your loader does not forward a setting, use the default root or configure a manual server. See the harness guide.

In the Codex CLI, run /hooks and review the five developer-plugin commands once. If the desktop app does not expose that review, use its bundled Codex CLI with the same Codex home. Restart the app after installation if it has not loaded the plugin. A changed hook definition needs review again. The chat plugin has no hook review step.

Before replacing a CMOS 3.3.0 adapter, remove only its CMOS entries from project .codex/hooks.json and any user-level ~/.codex/hooks.json; keep unrelated hooks. Remove any other imported CMOS hook registration too. Keep one answering MCP server: remove a duplicate manual entry, or deliberately retain it and set "pluginServer": "off" in ~/.config/cmos-mcp/config.json (under your custom config root when using one).

Reasonbook uses the working folder supplied on each supported Codex call, so a conversation in a project can call rbook_review() without naming a path. Outside that folder, choose a registered address from rbook_project(action="list") and pass it as projectRoot, for example rbook_review(projectRoot="rbook://you/project"). Unknown or ambiguous addresses refuse; local-only projects need their folder. Tool hints conservatively include telemetry deletion, so Codex Auto mode can still ask for approval for any Reasonbook tool.

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<n> id; a draft is not yet a decision. Inspect drafts from the project folder with:

reasonbook drafts list

reasonbook-chat asks for approval in the conversation and makes a direct record, preserving your observed words in its context. Reasonbook cannot independently verify that approval; it does not claim hook-verified approval for a chat-only record. 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, not requested network actions or shared-collaboration pushes. Implicit process-exit closes do not upload. Full network and data disclosure.

Technical reference

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 sync (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.0.2

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.0.2

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.0.2"]}'

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.0.2",
        "--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.0.2"]
    }
  }
}

Zed

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

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.0.2"]
    }
  }
}

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, and an AGENTS.md at the project root (unless one is already there). In a folder without that database, the tools that read or write a project refuse and name init; registry and sign-in actions need no project.

Then run rbook_agent_onboard once: on a new project it walks the first-session setup. Open every later session with the session digest:

Run rbook_review to see the project state.

rbook_review returns the shared session digest: project identity, current sprint, open work and recent decisions. Its local text core is capped at 4,000 characters; appended portfolio context and the surrounding MCP response are outside that cap.

The full walkthrough — install → config → init → first sprint/mission/session loop — lives in docs/getting-started.md.

Tool surface

Reasonbook exposes 15 consolidated tools. 12 use an action parameter to select the operation; rbook_agent_onboard, rbook_status and rbook_review take no action. TOOL_REFERENCE.md publishes one parameter table per action, so it says which parameters actually apply to a given call.

See TOOL_REFERENCE.md for the exact per-action parameter reference — it is generated from the tool definitions on every build, so it never drifts from the shipped surface.

Optional: hosted dashboard

The dashboard is a separate service. Sign up at reasonbook.ai to unlock:

• Sync — your local SQLite mirrors to a Postgres replica; survives machine swaps and IDE reinstalls.
• Project registry — addressable rbook://you/project-name URIs across machines.
• Messaging — rbook_message(action="send") between your own projects.

To connect:

export RBOOK_DASHBOARD_URL=https://reasonbook.ai

Then run rbook_auth(action="login_init") from your agent. It returns a one-time userCode and verificationUri — paste the code at the URL in your browser, then run rbook_auth(action="login_complete", deviceCode=...) to finish. Credentials persist atomically to ~/.config/rbook/credentials.json (mode 0600).

RBOOK_DASHBOARD_URL defaults to https://reasonbook.ai. Until you sign in, the dashboard tools (rbook_message, sync, registry) return a structured DASHBOARD_NOT_CONFIGURED error that names rbook_auth(action="login_init"). Local tools never depend on the dashboard.

With a stored user-scoped dashboard key or legacy environment credentials, explicit rbook_session(action="complete") and rbook_sprint(action="complete") calls attempt a background upload and may register the project first. For a registered project, an MCP tool call that actually writes its store also schedules an upload. It becomes due after 5 quiet minutes or 30 minutes of continuous writes, and starts within the next 60 seconds when no upload lease or failure backoff blocks it. A running server must have opened the project; work owed by a short-lived process survives for the next server. Each upload sends a consistent snapshot of the whole SQLite file, including pending, declined and expired proposals. Transfer time is additional, and concurrent servers share one upload lease per project.

Upload results and failures appear in rbook_status and rbook_review. HTTP 401, 402 or 403 pauses automatic retries until an explicit close succeeds. A failed upload does not fail the local write or close. Implicit process-exit closes do not upload. Set RBOOK_CHECKPOINT_SYNC=off in the server environment to disable automatic uploads; it does not disable explicit sync, messaging, sign-in, shared-collaboration pushes or other requested network actions. See SECURITY.md.

Project resolution

Reasonbook never acts on a project you did not name. For each tool call it picks one project, in this order, and refuses rather than falling back when that project cannot be used:

1. The projectRoot parameter on the call: a project folder or an exact registered rbook://owner/project address. Address discovery reads stored identities without repairing them; no match, duplicate matches or an unreadable registered identity refuse.
2. For a supported Codex request, its conversation working folder. An invalid supplied folder refuses instead of falling back to the server's folder.
3. The workspace roots your MCP client advertises: the first one inside a Reasonbook project.
4. The working directory, or the nearest folder above it that is a Reasonbook project — one holding rbook/db/; a plain folder named rbook does not count (the search stops below your home directory).
5. Only when the server has no project context at all — no projectRoot, no roots, and a working directory of /, your home directory or the server's install directory (as for a client that starts servers without a project folder): the --project-root <dir> argument in that server's config, then a registry default set with rbook_project(action="register", projectRoot="...", setAsDefault=true).
6. Otherwise the call is refused. In a folder that is not a Reasonbook project, a write names rbook_project(action="init") and a read answers "No Reasonbook project in ''".

rbook_project(action="list") includes stored ids, addresses and folders. init, register and unregister require folders; an address never becomes a filesystem path.

Every successful response names the project it used (projectRoot and resolvedBy in its data), and says so in its text whenever the project came from workspace roots, --project-root or the registry default. A registry default set before 3.2.0 is not applied until you re-run setAsDefault; the server, rbook_message(action="whoami") and rbook_review say so when one exists.

Move work out of a central planning folder

If you collect several efforts in one Reasonbook project, use spin-out when an effort needs its own project folder. It copies selected missions, their linked decisions, learnings and next steps, and any additional record IDs you name. The source remains a readable history with pointers to the new project.

Create the destination folder first. The source must be registered, and the two stores must have distinct project identities. Both roots are required; this command does not use an ambient project or registry default. Omit --apply to preview the selection and mapping:

reasonbook spin-out --from /work/projects --to /work/new-product --sprint sprint-12

# Or select missions, with additional decisions, learnings and next steps by ID:
reasonbook spin-out --from /work/projects --to /work/new-product \
  --missions product-plan,product-prototype \
  --decisions 41,42 --learnings 17 --next-steps 23,24

# Apply the same reviewed selection:
reasonbook spin-out --from /work/projects --to /work/new-product \
  --missions product-plan,product-prototype \
  --decisions 41,42 --learnings 17 --next-steps 23,24 --apply

Choose either --sprint or --missions. A destination without Reasonbook is reported as needing initialization in the preview; --apply initializes it and takes database backups before copying. Copied work retains its status but has no sprint assignment in the destination. Assign it to a target sprint when ready. Source Queued, Blocked and Deferred missions become Dropped; Completed and already Dropped missions retain their status. Source decisions and learnings become archived, and source next steps become dropped. Default lists and retrieval omit these transferred source rows. Sprint history retains its counts and identifies transfers with their destination pointers. No sprint closes automatically.

Read a source or copied decision, learning or mission with its existing show action and an explicit projectRoot; the result includes spunOutTo or spinOutOrigin and a readable address. For a historical next step, use rbook_context(action="next_steps", nextStepAction="list", nextStepIds=[23], projectRoot="/work/projects"). Explicit IDs include moved or dropped rows; an explicit nextStepStatus still filters them. The ordinary next-step list continues to show open work. Target next steps without a sprint are flagged idle after 42 days. The CLI does not upload either store immediately: each enters the normal upload schedule after its next successful MCP write, subject to the configured upload controls.

Retry the exact command after an interruption. A verified completed operation returns unchanged. If source records changed after the target copy committed, final source marking is refused and both stores are preserved for review. If a reserved retry lacks its committed target receipt, the command also refuses: it cannot distinguish a crash before copying from an erased proof of an earlier copy. Preserve both roots and the operation ID named in the remedy, inspect their ledgers and pre-write snapshots, and resolve or restore the conflicting state before retrying. Do not delete a reservation to force another copy; retries never silently overwrite copied work.

Environment variables

# Optional — connects to the hosted dashboard. Defaults to https://reasonbook.ai
# when unset; treat empty string as unset.
RBOOK_DASHBOARD_URL=https://reasonbook.ai

# Optional — the directory the server reads its own .env from. It does NOT select a project:
# use the projectRoot parameter, or --project-root in a server's config.
RBOOK_PROJECT_ROOT=/path/to/your/project

# Optional — override the credential + registry directory. Default: ~/.config/rbook
RBOOK_CONFIG_DIR=/custom/path

# Snapshot retention (default shown)
RBOOK_MAX_SNAPSHOTS=50

# Optional — disable background uploads after writes and explicit completion calls.
# Shared-store propagation and explicitly requested network actions remain available.
RBOOK_CHECKPOINT_SYNC=off

Error response shape

Every tool returns a uniform envelope:

{
  "success": false,
  "error": {
    "code": "MISSION_NOT_FOUND",
    "message": "Mission 's99-m01' not found",
    "suggestion": "Use rbook_mission(action=\"list\") to see available missions"
  }
}

code is machine-readable, message is human-readable, suggestion is a concrete next step. Validation errors carry validValues (a string[]). State errors can carry currentState: generally a status string when the relevant mission, session, or sprint state is available, and — on SESSION_ALREADY_ACTIVE only — an object { id, type, title, startedAt, captureCount }. Branch on code before reading it.

Safety

• Append-only audit. Session events and mission transitions are append-only rows. Context snapshots keep their rows, ids and events, but rbook_db(action="prune_snapshots") can empty the content of copies Reasonbook wrote on its own.
• Atomic credential writes. credentials.json is written via temp-file + rename with 0600 permissions.
• Database snapshots. rbook_db(action="snapshot") copies the database on demand. A rbook_sprint(action="complete") attempts a snapshot before and after the close; a snapshot failure warns without blocking completion. Applying rbook_db(action="prune_snapshots") to a nonempty selection requires a backup, and rbook_db(action="restore") first copies the live database to rbook/db/snapshots/pre-restore/. RBOOK_MAX_SNAPSHOTS caps how many are kept: taking one deletes the oldest beyond it, automatic ones included. Nothing else snapshots first, and there is no soft-delete net — rbook_db(action="purge") deletes this project's data from the dashboard mirror. See SECURITY.md.
• Dry-run where it exists. rbook_context(action="condense") and rbook_db(action="backfill") accept dryRun to preview without committing. It is not a general property of mutating tools.

Known limits

• Registered projects sync after writes and explicit closes while a server is running; manual rbook_db(action="backfill") requests a sync immediately.
• SQLite is the source of truth and the Postgres mirror is a mirror. To bring state down, rbook_db(action="clone") bootstraps a fresh machine from dashboard state and rbook_db(action="pull") merges events since your last cursor.

Documentation

• Documentation home — what it is, how to install it, the levels and where to read more.
• The handoff demo — a 75-second replay of recorded runs, with a transcript.
• Trust — what leaves your machine, what the hooks read, and how to turn each part off.
• Privacy — collection, dashboard visibility, retention and removal.
• The method — the five lines, the three levels and how to move up.
• Getting started — client configuration and an optional Builder walkthrough.
• Harness coverage — native adapters, MCP prompts and the fallback without hooks.
• Tool reference — every tool, action, and parameter (generated from the tool definitions).
• Changelog — release notes and tool-surface changes.

Development

git clone https://github.com/kneelinghorse/reasonbook
cd reasonbook
npm install
npm run build
npm test

Development needs Node.js 20.17 or newer (lint-staged 16.4); the published package runs on Node.js 20 or newer.

Pre-commit hooks run lint + format via husky/lint-staged. This public repository is a code mirror; release validation and npm publishing run from the private source.

License

Apache-2.0. See LICENSE and NOTICE.