{"_id":"@abix5/pi-beads","_rev":"3-5def5bf887c486046a6b7dd787c69015","name":"@abix5/pi-beads","dist-tags":{"latest":"0.2.2"},"versions":{"0.2.0":{"name":"@abix5/pi-beads","version":"0.2.0","keywords":["pi-package","pi","pi-extension","pi-coding-agent","beads","bd","task-tracking","issue-tracker","context-efficient","multi-repo"],"author":{"name":"Dmitriy Nenashev","email":"6427182+abix5@users.noreply.github.com"},"license":"MIT","_id":"@abix5/pi-beads@0.2.0","maintainers":[{"name":"abix5","email":"abix5@yandex.ru"}],"homepage":"https://github.com/abix5/pi-beads#readme","bugs":{"url":"https://github.com/abix5/pi-beads/issues"},"pi":{"skills":["./skills"],"extensions":["./src/index.ts"]},"dist":{"shasum":"013f7a08bd3e3801182cdca3f90b6f8f1da061cb","tarball":"https://registry.npmjs.org/@abix5/pi-beads/-/pi-beads-0.2.0.tgz","fileCount":6,"integrity":"sha512-yOf3OKLPUrsvtFzqcYOAKAXo4LV41t9NnEIBmfzVf1yqpmj5CzSSow2759SoVhIqfB1FYg+Ix5PQbkVdpRFJCQ==","signatures":[{"sig":"MEYCIQCNbygkoABtGqtZ4ZhY9xHI22D+XM3sK4v0+nGuL7332AIhANWfR1GjExL+NuhYR40ha6OFAZ5fNDTk2ZXeaJh7N1E2","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66501},"type":"module","engines":{"node":">=22.6.0"},"gitHead":"04644a9e61ddf3b1fb09dfa85a23cc52414a9d2d","scripts":{"test":"node --test src/widget-lines.test.mjs"},"_npmUser":{"name":"abix5","email":"abix5@yandex.ru"},"repository":{"url":"git+https://github.com/abix5/pi-beads.git","type":"git"},"_npmVersion":"10.9.8","description":"Context-lean beads (bd) task tracking for pi: compact beads_* tools, once-per-segment lean prime, umbrella multi-repo reads with prefix-routed writes, an in-progress widget, and a bundled beads skill.","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-beads_0.2.0_1787507143448_0.5266411005156015","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@abix5/pi-beads","version":"0.2.1","keywords":["pi-package","pi","pi-extension","pi-coding-agent","beads","bd","task-tracking","issue-tracker","context-efficient","multi-repo"],"author":{"name":"Dmitriy Nenashev","email":"6427182+abix5@users.noreply.github.com"},"license":"MIT","_id":"@abix5/pi-beads@0.2.1","maintainers":[{"name":"abix5","email":"abix5@yandex.ru"}],"homepage":"https://github.com/abix5/pi-beads#readme","bugs":{"url":"https://github.com/abix5/pi-beads/issues"},"pi":{"image":"https://raw.githubusercontent.com/abix5/pi-beads/main/docs/assets/widget.png","skills":["./skills"],"extensions":["./src/index.ts"]},"dist":{"shasum":"60ce44313f94ce95ea217732e5708dfaece1cc7d","tarball":"https://registry.npmjs.org/@abix5/pi-beads/-/pi-beads-0.2.1.tgz","fileCount":6,"integrity":"sha512-L8DxVMUU/94SbHmjZiqCccHu2Xro2hZ/eDMMaQdGgtUleO+ztxHgU9UY6FIqNth38HLbgMgixtnLp/p2lDSyCQ==","signatures":[{"sig":"MEUCIBJGbKMNJpNisv2QMM/GNLEbo9Vs2Vy+nEWjGCfjII+RAiEAxvEsmto6LfcLrtQmS1FqZq6nVWQAtffw/ex6h1d8O84=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66618},"type":"module","engines":{"node":">=22.6.0"},"gitHead":"0439dcdd5fa595385b20e415fa6b61f1b0a3fd43","scripts":{"test":"node --test src/widget-lines.test.mjs"},"_npmUser":{"name":"abix5","email":"abix5@yandex.ru"},"repository":{"url":"git+https://github.com/abix5/pi-beads.git","type":"git"},"_npmVersion":"10.9.8","description":"Context-lean beads (bd) task tracking for pi: compact beads_* tools, once-per-segment lean prime, umbrella multi-repo reads with prefix-routed writes, an in-progress widget, and a bundled beads skill.","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-beads_0.2.1_1787508221965_0.7157388958815323","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@abix5/pi-beads","version":"0.2.2","type":"module","description":"Context-lean beads (bd) task tracking for pi: compact beads_* tools, once-per-segment lean prime, umbrella multi-repo reads with prefix-routed writes, an in-progress widget, and a bundled beads skill.","license":"MIT","author":{"name":"Dmitriy Nenashev","email":"6427182+abix5@users.noreply.github.com"},"homepage":"https://github.com/abix5/pi-beads#readme","repository":{"type":"git","url":"git+https://github.com/abix5/pi-beads.git"},"bugs":{"url":"https://github.com/abix5/pi-beads/issues"},"keywords":["pi-package","pi","pi-extension","pi-coding-agent","beads","bd","task-tracking","issue-tracker","context-efficient","multi-repo"],"pi":{"extensions":["./src/index.ts"],"skills":["./skills"],"image":"https://raw.githubusercontent.com/abix5/pi-beads/main/docs/assets/widget.png"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"engines":{"node":">=22.6.0"},"publishConfig":{"access":"public"},"scripts":{"test":"node --test src/widget-lines.test.mjs"},"main":"./src/index.ts","exports":"./src/index.ts","_id":"@abix5/pi-beads@0.2.2","gitHead":"4843a6809734d46215a7db962eaff597d5d816e9","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-qXaPvWSISBEDUGpYJJW6ruw28Eis3didIa/hHiackjEoPCzkieRmo7TtYiizzKskg2gMZwD4dJFMDWFvhSyj1g==","shasum":"79eb29f55a7b5d3d7c3cd35103e39265efd2a779","tarball":"https://registry.npmjs.org/@abix5/pi-beads/-/pi-beads-0.2.2.tgz","fileCount":6,"unpackedSize":66677,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGwETuQnsskf8OJ3jcfxysbArcgNy1SPq1LnMeP7wZk7AiEA95yJ22nUnbxPYhZ6oYJetzL1KSNH+KihnICRkMfwMmA="}]},"_npmUser":{"name":"abix5","email":"abix5@yandex.ru"},"directories":{},"maintainers":[{"name":"abix5","email":"abix5@yandex.ru"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-beads_0.2.2_1787571169805_0.7568572508318716"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T17:45:43.317Z","modified":"2026-08-24T11:32:50.182Z","0.2.0":"2026-08-23T17:45:43.609Z","0.2.1":"2026-08-23T18:03:42.113Z","0.2.2":"2026-08-24T11:32:49.946Z"},"bugs":{"url":"https://github.com/abix5/pi-beads/issues"},"author":{"name":"Dmitriy Nenashev","email":"6427182+abix5@users.noreply.github.com"},"license":"MIT","homepage":"https://github.com/abix5/pi-beads#readme","keywords":["pi-package","pi","pi-extension","pi-coding-agent","beads","bd","task-tracking","issue-tracker","context-efficient","multi-repo"],"repository":{"type":"git","url":"git+https://github.com/abix5/pi-beads.git"},"description":"Context-lean beads (bd) task tracking for pi: compact beads_* tools, once-per-segment lean prime, umbrella multi-repo reads with prefix-routed writes, an in-progress widget, and a bundled beads skill.","maintainers":[{"name":"abix5","email":"abix5@yandex.ru"}],"readme":"# @abix5/pi-beads\n\n[![npm](https://img.shields.io/npm/v/%40abix5%2Fpi-beads)](https://www.npmjs.com/package/@abix5/pi-beads)\n[![license: MIT](https://img.shields.io/npm/l/%40abix5%2Fpi-beads)](https://github.com/abix5/pi-beads/blob/main/LICENSE)\n\nA context-lean bridge between the [pi coding-agent](https://github.com/earendil-works/pi)\nand the [beads](https://github.com/steveyegge/beads) issue tracker (`bd`). The agent\ngets compact in-process `beads_*` tools instead of a beads MCP server, a short prime\nonce per segment instead of once per turn, reads that span every repository of an\numbrella workspace, and writes routed to the owning repository by issue-id prefix.\nNext to the editor sits a widget of the work in progress; not one of its lines costs\nthe model a token.\n\n> [!TIP]\n> You need the `bd` binary on `PATH` and a `.beads/` directory in the project.\n> Without `.beads/` the extension stays quiet — `bd✗` in the status line, tools\n> answer with a refusal — so it is safe to install globally and forget about it\n> in projects that do not use beads.\n\n## Why\n\nThere are two usual ways to put an agent in front of beads, and both are paid for in\ncontext: either a full `bd prime` is poured into every turn, or a beads MCP server is\nstarted and its tool schemas occupy context for as long as the session lives. This\npackage does neither.\n\n| Approach | Context cost |\n|---|---|\n| Full `bd prime` every turn | ~1065 tokens × N turns |\n| beads MCP server | tool schemas resident for the whole session |\n| `@abix5/pi-beads` | `bd prime --mcp` ~141 tokens once per segment, plus ~16–208 token digests per read |\n\nThe beads MCP server is skipped deliberately: by the beads documentation it exists for\nclients that have no shell. pi has a shell, so calling `bd` directly and folding its\nJSON into a digest is the lighter path. Writes go through `bd` directly too — they are\ncheap either way.\n\nThe numbers above are the estimates recorded in the header of `src/index.ts` during\ndevelopment, not a measurement on your project; the order of magnitude is right.\n\n## What a session looks like\n\nAn umbrella workspace, three issues in progress and one just closed, at 80 columns:\n\n![The in-progress widget in an umbrella workspace](https://raw.githubusercontent.com/abix5/pi-beads/main/docs/assets/widget.png)\n\nEvery shot here is the real widget: the pictures are rendered by\n`scripts/widget-shots.mjs`, which imports `src/widget-lines.mjs` and calls\n`widgetLines(state, width - 1, theme)` with one leading space — exactly the way\n`src/index.ts` drives it — so nothing in this README is hand-drawn.\n\nBesides the widget there is a status-line segment: `bd✓` when beads is ready, `bd✗`\nwhen the project has no `.beads/`.\n\n## Widget legend\n\n![Every widget state and colour](https://raw.githubusercontent.com/abix5/pi-beads/main/docs/assets/widget-legend.png)\n\n1. `⦿ beads` — the header; it dims when nothing is in progress.\n2. The header counters: issues moved to `in_progress` in this session, issues closed in\n   this session, and how many are ready to work — open and unblocked. When the ready\n   number is unknown the segment disappears entirely: a `0` is never shown.\n3. `◐` is in progress, `✓` is closed. A closed row survives one agent turn and then\n   leaves; the header counter stays until the session ends.\n4. `P0`…`P4` — priority: `P0` red, `P1` yellow, the rest muted.\n5. `[crm-backend]` — the owning repository; in a single-repo project the column is gone.\n6. The right-hand column is how long the issue has been in progress, pinned to the\n   right edge.\n7. A closed issue's title is struck through.\n\nAt most six rows are drawn; the rest collapse into a `+N` tail, and closed rows are\nevicted first. In a narrow pane the titles are cut with an ellipsis and the repository\ncolumn disappears:\n\n![The widget in a narrow pane](https://raw.githubusercontent.com/abix5/pi-beads/main/docs/assets/widget-narrow.png)\n\n## Umbrella mode: many repositories, one list\n\nIf an umbrella workspace is nearby — a directory whose `bd` aggregates several\nrepositories — the extension finds it on its own. It can also be named explicitly with\n`PI_BEADS_ROOT`.\n\nReads (`beads_ready`, `beads_list`, `beads_show`, `beads_deps` and the prime) run\nagainst the aggregate, so the agent sees the issues of every repository at once, and an\nissue's owner is read off its id prefix: `crmback-1a2` belongs to `crm-backend`.\n\nWrites (`beads_create`, `beads_update`, `beads_close`, `beads_dep`, `beads_undep`,\n`beads_comment`) are routed to the owning repository by that same prefix; afterwards the\nrepository's JSONL is re-exported and the aggregate re-synced, so the next read is\nfresh. Writing straight into the aggregate is not allowed: what lives there are\nthrow-away copies.\n\nWith no umbrella around, the extension quietly works in ordinary single-repo mode. The\ncurrent mode and the routing table are always one `/beads-mode` away.\n\n## How it works\n\n**Prime.** Instead of a full `bd prime` on every turn, the extension injects a short\n`bd prime --mcp` block once per context segment, plus one line naming the id prefixes\nand the repositories they route to.\n\n**Reads.** Every read runs `bd` in-process and returns a digest — the fields an agent\nacts on — rather than raw JSON.\n\n**Writes.** Each write is dispatched to the owning repository by id prefix, then the\naggregate is re-hydrated so the next read cannot show a stale list.\n\n**Widget.** Widget state lives in session memory: it shows what this session moved into\nprogress and closed. Rendering happens in the UI process only, so it costs no tokens.\n\n## Install\n\n```bash\npi install npm:@abix5/pi-beads\n```\n\nThen restart pi or `/reload`. The bundled `beads` skill — how to read across\nrepositories, where to create, how to link — ships inside the package and registers\nitself; there is nothing to copy by hand.\n\n## Requirements\n\n- **pi** — the extension declares `@earendil-works/pi-coding-agent` in\n  `peerDependencies`, as the pi packages documentation prescribes.\n- **Node.js 22.6 or newer** — the code is ESM with `node:` prefixes and the extension is\n  loaded as `.ts` through built-in type stripping.\n- **The `bd` binary on `PATH`** — this is a wrapper, not an implementation of beads.\n  Verified against `bd version 1.0.5 (Homebrew)`.\n- **A `.beads/` directory in the project** — created by `/beads-init` or `bd init`.\n\n## Configuration\n\n| Variable | Default | Meaning |\n|---|---|---|\n| `PI_BEADS_ROOT` | auto-detected | Directory of the umbrella aggregate; understands `~`. Unset, the umbrella is searched for; not found, the extension runs in ordinary single-repo mode |\n\nThere is nothing else to configure: the rest is worked out at session start.\n\n## Commands & tools\n\nCommands are run by a person and their output never reaches the model's context.\n\n| Command | What it does |\n|---|---|\n| `/beads` | A compact board: what is in progress and what is ready, across all repositories |\n| `/beads-sync` | Re-hydrate the umbrella aggregate from every repository right now |\n| `/beads-init` | Quiet initialization of beads in the current project (see below) |\n| `/beads-mode` | Current mode, umbrella, default repository, prefix table, context economics |\n\nThe agent gets ten tools. All of them are direct in-process `bd` calls with no MCP\ntransport, and what comes back is a digest rather than raw JSON.\n\n| Tool | What it does |\n|---|---|\n| `beads_ready` | Issues ready to work (open and unblocked) across all repositories |\n| `beads_list` | A list filtered by status (`open,in_progress,blocked,deferred,closed`) |\n| `beads_show` | The essential fields of one issue: status, priority, type, description, dependency counts |\n| `beads_deps` | Blockers or dependents: a tree for one id, compact lines for several |\n| `beads_create` | Create an issue in the right repository (`repo` is a folder name or a prefix), return its id |\n| `beads_update` | Status, priority, title, notes, labels; routed by id prefix |\n| `beads_close` | Close one or more ids, with a reason |\n| `beads_dep` | Add a dependency (blocker blocks issue) within one repository |\n| `beads_undep` | Remove a dependency |\n| `beads_comment` | Add a progress comment to an issue |\n\n## Quiet init\n\n`/beads-init` runs `bd init --skip-agents --skip-hooks`. Those two flags mean `bd` will\nnot write `AGENTS.md`, `CLAUDE.md`, the `.claude/`, `.codex/` and `.agents/` directories,\nand will not point `core.hooksPath` at its own git hooks. Your instructions to agents stay\nas you wrote them.\n\n> [!NOTE]\n> What the flags do not cancel: outside a repository `bd init` still runs `git init`, it\n> still appends its lines to the root `.gitignore`, and it commits the files it created.\n> That is `bd`'s own behaviour and the extension has no say in it.\n\n## Limitations\n\nThe widget exists only in pi's interactive interface. Subagents and workflow runs have no\nUI context, so nothing is drawn there — the `beads_*` tools work as usual.\n\nWidget state is session memory. Changes made in another window, or straight through `bd`,\nappear only after the next read. A closed row survives one agent turn; the closed counter\nsurvives until the session ends. At most six rows are drawn, the rest collapse into a\n`+N` tail.\n\nbeads dependencies live inside a single repository, so `beads_dep` across repositories is\nimpossible — that is how the storage works. For the same reason writing directly into the\numbrella aggregate is not allowed: routing by id prefix is the only path.\n\nFinally, `bd`'s output format is not a stable contract. Verified against 1.0.5; on other\nversions the parsing may drift away from reality.\n\n## Not to be confused with\n\nnpm carries an older `pi-beads` package by a different author, depending on the retired\n`@mariozechner/*` namespace. That is not this project.\n\n## Development\n\n```bash\nmake test     # node --test src/widget-lines.test.mjs\nmake shots    # re-render the README screenshots from the shipped code (needs vhs + imagemagick)\n```\n\nSource lives in `src/` and there is no build step: after editing, `/reload` in pi.\nLicensed [MIT](https://github.com/abix5/pi-beads/blob/main/LICENSE).\n","readmeFilename":"README.md"}