Connect your agent

Pensieve for Claude Code

This page tells you how to connect Claude Code to Pensieve over MCP, and what changes on your computer.

Connect Claude Code

Install Pensieve (see Install).

Run one of these commands:

pensieve integrate recommended   # every agent on this computer
pensieve integrate claude-mcp claude pensieve-search   # only Claude Code

Restart Claude Code. It loads its MCP servers when it starts.
Ask Claude Code a question about your code, for example “where do we retry failed webhooks?”.

What Pensieve adds

Add-on	Id	File
MCP server	`claude-mcp`	`~/.claude.json` (through `claude mcp add --scope user`)
Instructions block	`claude`	`~/.claude/CLAUDE.md`
Skills	`pensieve-search`	a link to `~/.agents/skills` in `~/.claude/skills`

The instructions block goes in ~/.claude/CLAUDE.md, between  markers.

Or install the Claude Code plugin

The plugin gives Claude Code the MCP server, the four skills, the instructions block and the four recommended hooks. It does not change your settings files. Install Pensieve first, because the plugin starts ~/.local/bin/pensieve. Then type these commands in Claude Code:

/plugin marketplace add TedHaley/pensieve
/plugin install pensieve@pensieve

Use the plugin or pensieve integrate for Claude Code, not both. When the plugin is installed, pensieve integrate skips the Claude Code MCP server, instructions block, hooks and skill link.
The plugin's tools have names that start with mcp__plugin_pensieve_pensieve__.
If the backend uses another port, set PENSIEVE_PORT in the environment that starts Claude Code.

Hooks for Claude Code

pensieve integrate recommended adds four hooks to ~/.claude/settings.json:

Hook	Event	What it does
`claude-hook`	PostToolUse	After each Edit or Write, it sends the changed path to Pensieve. The next search finds the new code. It adds about 50 ms to each edit.
`claude-repo-check`	SessionStart	In a repo that Pensieve does not index, Claude asks you once whether to index it. Pensieve keeps your answer. In a repo that Pensieve indexes, it adds one line: the number of loose ends and the thread closest to done. Claude then offers to close it at a natural pause.
`claude-prompt-search`	UserPromptSubmit	Pensieve adds what the prompt needs: a thread, your list of threads, who knows the code, past sessions, or the 5 best code matches. It adds about 300 ms and 400 to 1,500 tokens.
`claude-search-gate`	UserPromptSubmit, PostToolUse, PreToolUse	In a repo that Pensieve indexes, Claude can't run Grep, Glob, `grep`, `rg`, `ag`, `find` or `git grep` in a turn until it calls a Pensieve tool. The prompt hook's results count as that call. Filtering output stays allowed. If Pensieve isn't running, nothing is blocked. One session in 5 runs without blocking, as a control group.

Slash commands, prompts of 1 or 2 words, and repos that Pensieve does not index get nothing from the prompt hook.

Connect by hand

claude mcp add --scope user pensieve -- pensieve mcp      # every project, scope "auto"
claude mcp add pensieve -- pensieve mcp --scope payments     # this folder only, a named scope
claude mcp add --transport http pensieve "http://127.0.0.1:8765/mcp?scope=payments"

Without --scope user, claude mcp add connects only the folder that you run it in. Claude Code shows the tools as mcp__pensieve__search, mcp__pensieve__read and more.

Remove

pensieve integrate claude-mcp claude --remove

Pensieve removes only the entries that it added.

See also: scopes, the MCP tools, and the benchmark.

Something wrong or missing? Tell us on GitHub.