{"_id":"@aprimediet/todo","name":"@aprimediet/todo","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aprimediet/todo","version":"1.0.0","type":"module","description":"todo_write tool + /todos command — extracted from @aprimediet/minion. Multi-step auto-create + crash-resilient resumption for the pi coding agent.","keywords":["pi-package"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aprimediet/pi-todo.git"},"bugs":{"url":"https://github.com/aprimediet/pi-todo/issues"},"homepage":"https://github.com/aprimediet/pi-todo#readme","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"scripts":{"test":"vitest run","test:watch":"vitest","prepublishOnly":"node -e \"const pkg=require('./package.json'); if(!pkg.files||pkg.files.length===0){console.error('files field empty — abort');process.exit(1)}; console.log('Publishing '+pkg.name+'@'+pkg.version+' with files:', pkg.files)\"","pack:dry":"npm pack --dry-run"},"pi":{"extensions":["./index.ts"]},"peerDependencies":{"@earendil-works/pi-coding-agent":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","typebox":"*"},"devDependencies":{"@types/node":"^20.0.0","vitest":"^1.6.0"},"engines":{"node":">=20"},"gitHead":"b5ab55a1df51276a0ef8b3a75a28226ea58cfa95","_id":"@aprimediet/todo@1.0.0","_nodeVersion":"24.18.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-afjqOoJySwGLXrIuJ2xeGxLgcmnac1TrWr3mjg7Dwq5k6blcXXzyAjms3rGjgrrmEnGNeweaK3K0+ykGtHeWjw==","shasum":"bb15c848a4616d043da977eecac2c3245e4460e7","tarball":"https://registry.npmjs.org/@aprimediet/todo/-/todo-1.0.0.tgz","fileCount":10,"unpackedSize":34687,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDLvng9WdwLpxaCnLbBA+e9DlY08nx+toYDpjdOEngvjwIhAKbb6UrJRqM8t/4tJOYRUqPFyQkUGA/Nt2HqG+pVZVZ0"}]},"_npmUser":{"name":"aditya.prima","email":"aprimediet@gmail.com"},"directories":{},"maintainers":[{"name":"aditya.prima","email":"aprimediet@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/todo_1.0.0_1782705650450_0.2243452625949769"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-29T04:00:50.243Z","1.0.0":"2026-06-29T04:00:50.581Z","modified":"2026-06-29T04:00:50.958Z"},"maintainers":[{"name":"aditya.prima","email":"aprimediet@gmail.com"}],"description":"todo_write tool + /todos command — extracted from @aprimediet/minion. Multi-step auto-create + crash-resilient resumption for the pi coding agent.","homepage":"https://github.com/aprimediet/pi-todo#readme","keywords":["pi-package"],"repository":{"type":"git","url":"git+https://github.com/aprimediet/pi-todo.git"},"bugs":{"url":"https://github.com/aprimediet/pi-todo/issues"},"license":"MIT","readme":"# @aprimediet/todo\n\nStandalone `todo_write` tool + `/todos` command for the [pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent). Extracted from `@aprimediet/minion` v1.0.0; minion v1.1.0+ depends on this package instead of bundling the tool itself.\n\n## Install\n\n```bash\npi install npm:@aprimediet/todo\n```\n\nIf 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`.\n\n## What it does\n\n- **`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`.\n- **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`).\n- **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.\n- **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`.\n- **`/todos` command** — show current checklist. Subcommands: `list` (browse snapshots), `show <file>` (cat one), `clear` (in-memory reset only), `config` (resolved settings).\n\n## Configuration\n\nConfig 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.\n\nExample `~/.pi/agent/settings.json`:\n\n```json\n{\n  \"defaultProvider\": \"opencode\",\n  \"defaultModel\": \"big-pickle\",\n  \"todos\": {\n    \"enabled\": true,\n    \"snapshotEveryCall\": true,\n    \"multiStepThreshold\": 3,\n    \"injectionMode\": \"hint\",\n    \"pruneSnapshotsDays\": 30\n  }\n}\n```\n\n- Flags: `--todo-disabled`, `--todo-mode <hint|silent|strict>`, `--todo-snapshot <true|false>`.\n- Env: `TODO_DISABLED=1`.\n- `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).\n- `snapshotEveryCall`: if `false`, only snapshot on `session_shutdown` (cheaper but loses mid-session forensics).\n\n## Storage model — clean working tree\n\nThe 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:\n\n```\n<cwd>/.pi/<project-id>.md            ← the ONLY artifact in your working tree (a pointer, shared with @aprimediet/memory + @aprimediet/minion)\n\n~/.pi/projects/<project-id>/\n  todos/                              ← owned by @aprimediet/todo (this package)\n    2026-06-29-abc123.md              ← one snapshot per session-day (mode 0o600)\n    2026-06-28-xyz789.md\n    2026-06-27-qwe456.md\n  project.json                        ← shared metadata (also written by memory + minion)\n```\n\nThe 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.\n\n## Commands\n\n- `todo_write { todos: [{ content, activeForm, status }] }` — replace the task list.\n- `/todos` — show the current checklist.\n- `/todos list` — list all snapshot files in `~/.pi/projects/<id>/todos/` (size + mtime).\n- `/todos show <filename>` — cat a specific snapshot file.\n- `/todos clear` — reset current session todos (in-memory only; snapshots untouched).\n- `/todos config` — show resolved config.\n\n## Compatibility\n\n| Co-installed extension | Behavior |\n|---|---|\n| `@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. |\n| `@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.** |\n| `@aprimediet/memory` | Disjoint scopes. Both write only under their own subdir (`memory/` vs `todos/`). Marker file is shared. |\n\n## Notes & boundaries\n\n- **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).\n- **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.\n- **Disable entirely** with `--todo-disabled` / `TODO_DISABLED=1` / `\"enabled\": false`.\n- The `strict` injection mode is documented but not yet implemented in v1.0; it currently behaves like `hint`. (Tracked for v1.1.)\n\n## License\n\nMIT — same as `@aprimediet/minion`.\n","readmeFilename":"README.md","_rev":"1-37544602b46c317d0a8433ab322fcbff"}