@aprimediet/todo

Standalone todo_write tool + /todos command for the pi coding agent. Extracted from @aprimediet/minion v1.0.0; minion v1.1.0+ depends on this package instead of bundling the tool itself.

Install

pi install npm:@aprimediet/todo

If you currently use @aprimediet/minion v1.0.0, install this package alongside it before upgrading minion to v1.1.0+. The two are co-installed: minion v1.1.0+ handles subagent / task / agents, this package handles todo_write / /todos.

What it does

• todo_write tool — Claude-Code-style TodoWrite. The model calls it with the full updated list whenever a task starts or finishes. State lives in the tool result's details (branch-correct on session fork) and is reconstructed by scanning the session branch on session_start / session_tree.
• Auto-create for multi-step prompts — when the user's prompt contains ≥3 detectable steps (imperative verbs, explicit "first/then/finally" sequencing, or a numbered list), a system-prompt hint nudges the agent to call todo_write as its first action. Configurable threshold (multiStepThreshold, default 3).
• Markdown snapshots — every todo_write call writes a snapshot to ~/.pi/projects/<id>/todos/YYYY-MM-DD-<rand>.md (mode 0o600). Snapshots older than pruneSnapshotsDays (default 30) are cleaned at session start.
• Crash-resilient resumption — three layers: (1) in-session branch replay of the last todo_write details.todos, (2) snapshot file recovery, (3) before_agent_start recovery hint when a recent snapshot exists for a project whose lastSeen < 24h.
• /todos command — show current checklist. Subcommands: list (browse snapshots), show <file> (cat one), clear (in-memory reset only), config (resolved settings).

Configuration

Config lives as an object under the todos key in ~/.pi/agent/settings.json. The extension auto-seeds a default todos: { enabled: true, snapshotEveryCall: true, multiStepThreshold: 3, injectionMode: "hint", pruneSnapshotsDays: 30 } object into settings.json on first session if no todos key is present (preserves other settings keys). Resolution order: hardcoded defaults → settings.json#todos → env (TODO_DISABLED=1) → flags.

Example ~/.pi/agent/settings.json:

{
  "defaultProvider": "opencode",
  "defaultModel": "big-pickle",
  "todos": {
    "enabled": true,
    "snapshotEveryCall": true,
    "multiStepThreshold": 3,
    "injectionMode": "hint",
    "pruneSnapshotsDays": 30
  }
}

• Flags: --todo-disabled, --todo-mode <hint|silent|strict>, --todo-snapshot <true|false>.
• Env: TODO_DISABLED=1.
• injectionMode: hint (append prompts/multi-step.md to system prompt on multi-step turns), silent (no injection; tool's own promptSnippet + promptGuidelines still apply), strict (TODO — not yet implemented in v1.0; treated like hint for now).
• snapshotEveryCall: if false, only snapshot on session_shutdown (cheaper but loses mid-session forensics).

Storage model — clean working tree

The only thing written into your working tree is a single identifier file, <cwd>/.pi/<project-id>.md. Every todo artifact (snapshot files, project.json) lives globally, keyed by that project id:

<cwd>/.pi/<project-id>.md            ← the ONLY artifact in your working tree (a pointer, shared with @aprimediet/memory + @aprimediet/minion)

~/.pi/projects/<project-id>/
  todos/                              ← owned by @aprimediet/todo (this package)
    2026-06-29-abc123.md              ← one snapshot per session-day (mode 0o600)
    2026-06-28-xyz789.md
    2026-06-27-qwe456.md
  project.json                        ← shared metadata (also written by memory + minion)

The project id is <dir-slug>-<8charPathHash>, recorded in the marker — stable across moves. Snapshot files are human-readable markdown; the in-session todos state lives in the tool result's details and is rebuilt on session start.

Commands

• todo_write { todos: [{ content, activeForm, status }] } — replace the task list.
• /todos — show the current checklist.
• /todos list — list all snapshot files in ~/.pi/projects/<id>/todos/ (size + mtime).
• /todos show <filename> — cat a specific snapshot file.
• /todos clear — reset current session todos (in-memory only; snapshots untouched).
• /todos config — show resolved config.

Compatibility

Co-installed extension	Behavior
@aprimediet/minion v1.1.0+	minion no longer registers todo_write or /todos. This package is the sole owner. The footer pill ▣ done/total is set by this package.
@aprimediet/minion v1.0.0	minion still registers its own todo_write (name collision). Don't co-install both at v1.0.0 — upgrade minion to v1.1.0+ first.
@aprimediet/memory	Disjoint scopes. Both write only under their own subdir (memory/ vs todos/). Marker file is shared.

Notes & boundaries

• Your working tree only ever gets <cwd>/.pi/<project-id>.md — same shared marker used by @aprimediet/memory and @aprimediet/minion. Safe to commit (stable id) and safe to delete (recreated).
• Auto-create behavior is heuristic. The injection happens when estimateStepCount(prompt) >= multiStepThreshold. False positives are recoverable: the agent just gets nudged, and a /todos clear resets state.
• Disable entirely with --todo-disabled / TODO_DISABLED=1 / "enabled": false.
• The strict injection mode is documented but not yet implemented in v1.0; it currently behaves like hint. (Tracked for v1.1.)

License

MIT — same as @aprimediet/minion.