# Set up ClarifyDoc — instructions for a coding agent

Paste this page (or its URL, https://clarifydoc.com/setup.md) into your coding agent and ask it to set
ClarifyDoc up for the project you have open.

ClarifyDoc maps a codebase from its source: screens → API calls → backend routes → database tables, joined
across languages and repositories. Its MCP server lets you, the agent, ask that map questions — "who calls
`PUT /orders/{id}`?", "which tables does this screen write?", "what breaks if I change this file?" — and get
short answers with `path:line` references instead of reading whole files. Everything runs locally: no
account, no telemetry, nothing uploaded, no model in the pipeline.

## For the agent

Do these steps in order. Show the user each command before running it, and stop to ask when a step says so.

### 1. Install the VS Code extension

The extension carries the analyzer, the MCP server and a Node runtime, so nothing else needs installing.

```sh
code --install-extension ClarifyDoc.clarifydoc-vscode
```

Use `cursor`, `windsurf` or `codium` instead of `code` for those editors (they install from Open VSX).

**No VS Code-family editor?** Install the CLI from npm instead (it needs Node.js), use `clarifydoc` as
`$CLARIFYDOC` below, and skip step 2:

```sh
npm install -g clarifydoc
```
If the user's editor already has GitHub Copilot, its agent mode picks up the MCP server by itself after
step 3 — skip step 4 for Copilot.

### 2. Find the launcher

The extension writes a launcher the first time the editor starts with it. Its path does not change between
extension versions, so it is safe to write into config files:

| OS | Launcher (`$CLARIFYDOC` below) |
|---|---|
| macOS | `~/Library/Application Support/Code/User/globalStorage/clarifydoc.clarifydoc-vscode/bin/clarifydoc` |
| Linux | `~/.config/Code/User/globalStorage/clarifydoc.clarifydoc-vscode/bin/clarifydoc` |
| Windows | `%APPDATA%\Code\User\globalStorage\clarifydoc.clarifydoc-vscode\bin\clarifydoc.cmd` |

For Cursor, Windsurf or VSCodium, replace `Code` with `Cursor`, `Windsurf` or `VSCodium`.
**If the file is not there, ask the user to open the editor once, then look again.**
Check it with `"$CLARIFYDOC" --version`.

### 3. Analyze the project

From the project root:

```sh
"$CLARIFYDOC" analyze . --incremental --no-lsp
```

The map is written to `.clarifydoc/` in the project. Suggest adding `.clarifydoc/` to `.gitignore`. A large
repository can take a few minutes the first time; re-runs read only the files that changed.

### 4. Connect the MCP server to your own client

Print what would be written first, and show it to the user:

```sh
"$CLARIFYDOC" install . --client <client> --command "$CLARIFYDOC" --print
```

`<client>` is one of `claude-code`, `cursor`, `vscode`, `windsurf`, `gemini`, `codex`, `claude-desktop`,
`zed`, `opencode`, `cline`, `kilo` or `copilot`. When the user agrees, run it again without `--print`. The
entry is merged into the client's existing config.
How each client reloads its servers and lists them: one page per client (all but `kilo`), at
`https://clarifydoc.com/mcp-<client>.html` (for example https://clarifydoc.com/mcp-cursor.html).

Optional, **only if the user asks**:

- `--skills` — one skill per ClarifyDoc workflow (before editing, trace a feature, review a branch, …);
- `--hooks` — what the map knows, added beside searches and edits (never blocks a tool call);
- `--guidance` — a short marked section in `AGENTS.md` telling agents when to ask the map. This edits a file
  the user's team shares, so confirm first.

### 5. Reload and confirm

Restart the client or reload its MCP servers. Then call `clarifydoc_status`. It should name the project root,
when it was analyzed, and how many routes, screens and tables were found. If it says no analysis was found,
run step 3 from the project root.

A good first question: call `clarifydoc_routes` with a path you know, or `clarifydoc_search` with the name of a
screen, and check that the answer's `path:line` references open the right code.

## What the server offers

<!-- fact:mcp.tools -->23<!-- /fact --> tools, all read-only except `clarifydoc_analyze` and `clarifydoc_diff` (which
write only to `.clarifydoc/`); <!-- fact:mcp.prompts -->8<!-- /fact --> workflow prompts; resources for the
analysis status, its schema, the project's detected languages and frameworks, and the session's token usage. `--tools core` offers a smaller set of
<!-- fact:mcp.coreTools -->8<!-- /fact --> tools for a host that already runs many servers. The full list, with
when to call each one: https://clarifydoc.com/agents.html#tools

## Keeping it current

The extension re-analyzes after saves in small projects. Otherwise run step 3 again, or call
`clarifydoc_analyze`, which re-reads only changed files. The launcher keeps working across extension
updates.

## Removing it

Uninstall the extension, delete `.clarifydoc/`, remove the `clarifydoc` entry from the client's MCP config,
and — if they were added — the `.claude/skills/clarifydoc-*` folders, the ClarifyDoc hooks, and the block
between `<!-- clarifydoc:start -->` and `<!-- clarifydoc:end -->` in `AGENTS.md`. Details:
https://clarifydoc.com/index.html#uninstall

## What leaves the machine

Nothing, with these steps. Every network request any part of ClarifyDoc can make, and what starts it:
https://clarifydoc.com/trust.html