What you need
Three things — that's it. If you've been writing Node.js code you likely already have all of them.
Node.js 20+
Install from nodejs.org or via nvm. pm-cli uses modern ESM and requires Node 20 or higher.
npm or pnpm
Comes bundled with Node.js. Use npm, pnpm, or yarn — whichever you prefer for global installs.
A git repository
pm-cli stores items in your repo. Run git init if you don't have one yet. Any existing repo works immediately.
Follow along step by step
Seven steps take you from a bare repository to a fully tracked project with history, comments, stats, and agentic planning.
Install pm-cli
Install the package globally so the pm command is available everywhere on your system.
Initialize your workspace
Inside your git repository, run pm init. It creates the .agents/pm/ directory structure and a default config — zero prompts, zero fuss.
Tip: Commit the .agents/pm/ folder just like you commit your code.
Every team member and AI agent gets a shared, version-controlled view of your project items.
Create your first item
Create a work item with a type, title, and priority. pm-cli supports 11 built-in types —
Chore, Decision, Epic, Event, Feature, and more.
List and find work
Three commands cover most day-to-day browsing: pm list-open for a quick table,
pm context for an AI-optimized snapshot, and pm search for keyword or semantic lookup.
Claim and work
pm start-task claims an item and moves it to in_progress — preventing double-work when multiple agents or developers are active.
Add comments to capture progress notes as you go.
Plan agentic workflows New
pm plan is purpose-built for coding agents and AI-driven workflows.
Create a structured plan with ordered steps, link dependencies between items, and materialize
steps into real work items — all in a deterministic, scriptable way.
Agents can use pm plan approve <id> to gate execution until a human signs off.
Tip for agents: Use pm plan at the start of a task to decompose work into auditable steps.
The approve gate lets a human review the plan before any items are materialized — preventing runaway agent execution.
Close and track
Close work with a resolution note — that note lands in the append-only history log.
Then run pm stats to see project-level metrics.
You're done. That's the complete workflow.
Every step — create, claim, comment, close — is preserved as an RFC6902 patch in .agents/pm/history/.
Nothing is ever lost.
Key concepts to know
A handful of ideas underpin everything pm-cli does — understand these and the whole CLI clicks into place.
.agents/pm/ Storage
Items live as JSONL files inside your repository — fully version-controlled, no external database, no credentials to manage. git diff and git log work on your project data too.
Item Types
11 built-in types: Chore, Decision, Epic, Event, Feature, Issue, Meeting, Milestone, Plan, Reminder, Task. Each type has its own option policies and smart defaults. Custom types via config or extensions.
Status Flow
Items move through a clear lifecycle: draft → open → in_progress → closed or canceled. A blocked status is also available for items waiting on external work.
TOON Output
Token-Optimized Object Notation — a sparse output format designed for AI agents. Only changed fields are emitted, keeping LLM context windows lean without sacrificing readability. Machine contracts available via pm contracts --json.
Append-only History
Every change is recorded as an RFC6902 JSON patch in .agents/pm/history/ — full audit trail with content hashes and timestamps. The log never loses data and supports full state replay.
Extension System
9 capability types to extend pm-cli: custom commands, schemas, hooks, importers, renderers, search providers, preflights, services, and command flags. Publish and install extensions with a single command.
Essential commands
The ten commands you'll use on every project. For the full 96+ command reference, visit the commands page.
Keep going
You've got the basics. Here's where to go next.