# pm cli

project management is a context problem. pm cli keeps goals, acceptance criteria, decisions and history next to your code, as plain files that people and coding agents share. every change lands in an append-only history, so a fresh session can read what happened and carry on.

- git-native, plain-text storage
- cli, sdk and mcp server
- mit licensed

```sh
npm install -g @unbrained/pm-cli
```

requires node.js 22.18 or newer. source: https://github.com/unbraind/pm-cli. docs: https://pm-cli.unbrained.dev. package: https://www.npmjs.com/package/@unbrained/pm-cli.

## one task, two sessions

the first session creates a task, records a decision and stops. a second session starts with no chat history; everything it needs is in the repository. synthetic project, real output recorded with pm 2026.10.18 on 18 Oct 2026. lines marked … are trimmed.

### session 1: create the task with its acceptance criteria.

```console
$ pm create task "Rate-limit the public orders API" --ac "Clients over 100 requests/min per API key receive 429 with Retry-After" --ac "Limits hold across all replicas"
id: "shop-o0z1"
status: "open"
changed_field_count: 11
```

### session 1: claim it and start work.

```console
$ pm claim shop-o0z1 --start
id: "shop-o0z1"
action: "start_task"
…
  claimed_by: "agent-one"
…
```

### session 1: record the decision and the rejected alternative.

```console
$ pm comments shop-o0z1 "Decision: shared token bucket in Redis. Rejected in-memory counters: each of the 3 replicas would allow its own 100/min."
comments[1]{created_at,author,text}:
  "2026-10-18T19:09:13.058Z",agent-one,"Decision: shared token bucket in Redis. Rejected in-memory counters: each of the 3 replicas would allow its own 100/min."
…
```

### session 1: leave a note for whoever continues, then stop.

```console
$ pm comments shop-o0z1 "Next: middleware is written; integration test for Retry-After still missing."
comments[1]{created_at,author,text}:
  "2026-10-18T19:09:16.295Z",agent-one,"Next: middleware is written; integration test for Retry-After still missing."
…
```

### session 2: a fresh session asks what is in progress.

```console
$ pm list --status in_progress
items[1]{id,status,type,title}:
  shop-o0z1,in_progress,Task,Rate-limit the public orders API
…
```

### session 2: it reads the criteria, the decision and the open step.

```console
$ pm get shop-o0z1 --fields title,status,acceptance_criteria,comments
  title: "Rate-limit the public orders API"
  status: "in_progress"
  acceptance_criteria: "Clients over 100 requests/min per API key receive 429 with Retry-After; Limits hold across all replicas"
  comments[2]{created_at,author,text}:
    "2026-10-18T19:09:13.058Z",agent-one,"Decision: shared token bucket in Redis. Rejected in-memory counters: each of the 3 replicas would allow its own 100/min."
    "2026-10-18T19:09:16.295Z",agent-one,"Next: middleware is written; integration test for Retry-After still missing."
…
```

### session 2: it finishes the work and closes the task with evidence.

```console
$ pm close shop-o0z1 "Retry-After integration test added and passing" --resolution "Redis token bucket middleware plus integration test" --expected "429 with Retry-After above 100/min on every replica" --actual "Request 101 across 3 replicas returned 429 with Retry-After"
id: "shop-o0z1"
status: "closed"
…
close_reason: "Retry-After integration test added and passing"
```

### session 2: every step stays in the item history.

```console
$ pm history shop-o0z1
compact_history[8]{index,ts,op,author,patch_ops,…}:
  1,"2026-10-18T19:09:07.303Z",create,agent-one,11,…
  2,"2026-10-18T19:09:10.152Z",claim,agent-one,3,…
…
  4,"2026-10-18T19:09:13.058Z",comment_add,agent-one,2,…
  5,"2026-10-18T19:09:16.297Z",comment_add,agent-one,2,…
  6,"2026-10-18T19:09:18.294Z",release,agent-one,3,…
  7,"2026-10-18T19:09:25.381Z",claim,agent-two,3,…
  8,"2026-10-18T19:09:28.630Z",close,agent-two,9,…
…
```

## run it yourself

in an empty git repository; replace <id> with the id that `pm create` prints.

```sh
export PM_AUTHOR=agent-one
pm init shop --defaults --agent-guidance skip --workspace .
pm create task "Rate-limit the public orders API" --ac "Clients over 100 requests/min per API key receive 429 with Retry-After" --ac "Limits hold across all replicas"
pm claim <id> --start
pm comments <id> "Decision: shared token bucket in Redis. Rejected in-memory counters: each of the 3 replicas would allow its own 100/min."
pm comments <id> "Next: middleware is written; integration test for Retry-After still missing."
pm release <id>
export PM_AUTHOR=agent-two
pm list --status in_progress
pm get <id> --fields title,status,acceptance_criteria,comments
pm claim <id>
pm close <id> "Retry-After integration test added and passing" --resolution "Redis token bucket middleware plus integration test" --expected "429 with Retry-After above 100/min on every replica" --actual "Request 101 across 3 replicas returned 429 with Retry-After"
pm history <id>
```

## beyond the terminal

the cli keeps the record in plain files next to your code. the same tracker also runs hosted, shared live from the browser, chatgpt or any mcp client, and public trackers are searchable.

- documentation: [pm-cli.unbrained.dev](https://pm-cli.unbrained.dev). quickstart, command reference, package catalog and changelog.
- browser: [pm-web.unbrained.dev](https://pm-web.unbrained.dev). boards, lists and item history in the browser, live for the whole team.
- chatgpt and codex: [pm-gpt.unbrained.dev](https://pm-gpt.unbrained.dev). read, plan and update hosted pm projects from chatgpt and codex.
- any mcp client: [pm-mcp.unbrained.dev](https://pm-mcp.unbrained.dev). a remote mcp endpoint with oauth for coding agents and ides.
- public search: [pm-search.unbrained.dev](https://pm-search.unbrained.dev). find decisions, tasks and fixes in the pm items of public repositories, pinned to the exact commit.