reasonbook

# Reasonbook — decisions that survive the session

[![npm version](https://img.shields.io/npm/v/@aquex/reasonbook)](https://www.npmjs.com/package/@aquex/reasonbook)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)

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](docs/demo/README.md) in a 75-second replay of recorded runs in Claude Code and
Codex, and read [what it sends and stores](docs/trust.md).

## Install it in Claude Code

Install the plugin once for all your projects:

```sh
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](docs/migrating-from-cmos.md#recover-an-already-refreshed-claude-marketplace).
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](https://code.claude.com/docs/en/discover-plugins).
Other tools use the [harness adapters and coverage guide](docs/harnesses.md).

## Get a project digest in three steps

Requires Node.js 20 or newer.

1. Install the pinned CLI:

   ```sh
   npm install -g @aquex/reasonbook@4.0.1
   ```

   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:

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

3. Read its first digest:

   ```sh
   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.1

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:

```sh
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:

```sh
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](docs/migrating-from-cmos.md) 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](docs/harnesses.md#codex).

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:

```sh
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](docs/method.md) gives the five lines in full, what Reasonbook does at each level, and
how to move up; the [starter templates](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](#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](SECURITY.md#outbound-network).

## 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](docs/harnesses.md)); 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](https://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:

```bash
npm install -g @aquex/reasonbook@4.0.1
```

If the former package is i