changebook

ChangeBook for coding agents (MCP server + CLI)

MCP (Model Context Protocol) server that lets coding agents — Claude Code, Codex, Cursor — query the ChangeBook product memory (the module map and the analyzed change history from your ChangeBook account) instead of re-reading the codebase, plus a CLI that feeds that memory from any terminal: sign in, analyze uncommitted changes, sync the product map. All MCP tools are read-only, and every query is scoped to the signed-in user.

Two ways to run it

Local (npm): the CLI runs the MCP server on stdio — no server to host, works offline against your account. See Quick start below.

Hosted (HTTP, no install): point any client at the hosted endpoint with a Personal Access Token — nothing to install, just a URL:

claude mcp add --transport http changebook \
  https://mcp.changebook.app \
  --header "Authorization: Bearer <your-PAT>"

Generate the PAT in the web app (Account → Access tokens). The token is SHA-256-hashed server-side and revocable; every query is scoped to your account.

Quick start (local)

npx changebook init   # login (browser) + register in Claude Code/Codex + sync

init does four things: opens the browser so you sign in on changebook.app (one Authorize click — no token copy-pasting), registers the MCP server in every coding agent it finds on the machine — Claude Code, Codex, Cursor, Windsurf, Claude Desktop and VS Code (Copilot agent mode) — installs the git hooks (post-commit: the atlas updates itself; pre-commit: the signal guard warns before touching a module with an open alert), and writes the product map into the project's CLAUDE.md/AGENTS.md. It only touches agents that are actually installed, and merges into existing MCP configs without clobbering your other servers.

CLI commands

Command	What it does
changebook login	Browser sign-in; stores the session in ~/.changebook/credentials.json (0600).
changebook logout	Forget the stored session.
changebook analyze [dir]	Analyze the repo's uncommitted changes (git diff HEAD) and update the atlas — same pipeline as the VS Code extension, no editor needed.
changebook analyze --commit [ref]	Analyze one commit. Deduped by hash server-side, so re-runs never bill.
changebook hook install|uninstall|status [dir]	Git hooks: every new commit is analyzed in the background (post-commit, never blocks), and the signal guard warns before you commit to a module with an open alert (pre-commit). One pair of hooks covers Claude Code, Codex and manual commits — they all commit through git.
changebook hook-context install|uninstall|status [dir]	Claude Code SessionStart hook: pushes the fresh atlas map into every session at turn 0 — no tool call to remember, and generated on the spot so it can't go stale. Writes to .claude/settings.json; running the command is the consent, and it refuses to touch a config it can't parse.
changebook hook-impact install|uninstall|status [dir]	Claude Code PreToolUse hook: before every edit, tells the agent which modules depend on the file it is about to touch, plus any open alert and repeat-offender history. Never blocks an edit, never touches the network on the critical path (reads a short-lived cache in .git/ and refreshes it out of band), warns once per file per session, and stays silent when there is nothing to say.
changebook impact / changebook context [dir]	What those two hooks run. Both read from stdin/disk, print a JSON payload (or nothing) and always exit 0 — you don't call them by hand.
changebook import [dir] [--commits N]	Backfill the last N commits (default 25) through the Anthropic Batch API — 50% cheaper and non-interactive, for seeding the atlas on an existing repo.
changebook scan [dir] [--json|--card|--badge]	Coupling report for any repo from its git history alone: no account, no network, writes nothing — run it on something you just cloned. --card renders a shareable SVG, --badge publishes four numbers and prints the README snippet (needs an account; --badge --off turns it off). The badge exposes those four numbers and nothing else — not your code, modules or change summaries.
changebook silence [dir]	How often the PreToolUse hook stays quiet, with both raw numbers. Local by design: it answers the day you install it, not two days later.
changebook friction [dir]	Where the agent's work gets redone in this repo, read from the local Claude Code transcripts — no prose leaves the machine, only paths, modules, dates and a session hash. Says MUERTO if the repo has edits and it read nothing, and reports its own blind spot: edits made through the shell (sed -i, heredocs) leave no before/after, so ~25% of writes are invisible to it and it says so.
changebook audit [dir]	Static check of your agent setup — no network, no credentials, nothing written. Flags rules in CLAUDE.md/AGENTS.md that cite files which no longer exist (with a «did you mean…»), how much context you pay every session, and whether the impact hook is actually installed. Every check here was written after it found something real, not from a best-practices list.
changebook guard [dir]	What the pre-commit hook runs: checks staged files against the atlas' open alerts. Warn-only and fail-open by default; CHANGEBOOK_GUARD=block makes findings abort the commit (bypass once with git commit --no-verify), CHANGEBOOK_GUARD=off silences it.
changebook sync [dir]	Refresh the product map inside CLAUDE.md/AGENTS.md.
changebook init [dir]	login + register MCP server + install hook + sync, in one go.
changebook open	Open the web atlas in the browser.
changebook serve	Run the MCP server on stdio (also the default with no arguments).

Every command also works as npx changebook <command> with no install.

MCP tools

Tool	What it does
atlas_recent_changes	Recent analyzed changes: business impact, tech summary, modules touched. Supports limit, offset, search.
atlas_modules	Aggregated module map: domain, category, risk, change count, last change, files. Optional domain filter.
atlas_module_detail	One module's history: impact, notes, files and verbatim diff excerpts.

Manual registration (instead of init)

claude mcp add --scope user changebook -- npx -y changebook serve

Or in the project's .mcp.json:

{
  "mcpServers": {
    "changebook": {
      "command": "npx",
      "args": ["-y", "changebook", "serve"]
    }
  }
}

Credentials come from changebook login (~/.changebook/credentials.json); the env vars below override them for CI/headless setups.

Environment variables

Variable	Default	Purpose
CHANGEBOOK_REFRESH_TOKEN	—	Session token override (CI/headless; wins over the credentials file).
CHANGEBOOK_ACCESS_TOKEN	—	Short-lived JWT; refreshed automatically when it expires.
CHANGEBOOK_PROJECT	—	Scope every query to one project (matched by slug, then exact name — usually the workspace folder name). Unset = all projects.
CHANGEBOOK_WEB_URL	https://changebook.app	Web app used by login/open and printed after analyze.

sync: product map inside CLAUDE.md / AGENTS.md

npx changebook sync [dir]

Writes (or refreshes, idempotently) an auto-generated section between <!-- changebook:start --> / <!-- changebook:end --> markers in the target directory's CLAUDE.md and AGENTS.md: the module map, the latest changes and a hint telling agents to use the atlas_* tools. Those files load into every Claude Code / Codex session and get prompt-cached, so the map orients agents at near-zero marginal cost. Content outside the markers is never touched. Re-run after analyzing changes (or wire it to a git hook).

Security notes

• MCP tools are read-only; only analyze writes (through the same audited server endpoint as the extension, with the same quotas).
• login uses a loopback-only handoff: the web app asks for an explicit Authorize click and redirects the tokens to http://127.0.0.1:<port> in the URL fragment — they never leave your machine, and a state nonce ties the handoff to the CLI process that requested it.
• Your session lives in ~/.changebook/credentials.json (0600) — treat it like a password. changebook logout removes it.