flagship project, open source

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.

source on github documentation npm package

demonstration

one task, two sessions

the first agent session creates a task, records a decision and stops. a second session starts with no chat history at all. everything it needs is in the repository.

the project is synthetic; the output is real, recorded with pm 2026.10.18. item ids differ on every run.

shop-api · synthetic project · pm 2026.10.18

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

    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

  2. claim it and start work.

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

  3. record the decision and the rejected alternative.

    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."
…

  4. leave a note for whoever continues, then stop.

    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."
…

  5. session 1 ends. only the repository carries over.

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

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

  6. it reads the criteria, the decision and the open step.

    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."
…

  7. it finishes the work and closes the task with evidence.

    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"

  8. every step stays in the item history.

    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,…
…

recorded 18 Oct 2026 with pm 2026.10.18. lines marked … are trimmed.

try it yourself

run the same handoff

install the cli, then run these commands in an empty git repository. use a second terminal for session 2: nothing but the files in the repository carries over.

npm install -g @unbrained/pm-cli

requires node.js 22.18 or newer.

# Session 1
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>

# Session 2: a new terminal, no shared history
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>

replace <id> with the id that pm create prints.

ecosystem

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.