States

What the agent is doing now: one rewritten snapshot per workstream, plus the checkpoint ritual.

1. Step 1 of 4

   Snapshot what you are doing

   A state is what the agent is doing NOW, one per workstream. It is REWRITTEN every time (matched by title or sta_ id), never appended, so a state is always the current truth, not a history. Status moves active → parked → done. The body is the resume note: where you are, what is next, the ids in play. Boot loads every ACTIVE state, so this is how a fresh session picks up mid-task.

   plm agent state set

   $ plm agent state set agents-backend --status active --body -

   ✓ state sta_2ee2c65af64d48b2 (agents-backend) rewritten

   full form · plm agent state set <title> [--status active|parked|done] [--body -|text]

2. Step 2 of 4

   Scan the workstreams

   The board of what the agent is carrying. Rows are status-tagged and ordered active → parked → done, so what matters now sits on top; the footer counts the split. A bare query searches title and body, and --active / --parked / --done narrow to one status. This is the first thing to read on resume: what is still open.

   plm agent state ls

   $ plm agent state ls --active

   sta_2ee2c65af64d48b2 [active] agents-backend

   1 states (1 active · 0 parked · 0 done)

   full form · plm agent state ls [query] [--active|--parked|--done]

3. Step 3 of 4

   Read the resume note

   ls tells you a workstream exists; show reads it. The full body is the handoff the agent wrote to its future self — where it stopped, what is next, the live ids. With NO target it prints every active state in full, so a fresh session gets back in context with a single command; pass an id or title to read one exactly.

   plm agent state show

   $ plm agent state show

   sta_2ee2c65af64d48b2 · active

   agents-backend

   ## Now

   Migration complete…

   ## Next

   - Adversarial review workflow

   full form · plm agent state show [id|title]

4. Step 4 of 4

   Checkpoint before you lose context

   The pre-compact ritual as one verb: it rewrites the active state AND drops one log line, so the snapshot and the trail move together. With no title it targets THE active state, so a fast checkpoint can never fork a new workstream on a mistyped title. Run it whenever you are about to lose context (compaction, a handoff, end of session) and the next boot resumes exactly here.

   plm agent checkpoint

   $ plm agent checkpoint --body -

   ✓ checkpointed agents-backend

   full form · plm agent checkpoint [title] --body -|text

Also in this chapter