Branchpoint

English | Español

Branchpoint gives your Git workflow persistent memory, per branch. AI coding agents use it as an MCP server so they stop mixing up context between branches; you use it as a CLI to see at a glance what was going on in each branch. One binary, two faces: the same .git/branchpoint/ store feeds both.

# For your agent (Claude Code):
claude mcp add branchpoint -- npx -y branchpoint

# For you:
npx branchpoint status

The problem

When an AI coding agent (Claude Code, Cursor, Cline...) works in a repository with several active branches, it has no memory of what was decided or done on each one. That causes two familiar symptoms:

• Cross-branch hallucination: the agent mixes code context or decisions from one branch into the current work on another.
• Wasted tokens: the agent has to re-explore and re-explain the state of the project every session, because nothing persisted was tied to the branch.

And you hit the same problem yourself coming back to a branch a week later: what was this even about?

How it works

Branchpoint detects the active Git branch and persists context summaries per branch under .git/branchpoint/<branch>.md. When context is read, it's automatically enriched with information pulled from Git itself (recent commits, divergence from the default branch), so switching branches automatically switches the relevant context.

The same executable picks its mode based on how it's launched:

• No arguments, piped stdio (how an MCP client launches it) → MCP server over stdio.
• Arguments present → CLI with subcommands (status, list, context).
• No arguments, in a terminal → interactive mode with a menu.

See ARCHITECTURE.md for the full design: data flow, file-by-file responsibilities, the stack and why each piece was chosen, and the testing philosophy.

For AI agents (MCP server)

Claude Code

claude mcp add branchpoint -- npx -y branchpoint

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

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

Cursor

Add to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global — Cursor uses the same format as Claude Desktop):

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

Cline

Add to Cline's MCP settings file (VS Code global storage — .../globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json, reachable from Cline's "Configure MCP Servers" menu):

{
  "mcpServers": {
    "branchpoint": {
      "command": "npx",
      "args": ["-y", "branchpoint"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

VS Code (agent mode)

Add to .vscode/mcp.json in your workspace. Note the top-level key is servers, not mcpServers like the tools above:

{
  "servers": {
    "branchpoint": {
      "command": "npx",
      "args": ["-y", "branchpoint"]
    }
  }
}

MCP tools are only available in agent mode — they're invisible in Ask or Edit mode.

Any other MCP client not listed here should work the same way: it's a standard stdio server launched with npx -y branchpoint (or node /absolute/path/to/branchpoint/dist/index.js if you built from source). If a client needs a different setup, please open an issue.

Tools exposed

get_branch_context

No parameters. Returns the manually saved summary for the active branch (or a clear notice if there isn't one) combined with context enriched from Git: divergence from the default branch (commits since the merge-base plus diff --stat, omitted if no default branch is detected or you're already on it) and the 10 most recent commits.

Real output on a branch with a saved summary and 2 commits of divergence:

## Saved summary

Implementing the OAuth login flow. Still need to handle the refresh token.

## Divergence from "main"

2 commit(s) since the divergence point.

 src/auth.ts | 45 +++++++++++++++++++++++++++++++++++++++++++++
 src/login.ts | 12 ++++++------
 2 files changed, 51 insertions(+), 6 deletions(-)

## Recent commits

- a1b2c3d feat: add refresh token handling
- e4f5g6h feat: initial OAuth login flow
...

Degraded repository states are reported as normal tool content, never as protocol errors — a detached HEAD returns an explanatory message instead of crashing, and a repository with no commits yet says so plainly.

save_branch_context

Parameter summary: string. Saves a manual context summary for the active branch, persisted at .git/branchpoint/<branch>.md and combined with the Git-derived enrichment on the next read. An empty or whitespace-only summary is rejected with a clear message rather than saved as an empty file; summaries are capped at 50,000 characters (about 12,000 tokens — comfortably more than a real summary needs) to guard against accidental dumps.

ping exists as an internal diagnostic tool to verify the MCP server is responding correctly; it isn't a product feature.

For humans (CLI)

The same data your agent sees, in your terminal. Every subcommand accepts --json for raw, color-free output (scripts, CI).

branchpoint status

Active branch, whether it has saved context, and divergence from the default branch:

╭───────────────────────── branchpoint ──────────────────────────╮
│  Active branch:  feature/oauth-login                           │
│  Context:        saved (updated 2026-07-11 18:30)              │
│  Divergence:     2 commit(s) since the common point with main  │
╰────────────────────────────────────────────────────────────────╯

With --json:

{
  "branch": "feature/oauth-login",
  "hasContext": true,
  "updatedAt": "2026-07-11T16:30:00.000Z",
  "defaultBranch": "main",
  "hasCommits": true,
  "divergence": {
    "baseBranch": "main",
    "commitCount": 2
  }
}

branchpoint list

Every branch with saved context, most recently updated first:

┌─────────────────────┬──────────────────┬──────────────────────────────────────────────────────────────┐
│ Branch              │ Updated          │ Summary                                                      │
├─────────────────────┼──────────────────┼──────────────────────────────────────────────────────────────┤
│ feature/oauth-login │ 2026-07-11 18:30 │ Implementing the OAuth login flow. Decided to use PKCE…      │
├─────────────────────┼──────────────────┼──────────────────────────────────────────────────────────────┤
│ main                │ 2026-07-10 09:14 │ Stable branch. Latest release: v1.2.0. Don't touch until QA… │
└─────────────────────┴──────────────────┴──────────────────────────────────────────────────────────────┘

branchpoint context [branch]

The full saved context for a branch (defaults to the active one):

feature/oauth-login — updated 2026-07-11 18:30

Implementing the OAuth login flow. Decided to use PKCE instead of a client secret. Still need to handle refresh token expiration.

Interactive mode

branchpoint with no arguments in a terminal opens a menu to view the active branch's context, list every saved branch, or save a new summary, without memorizing subcommands. Ctrl+C exits cleanly at any point.

Troubleshooting

Registering the server on Windows with a raw absolute path fails or behaves oddly. If you're pointing an MCP client's config directly at node C:\path\to\branchpoint\dist\index.js instead of using npx, remember the config file is JSON: backslashes need to be escaped (C:\\path\\to\\...) or replaced with forward slashes (C:/path/to/...), or a raw Windows path will fail to parse or get silently mangled.

npm install or yarn install fails or warns inside a cloned copy of this repo. The project pins pnpm via devEngines.packageManager in package.json; install pnpm and use pnpm install instead.

Everything returns "detached HEAD" / no active branch. You're on a bare commit checkout or mid-rebase, where Git itself has no current branch name. This is a normal Git state, not a Branchpoint error: run git checkout <branch> to return to a branch, and context tracking resumes.

Where is my data, and how do I delete it? Context lives as one markdown file per branch under .git/branchpoint/, rooted at the repository's shared .git directory (so it's the same store across every worktree of a repo, not duplicated per worktree). To wipe everything: delete the branchpoint folder there. To remove a single branch's context: delete its corresponding .md file (or its parent folder, for branches with / in the name).

Roadmap

• Publish to npm (the package is ready; npm publish is a manual step pending final review).
• Detect and optionally clean up orphaned context (branches that were deleted but still have a saved summary).
• Commercial version (teams, remote sync) built on top of this open-source core.

License

MIT