Claude Code setup

Install the CLI

Paste this into your terminal — it downloads the latest release of the commitmind binary into ~/.local/bin/, then prints the next-step hints.

$ curl -fsSL https://commitmind.dev/install.sh | bash

Then run commitmind init once per repo (or commitmind onboard for the guided wizard). This binds the repo to a CommitMind project — mints the repo-scoped agent token, registers the repo with the local indexer, installs the git hooks, and runs the commit backfill. It does not touch your Claude Code config; wiring CommitMind into Claude Code is the plugin's job (next step).

Heads up. This page is for Claude Code — Anthropic's CLI (the claude binary). If you're using Claude Desktop (the macOS / Windows native app), see Claude Desktop setup instead. The two products are independent and read MCP config from different files.

Install the plugin

CommitMind ships as a Claude Code plugin that wires everything agent-side in one step — the MCP servers, the deterministic hooks, and the routing skills:

/plugin marketplace add commitmind/claude-plugin
/plugin install commitmind@commitmind

The plugin's MCP servers exec your locally-installed commitmind binary, so the CLI install + commitmind init above are prerequisites. The agent token is repo-scoped, so run commitmind init in each repo you want CommitMind in — but the plugin install itself is one-time per machine. Restart Claude Code after installing so it picks up the MCP servers and hooks.

What the plugin wires

MCP servers — commitmind (memory + tasks) and commitmind-code (xref + code-intel). Both enabled.
Hooks — deterministic gates that fire before tool execution: anchor-distinct-concerns on Edit/Write, commit-before-advance on task_advance, memory-routing redirects for git log / grep-on-identifier patterns, and a lean SessionStart prime. These fire only on the local Claude Code CLI.
Skills — advisory routing for memory / code / playbook flows, lazy-loaded by description match.

Manual alternative (without the plugin)

If you'd rather not use the plugin — or want only the MCP tools without the hooks/skills layer — wire the MCP servers yourself. The quickest way is the surgical init flag, which writes the per-project .mcp.json for you without re-running onboarding:

commitmind init --mcp-config-only=claude-code

Or do it by hand. Claude Code reads MCP server definitions from a .mcp.json file at the repo root:

<repo>/.mcp.json

This is the same path Anthropic recommends for project-scoped MCP servers. Per-project config is the right default because the CommitMind agent token is repo-scoped — it lives under ~/.config/commitmind/tokens/<repo_hash>.json, keyed on the git remote of the repo you ran init in.

The exact block commitmind init writes (memory + code — enable both in the host):

{
  "mcpServers": {
    "commitmind": {
      "command": "commitmind",
      "args": ["mcp", "serve"]
    },
    "commitmind-code": {
      "command": "commitmind",
      "args": ["mcp", "serve-code"]
    }
  }
}

If .mcp.json already exists with other MCP entries, commitmind init --mcp-config-only preserves them — it only touches its own commitmind and commitmind-code keys.

If you point CommitMind at a non-default backend, the env block is included automatically:

{
  "mcpServers": {
    "commitmind": {
      "command": "commitmind",
      "args": ["mcp", "serve"],
      "env": {
        "COMMITMIND_BACKEND_URL": "https://api.commitmind.dev"
      }
    },
    "commitmind-code": {
      "command": "commitmind",
      "args": ["mcp", "serve-code"],
      "env": {
        "COMMITMIND_BACKEND_URL": "https://api.commitmind.dev"
      }
    }
  }
}

Restart Claude Code in the repo after editing .mcp.json.

Imperative alternative: `claude mcp add`

If you'd rather skip JSON entirely, Claude Code's CLI accepts an imperative command that writes the same per-project entry for you:

claude mcp add commitmind --scope local -- commitmind mcp serve

--scope local writes the entry into the repo's .mcp.json — equivalent to what commitmind init does. Use --scope user to write to the user-global ~/.claude.json instead, but per-project is recommended so each repo's MCP server picks up the right token.

Tools

CommitMind exposes a focused MCP tool surface. Claude picks them up automatically once the server is connected.

`prime_session`

Loads a compact bundle of project context: the last N commits, active (non-stale) decisions, and recent high-signal observations. When the session has an active task pinned, the active task's title, current phase, last manual transition note, and recent linked observations + decisions are delivered as the first block of the output.

Claude will usually call this on its own when you ask something like "what do you remember about this project?" — no prompting required.

`search_memory`

Hybrid retrieval across your project's memory: full-text search fused with vector similarity over observations, decisions, and commit summaries. Great for questions like "why did we switch to OAuth 2.1 PKCE?" — it finds the decision plus related context. (Also registered on the commitmind-code MCP host so agents can reach it from the code side when routing tables point there.)

`log_observation`

Captures a note during a session. Use it when Claude discovers something worth remembering — an invariant, a gotcha, a repo-local convention — so the next session starts knowing it too.

When a task is pinned via task_set_active, every log_observation call inherits its task_id automatically — no extra arguments needed.

`promote_decision`

Promotes an observation to an explicit architectural decision with a status (proposed, accepted, rejected, superseded) and an author. Decisions show up in the dashboard and in every future prime_session call until they're superseded.

When a task is pinned, decisions auto-link to it the same way observations do.

Task tools

Six tools manage the project-scoped task lifecycle (discovery → design → implementation → review → done). When a task is pinned via task_set_active, every log_observation, every promote_decision, and every commit ingested in that session automatically links to the task.

task_create(title, description?) — start a new task; defaults to the discovery phase.
task_advance(task_id, to_phase, note?) — move forward through the lifecycle. Reverse moves are rejected; terminal states (done, abandoned) are sticky.
task_set_active(task_id?) — pin which task this session works on. Omit task_id to unpin.
task_get_active() — returns the active task, recent linked observations, and recent linked decisions in one round-trip.
task_list(include_terminal?, limit?) — browse all tasks for the project.
task_complete(task_id, note?) — convenience wrapper for moving a task to done.

See Task planner for the full workflow, the phase model, and the auto-summary worker that writes per-phase retrospectives.

Troubleshooting

MCP server not connecting

Run through the checklist:

Agent token present. commitmind status should show a logged-in user and a linked project. If not, re-run commitmind init.
Plugin installed (plugin route). Run /plugin in Claude Code and confirm commitmind@commitmind is listed and enabled. If you wired MCP manually instead, check that .mcp.json is in the repo root (cat .mcp.json should show the commitmind entry) — per-project MCP only loads when you launch Claude Code from inside the repo.
Backend URL reachable. curl https://api.commitmind.dev/healthz from the machine where Claude Code runs. Corp VPNs occasionally block it.
Claude Code restarted. MCP config is read on session start — exit and relaunch after any edit.
Tool listing. Inside a Claude Code session, ask "what MCP tools do you have?" — mcp__commitmind__* entries should appear. If they don't, the server isn't loaded; check claude mcp list for status.

The `commitmind` binary isn't found

Claude Code inherits your login shell's $PATH. If commitmind works in your terminal but not from Claude, point the MCP config at an absolute path:

{
  "mcpServers": {
    "commitmind": {
      "command": "/Users/you/go/bin/commitmind",
      "args": ["mcp", "serve"]
    },
    "commitmind-code": {
      "command": "/Users/you/go/bin/commitmind",
      "args": ["mcp", "serve-code"]
    }
  }
}