pm-cli (pm)

pm is a git-native project management CLI for humans and coding agents. It stores work items in reviewable repository files, records every mutation in append-only history, and defaults to sparse TOON output so agents can spend fewer tokens while still getting deterministic data.

Start Here

| Need | Read | |------|------| | Install and create the first item | Quickstart | | Agent workflow and token-minimal loops | Agent Guide | | Command families and examples | Command Reference | | Settings, storage, search, and output | Configuration | | Safe test execution and linked tests | Testing | | Package and extension authoring | Packages and Extensions and SDK | | Codex native integration | Codex Plugin | | Maintainer release process (daily auto-release + local parity) | Releasing | | Contributor internals | Architecture |

Full documentation starts at docs/README.md.

Install the optional guide package when an agent should stay inside terminal context for local docs routing:

pm install guide-shell --project
pm guide
pm guide quickstart
pm guide commands --depth standard
pm guide skills --depth deep --format markdown

Install

pm-cli requires Node.js 20 or newer.

npm install -g @unbrained/pm-cli
pm --version
pm --help

Use the npm registry package for global installs and updates. Avoid npm install -g from the GitHub git URL for routine updates; npm can leave a stale global shim when replacing git-sourced installs. If that happens, run bash scripts/install.sh --repair from a checkout or npm uninstall -g @unbrained/pm-cli && npm install -g @unbrained/pm-cli.

Project-local invocation also works:

npx @unbrained/pm-cli --help

For Claude Code, install the native plugin (no pm CLI required):

/plugin install pm-cli@pm

This registers 18 MCP tools, 5 workflow skills, 14 slash commands, 3 subagents, hybrid TUI tracking, and a session-start context hook — all without shelling out to the pm CLI.

pm packages use the same package-first vocabulary:

pm install '*'
pm install ./my-package
pm package manage --project
pm package doctor --detail summary
pm upgrade --dry-run

The legacy pm extension ... command remains available for existing automation.

60 Second Example

pm init

pm create \
  --title "Fix stale lock restore failure" \
  --description "Restore should retry cleanly after stale lock cleanup." \
  --type Issue \
  --status open \
  --priority 1 \
  --tags "restore,locks" \
  --ac "Restore succeeds after stale lock cleanup and has regression coverage." \
  --create-mode progressive

pm list-open --limit 10
pm claim <item-id>
pm update <item-id> --status in_progress --message "Start implementation"
pm files <item-id> --add path=src/core/lock/lock.ts
pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/lock.spec.ts",timeout_seconds=240
pm test <item-id> --run --progress
pm close <item-id> "Fixed stale lock retry path; linked test passed."
pm release <item-id>

Agent Loop

Use pm context first, then search before creating anything:

pm context --limit 10
pm search "keywords for the requested work" --limit 10
pm list-open --limit 20
pm list-in-progress --limit 20

If no relevant item exists, create a parent lineage before child work, claim the child item, link changed files/docs/tests, and leave evidence comments before closing. The full workflow is in the Agent Guide.

For token-aware local routing, install guide-shell with pm install guide-shell --project, then use pm guide workflows and drill into related topics (commands, skills, release) only when needed.

Release Automation

• Daily release preparation runs in .github/workflows/auto-release.yml.
• Tag-driven publishing remains in .github/workflows/release.yml.
• Local parity commands:
  • pnpm release:pipeline:dry-run
  • pnpm release:pipeline -- --telemetry-mode required

Core Model

• Items live under .agents/pm/ as TOON by default, with JSON-front-matter markdown also supported.
• History lives in .agents/pm/history/<id>.jsonl and is append-only.
• Statuses are draft, open, in_progress, blocked, closed, and canceled.
• Built-in types include Epic, Feature, Task, Chore, Issue, Decision, Event, Reminder, Milestone, and Meeting.
• Output defaults to sparse TOON. Use --json for strict parsing.
• pm contracts is the machine-readable command and schema contract surface for agents.
• pm guide is the optional local progressive-disclosure docs and skills index for agents after installing guide-shell.

Tracker References

This documentation refresh is tracked through pm:

• pm-3042 - documentation overhaul epic
• pm-r9gu - documentation structure feature
• pm-1sb2 - README and public docs rewrite task

Docs should link to relevant pm items, and pm items should link back to changed docs through pm docs.

License

MIT