Claude Code integration

How to give Claude Code the CodeLoupe tools. Two ways to connect, both ending in the same MCP server (http://127.0.0.1:47391/mcp, header x-codeloupe: 1; the daemon token reaches it through a headers helper, never in the configuration). codeloupe must be on PATH (the bundle's bin/) for the session hook; without it the plugin still works while the daemon runs (tray app, codeloupe start).

1. Plugin (recommended)

MCP server, a skill saying which tool to use when, and a SessionStart hook that runs codeloupe start, so the daemon is up with the session. The repository is its own marketplace:

claude plugin marketplace add Terrio-cz/CodeLoupe      # or the path of a checkout / the app's claude-plugin folder
claude plugin install codeloupe@codeloupe              # --scope user (default) | project | local

The plugin lives in plugin/ (.claude-plugin/plugin.json, .mcp.json, hooks/, skills/codeloupe/) and the marketplace manifest in .claude-plugin/marketplace.json. Check changes with claude plugin validate plugin and claude plugin validate . (each reports one warning, No version specified, on purpose: see below, so not --strict); try it for one session without installing: claude --plugin-dir plugin. What the hook does and its settings: Hooks and token savings. The skill, SKILL.md, is the agent's routing table (which tool instead of which grep or read); this wiki's Tools reference is for people.

Plugin version and updates

Claude Code offers a plugin update when the plugin's version changes, and only then. Two copies exist:

• From GitHub (marketplace add Terrio-cz/CodeLoupe): plugin.json in the repository has no version, so Claude Code versions the plugin by the commit. claude plugin marketplace update codeloupe && claude plugin update codeloupe@codeloupe brings the latest main. A pinned version there would keep every install on its first copy for good (the plugin said 0.1.1 through seven releases, CL-255); a test (tools/plugin-version.test.mjs) keeps it unversioned.
• From the app: the installer ships claude-plugin/ with the app's version in every plugin.json (stamped by the afterPack hook, so a release carries the release version and the installer smoke test checks it). After an app update the same two commands bring the installed plugin to that version; Settings → Claude Code shows both versions and says when they differ.

2. MCP entry only

No skill, no autostart:

claude mcp add-json --scope user codeloupe '{"type":"http","url":"http://127.0.0.1:47391/mcp","headers":{"x-codeloupe":"1"},"headersHelper":"codeloupe mcp-headers"}'

codeloupe mcp-config prints that entry for your port. headersHelper runs codeloupe mcp-headers on each connection; it prints the x-codeloupe header and, once the daemon has proved it holds <home>/daemon.token, the token, so the secret never sits in Claude Code's configuration. Without the helper (claude mcp add ... --header "x-codeloupe: 1", the entry older versions made) every tool says that it needs the token, unless api.strict is false (then only run, env, edit and job do); see Who may call the daemon. The plugin's .mcp.json has the helper (hooks/mcp-headers.cmd, which runs hooks/mcp-headers.sh), so a plugin install or update needs no extra step. Claude Code runs a headersHelper through the platform shell (cmd.exe on Windows), unlike the hooks, which it runs under Git Bash; a bare bash there can be the WSL launcher in System32, which cannot read a Windows path and leaves the client without the token (Dynamic Client Registration rejected (HTTP 401)). So the entry is sh "<plugin>/hooks/mcp-headers.cmd" || "<plugin>/hooks/mcp-headers.cmd": sh (macOS, Linux) starts the bash script; on Windows, which has no sh, cmd.exe runs the same file, which looks for Git Bash (CLAUDE_CODE_GIT_BASH_PATH, Program Files\Git, the git on the PATH) and never runs a bare bash. Without Git Bash it prints the plain x-codeloupe header, so the read-only tools still work.

Your own agents (subagents with a tools: list)

A connected server is not enough for an agent you define yourself. In a controlled run of a reviewer agent that had the tools in its tools: list and one bullet about them in its body, 0.2 CodeLoupe calls per run came out (1 run of 10); it kept to cd <worktree> && rg …. Adding grep to tools: alone changed nothing (0 of 4 runs); a short routing table in the body together with grep in tools: did (6.0 calls per run, 9 of 10 runs; 2.8 with the table but no grep).

• List what you want it to use in tools:, mcp__codeloupe__grep included: it answers the text, string, SQL and regex searches that make up most of an agent's rg calls, and is the tool most often forgotten.

• Put the routing table in the body, imperative, and say what rg is left for:

  Code: call mcp__codeloupe__* (root = the worktree) before rg, sed, cat or a whole Read: a symbol → symbol / context; users → usages, callers → calls; what the branch changed → changes; members of a file → outline, always before a Read of a .kt over 200 lines; a text, string, SQL or regex → grep; a name → find. Read offset/limit only for lines they did not show, rg -n only for non-Kotlin files.

  A softer last sentence ("Read and rg -n for the rest") brought the calls back to 1.5 per run.

• The plugin's steering hook (Plugin hooks) is not a substitute: in advise mode (the default) it spoke 6-8 times per run and the agent did not follow it once; in redirect mode the first rg over source is refused with the equivalent call, and 4 of 4 runs used the tools. The hook belongs to the plugin, so it does not run for an agent in a workspace where the plugin is not installed.

What this buys is adoption, not tokens: the same runs cost the same (median 333 against 323 thousand weighted units, findings unchanged), because more than half of the tool results of a review run is the review packet the agent reads whole; CodeLoupe only replaces the searches and range reads around it. Numbers, method and limits: Agent runs.

From the desktop app

Settings → Claude Code shows whether claude is found and what is connected, and the buttons Connect plugin… and Add MCP server only… run exactly the commands above (after a native confirmation that lists them, with the daemon's current port), through the claude CLI, so Claude Code writes its own configuration. Without claude on PATH the card shows the commands to run by hand. The plugin is added from the marketplace folder next to the app (resources/claude-plugin when packaged, CODELOUPE_PLUGIN_DIR to override, the repository root in a development run); the installers ship .claude-plugin/marketplace.json and plugin/ there. The card shows the installed plugin's version next to the one the app ships and flags a difference with the commands that refresh it. The plugin's session hook looks for codeloupe on PATH; an installed app does not put it there, so set CODELOUPE_BIN to <install>/resources/codeloupe/bin/codeloupe (.bat on Windows) or add that directory to PATH.

Another port

A daemon on another port: set CODELOUPE_PORT for it and for Claude Code (the plugin's URL reads it); for the MCP entry the app writes the port it watches, and codeloupe mcp-config prints the entry for the configured one.

If the tools fail

connection refused or an MCP server shown as failed means the daemon is not running: run codeloupe start, then reconnect the MCP server with /mcp. More in FAQ and troubleshooting.