cpm-planner

# cpm-planner

[![CI](https://github.com/praxec/cpm-planner/actions/workflows/ci.yml/badge.svg)](https://github.com/praxec/cpm-planner/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/praxec/cpm-planner)](https://github.com/praxec/cpm-planner/releases/latest)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

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](https://github.com/praxec/praxec) workflow) drives it over stdio. It is a
standalone tool with no dependency on praxec.

## Contents

- [Install](#install)
  - [Prebuilt binary (recommended)](#prebuilt-binary-recommended)
  - [Pin a version](#pin-a-version)
  - [npm](#npm)
  - [From source](#from-source)
  - [Docker](#docker)
  - [Verify the install](#verify-the-install)
- [Quickstart: plan as code](#quickstart-plan-as-code)
- [Quickstart: earned value](#quickstart-earned-value)
- [Use with AI agents](#use-with-ai-agents)
- [MCP tools](#mcp-tools)
  - [Plan-as-code workflow](#plan-as-code-workflow)
  - [Plan review (optional)](#plan-review-optional)
- [Use as a library](#use-as-a-library)
- [Praxec](#praxec)
- [Environment variables](#environment-variables)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#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.

```sh
# 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.

<details>
<summary>Installer details: inspecting the script, PATH, upgrades and direct downloads</summary>

If you would rather read the script before running it, download, inspect, then run
(see [Pin a version](#pin-a-version) for `<version>`):

```sh
# Linux / macOS
curl -fsSLO https://github.com/praxec/cpm-planner/releases/latest/download/install.sh
less install.sh
sh install.sh --version <version>
```

```powershell
# 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:

- `~/.zshrc` for zsh;
- `~/.bash_profile` if it exists, else `~/.bashrc`, for bash;
- `~/.profile` for 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` |

</details>

### 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](https://github.com/praxec/cpm-planner/releases).

```sh
# 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:

```sh
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](npm/README.md).

### From source

Build and install a tagged release with Cargo (Rust 1.99 or newer):

```sh
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

```sh
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:

```sh
claude mcp add cpm-planner --scope user -- docker run -i --rm -v cpm-planner-data:/data ghcr.io/praxec/cpm-planner
```

### Verify the install

```sh
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:

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

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 <tool> --user` (or `--project <dir>`), where
`<tool>` is `claude`, `codex`, `cursor`, `copilot`, `gemini`, `all`, or
`agents-md` (project only).

[docs/AGENT-INSTALL.md](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](llms.txt) indexes the docs
for LLMs.

## MCP tools

| Tool | Does |
|------|------|
| `plan.submit` | Submit a task graph; returns a plan id (id