ClarifyDoc Install

For AI agents · Claude Code

ClarifyDoc in Claude Code. One command, then ask.

Give Claude Code (Anthropic’s coding agent in the terminal and in your editor) a map of your codebase: which screen calls an endpoint, which tables it touches, what an edit breaks. It asks ClarifyDoc’s MCP server and gets short answers with path:line references instead of reading whole files. Local, read-only, no account.

npm install -g clarifydoc && clarifydoc install . --client claude-code
// .mcp.json — what clarifydoc install . --client claude-code writes
{
  "mcpServers": {
    "clarifydoc": {
      "command": "clarifydoc",
      "args": [
        "mcp"
      ]
    }
  }
}

SET IT UP

From install to the first answer

  1. Install ClarifyDoc and connect Claude Code

    The CLI is on npm and needs Node.js. From the project root, the second command merges the entry into Claude Code’s config and keeps everything else in it. Add --print to see what it would write first.

    npm install -g clarifydoc && clarifydoc install . --client claude-code

    Or let Claude Code add it: claude mcp add clarifydoc -- clarifydoc mcp.

    With the VS Code extension instead: VS Code’s ClarifyDoc: Set Up MCP for an AI Agent… offers Claude Code too: through claude mcp add when the claude command is installed, or as this project’s .mcp.json.

  2. Where the entry goes

    .mcp.json in the project

    The entry names no project: the server serves the folder Claude Code runs in, so the same file works for everyone who opens the project.

    {
  "mcpServers": {
    "clarifydoc": {
      "command": "clarifydoc",
      "args": [
        "mcp"
      ]
    }
  }
}

  3. Reload Claude Code

    Start a new session with claude in the project folder. The first time, Claude Code asks whether to use the servers in the project’s .mcp.json: approve clarifydoc.

  4. Ask the first question

    Type this as it is. If the project has no analysis yet, the first call makes one; a large repository can take a few minutes, and every analysis after it reads only the files that changed. To have it ready first, run clarifydoc analyze . from the project root.

    Call clarifydoc_status, then use clarifydoc_routes to pick one API route. Tell me which screen calls it and which tables it reads and writes, with path:line for each.

    Then one about your own change:

    Before I change <a file you know>, what depends on it and which tests should I run?

  5. Check that it worked

    clarifydoc_status answers with the project root, when it was analyzed and how many routes, screens and tables were found. If it says no analysis was found, the server is looking at another folder: start Claude Code from the project root.

    /mcp lists the server as connected, with its tools.

  6. Keep it current

    Ask the agent to call clarifydoc_analyze, or run clarifydoc analyze . --incremental: either re-reads only the files that changed. clarifydoc install --git-hooks does it in the background after each commit, merge and branch checkout. To update ClarifyDoc itself, npm install -g clarifydoc@latest (the extension updates itself, and its launcher keeps its path), then reload Claude Code.

  7. Remove it

    Delete the clarifydoc entry from .mcp.json (or claude mcp remove clarifydoc if you added it that way). If you added them: the hooks whose command runs clarifydoc hook in .claude/settings.json, and the .claude/skills/clarifydoc-* folders. Delete .clarifydoc/ in the project, and npm uninstall -g clarifydoc. If you asked for them, --guidance wrote between <!-- clarifydoc:start --> and <!-- clarifydoc:end --> in AGENTS.md, and --git-hooks between # clarifydoc:start and # clarifydoc:end in the repository’s git hooks. Nothing else is written.

OPTIONAL

More than the server

Each is a flag on the same clarifydoc install command, off unless you ask for it, and --print shows it before anything is written.

Hooks

--hooks adds hooks to .claude/settings.json: before a search (Grep, Glob, a grep or rg in Bash) the agent is told what the map knows about the name; after an edit, who depends on the file; at session start, how fresh the map is. A hook never blocks a tool call.

Skills

--skills writes one skill per workflow — eight of them, from before editing a file to reviewing a branch — into .claude/skills/clarifydoc-*.

A plugin bundle

clarifydoc install --plugin ./clarifydoc-plugin writes a plugin directory — the server entry, the skills and a read-only clarifydoc-explorer subagent — that Claude Code loads with claude --plugin-dir ./clarifydoc-plugin.

A section in AGENTS.md

--guidance adds a short, marked section to AGENTS.md that tells agents when to ask the map instead of searching text, and what this project’s analysis says to know first. It edits a file your team shares, so --print it first.

WHAT IT ANSWERS

23 tools, all read-only but two

Routes and who calls them, the tables a screen reads and writes, the call path between two functions, what a diff reaches, one function’s source instead of its file. Only clarifydoc_analyze and clarifydoc_diff write, and only to .clarifydoc/. Nothing leaves your machine — every network request any part can make.

Every tool Open a live report

OTHER HOSTS

The same server, elsewhere

VS CodeCursorWindsurfCodexGemini CLICopilot CLIZedOpenCodeClineClaude DesktopInstructions for an agent (setup.md)