io.github.raulbr90/changebook
Your agent already broke this three times. ChangeBook tells it before the fourth.
Open source Open in the app JSON README (API)
About
Your agent already broke this three times. ChangeBook tells it before the fourth.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- raulbr90
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.10.0
- Added
- 2026-08-29 04:01:16
- Updated
- 2026-09-05 13:00:12
- Origin id
io.github.raulbr90/changebook
README
# 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:
```bash
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)
```bash
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 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. |
| `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`)
```bash
claude mcp add --scope user changebook -- npx -y changebook serve
```
Or in the project's `.mcp.json`:
```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
```bash
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.