# Claude PM MCP

Claude PM MCP turns Claude Code into the accountable engineering PM for a feature: it creates durable task state, gives workers isolated Git worktrees, validates their structured results, independently runs verification, and only permits integration after explicit approval.

It is a self-contained Claude Code plugin: no `npm install`, cloud service, or background daemon is required.

## Start in two minutes

Prerequisites: Claude Code 2.1.128+, Node.js 22.5+, and Git. For real interactive workers, use a Unix-like environment with `tmux` (WSL is recommended on Windows).

```powershell
git clone https://github.com/ch1kim0n1/claude-pm-mcp.git
cd claude-pm-mcp
claude --plugin-dir .
```

In Claude Code, activate PM mode and give it a feature objective:

```text
/claude-pm-mcp:pm-mode Add organization invitations with role-based access and tests.
```

The plugin starts its configured workers automatically. Its MCP state and evidence are kept in the active project’s `.coordify/` directory; worker worktrees are created beside that project in `<project>.coordify-worktrees/`.

## Exact `/pm-mode` shortcut

Claude Code namespaces every plugin command to prevent collisions, so the portable plugin command is `/claude-pm-mcp:pm-mode`. If your team wants the exact shorter `/pm-mode` command in a project, create the opt-in project shortcut once:

```powershell
node <path-to-coordify-plugin>\scripts\enable-pm-mode.mjs <path-to-your-project>
```

Restart Claude Code or run `/reload-plugins`, then use:

```text
/pm-mode Implement API-key creation, revocation, authorization tests, and audit logging.
```

The shortcut checks that the bundled MCP tools are available and applies the same safety contract as the plugin command.

## Install from a downloaded release

Build a portable archive from this checkout:

```powershell
npm run package:plugin
claude --plugin-dir .\release\claude-pm-mcp-1.1.0.zip
```

Claude Code can load a plugin directory or ZIP with `--plugin-dir`. Use `/reload-plugins` after updating a plugin in an existing session.

## What PM mode does

1. Inspects the repository and defines measurable acceptance criteria.
2. Creates a durable run with idempotent operations and bounded iteration limits.
3. Dispatches only independent tasks to isolated worker worktrees.
4. Waits at a batch barrier, rejects invalid worker results, and detects scope violations.
5. Runs independent test/build/lint commands and maps their evidence to criteria.
6. Sends narrowly scoped repair follow-ups when evidence fails.
7. Produces a final evidence report and requires explicit approval before integration.

## Worker setup

Run `node src/cli.js init` in a target repository to create `.coordify/config.yaml` and `.coordify/config.json`.

The default two `fake` workers make the complete protocol runnable for local development and automated tests. For real work, replace a worker in `config.json` with either:

- `tmux-interactive-cli` for a persistent Claude Code or GLM-backed interactive terminal. The worker receives a scoped task envelope and writes an authoritative result JSON file.
- `process-json` for a noninteractive CLI that accepts the task envelope on stdin and prints one structured result JSON object on stdout.

Never use a shared writable checkout for multiple workers. Claude PM MCP requires a clean Git base before it creates task worktrees.

## CLI and MCP

```powershell
node src/cli.js init
node src/cli.js doctor
node src/cli.js start
node src/cli.js status <run-id>
node src/cli.js recover
```

The plugin launches the bundled stdio MCP server automatically. Its tools cover run creation, worker health, batch dispatch/await, task results and follow-ups, verification, recovery, status, and approval-gated integration.

## Validate and develop

```powershell
npm run doctor:plugin
npm run package:plugin
```

`doctor:plugin` runs strict Claude plugin validation, the integration tests, and syntax checks. See [CHANGELOG.md](CHANGELOG.md) for releases.