Claude Code support

Synced from deepwork/docs/claude-code.md. The repository is the source of truth.

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)

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

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:

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):

{
  "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.