JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2397
  • Score
    100M100P100Q111570F
  • License MIT

Git-native project management CLI for humans and agents.

Package Exports

  • @unbrained/pm-cli
  • @unbrained/pm-cli/cli
  • @unbrained/pm-cli/package.json
  • @unbrained/pm-cli/sdk

Readme

pm-cli (pm)

CI npm version Node >=20 License: MIT

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
Extension authoring Extensions and SDK
Maintainer release process (daily auto-release + local parity) Releasing
Contributor internals Architecture

Full documentation starts at docs/README.md.

Install

pm-cli requires Node.js 20 or newer.

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

Project-local invocation also works:

npx @unbrained/pm-cli --help

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,scope=project
pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/lock.spec.ts",scope=project,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.

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.

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.

Privacy Boundary

Private production operations material is local-only, gitignored, and intentionally not linked from public documentation or packaged release files. Keep public docs focused on user-facing CLI behavior and safe contribution workflows.

License

MIT