Cpm Planner

cpm-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
• Prebuilt binary (recommended)
• Pin a version
• npm
• From source
• Docker
• Verify the install
• Quickstart: plan as code
• Quickstart: earned value
• Use with AI agents
• MCP tools
• Plan-as-code workflow
• Plan review (optional)
• 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.

Installer details: inspecting the script, PATH, upgrades and direct downloads

If you would rather read the script before running it, download, inspect, then run (see Pin a version for ):

# Linux / macOS

curl -fsSLO https://github.com/praxec/cpm-planner/releases/latest/download/install.sh less install.sh sh install.sh --version

# Windows

irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1 -OutFile install.ps1 Get-Content install.ps1 .\install.ps1 -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:

• ~/.zshrc for zsh;
• ~/.bash_profile if it exists, else ~/.bashrc, for bash;
• ~/.profile for other shells.

For fish it prints fish_add_path 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.

Pin a version

In the commands in this README, 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

Windows (PowerShell): the piped form cannot take parameters, so use the environment variable...

$env:PRAXEC_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

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 . 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/ / .json (a PlanGraph):

1. plan.lint {path: ".cpm-planner/plans/checkout/main.json"} — static checks, no state written.
2. plan.sync {path: ".cpm-planner/plans/checkout/main.json"} — register the variant and return its plan_id.
3. 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):

1. plan.baseline {plan_id} — freeze the CPM schedule and budgets as baseline 1.
2. 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.
3. plan.ev {plan_id} — PV, EV, AC, SV, CV, SPI, CPI, EAC and alerts.
4. 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 --user (or --project ), where 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

| 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; th