# Claude Code support

DeepWork is a native Pi package first: Pi loads `src/index.ts` directly and needs no MCP server. Claude Code has no equivalent native extension API, so this repository also ships a thin Claude Code bridge that reuses the same TypeScript core (`src/bridge.ts` and the modules under `src/`):

- an MCP stdio server (`src/mcp/server.ts`) exposing the full `deepwork_*` tool surface
- a Claude Code plugin manifest (`.claude-plugin/plugin.json`) plus `.mcp.json`, which together register the MCP server, the `/deepwork` and `/review` commands (`commands/`), the packaged skills (`skills/`), and a `PostToolUse` hook for DeepSchema write feedback (`hooks/hooks.json`)

Nothing about the Pi integration changes: the Pi extension still does not use MCP, and never reads `.mcp.json`.

## Setup

### Option 1: install from the marketplace (recommended)

```bash
claude plugin marketplace add ai-outfitter/deepwork
claude plugin install deepwork@ai-outfitter
```

Nothing else is required. The MCP server runs from `dist/mcp/server.mjs`, which
is a dependency-free bundle committed to the repository — a plugin install
copies the git tree, which has no `node_modules`, so a `tsx` launcher could
never start.

### Option 2: load a checkout as a plugin

```bash
git clone https://github.com/ai-outfitter/deepwork.git
cd deepwork && npm ci && npm run build
claude --plugin-dir /path/to/deepwork
```

Run `npm run build` after changing anything under `src/`; the committed bundle
is what the plugin actually executes.

This provides in one step:

- the DeepWork MCP tools (tool names end in `deepwork_get_workflows`, `deepwork_start_workflow`, and so on)
- the `/deepwork:deepwork` and `/deepwork:review` commands
- the packaged skills
- automatic DeepSchema feedback after `Write`/`Edit` calls

### Option 2: register only the MCP server

If you only want the tools, register the server directly:

```bash
claude mcp add deepwork -- node /path/to/deepwork/dist/mcp/server.mjs
```

Or add it to your project's own `.mcp.json` (in *your* project, not this repository):

```json
{
  "mcpServers": {
    "deepwork": {
      "command": "/path/to/deepwork/node_modules/.bin/tsx",
      "args": ["/path/to/deepwork/src/mcp/server.ts"]
    }
  }
}
```

The server resolves the DeepWork project root from its working directory. Set `DEEPWORK_PROJECT_DIR` in the server's `env` if the MCP host spawns it outside the project.

## Capability mapping

| DeepWork capability | Pi mechanism | Claude Code mechanism |
| --- | --- | --- |
| `deepwork_*` tools (workflows, session jobs, reviews, schemas) | Native `pi.registerTool` | MCP stdio server |
| `/deepwork` dispatch prompt | Pi prompt template | `commands/deepwork.md` |
| `/review` | Native Pi command | `commands/review.md` |
| Skills | Pi packaged skills | Plugin `skills/` auto-discovery |
| DeepSchema write feedback | Pi `tool_result` hook | Plugin `PostToolUse` hook |

## Known gaps

- **Session lifecycle** — Pi restores active workflow context on session start and clears stale workflow state when a new session begins. The Claude Code bridge has no equivalent yet; if a session ends mid-workflow, ask the agent to call `deepwork_get_workflows`/`deepwork_go_to_step` or abort the stale workflow explicitly.
- **Commit review reminders** — the Pi extension appends post-commit review reminders to `git commit` tool results. Not bridged yet.
- **Review subagent autolaunch and pass markers** — under Pi, `/review` can launch fresh-context reviewer subagents and harvest `DEEPWORK_REVIEW_PASSED` markers automatically. Under Claude Code, the `/review` command instructs the agent to run review tasks (via its own subagents where available) and to call `deepwork_mark_review_as_passed` itself.
- **Session IDs** — the MCP server scopes session jobs to one server process by default. Pass an explicit `session_id` to the tools to share session jobs across processes.
- **Skill wording** — the packaged skills were written for Pi and mention Pi commands; the underlying tool surface is identical, so the guidance still applies under Claude Code.

## Why MCP config lives in `.mcp.json`

Claude Code reads a plugin's MCP configuration from a plugin-root `.mcp.json`
when the plugin is installed from a marketplace. An inline `mcpServers` block in
`.claude-plugin/plugin.json` works under `--plugin-dir` and is **silently
ignored** once installed — `claude plugin details` then reports
`MCP servers (0)`. A custom `mcpServers` path in the manifest is ignored the
same way. `.mcp.json` is the only form that works in both.

## Session state

DeepWork keys workflow state by session ID. Claude Code exposes no session
identifier to an MCP server, so the server derives a stable ID from the project
path rather than minting one per process — otherwise every new session or MCP
reconnect would strand the workflow stack and leave an unreachable entry in
`.deepwork/state/pi-workflows.json`. Set `DEEPWORK_SESSION_ID` to override.