{
  "markdown": "# ChangeBook for coding agents (MCP server + CLI)\n\nMCP (Model Context Protocol) server that lets coding agents — Claude Code,\nCodex, Cursor — query the **ChangeBook product memory** (the module map and the\nanalyzed change history from your ChangeBook account) instead of re-reading\nthe codebase, plus a CLI that feeds that memory from any terminal: sign in,\nanalyze uncommitted changes, sync the product map. All MCP tools are\nread-only, and every query is scoped to the signed-in user.\n\n## Two ways to run it\n\n**Local (npm):** the CLI runs the MCP server on stdio — no server to host, works\noffline against your account. See Quick start below.\n\n**Hosted (HTTP, no install):** point any client at the hosted endpoint with a\nPersonal Access Token — nothing to install, just a URL:\n\n```bash\nclaude mcp add --transport http changebook \\\n  https://mcp.changebook.app \\\n  --header \"Authorization: Bearer <your-PAT>\"\n```\n\nGenerate the PAT in the web app (Account → Access tokens). The token is\nSHA-256-hashed server-side and revocable; every query is scoped to your account.\n\n## Quick start (local)\n\n```bash\nnpx changebook init   # login (browser) + register in Claude Code/Codex + sync\n```\n\n`init` does four things: opens the browser so you sign in on changebook.app\n(one Authorize click — no token copy-pasting), registers the MCP server in\n**every coding agent it finds on the machine** — Claude Code, Codex, Cursor,\nWindsurf, Claude Desktop and VS Code (Copilot agent mode) — installs the\ngit hooks (post-commit: the atlas updates itself; pre-commit: the signal\nguard warns before touching a module with an open alert), and writes the\nproduct map\ninto the project's `CLAUDE.md`/`AGENTS.md`. It only touches agents that are\nactually installed, and merges into existing MCP configs without clobbering\nyour other servers.\n\n## CLI commands\n\n| Command | What it does |\n| --- | --- |\n| `changebook login` | Browser sign-in; stores the session in `~/.changebook/credentials.json` (0600). |\n| `changebook logout` | Forget the stored session. |\n| `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. |\n| `changebook analyze --commit [ref]` | Analyze one commit. Deduped by hash server-side, so re-runs never bill. |\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `changebook spend [dir]` | Where the model money goes and why: cost by month and model, whether the prompt cache is actually paying for itself (it reports the median gap between calls against the cache window — that gap is what decides it), how often responses hit the output cap, and whether every analysis left a row in the billing ledger. Account-wide: `usage_ledger` has no project column. |\n| `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. |\n| `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. |\n| `changebook sync [dir]` | Refresh the product map inside `CLAUDE.md`/`AGENTS.md`. |\n| `changebook init [dir]` | login + register MCP server + install hook + sync, in one go. |\n| `changebook open` | Open the web atlas in the browser. |\n| `changebook serve` | Run the MCP server on stdio (also the default with no arguments). |\n\nEvery command also works as `npx changebook <command>` with no install.\n\n## MCP tools\n\n| Tool | What it does |\n| --- | --- |\n| `atlas_recent_changes` | Recent analyzed changes: business impact, tech summary, modules touched. Supports `limit`, `offset`, `search`. |\n| `atlas_modules` | Aggregated module map: domain, category, risk, change count, last change, files. Optional `domain` filter. |\n| `atlas_module_detail` | One module's history: impact, notes, files and verbatim diff excerpts. |\n\n### Manual registration (instead of `init`)\n\n```bash\nclaude mcp add --scope user changebook -- npx -y changebook serve\n```\n\nOr in the project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"changebook\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"changebook\", \"serve\"]\n    }\n  }\n}\n```\n\nCredentials come from `changebook login` (`~/.changebook/credentials.json`); the\nenv vars below override them for CI/headless setups.\n\n### Environment variables\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `CHANGEBOOK_REFRESH_TOKEN` | — | Session token override (CI/headless; wins over the credentials file). |\n| `CHANGEBOOK_ACCESS_TOKEN` | — | Short-lived JWT; refreshed automatically when it expires. |\n| `CHANGEBOOK_PROJECT` | — | Scope every query to one project (matched by slug, then exact name — usually the workspace folder name). Unset = all projects. |\n| `CHANGEBOOK_WEB_URL` | `https://changebook.app` | Web app used by `login`/`open` and printed after `analyze`. |\n\n## `sync`: product map inside CLAUDE.md / AGENTS.md\n\n```bash\nnpx changebook sync [dir]\n```\n\nWrites (or refreshes, idempotently) an auto-generated section between\n`<!-- changebook:start -->` / `<!-- changebook:end -->` markers in the target\ndirectory's `CLAUDE.md` and `AGENTS.md`: the module map, the latest changes\nand a hint telling agents to use the `atlas_*` tools. Those files load into\nevery Claude Code / Codex session and get prompt-cached, so the map orients\nagents at near-zero marginal cost. Content outside the markers is never\ntouched. Re-run after analyzing changes (or wire it to a git hook).\n\n## Security notes\n\n- MCP tools are read-only; only `analyze` writes (through the same audited\n  server endpoint as the extension, with the same quotas).\n- `login` uses a loopback-only handoff: the web app asks for an explicit\n  Authorize click and redirects the tokens to `http://127.0.0.1:<port>` in\n  the URL fragment — they never leave your machine, and a `state` nonce ties\n  the handoff to the CLI process that requested it.\n- Your session lives in `~/.changebook/credentials.json` (0600) — treat it like\n  a password. `changebook logout` removes it.",
  "bytes": 8945,
  "sha": "834b94cea2c28d085fa08ec93fcdde92acc1deda8ef7ea1bdf089ff54dfd841f",
  "repo_slug": "",
  "fonte": "npm",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_raulbr90_changebook_6b49c009/readme"
}