{"id":50774931,"url":"https://github.com/roodriigoooo/pi-docket","last_synced_at":"2026-06-11T22:30:46.154Z","repository":{"id":355250996,"uuid":"1226427018","full_name":"roodriigoooo/pi-docket","owner":"roodriigoooo","description":"An inbox and worker fleet for the Pi coding agent. Parallel tmux workers, decision-focused dock, durable checkpoint handoffs.","archived":false,"fork":false,"pushed_at":"2026-06-06T23:40:14.000Z","size":21468,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T00:10:55.301Z","etag":null,"topics":["agentic-coding","artifact-navigator","checkpoints","event-stream","handoffs","parallel-agents","pi","spawn-worker-sessions","tmux"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@roodriigoooo/trail","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roodriigoooo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T11:37:07.000Z","updated_at":"2026-06-06T23:40:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/roodriigoooo/pi-docket","commit_stats":null,"previous_names":["roodriigoooo/trail","roodriigoooo/pi-docket"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/roodriigoooo/pi-docket","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roodriigoooo%2Fpi-docket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roodriigoooo%2Fpi-docket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roodriigoooo%2Fpi-docket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roodriigoooo%2Fpi-docket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roodriigoooo","download_url":"https://codeload.github.com/roodriigoooo/pi-docket/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roodriigoooo%2Fpi-docket/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34221150,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","artifact-navigator","checkpoints","event-stream","handoffs","parallel-agents","pi","spawn-worker-sessions","tmux"],"created_at":"2026-06-11T22:30:45.478Z","updated_at":"2026-06-11T22:30:46.147Z","avatar_url":"https://github.com/roodriigoooo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/docket_logo.jpeg\" alt=\"Docket logo\" width=\"220\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@roodriigoooo/pi-docket\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@roodriigoooo/pi-docket?color=cb3837\u0026label=npm\u0026logo=npm\" alt=\"npm version\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# pi-docket\n\nDocket is a decision queue for work done inside pi.\n\nIt pulls the few moments that need human judgment out of long agent work: worker findings, proposed patches, failed commands, saved evidence bundles, and questions. It is not a transcript browser, not a memory system, and not a task manager. Docket keeps evidence available and asks: **what needs a decision now?**\n\n\u003e Formerly `trail`. The rename is intentional: the product is no longer framed as a history trail or session-resume system. Docket is a docket of cases needing judgment, with evidence bundles attached.\n\n## Core philosophy\n\n- **Pi owns sessions.** Use pi's `/tree`, `/fork`, `/clone`, `/compact`, `/new`, and `/resume` for conversation topology and context-window management.\n- **Docket owns decisions.** It ranks artifacts into review items, shows cards, and keeps evidence out of model context until you attach it.\n- **tmux owns parallel visibility.** Workers are visible pi processes in one shared tmux session. You can attach and inspect them directly.\n- **Workers are explicit.** Docket may eventually suggest a worker only when context-heavy work is obvious and maps to a known worker kind. It must never silently spawn.\n\n## Install\n\n```bash\npi install git:github.com/roodriigoooo/pi-docket\n```\n\nOpen Docket:\n\n```bash\n/docket\n```\n\nSpawn a worker explicitly:\n\n```bash\n/docket spawn --as scout map callers of getUser()\n```\n\nSave evidence as a zero-token bundle:\n\n```bash\n/docket save auth investigation findings\n```\n\nLoad a bundle or worker artifacts:\n\n```bash\n/docket load last\n/docket load w1\n```\n\n## Rename from Trail\n\nThis release is a breaking rename.\n\n- Package: `@roodriigoooo/pi-docket`\n- GitHub repo title: `pi-docket`\n- Slash command: `/docket`\n- Old `/trail` commands are not kept as aliases.\n- Worker protocol tools are now `docket_wait`, `docket_done`, `docket_fail`, `docket_todos`, and `docket_spawn_child`.\n- Storage/config paths now use `docket`:\n  - `~/.pi/agent/docket/`\n  - `~/.pi/agent/docket.json`\n  - `\u003cproject\u003e/.pi/docket.json`\n  - `\u003cproject\u003e/.pi/docket/worker-kinds/*.md`\n\nIf you need old data, copy it manually before deleting the old package:\n\n```bash\ncp -R ~/.pi/agent/trail ~/.pi/agent/docket\ncp ~/.pi/agent/trail.json ~/.pi/agent/docket.json 2\u003e/dev/null || true\ncp -R .pi/trail .pi/docket 2\u003e/dev/null || true\ncp .pi/trail.json .pi/docket.json 2\u003e/dev/null || true\n```\n\n## Basic loop\n\n```text\n  work / spawn       capture             decide                act\n  current pi    -\u003e   artifacts       -\u003e  /docket cards   -\u003e   Enter review\n  /docket spawn      status.json         evidence             c reply/save\n                                      bundles/workers         a attach ref\n```\n\n1. **Work or spawn** — keep working in the parent session, or explicitly start a background worker with `/docket spawn`.\n2. **Capture** — Docket records failed commands, file changes, worker results, saved bundles, and questions.\n3. **Decide** — `/docket` opens only items that likely need attention.\n4. **Act** — review, reply, promote, dismiss, attach evidence, save/load bundles, or attach to tmux.\n\n## Commands\n\nPrimary commands:\n\n| Command | Purpose |\n|---|---|\n| `/docket` | Open decision docket. |\n| `/docket verdict [w\u003cN\u003e]` | Resolve the top worker decision (accept/reject/chat). |\n| `/docket spawn [--fresh] [--as \u003ckind\u003e] \u003ctask\u003e` | Start explicit background worker. |\n| `/docket tell w\u003cN\u003e [text]` | Reply to worker. |\n| `/docket attach [w\u003cN\u003e]` | Copy tmux attach command for shared worker session. |\n| `/docket save [flags] [note]` | Save selected evidence as bundle and label current pi tree leaf. |\n| `/docket load [id\\|last\\|w\u003cN\u003e]` | Mount bundle or worker artifacts at zero model-context cost. |\n\nAdvanced commands:\n\n| Command | Purpose |\n|---|---|\n| `/docket workers [--all]` | Worker dashboard. |\n| `/docket kinds` | List worker kinds. |\n| `/docket respawn \u003cw\u003cN\u003e\\|all\u003e` | Relaunch worker whose tmux window died. |\n| `/docket answers [query]` | Browse assistant/worker answers. |\n| `/docket log` | Audit timeline grouped by episode. |\n| `/docket search \u003cquery\u003e` | Ranked artifact search. |\n| `/docket list [--include-consumed] [--workers\\|--all]` | List saved bundles or workers. |\n| `/docket unload \u003cid\\|w\u003cN\u003e\\|all\u003e` | Drop mounted bundle/worker artifacts. |\n| `/docket delete [id\\|last\\|w\u003cN\u003e]` | Delete bundle or worker. Worker delete cascades to children. |\n| `/docket ref \u003cartifact-id\u003e` | Attach compact artifact reference to next prompt. |\n| `/docket inject-full \u003cartifact-id\u003e` | Attach full artifact text to next prompt. |\n| `/docket copy \u003cartifact-id\u003e` | Copy artifact text. |\n| `/docket clear` | Drop pending chips/widgets. |\n\nNo short aliases are intentionally provided. Fewer commands, clearer intent.\n\n## Evidence bundles\n\nA Docket bundle is a frozen artifact sidecar plus a small orientation markdown file. It is not a model-written summary by default.\n\n`/docket save`:\n\n- selects relevant artifacts,\n- lets you prune/edit the bundle header,\n- writes `\u003cid\u003e.md` + `\u003cid\u003e.artifacts.json`,\n- labels the current pi session tree leaf as `docket:\u003cid\u003e`.\n\n`/docket load` mounts bundle artifacts into the current session's Docket navigator at zero model-context cost. Nothing enters the model prompt until you explicitly attach a compact ref or full artifact.\n\nThis deliberately complements pi:\n\n- use `/tree` to move conversation state,\n- use `/fork` or `/clone` to split sessions,\n- use `/compact` for lossy summary,\n- use `/docket save` for durable evidence,\n- use `/docket load` when that evidence becomes relevant.\n\n## Workers\n\n`/docket spawn \u003ctask\u003e` starts a background pi worker as one window in a shared tmux session named `docket-workers`.\n\nWorkers have:\n\n- hidden workspace, often a detached git worktree,\n- task file,\n- `status.json`,\n- `artifacts.json`,\n- append-only `events.ndjson`,\n- protocol tools for parent communication.\n\nWorker artifacts never enter model context automatically except for the short ready summary, if enabled. Full evidence stays on disk until loaded or attached.\n\n### Worker kinds\n\nBundled kinds:\n\n- `default` — general worker, edits allowed when task asks.\n- `scout` — fast read-only recon.\n- `patcher` — edits in worker worktree and proposes a change set.\n\nExamples:\n\n```bash\n/docket spawn --as scout find route handlers that touch auth cookies\n/docket spawn --as patcher rename AccountService in src only\n```\n\nCustom kinds live in:\n\n- `~/.pi/agent/docket/worker-kinds/*.md`\n- `\u003cproject\u003e/.pi/docket/worker-kinds/*.md`\n\nSee [docs/configuration.md](./docs/configuration.md#worker-kinds).\n\n### Worker protocol\n\nWorkers use tools, not shell commands:\n\n| Tool | Purpose |\n|---|---|\n| `docket_todos` | Publish small progress board. |\n| `docket_wait` | Ask parent for input and pause. |\n| `docket_done` | Mark useful output ready for review. |\n| `docket_fail` | Mark cannot continue with no useful partial output. |\n| `docket_spawn_child` | Dispatch allowed child worker kind. |\n\nWorker-side `/docket wait`, `/docket done`, and `/docket fail` are fallback prompt commands only.\n\n## tmux\n\nAll workers live in one shared tmux session:\n\n```bash\ntmux attach -t docket-workers\n```\n\n`/docket attach` copies the attach command. `/docket attach w2` selects that worker's window.\n\nThis is intentional: tmux gives direct observability and real parallelism, while Docket controls artifact capture and parent/worker coordination.\n\n## Development\n\nRun from repo:\n\n```bash\npi --no-extensions -e ./extensions/docket.ts\n```\n\nSmoke test:\n\n```bash\nnpm run smoke:help\n```\n\nType check:\n\n```bash\nnpm run check\n```\n\nTests:\n\n```bash\nnpm test\n```\n\nDry-run package:\n\n```bash\nnpm run pack:dry\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froodriigoooo%2Fpi-docket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froodriigoooo%2Fpi-docket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froodriigoooo%2Fpi-docket/lists"}