# Claude Setup

`prodex` exposes a stdio MCP server so Claude can create bridge tasks, inspect task/result/session/receipt records, read/search the current repo, and request receipt-gated text-file edits.

## Build

Requires Node.js 20 or newer, `git`, and `ripgrep` (`rg`) on PATH.

Install with `npm install -g @youdie006/prodex` (note the scope — the unscoped `prodex` on npm is an unrelated package; do not install it). Once installed, `prodex` is on your PATH and you can use `prodex mcp` directly.

The installed npm package is CLI-only. Use the `prodex` command and MCP server surfaces; JavaScript imports from `prodex` or `prodex/dist/*` are unsupported until a library API is designed and documented.

For a source checkout:

```bash
cd /absolute/path/to/prodex
npm install
npm run build
```

## Claude Desktop

Generate a Claude Desktop MCP config:

```bash
prodex claude config --cwd /absolute/path/to/your/repo
```

It prints this token-free JSON:

```json
{
  "mcpServers": {
    "prodex": {
      "command": "prodex",
      "args": ["mcp", "--cwd", "/absolute/path/to/your/repo"]
    }
  }
}
```

For a source checkout instead of an installed package, first build the project, then generate a `node dist/cli.js` config:

```bash
node dist/cli.js claude config --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js
```

It prints this shape:

```json
{
  "mcpServers": {
    "prodex": {
      "command": "node",
      "args": ["/absolute/path/to/prodex/dist/cli.js", "mcp", "--cwd", "/absolute/path/to/your/repo"]
    }
  }
}
```

Restart Claude Desktop after editing the config.

## Claude Code

Use the same command shape in Claude Code's MCP configuration. If your Claude Code install supports adding servers from the CLI, the command is conceptually:

```bash
claude mcp add prodex -- prodex mcp --cwd /absolute/path/to/your/repo
```

For a source checkout without a global `prodex` binary, point Claude Code at the built CLI:

```bash
claude mcp add prodex -- node /absolute/path/to/prodex/dist/cli.js mcp --cwd /absolute/path/to/your/repo
```

If your install expects a JSON config, use the Claude Desktop JSON above.

## Tools

The server currently exposes ledger-first tools:

- `bridge_create_task`
- `bridge_list_tasks`
- `bridge_get_task`
- `bridge_claim_task`
- `bridge_complete_task`
- `bridge_block_task`
- `bridge_list_results`
- `bridge_fetch_result`
- `bridge_fetch_result_artifact`
- `bridge_list_receipts`
- `bridge_get_receipt`
- `bridge_list_sessions`
- `bridge_get_session`
- `repo_read_file`
- `repo_search`
- `repo_write_file_dry_run`
- `repo_write_file_apply`
- `repo_stage_reviewed_paths`
- `pro_consult`

`bridge_complete_task` and `bridge_block_task` close tasks by writing durable `.bridge/results` records; they do not modify repo files. `bridge_fetch_result_artifact` only returns text artifacts that are listed on a result record and stored under `.bridge/artifacts/pro-consults/` or `.bridge/artifacts/results/`; it does not expose arbitrary `.bridge/artifacts` files. Newly finalized result artifacts record a sha256, and fetch rejects the artifact if its content changed afterward. The bridge rejects oversized result artifacts before task finalization; if a Pro browser answer is too large for `bridge_fetch_result_artifact`, it stays in the result summary with `answer_artifact_warning` instead of listing an unfetchable artifact.

Write tools are narrow and receipt-gated, and they require a git worktree with a committed HEAD. Claude must first call `repo_write_file_dry_run` with an existing repo-relative text file, replacement content, and the expected git HEAD. The file is not changed; the receipt stores hashes/diff and points at a replacement-text artifact under `.bridge/artifacts/repo-writes/`. To apply it, Claude must call `repo_write_file_apply` with the dry-run receipt id, the same expected HEAD, and the reported preimage hash. If git HEAD, file content, or artifact content changed, apply fails. To stage the result, Claude must call `repo_stage_reviewed_paths` with applied write receipt ids and the same expected HEAD; staging fails if any file changed after apply.

`pro_consult` lets Claude ask your logged-in ChatGPT (Pro) directly: it drives the same explicit visible-browser consult as `prodex pro browser ask` (human-paced, blocker-gated, receipt-recorded, answer saved under `.bridge/artifacts/pro-consults/`) and can take minutes for Pro extended reasoning. It requires a prior `prodex pro browser login` session and is registered only on the local stdio MCP server — the HTTP MCP surface never exposes it, so nothing reachable through a tunnel or ChatGPT itself can drive your browser.

No shell, public tunnel, direct ungated write, or direct ungated staging tools are exposed through the Claude stdio MCP server; the only browser-facing tool is the explicit `pro_consult` consult described above.

## First Prompt

After adding the MCP server, generate a paste-ready verification prompt:

```bash
prodex claude prompt --cwd /absolute/path/to/your/repo
```

For a source checkout, include the built CLI path so the generated local follow-up commands also use `node dist/cli.js`:

```bash
node dist/cli.js claude prompt --cwd /absolute/path/to/your/repo --source-cli /absolute/path/to/prodex/dist/cli.js
```

Paste the generated prompt into Claude. It asks Claude to use `bridge_create_task`, `bridge_list_tasks`, and `bridge_get_task`, then wait while you complete the verification task locally with a result artifact:

```bash
prodex tasks list --status new --cwd /absolute/path/to/your/repo
prodex tasks show <task-id> --cwd /absolute/path/to/your/repo
prodex tasks complete <task-id> --cwd /absolute/path/to/your/repo --summary "prodex Claude MCP verification result" --artifact .bridge/artifacts/results/claude-verification.md="prodex Claude MCP verification artifact"
```

Then reply to Claude with `local completion done`. The generated prompt asks Claude to call `bridge_fetch_result` for the same task id, call `bridge_fetch_result_artifact` for every listed result artifact path, and report whether it can read both the verification result summary and artifact content. It also includes local `claude config --cwd ...` and `doctor --cwd ...` troubleshooting commands in case Claude cannot see or call the MCP tools. Source-checkout prompts keep `--source-cli` on those troubleshooting commands too.