cpm-planner MCP server
Commit Nov 13, 2026Computes Critical Path Method schedules and manages lock-aware parallel task cohorts for AI agents to prevent file collisions.
Also known as praxec/cpm-planner
- Stars
- 0
- Tools
- 28
- Downloads, 30 days
- —
- Latest version
- 0.8.0
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is cpm-planner MCP?
cpm-planner computes Critical Path Method schedules and manages lock-aware parallel task cohorts for AI agents to prevent file collisions. It exposes 28 tools, such as plan.release.compile, plan.release.diff, plan.submit.
Summary generated from the project's README
About cpm-planner MCP server
Managing complex task dependencies and preventing file collisions during parallel agent execution is what cpm-planner enables. This MCP server allows developers to submit task graphs to compute Critical Path Method schedules, identifying bottlenecks, slack, and the critical path. It is designed for AI agents and orchestrators using clients like Claude Code, Cursor, or VS Code via stdio.
Users can manage work through a plan-as-code workflow, storing task definitions in JSON files within a repository. The server provides tools to lint plans, run Monte Carlo risk simulations, and track project health using earned-value metrics like SPI and CPI. To support parallel workers, it features a unique mechanism to lease lock-aware cohorts of ready deliverables that possess disjoint file sets, ensuring multiple agents can operate simultaneously without overwriting each other's work.
What you can do with it
- 1Preventing file collisions in parallel tasksAn AI agent can request a group of tasks that are safe to run at the same time without overlapping file access.
- 2Analyzing project schedule risksA developer can use Monte Carlo simulations to evaluate the uncertainty in their task estimates.
- 3Tracking project progress against a baselineAn orchestrator can monitor earned value metrics to see if a project is ahead of or behind schedule.
- 4Identifying project bottlenecksAn agent can determine which specific tasks are currently gating the completion of the entire plan.
Written from the project's README. Every use case is checked against a quote from it.
How to install cpm-planner MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall cpm-planner MCP in Claude Code
$ claude mcp add cpm-planner -- docker run -i --rm ghcr.io/praxec/cpm-planner:0.8.0Install cpm-planner MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"cpm-planner": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/praxec/cpm-planner:0.8.0"
]
}
}
}Install cpm-planner MCP in VS Code
.vscode/mcp.json
{
"servers": {
"cpm-planner": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/praxec/cpm-planner:0.8.0"
]
}
}
}Install cpm-planner MCP in VS Code CLI
$ code --add-mcp '{"name":"cpm-planner","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/praxec/cpm-planner:0.8.0"]}'Install cpm-planner MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"cpm-planner": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/praxec/cpm-planner:0.8.0"
]
}
}
}Install cpm-planner MCP in Codex
$ codex mcp add cpm-planner -- docker run -i --rm ghcr.io/praxec/cpm-planner:0.8.0Install cpm-planner MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.cpm-planner] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/praxec/cpm-planner:0.8.0"]
Install cpm-planner MCP in Gemini CLI
$ gemini mcp add -s user cpm-planner docker -- run -i --rm ghcr.io/praxec/cpm-planner:0.8.0Install cpm-planner MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"cpm-planner": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/praxec/cpm-planner:0.8.0"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for ghcr.io/praxec/cpm-planner:0.8.0 0.8.0 in an isolated container with no network and no keys. It answered and listed 28 tools.
cpm-planner MCP tools 28
Read from the server with tools/listplan.release.compileCompile version-1 bounded release metadata into an ordinary lint-clean PlanGraph. Expands protected PR/check/approval/merge hops, producer retries, retained receipts and central acceptance. Every collection declares cardinality or a bounded retained source. Pure offline operation: never executes, accepts, submits or baselines work.
plan.release.diffCompare a retained compiled graph with current version-1 workflow/promotion policy. Reports policy_changed, added/removed/changed ids and stale; includes retained-history estimate drift. Read-only: apply accepted changes through normal plan.sync or plan.revise.
plan.submitSubmit a plan graph and receive a plan_id. Idempotent: identical graphs return the same plan_id. With `name` (and optional `project`/`variant`, variant defaults to "main"), registers a named variant instead: project defaults to the discovered project root.
plan.acquire_cohortAcquire up to max_count ready deliverables with no conflicting file claims atomically. Returns the cohort plus per-deliverable locks. A deliverable explicitly marked failed 3 times is circuit-broken to failed instead of re-leased; leases lost environmentally (TTL lapse, no terminal mark) never trip that breaker but are bounded separately (LAPSE_LIMIT at 10). Optional ttl_seconds sets the lease TTL (clamped to the server maximum). Optional ids targets specific deliverables and filter.metadata narrows by metadata equality; deliverables with metadata.kind = "manual" or "gate" are never leased. ids that do not match filter.metadata are ignored (not reported in blocked). The response carries blocked [{id, code, reason}], blocked_count, and needs_operator (true when any blocked code is LAPSE_LIMIT: clear with plan.force_release {reset_counters: true}). Thread affinity: the caller that last completed a metadata.thread deliverable is offered that thread's next one first; optional thread prefers one thread and affinity_seconds holds other callers' threads back (blocked code AFFINITY_HOLD). Select the plan by plan_id, plan line name, or active: true.
plan.heartbeatRefresh the TTL on a held lock; LOCK_NOT_HELD or LOCK_EXPIRED on failure. Optional ttl_seconds sets the new TTL (clamped to the server maximum); without it the lease is never shortened. Select the plan by plan_id, plan line name, or active: true.
plan.mark_statusSet a deliverable's status. Complete/Failed releases the lock; caller_id mismatch yields LOCK_NOT_HELD. Without a lock, Complete, Ready or InProgress requires all prerequisites complete (PREREQUISITES_INCOMPLETE) and is audited; other lockless marks are audited too, and an already-complete deliverable cannot be changed (LOCK_NOT_HELD). A lockless in_progress persists across restarts and is not leasable; hand it back with a lockless ready (or other status) mark. plan.force_release does not affect it. Optional earned-value progress: earned_pct (0..100, only with in_progress; ignored with complete), actual_effort_hours (total so far, 0..1000000; replaces leased hours as actual cost) and evidence (a note of <= 2048 chars or an evidence record object, appended to a list of at most 100; records are checked as INVALID_EVIDENCE, EVIDENCE_SCOPE_MISMATCH, EVIDENCE_REQUIRED or EVIDENCE_STALE); violations are INVALID_ACTUALS. Every lease that ends adds its hours to the deliverable's leased hours. Select the plan by plan_id, plan line name, or active: true.
plan.statusRead-only snapshot: per-deliverable [id, status, attempt_count, failure_count, lapse_count] rows, critical_path (one real chain, always from __start__ to __finish__), critical_ids, per-deliverable schedule (es/ef/ls/lf/float, hours; synthetic __start__/__finish__ rows have synthetic=true), the ready set in float-ascending order (smallest float first, then smallest latest start, then id), plan_complete, milestones (per milestone: id, critical_path from __start__, hours, complete), and held locks. Select the plan by plan_id, plan line name, or active: true.
plan.getReturn the stored PlanGraph (deliverables, estimates, files, metadata) for a plan selected by plan_id, plan line name, or active: true.
plan.force_releaseOperator escape hatch — release a lock regardless of caller. Emits an audit event carrying `reason`. Select the plan by plan_id, plan line name, or active: true.
plan.acceptManager/owner acceptance: mark a deliverable Complete without holding its lease. Requires all prerequisites Complete and evidence (a note or an evidence record object; records are checked as on plan.mark_status); audited. A live lease held by someone else is refused (LOCK_HELD) unless override_lock is true. Select the plan by plan_id, plan line name, or active: true.
plan.lintLint a graph, stored plan, or plan file without creating one: cycles (with the loop), redundant edges, edges without rationale, interface edges not targeting a contract, deliverables feeding no milestone, and unordered file overlaps. Linting by plan_id also adds NO_BASELINE (warning) when the plan is executable and has recorded progress but no earned-value baseline. Provide exactly one of graph, plan_id, or path.
plan.scheduleLevel a graph or stored plan against resource capacities (`metadata.owner` by default; metadata.resources can claim several pools concurrently): makespan, per-deliverable start/finish, per-resource load, the driving chain (dependency vs named resource waits), and project/feeding buffers. A deliverable with duration_hours plus metadata.wall_clock_only:true advances elapsed time but consumes no capacity. Provide exactly one of graph or plan_id. capacities is required: every resource that carries work needs at least 1 unit (otherwise INVALID_CAPACITIES: lists the missing resources). plan.schedule rejects what plan.submit rejects (INVALID_GRAPH:). Optional calendar (one calendar or a per-resource map with a default entry) and start place the schedule on working windows: wall-clock hours from start, start_at/finish_at per row, calendar_wait_hours, cpm_makespan and driving-chain links waited_on "calendar".
Show all 28 toolsShow fewer tools
plan.simulateRead-only what-if for a graph, stored plan, or plan file (nothing is persisted): lint, critical path, schedule, milestones, optional resource schedule and Monte Carlo, and the scorecard. Provide exactly one of graph, plan_id, or path. schedule takes the plan.schedule inputs (capacities required; INVALID_CAPACITIES: when a working resource has none). monte_carlo takes iterations (1..50000, default 2000) and seed (default 0xC0FFEE); iterations × (deliverables + prerequisite edges) must not exceed 200000000. plan.simulate rejects what plan.submit rejects; lint errors or an invalid graph are INVALID_GRAPH:. Optional calendar and start (as on plan.schedule) apply to the resource schedule and Monte Carlo; calendars are looked up by schedule.resource_key, else owner.
plan.syncRegister or update one variant of a named plan line from a plan file (`path`) or an inline `graph`. A path is read from .cpm-planner/plans/<name>/<variant>.json and tracked by content hash for drift detection. An inline graph requires `name`; `variant` defaults to "main". `project` defaults to the discovered project root. `force` releases live locks of removed deliverables.
plan.listList every plan line of `project` (default: the discovered project root), sorted by name with each line's variants sorted by variant. Archived lines and variants are omitted unless include_archived. With active: true, return only the project's active lines.
plan.exportWrite the head graph of `plan_id` under the project root and return its root-relative path: to `path` when given (confined to .cpm-planner/plans/<name>/<variant>.json), else to its own variant file. Refuses (INVALID_PATH) another variant's tracked plan file, or the variant's own file while it holds local edits never synced, unless force. The written file is not synced; exporting to the variant's own tracked file records its hash, so drift is false.
plan.reviseReplace a plan's graph in place, carrying progress over: unchanged deliverables keep status and counters; changed or reopened ones are re-derived. Removed deliverables holding live locks are refused (LOCK_HELD) unless force. Returns the new revision and the diff.
plan.forkCopy the head graph of a named variant, apply `edits` in order, and register the result as a new draft (not selected) variant of the same line. Fails if the variant already exists.
plan.selectMake the named variant owning `plan_id` its line's selected (the only executable) variant. Progress carries over from the previously selected variant. Live locks on the previous variant refuse selection with LOCK_HELD unless force releases them (audited).
plan.archiveArchive (archived defaults to true) or unarchive a whole plan line (`variant` omitted) or one variant. Archived variants stay readable but are hidden from plan.list unless include_archived, and refuse sync, selection and execution (ARCHIVE_REFUSED).
plan.compareCompare stored plans on the scorecard, returning the Pareto front, weighted rank and a recommended plan. Give exactly one of `plan_ids` (2 to 16 distinct plans) or `plan` (a line name in `project`: every non-archived variant, at most 16). Read-only. Weights must be finite and >= 0. With monte_carlo, iterations × (deliverables + prerequisite edges) summed over all variants must not exceed 200000000.
plan.baselineFreeze the plan's current CPM schedule (earliest start/finish), or with capacities its levelled schedule, and budgets (effort basis x metadata.cost_rate) as its next numbered baseline for earned value. The first baseline is number 1; re-baselining needs a non-blank `reason` (INVALID_GRAPH otherwise) and keeps actuals and snapshots. Without `calendar`, a re-baseline keeps the previous baseline's calendar (the first baseline counts wall-clock hours); `calendar: null` clears it, and a map with a `default` entry gives each resource its own calendar. capacities, resource_key and project_buffer_pct are reused the same way; schedule: "cpm" returns to a CPM baseline. `backfill_from` (RFC 3339) sets the baseline's `start` retroactively and marks it `backfilled: true` (reported by plan.ev); it must not be in the future or before the plan's creation time (INVALID_VALUE). Execution-side: the plan must be its line's selected, unarchived variant (VARIANT_NOT_SELECTED / ARCHIVE_REFUSED). Audited as plan.ev.baselined. Select the plan by plan_id, plan line name, or active: true.
plan.evEarned-value report against the plan's latest baseline as of `as_of` (default now). `as_of` is the PV status date; EV and AC reflect progress and actuals recorded up to the moment the call runs. Returns BAC, PV, EV, AC, SV, CV, SPI, CPI, EAC, ETC, VAC, TCPI, per-deliverable rows (a baselined deliverable later removed by plan.revise has status `removed` and keeps the percent it had earned: 100 if complete), critical float consumed, SPI_BELOW_0_9 / CPI_BELOW_0_9 alerts from the two latest stored non-backfilled snapshots (by as_of) of the current baseline, and deliverables added since the baseline. AC counts every recorded hour of the plan, including removed and unbaselined deliverables (rate 1 when the baseline has no row). A ratio whose denominator is 0 is null and explained in `undefined`. `backfilled` is true when the baseline was taken with `backfill_from`. Read-only; works on any variant. NOT_BASELINED before plan.baseline. Select the plan by plan_id, plan line name, or active: true.
plan.snapshotCompute the earned-value report (as plan.ev) and append it as a snapshot. `as_of` is the PV status date; EV and AC are the progress recorded when the call runs, so a snapshot whose as_of is more than an hour before its taken_at is marked `backfilled: true` and ignored by alerts. Returns the snapshot summary (alerts consider this snapshot and the latest earlier non-backfilled one by as_of of the current baseline) and an export of the newest 100 snapshots by as_of, oldest first (an older backfill is counted but not listed): a list of summaries (format json, default) or a Markdown table with columns date, PV, EV, AC, SPI, CPI, EAC (format markdown). Execution-side like plan.baseline. NOT_BASELINED before plan.baseline. Select the plan by plan_id, plan line name, or active: true.
plan.reviewOptional AI review of a graph, stored plan, or plan file (read-only; provide exactly one of graph, plan_id, or path). Lint always runs; lint errors return status invalid_graph without calling the judge. Otherwise one batched call to Jev (calibrated judgments, via OpenRouter) asks up to max_questions (1..64, default 64) questions about likely false or missing dependencies, split and interface-split candidates and crash options; findings carry advisory probabilities. Proposals are plan.fork edit lists, each verified by simulate (lint clean, makespan shorter) and ranked by hours_saved / max(cost, 1). Without an OpenRouter key (or with an unusable LLM configuration) status is review_unavailable with a reason, plus lint. The plan graph (ids, descriptions, metadata) is sent to OpenRouter.
plan.overviewRead-only, deterministic snapshot of one plan at as_of (default now): what plan.status, plan.get and plan.ev say, joined (schema cpm-planner/overview/v1): plan identity, counts, the EV headline, critical_path_hours, and bounded sections {total, omitted, items} for critical_path (remaining hours, milestones fed), milestones, ready (action acquire/accept/operator, float, file_conflicts), blocked (class dependency/manual/external/gate, waiting_on, root_blockers), leases, attention, and stale_evidence; every entry carries its evidence status (current/stale/unknown/unbound/none). detail brief (default, 10 per list) or full (100, adds chains, es/ef and owned files); limit 1..1000; filter {owner, milestone} narrows the lists only (an unknown milestone is DELIVERABLE_NOT_FOUND, a non-milestone INVALID_VALUE). evidence_target judges every evidence record against one identity (malformed: INVALID_EVIDENCE). format json (default) or markdown. No AI or network call; never writes. Select the plan by plan_id, plan line name, or active: true.
plan.explainRead-only, deterministic: why one deliverable is not moving and what completing it changes (schema cpm-planner/explain/v1). With deliverable_id: its state (complete/leased/in_progress/ready/blocked/failed), the blocker class, waiting_on, root_blockers and the driving chain, unlocks (what becomes ready when it completes), the milestones it feeds with slack_hours, and a one-sentence critical_path_impact. Always: next_work, every ready or blocked deliverable in exactly one class (ready_critical, ready_slack, blocked_dependency, blocked_manual, blocked_external, blocked_gate, file_conflicting). An unknown id is DELIVERABLE_NOT_FOUND; limit 1..1000 (default 10). format json (default) or markdown. Agrees with plan.overview at the same as_of. Select the plan by plan_id, plan line name, or active: true.
plan.optimizeOffline, deterministic plan optimization (read-only; no model, provider or network call; provide exactly one of graph, plan_id, or path). Proposes plan.fork edit lists that make the plan shorter, cheaper or simpler: merge (same-owner deliverables sharing a file), false_dependency, parallel_cohort, gate_consolidation and gate_bypass. Each proposal is checked by lint, the schedule and simulate, keeps every acceptance criterion, gate, milestone, approval, interface contract and owned file, never lengthens the makespan (the leveled one with capacities) or adds effort, and is ranked by score; rejected candidates are reported with their reasons. Optional capacities, resource_key and project_buffer_pct level every candidate (as plan.schedule); max_proposals caps proposals (default 32). A graph that does not simulate is INVALID_GRAPH:. Run it before the optional AI plan.review.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepraxec/cpm-planner is public and reachablegithub.com/praxec/cpm-planner ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/praxec/cpm-planner ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model9 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcpm-planner
cpm-planner is a Critical Path Method (CPM) planner for agent work, exposed as an MCP server. You submit a task graph and it computes the schedule: earliest and latest start and finish, slack, the critical path and the bottleneck tasks that gate completion. It then leases lock-aware cohorts of ready deliverables with disjoint file sets, so several workers can run in parallel without colliding. Plans can live in the repository as plan-as-code files with forkable, comparable variants; read-only tools lint, level against resource capacities and run Monte Carlo risk; earned-value tools track PV, EV, AC, SPI and CPI against a frozen baseline; and an optional AI review proposes verified schedule improvements. Any MCP client (Claude Code, Cursor, VS Code, Codex, a custom orchestrator, or a praxec workflow) drives it over stdio. It is a standalone tool with no dependency on praxec.
Contents
- Install
- Quickstart: plan as code
- Quickstart: earned value
- Use with AI agents
- MCP tools
- Use as a library
- Praxec
- Environment variables
- Documentation
- Contributing
- License
Install
Prebuilt binary (recommended)
Prebuilt packages are published for Linux, macOS and Windows on x86_64 and ARM64.
The installers resolve your OS and CPU and download the matching archive. They
verify its SHA-256 against the release's checksums.sha256 before installing,
then atomically replace the binary in a user-local directory. A checksum mismatch
aborts with a non-zero exit and installs nothing. Re-running the installer upgrades
in place.
# Linux / macOS -> ~/.local/bin/cpm-planner
curl -fsSL https://github.com/praxec/cpm-planner/releases/latest/download/install.sh | sh
# Windows (PowerShell) -> %LOCALAPPDATA%\Programs\cpm-planner\cpm-planner.exe
irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1 | iex
The installer prints the absolute path it installed to. Use that path when you register the server with a GUI client.
If you would rather read the script before running it, download, inspect, then run
(see Pin a version for <version>):
# Linux / macOS
curl -fsSLO https://github.com/praxec/cpm-planner/releases/latest/download/install.sh
less install.sh
sh install.sh --version <version>
# Windows
irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1 -OutFile install.ps1
Get-Content install.ps1
.\install.ps1 -Version <version>
PATH. If the install directory is not on your PATH, the installer prints the
exact line to add. Pass --add-to-path (-AddToPath on Windows) to have it do that
for you, user-level only and never with sudo.
On Linux and macOS it appends the line only if it is not already there, to:
~/.zshrcfor zsh;~/.bash_profileif it exists, else~/.bashrc, for bash;~/.profilefor other shells.
For fish it prints fish_add_path <dir> for you to run instead of writing a file.
Downloads. The installers only accept https:// download URLs.
Upgrades. After upgrading, restart your MCP client so it launches the new
binary. On Windows the old exe is renamed to cpm-planner.exe.old and removed on
the next run.
Direct downloads. You can also download an archive yourself and check it
against checksums.sha256; a machine-readable release-manifest.json is published
too. All assets are at https://github.com/praxec/cpm-planner/releases/latest.
| Platform | Asset |
|---|---|
| Linux x86_64 | cpm-planner-x86_64-unknown-linux-gnu.tar.gz |
| Linux ARM64 | cpm-planner-aarch64-unknown-linux-gnu.tar.gz |
| macOS x86_64 | cpm-planner-x86_64-apple-darwin.tar.gz |
| macOS Apple Silicon | cpm-planner-aarch64-apple-darwin.tar.gz |
| Windows x86_64 | cpm-planner-x86_64-pc-windows-msvc.zip |
| Windows ARM64 | cpm-planner-aarch64-pc-windows-msvc.zip |
Pin a version
In the commands in this README, <version> is a release tag such as v0.2.0. Pick
one from the releases page.
# Linux / macOS
curl -fsSL https://github.com/praxec/cpm-planner/releases/latest/download/install.sh | sh -s -- --version <version>
# Windows (PowerShell): the piped form cannot take parameters, so use the environment variable...
$env:PRAXEC_VERSION = '<version>'; irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1 | iex
# ...or a script block
& ([scriptblock]::Create((irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1))) -Version <version>
npm
With Node 18 or later, install the cpm-planner command from npm:
npm install -g @matthew-cochran/cpm
cpm-planner --version
The package is a small launcher. It downloads the release binary for your
platform, verifies its checksum and caches it, during install or, where npm
skips install scripts, on first run. The package
version is the release version, so npm install -g @matthew-cochran/cpm@0.2.0
pins one. To run it without installing, use npx -y @matthew-cochran/cpm.
For details and environment variables, see npm/README.md.
From source
Build and install a tagged release with Cargo (Rust 1.99 or newer):
cargo install --git https://github.com/praxec/cpm-planner --tag <version> --locked
The crates.io listing lags behind the GitHub releases until the next
cargo publish, so cargo install cpm-planner does not give you the current
version yet. Install from the tag as above.
Docker
docker pull ghcr.io/praxec/cpm-planner
docker run -i --rm -v cpm-planner-data:/data ghcr.io/praxec/cpm-planner
-i keeps stdin open for the stdio transport.
The image sets CPM_PLANNER_DB=/data/cpm-planner.db and declares /data as a
volume owned by the unprivileged app user, so a named volume persists plan state
across runs. For a bind mount (-v "$PWD:/data"), run as yourself so the directory
is writable: --user "$(id -u):$(id -g)". Pass -e CPM_PLANNER_DB=... only to
override the path.
To register the image with a client, put docker in command and the rest in
args. For example, in Claude Code:
claude mcp add cpm-planner --scope user -- docker run -i --rm -v cpm-planner-data:/data ghcr.io/praxec/cpm-planner
Verify the install
cpm-planner --version
It prints cpm-planner <version>. To check the MCP side without a client, run the smoke
script from the repository. It performs the MCP initialize and tools/list handshake and
fails if plan.submit, plan.status or plan.get is missing:
node scripts/mcp-smoke.mjs /absolute/path/to/cpm-planner
Quickstart: plan as code
Write a plan as .cpm-planner/plans/<name>/<variant>.json (a PlanGraph):
plan.lint {path: ".cpm-planner/plans/checkout/main.json"}— static checks, no state written.plan.sync {path: ".cpm-planner/plans/checkout/main.json"}— register the variant and return itsplan_id.plan.status {plan_id}— schedule, critical path, ready set and locks.
plan.sync tracks the file by content hash; plan.status reports
definition_drift when the tracked file and the stored head graph disagree.
Quickstart: earned value
Freeze the baseline, record progress, then read the report (earned_pct is earned in
proportion under earning_rule: "weighted"; fifty_fifty credits 50% once a deliverable is in progress or has any
reported earned_pct, and the default zero_hundred
earns at completion):
plan.baseline {plan_id}— freeze the CPM schedule and budgets as baseline 1.plan.mark_status {plan_id, deliverable_id, caller_id, status: {"status": "in_progress"}, earned_pct: 50, actual_effort_hours: 4}— report progress and actual cost.plan.ev {plan_id}— PV, EV, AC, SV, CV, SPI, CPI, EAC and alerts.plan.snapshot {plan_id, format: "markdown"}— append the reading and export a Markdown table.
A ratio with a zero denominator is null and explained in undefined; alerts
(SPI_BELOW_0_9, CPI_BELOW_0_9) compare the two latest stored readings.
Use with AI agents
Any MCP client can run cpm-planner over stdio: register the cpm-planner
binary as the command, or, with Node 18 or later, npx -y @matthew-cochran/cpm.
For a GUI client, use the absolute path the installer printed.
Install the agent skills (/cpm-plan and friends) with
cpm-planner skills install --target <tool> --user (or --project <dir>), where
<tool> is claude, codex, cursor, copilot, gemini, all, or
agents-md (project only).
docs/AGENT-INSTALL.md has the per-client steps (Claude
Code, Claude Desktop, Codex, Cursor, VS Code, Gemini CLI and others), env
blocks, verification and troubleshooting. llms.txt indexes the docs
for LLMs.
MCP tools
| Tool | Does |
|---|---|
plan.submit |
Submit a task graph; returns a plan id (idempotent on the graph + caller). A prerequisite is a deliverable id string or an object {id, consumes?, kind?: artifact|interface, lag_hours?}; both forms round-trip through plan.get. A deliverable may set milestone: true (an acceptance point, zero-length unless given an estimate or duration, reported in plan.status milestones). An optional earning_rule (zero_hundred, the default: 100% only when complete; fifty_fifty: 50% once in progress or any earned_pct is reported; weighted: the reported earned_pct) sets how earned value credits partial progress and is part of the plan's identity. A deliverable's optional duration_hours (calendar time) replaces effort as its scheduled length and a prerequisite's lag_hours delays the dependent's start; effort stays the cost basis. An optional estimate {optimistic, likely, pessimistic} (0 <= optimistic <= likely <= pessimistic) is a three-point effort estimate. Scheduled-length precedence: duration_hours > estimated_effort_hours > estimate.likely > 0 for a milestone > the estimator default; Monte Carlo samples the estimate only when neither duration_hours nor estimated_effort_hours is set. Limits: at most 5000 deliverables, and every hour value (effort, duration, lag, estimate) finite and between 0 and 1000000 (INVALID_GRAPH). With name (optional project/variant, variant defaults to main) it registers a named variant instead of an unnamed plan. |
plan.acquire_cohort |
Atomically acquire up to N ready deliverables with mutually disjoint file sets (an owned_files entry may be {path, mode: "append"}; append claims on one path may be co-leased and appear in shared_paths; a file may be owned by several deliverables only if they are ordered by prerequisites, or all claims are append); optional ttl_seconds sets the lease TTL (clamped to the server maximum); optional ids and filter.metadata target deliverables; metadata.kind = "manual" deliverables are never leased; the response lists unleased candidates in blocked (with blocked_count, needs_operator). Thread affinity (threads): the caller that last completed a metadata.thread deliverable is offered that thread's next one first; optional thread prefers one thread, and optional affinity_seconds (default 0) holds back a thread another caller advanced less than that long ago, reported in blocked as AFFINITY_HOLD. |
plan.heartbeat |
Refresh the TTL on a held lock; optional ttl_seconds sets the new TTL (clamped to the server maximum). |
plan.mark_status |
Mark a deliverable complete/failed; releases its lock. Without a lock, Complete requires complete prerequisites (PREREQUISITES_INCOMPLETE) and every lockless mark is audited. A lockless in_progress (owner or manual work) persists across server restarts and is not leasable; hand it back with a lockless ready (or any other status) mark. Optional earned-value progress: earned_pct (integer 0 to 100, only with in_progress; accepted and ignored with complete), actual_effort_hours (total effort so far, finite, 0 to 1000000; replaces leased hours as actual cost) and evidence (a note of at most 2048 characters, or an evidence record with a scope and the identity of what was checked; appended to the deliverable's evidence list, which keeps at most 100 entries); violations are INVALID_ACTUALS, including a negative, fractional or over-100 earned_pct. A malformed record is INVALID_EVIDENCE, a record whose scope may not close the deliverable EVIDENCE_SCOPE_MISMATCH, closing a deliverable that declares metadata.evidence_scope without a matching record EVIDENCE_REQUIRED, and a gate record that does not match its metadata.candidate EVIDENCE_STALE. plan.select copies the actuals of every deliverable whose Complete status it carries (leased hours add up, the carried deliverable's reported percent and hours win, the newest 100 evidence entries are kept). Every lease that ends (complete, failed, force release, expiry, accept override, forced revise/select/archive) adds its hours to the deliverable's leased hours; a lapsed lease counts up to its expiry. |
plan.status |
Read-only snapshot of the plan and its locks. critical_path always runs __start__ to __finish__ (synthetic zero-effort endpoints; their schedule rows carry synthetic: true, and __start__/__finish__ are reserved deliverable ids rejected with INVALID_GRAPH). A forced revision that invalidates a lease reports superseded_revision; it is re-acquirable after its prerequisites complete but the stale holder cannot mark it complete. plan_complete is true once every deliverable is Complete; the plan.completed audit event fires once when that happens. milestones has one row per deliverable with milestone: true (or legacy metadata.milestone == true): id, critical_path (longest chain from __start__ to it), hours (its earliest finish) and complete. For a named variant it also reports name, variant, selected, archived and active_plan (the project's single active line's name when the variant is archived; archived and active_plan are null for an unnamed plan), and definition_drift: null (unknown) without a project root for the variant's project, without a tracked plan file, or when the file is missing, unreadable or over 8 MiB; otherwise false when the file's bytes match the last synced or exported hash or the file's graph equals the head graph (re-formatting is not drift), and true when the file's graph differs from the head (or does not parse). An inline plan.revise/plan.sync of a file-backed variant therefore reports true until the file is re-exported or re-synced. |
plan.get |
Return the stored plan graph for a plan selected by plan_id, plan line name or active: true (read back what was submitted). |
plan.force_release |
Operator escape hatch: release a lock regardless of holder/TTL; reset_counters: true also clears lapse/failure counters. A lockless in_progress has no lock, so plan.force_release leaves it as is; hand it back with a lockless plan.mark_status. |
plan.accept |
Manager/owner acceptance: complete a deliverable without holding its lease (audited, with evidence: a note or an evidence record, checked as on plan.mark_status and appended to the deliverable's evidence list). |
plan.lint |
Static checks without submitting: cycles (with the loop), redundant edges, edges without rationale, interface edges not targeting a contract, deliverables feeding no milestone, and unordered file overlaps (#20). |
plan.schedule |
Level a graph against resource capacities (metadata.owner by default): makespan, per-deliverable start/finish, per-resource load, the driving chain (dependency vs named resource waits), and project/feeding buffers (#19). A deliverable can atomically claim multiple pools with metadata.resources: {"agent":1,"builder":1}; every claimed pool needs enough capacity. duration_hours with metadata.wall_clock_only: true models CI/observation time that blocks dependents but consumes no capacity. project_buffer_pct is 0 to 100 (default 25). Optional calendar (one working calendar, or a per-resource map with a default entry) and start (RFC 3339, default now) place each deliverable in its resource's working windows: hours become wall-clock hours from start, rows add start_at, finish_at, calendars and calendar_wait_hours, and the driving chain reports waited_on: "calendar" (calendars). Without calendar the output is unchanged. |
plan.simulate |
Read-only what-if for a graph, stored plan or plan file (persists nothing): lint, critical path, schedule, milestones, optional resource schedule (schedule, same inputs and INVALID_CAPACITIES: rule as plan.schedule) and Monte Carlo (monte_carlo: iterations 1 to 50000, default 2000; seed, default 0xC0FFEE; iterations × (deliverables + prerequisite edges) must not exceed 200000000), and the scorecard (#23). Optional calendar and start, as on plan.schedule, apply to the resource schedule and to Monte Carlo. |
plan.release.compile |
Compile versioned, bounded workflow/promotion metadata into a lint-clean ordinary plan: protected PRs, parallel checks/joins, owner waits/approvals/merges, producer retry receipts, retained artifacts, native fixed-cost integration waves/evidence reuse, and central acceptance. Reports batched-versus-per-change gate economics and dominance warnings; runs offline and never executes or accepts work (release workflows). |
plan.release.diff |
Compare a retained generated graph with current workflow metadata; report policy/estimate drift and added, removed or changed ids before revising or baselining (release workflows). CLI equivalents: cpm-planner release compile, release lint, and release diff. |
plan.sync |
Register or update one variant of a named plan line from a plan file (path, of the form .cpm-planner/plans/<name>/<variant>.json) or an inline graph (requires name; variant defaults to main). A file is read with a no-follow confined path and tracked by content hash for drift detection; project defaults to the discovered project root; with path, any name/variant/project given must match the file's (INVALID_PATH: name/variant/project must match the plan file path); force releases live locks of removed deliverables. |
plan.list |
List every plan line of project (default: discovered project root), sorted by name with variants sorted; archived lines and variants are omitted unless include_archived. active: true returns only the project's active lines and cannot be combined with include_archived. |
plan.export |
Write the head graph of plan_id to its own variant file, or to a confined path, and return the root-relative path. Refuses (INVALID_PATH) another variant's tracked plan file, or the variant's own file while it holds local edits never synced, unless force: true. The written file is not synced, except that exporting to the variant's own tracked file records its hash (drift is then false). |
plan.revise |
Replace a plan's graph in place, carrying progress over (unchanged deliverables keep status/counters; changed or reopened ones are re-derived). A deliverable can declare metadata.consumes_revision_from for a direct prerequisite; changing that barrier or any prerequisite refuses its active lease unless force, which reports a diagnostic superseded_revision and preserves its prior evidence/hours. Returns the new revision and diff; force releases live locks of removed deliverables. |
plan.fork |
Copy a named variant's head graph, apply ordered edits, and register the result as a new draft (not selected) variant of the same line. Forking into an archived line is ARCHIVE_REFUSED before any file is written; forking from an archived variant of a live line is allowed. If registration fails after the file was written, the file is removed. |
plan.select |
Make a named variant its line's selected (only executable) variant, carrying progress over; force releases locks on the previously selected variant. |
plan.archive |
Archive (archived defaults true) or unarchive a whole line or one variant. Archived variants stay readable but refuse sync, selection and execution (ARCHIVE_REFUSED). |
plan.compare |
Compare stored plans on the scorecard (plan_ids, 2 to 16 distinct ids, or plan line name in project (default: the discovered root) for every non-archived variant, at most 16): Pareto front, weighted rank and recommended plan; equal scores share a rank and tied_with_recommended lists the variants tied with the recommendation. Weights must be finite and >= 0. With monte_carlo, iterations × (deliverables + prerequisite edges) summed over all variants must not exceed 200000000 (INVALID_GRAPH). Read-only; scoring runs off the async runtime. |
plan.baseline |
Freeze the plan's current CPM schedule (earliest start/finish per deliverable), or with capacities the levelled schedule plan.schedule computes, and budgets (effort basis × metadata.cost_rate, default 1) as its next numbered earned-value baseline. Optional start (RFC 3339, default now) and calendar {hours_per_day (0 < h ≤ 24, default 8), day_start ("HH:MM", default 00:00), workdays (default mon–fri), utc_offset_minutes (default 0)} (omitted: wall-clock hours on the first baseline; a re-baseline keeps the previous baseline's calendar; null returns to wall-clock hours; a map with a default entry gives each resource its own calendar, so PV accrues only inside each deliverable's windows). Optional capacities, resource_key and project_buffer_pct (reused by a re-baseline that omits them) and schedule ("cpm" or "levelled") choose the frozen schedule (calendars). The first baseline is number 1; re-baselining needs a non-blank reason (at most 2048 characters, INVALID_GRAPH otherwise) and keeps actuals and snapshots. Baselines, actuals and snapshots belong to one variant: a newly selected variant takes its own baseline 1, with no reason needed. Execution-side: only the selected, unarchived variant (VARIANT_NOT_SELECTED / ARCHIVE_REFUSED). Audited as plan.ev.baselined. |
plan.ev |
Earned-value report against the latest baseline as of as_of (RFC 3339, default now). as_of is the PV status date; EV and AC reflect progress and actuals recorded up to the moment the call runs. Returns BAC, PV, EV, AC, SV, CV, SPI, CPI, EAC, ETC, VAC, TCPI, per-deliverable rows, critical float consumed, SPI_BELOW_0_9 / CPI_BELOW_0_9 alerts (metric below 0.9 on the two latest stored, non-backfilled snapshots by as_of of the current baseline; the current reading is not one of them) |
cpm-planner MCP questions
How do I add cpm-planner MCP to Claude Code?
Run claude mcp add cpm-planner -- docker run -i --rm ghcr.io/praxec/cpm-planner:0.8.0 in your terminal. Add --scope user to make it available in every project.
How do I add cpm-planner MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does cpm-planner MCP provide?
It exposes 28 tools, including plan.release.compile, plan.release.diff, plan.submit, plan.acquire_cohort, plan.heartbeat.
How does cpm-planner handle parallel execution?
It leases lock-aware cohorts of ready deliverables with disjoint file sets, allowing several workers to run in parallel without colliding.
Can I use cpm-planner with my existing AI agents?
Yes, any MCP client like Claude Code, Cursor, or VS Code can drive it over stdio, and you can install specific agent skills for various tools.
Does it support risk analysis?
Yes, the tool includes read-only tools that can run Monte Carlo risk simulations based on effort estimates.
How is progress tracked?
It uses earned-value tools to track PV, EV, AC, SPI, and CPI against a frozen baseline.