HOW IT WORKS
The analysis is done once. Every question after that is a lookup.
Text search answers “where does this string appear?”. An agent usually needs “who calls this, across the HTTP boundary, and what does it write?” — which grep can only approximate by reading everything it finds. ClarifyDoc has already joined those facts.
Analyze
VS Code analyzes the workspace (or clarifydoc analyze does). Screens, routes, calls, data access and their links are written to .clarifydoc/ beside the code.
Serve over MCP
A local MCP server reads that analysis and speaks to the agent over stdio. No network, no account, nothing uploaded; it finds the project from the agent’s working directory.
The agent asks
Routes, callers, the data a screen reaches, what a diff breaks. Each answer is cut to what was asked, with path:line for every fact, so the agent opens only the lines it needs.
It stays current
Re-runs re-read only the files that changed, and VS Code can run them on save. clarifydoc_status says how fresh the map is, and clarifydoc_analyze refreshes it on request.
FEWER TOKENS, FEWER WRONG GUESSES
An answer instead of a reading list
Measured, not estimated from the whole repository: each answer is compared with the files a person would open to answer the same question, using the same ~4-characters-per-token estimate on both sides.
“What does PUT /user take, who calls it, what does it write?” ≈60 tokens from clarifydoc_routes, against ≈2,180 for the four files involved. Conduit example.
“What breaks if I change agent.js?” ≈1,090 tokens from clarifydoc_blast_radius, against ≈10,900 for the file and its 17 direct dependents. Conduit example.
The benchmark: questions labelled by hand on real repositories at pinned commits, scored against only the files that hold the answer. An answer that misses what it should name counts as no saving.
Tokens, the most one answer costs by default. Longer answers stop there with a next-page offset and a note on how to ask for less.
The benchmark covers three questions so far, and we say so; the method and every number are in the CLI’s accuracy section.
Why the answers stay small
Budgets the agent sets
clarifydoc_explain packs a route, screen, function or file into maxTokens in priority order — contract and callers, the data it reaches, the handler’s source, its blast radius — and names the calls for whatever didn’t fit.
One function, not one file
clarifydoc_extract returns a function’s source and the functions it calls, breadth-first, cut to a budget. Callees that don’t fit are listed with their size, so the agent decides.
A smaller tool list when you need it
--tools core offers eight tools — status, search, explain, trace, file, extract, impact, analyze — under half the up-front cost of the full set, for a host already running many servers.
No silent “everything”
A misspelt argument or filter value is refused with the nearest valid spelling (paths → did you mean path?), instead of being ignored and returning every row.
Measure it yourself
The clarifydoc://session/usage resource lists every call of the session with its answer size and time; CLARIFYDOC_MCP_LOG appends them to a local file, with the session’s totals.
Asked before it greps
With hooks — one tick in VS Code’s setup — a search the agent is about to run is answered first with what the map knows about that name, and an edit is followed by who depends on the file. A hook never blocks a tool call.
WHAT YOUR AGENT CAN ASK
23 tools, all read-only but two
Every answer comes from facts extracted from the source — never from a model — and each cross-file link says whether it was extracted, inferred or ambiguous, so the agent knows which ones to check.
Find and orient
- clarifydoc_status
- What is mapped, how fresh it is, and how much of each kind of fact exists. Start here.
- clarifydoc_search
- Routes, screens, files, symbols, entities and API calls by name — or functions by what their code says.
- clarifydoc_explain
- One route, screen, function or file, packed into a token budget.
- clarifydoc_context_docs
- Decision records, architecture and glossary docs, schema dumps — each flagged when the files it names changed after it.
- clarifydoc_facts
- Routes, screens, entities and links as stable IDs (
[R-3fa2c1]) a document can cite — and a check of the IDs a text cites against the current code.
Endpoints and screens
- clarifydoc_routes
- Every route with its handler, guards, the frontend calls that reach it and what it reads and writes;
gapsfor calls that reach no route and routes nothing calls. - clarifydoc_contract
- One endpoint as an OpenAPI operation: auth, versions, each parameter’s binding, the request body — and who calls it.
- clarifydoc_screens
- Screens with their route, the endpoints they call and the dialogs they open.
- clarifydoc_services
- Which service calls which, over HTTP or a queue, with the endpoints behind each edge.
Code and calls
- clarifydoc_trace
- Callers and callees of a symbol, N hops, through dependency injection and across the HTTP boundary;
togives the path between two symbols. - clarifydoc_extract
- A function’s source and the functions it calls, cut to a budget.
- clarifydoc_file
- One file: its functions and complexity, routes, data access, callers, findings and blast radius.
- clarifydoc_control_flow
- A function as a flowchart, or the statements that can affect the values used at one line.
- clarifydoc_sequence
- What a route or function does, in order — its calls, data access and HTTP hops — as a Mermaid sequence diagram.
Data
- clarifydoc_data_model
- Entities and tables with columns, keys and relationships, and the functions that read or write each one.
- clarifydoc_data_flows
- Which screens and routes reach a table write, a queue or an outbound call, through how many hops.
Before and after a change
- clarifydoc_impact
- What the current diff — or a proposed new version of a file — reaches: screens, routes, tables, signature breaks, owners, files usually changed with it, and the tests to run as the runner’s own command.
- clarifydoc_blast_radius
- What breaks if a file changes: dependents, screens, routes and tables, with a verdict and how much must be read to edit it safely.
- clarifydoc_diff
- How the API surface changed since a git ref: routes, parameters, bodies, guards, links and data reached, each marked breaking or risky. Analyzes the ref once and caches it in
.clarifydoc/.
Quality and structure
- clarifydoc_health
- The grade and its findings: security, layer violations, complexity, duplicates, dead code, performance, refactor pressure.
- clarifydoc_architecture
- Folder dependencies, communities, hub files, import cycles and files that change together.
- clarifydoc_export
- A whole-project document or diagram: ARCHITECTURE.md, DATA-MODEL.md, FLOWS.md, Mermaid, GraphML, Cypher, CSV.
- clarifydoc_analyze
- Re-run the analysis, incrementally, and write
report.htmlwhen asked. Withclarifydoc_diff, the only tools that write anything — and only to.clarifydoc/.
A REAL ANSWER
“Before I change PUT /user, what do I need to know?”
One call to clarifydoc_explain on the Conduit example returns the
endpoint’s contract and guard, the frontend call that reaches it, the handler’s call path down to the
table it writes, the tests that cover it — none, here — and the other routes sharing that table. About
960 tokens; shortened below to fit, paths included.
- Every fact carries the file and line it came from
- Links the analysis could only infer are marked
[inferred] - The same answer for the same commit, every time
# agent → clarifydoc_explain { subject: "PUT /user" }
# PUT /user — inline handler (auth.controller.ts:61)
## Contract and callers
guards: auth.required
called from: frontend/src/agent.js:37
## What it reaches
- updateUser() auth.service.ts:151
- generateToken() token.utils.ts:3
- db-write User — via updateUser() [inferred]
## Tests
None of the analysed tests reaches it.
## Routes sharing its tables
- POST /users — reads and writes User
- POST /profiles/:username/follow — writes User
…CONNECT YOUR AGENT
Set it all up from VS Code
The extension carries the analyzer, the MCP server and the installer for the server, its skills and its hooks. Nothing to build, no Node.js, no paths to type — and the config points at a launcher that survives extension updates, so it never goes stale.
Install the extension
From the Marketplace, or Open VSX for Cursor, Windsurf and VSCodium. Copilot’s agent mode picks up the server right away — nothing else to do for Copilot.
Set Up MCP for an AI Agent…
Pick Claude Code, Cursor, Windsurf, Gemini CLI, Codex or Claude Desktop. The command writes that agent’s MCP config, merged into what is already there.
Tick hooks and skills
For Claude Code, the same command offers Hooks — what the map knows, beside each search, edit and new session — and Skills, one per ClarifyDoc workflow. Both optional; a hook never blocks.
Tell it when to ask
Tell Agents When to Use It adds a short section to AGENTS.md — or the Copilot instructions file or Cursor rule the project already has — after showing you the diff.
code --install-extension ClarifyDoc.clarifydoc-vscodeStep by step for your host — install, reload, the first question to type, how to check it worked, how to remove it:
Without VS Code? The CLI does the same — clarifydoc install writes the entry for
Claude Code, Cursor, VS Code, Gemini CLI, Zed, OpenCode, Windsurf, Codex, Claude Desktop or Cline, with
--hooks --skills --guidance, and --plugin lays out a plugin bundle for Claude Code,
Codex and Copilot CLI. It is on npm:
npm install -g clarifydoc, then any client takes this entry (or "command": "npx", "args": ["-y", "clarifydoc", "mcp"]
without installing):
// .mcp.json, .cursor/mcp.json, … — the server finds the project from the agent's working directory
{
"mcpServers": {
"clarifydoc": { "command": "clarifydoc", "args": ["mcp"] }
}
}BEYOND SINGLE QUESTIONS
Workflows, hooks and guidance
Eight ready-made workflows
Served as MCP prompts, and as Claude Code skills when you tick them in setup: before editing a file, before changing an endpoint, trace a feature from screen to table, explain a screen, endpoint gaps, before writing (does a helper already exist, and what does the installed package export), refactor (a rename, move or split checked against a baseline), and review a branch. In VS Code, Ask an AI Agent… starts one from where your cursor is.
Hooks that inform, never block
Before a search: what the map knows about the name. After an edit: who depends on the file and what to run before finishing. At session start: what the map covers and how fresh it is. One tick in VS Code’s setup; silent on any error.
A section in AGENTS.md
A short, marked section — or a Copilot instructions file or Cursor rule, where the project has those — tells the agent when to ask the map instead of searching text, and what this project’s analysis says it should know first.
A plugin bundle
clarifydoc install --plugin lays out the MCP entry, the skills and a read-only explorer subagent for Claude Code, Codex and Copilot CLI in one directory.
Safe to hand to an agent
- Local stdio server — no network, no account, no telemetry
- Read-only: only
clarifydoc_analyzewrites, and only to.clarifydoc/ - Deterministic: the same commit gives the same answers
- Refuses to map your home directory or a filesystem root unasked
- Every list is capped; long answers page instead of flooding the context
- MIT-licensed — read the server yourself