pm CLI — Claude Code Plugin

Native pm integration for Claude Code via the Model Context Protocol (MCP). Claude can use all pm operations as native tools — no shell invocation, no context switching.

Architecture

pm-cli/ (repo root)
├── .claude-plugin/
│   └── marketplace.json     # Root marketplace catalog — read by /plugin marketplace add
├── plugins/pm-claude/
│   ├── .claude-plugin/
│   │   └── plugin.json      # Claude Code plugin manifest (name: "pm-claude")
│   ├── .mcp.json            # MCP server config using ${CLAUDE_PLUGIN_ROOT}
│   ├── skills/
│   │   ├── pm-workflow/     # Auto-invoked: orient → claim → implement → close
│   │   ├── pm-developer/    # Developer execution loop with evidence requirements
│   │   ├── pm-release/      # Release gate sequence and evidence linking
│   │   ├── pm-audit/        # Comprehensive audit suite
│   │   ├── pm-planner/      # Planning: decompose, prioritize, triage
│   │   └── pm-*/           # Nine focused skill invocations (all /pm-* names retained)
│   ├── hooks/
│   │   ├── hooks.json       # SessionStart hook definition
│   │   └── session-start.mjs # Injects pm context at session start
│   ├── agents/              # Subagent definitions (one .md per coordinator/triage/verification subagent)
│   ├── scripts/
│   │   ├── pm-mcp-server.mjs # MCP server launcher
│   │   └── plugin-runtime.mjs # Exact-version runtime resolver
│   ├── package.json         # Pinned pm-cli dependency
│   └── README.md            # User-facing installation guide
└── scripts/
    └── smoke-claude-plugin.mjs  # Full plugin smoke test (run in CI)

The MCP server itself lives at src/mcp/server.ts (compiled to dist/mcp/server.js) and is bundled with the npm package as the pm-mcp binary.

.claude-plugin/marketplace.json is the current Claude marketplace entrypoint. The root marketplace.json remains for older marketplace consumers. Both files must contain identical bytes after version stamping; the plugin contract test checks this so the compatibility copy cannot silently drift.

Capability Inventory

The canonical user-facing inventory for MCP tools, skills, slash invocations, subagents, and pm_run actions lives in plugins/pm-claude/README.md. This page focuses on architecture, launcher behavior, and smoke-test expectations so capability counts do not drift between docs.

Installation Methods

1. Plugin marketplace (recommended — full feature set)

Add the pm-cli GitHub repo as a marketplace source, then install:

/plugin marketplace add unbraind/pm-cli
/plugin install pm-claude@pm

This clones the repo, reads .claude-plugin/marketplace.json at the root, installs the plugin from ./plugins/pm-claude/, and configures the MCP server, skills with the same /pm-* names, subagents, and the session hook automatically.

2. Global MCP via Claude Code CLI (MCP tools only)

claude mcp add --transport stdio pm-mcp -- npx -y --package=@unbrained/pm-cli@latest pm-mcp

Gives you the 32 MCP tools without skills.

3. Direct project .mcp.json (project-scoped MCP only)

Add to the project's .mcp.json:

{
  "mcpServers": {
    "pm-mcp": {
      "command": "node",
      "args": ["./plugins/pm-claude/scripts/pm-mcp-server.mjs"]
    }
  }
}

The repo root .mcp.json uses this approach and activates automatically when Claude Code opens this repository. Under MCP 2026-07-28, every request carries the protocol version, client capabilities, and client identity in _meta, so pm's bounded identity detector does not depend on session state and normal agent mutations do not need a hard-wired PM_AUTHOR.

MCP Server Launcher

plugins/pm-claude/scripts/pm-mcp-server.mjs resolves the server in order:

1. PM_CLI_MCP_SERVER env var (explicit override)
2. dist/mcp/server.js at the matching repository root, when the checkout package and plugin versions agree
3. The exact @unbrained/pm-cli version declared in the plugin's package.json, installed under the plugin data directory on first use

The cached runtime is reused offline. It never resolves npm's moving latest tag. A first install needs npm access; an unavailable pinned release causes an explicit startup failure.

Session Start Hook

hooks/session-start.mjs runs at the start of each Claude Code session. It:

1. Checks for .agents/pm/settings.json in the current workspace.
2. Exits silently if pm is not initialized.
3. Runs pm context --limit 5 --json from the same pinned runtime as the MCP server, with a 15-second command timeout.
4. Injects a compact status line into the session context.

Example injection:

pm tracker: 3 in_progress, 2 open
  • [pm-xxxx] Fix authentication bug (in_progress)
  • [pm-yyyy] Add calendar feature (in_progress)
  • [pm-zzzz] Update docs (open)
Use pm_context tool or /pm-status for full details.

Testing the Plugin

Full Claude Code plugin smoke test (runs in CI)

node scripts/smoke-claude-plugin.mjs
# or:
pnpm smoke:claude-plugin

Verifies: plugin file structure, manifest name consistency, stateless MCP discovery for 2026-07-28, 32 tools present, full workflow (init → create → claim → update → link files/docs/tests → get → context → search → validate → health), and session-start hook.

The copied-cache smoke packs the current build, installs it under a temporary plugin data directory, copies both plugin bundles away from the checkout, and restarts their MCP launchers with npm unavailable:

pnpm build
pnpm smoke:plugin-cache

MCP server smoke test

node scripts/smoke-codex-plugin-mcp.mjs
# or:
pnpm smoke:codex-plugin

Contract-safe preflight (recommended for CI agents)

pm contracts --schema-only --json
pm contracts --command extension --flags-only --json
pm package doctor --project --detail summary --strict-exit
pm package reload --project

Why this matters:

• pm contracts is extension-aware and reflects active runtime action/flag surfaces.
• extension --doctor now includes policy diagnostics and deterministic warning codes.
• extension --reload provides cache-busted module reload for extension dev loops.
• --strict-exit turns warning states into CI-failing exits when governance gates require it.

CLI simplification compatibility notes

The conservative CLI simplification pass adds invocation normalization and replay metadata that plugin/tooling flows should consume:

• long-option aliases/shape variants and high-confidence typos are normalized before parse
• setup resolution can auto-discover initialized tracker roots from ancestor directories
• structured error envelopes may include recovery with replay-ready guidance (attempted_command, normalized_args, provided_fields, missing, suggested_retry)

For migration details and automation expectations, see:

• CLI Simplification Migration

Validate manifests

claude plugin validate . --strict
claude plugin validate plugins/pm-claude --strict

Manual verification

After installing the plugin:

1. Start Claude Code: claude (in a pm-initialized directory)
2. Ask: "What's the current pm project status?" → Verify Claude uses pm_context (not Bash)
3. Try /pm-status — active items + calendar
4. Try /pm-search authentication — search results
5. Try /pm-new Fix the login timeout bug — duplicate-checked create
6. Try /pm-start-task pm-xxxx — claim and start
7. Try /pm-calendar week — upcoming deadlines
8. Try /pm-close-task pm-xxxx — verify, evidence, close

Compatibility

pm-cli version	Plugin version	Claude Code version
Exact same date-based version as the plugin	Exact same date-based version as pm-cli	Current supported Claude Code

The authoritative plugin version is plugins/pm-claude/.claude-plugin/plugin.json; pnpm version:check also verifies the pinned runtime dependency.

The MCP server uses JSON-RPC 2.0 over stdio with canonical protocol version 2026-07-28. A bounded legacy path remains for unversioned older hosts, with initialize-era handshakes available to enrich client identity; current hosts discover the server and send metadata on every request.

Extension Policy Diagnostics

When extension governance policy is configured (settings.extensions.policy), plugin and MCP automation can surface:

• extension_policy_violation_* warnings in warn mode
• extension_policy_blocked_* warnings in enforce mode
• extension_policy_*_trust warnings for trust/provenance gates
• policy summary counters under extension doctor details (summary.policy + triage.policy_*)

This enables contract-safe and policy-safe automation without falling back to shell heuristics.