{"id":"beads-viewer","repo":"cuongntr/paseo-beads-viewer","url":"https://github.com/cuongntr/paseo-beads-viewer","package":"beads-viewer","npm":{"package":"beads-viewer","version":"0.2.0","integrity":"sha512-PVENPID+gmT+gqV1dr7rlfTKgCAbvm0jPfPQ5CsQTCGIzAACBA5jYgrcwgU3y1oGLAdL6M5eqGeogW0FN4AI8A==","publishedAt":"2026-09-24T09:03:35.315Z","downloadsLast30Days":0},"name":"beads-viewer","description":"Read-only Beads console for Paseo: project progress, ready and waiting work, the critical chain, and a whole-project board, read through bv.","categories":["monitoring","productivity","orchestration"],"platforms":["macos","linux"],"caveats":["Requires the bv (beads_viewer) CLI on the Paseo daemon's PATH; verified against bv v0.25.0.","Read-only by design: it never claims, closes or edits issues; do that with br or bd.","Issue detail, types and assignees need the project's br or bd CLI on the daemon's PATH.","Custom statuses from .beads/policy.yaml are shown as written, never mapped to ready or done.","Projects over 2000 issues load all open work but only some closed issues, and the panel says so.","Composer attachment search covers at most 4 recently active Beads workspaces."],"images":["https://raw.githubusercontent.com/cuongntr/paseo-beads-viewer/47227c7b5bb7fd98fee1652a1c9038214c14df94/images/board.png","https://raw.githubusercontent.com/cuongntr/paseo-beads-viewer/47227c7b5bb7fd98fee1652a1c9038214c14df94/images/overview.png","https://raw.githubusercontent.com/cuongntr/paseo-beads-viewer/47227c7b5bb7fd98fee1652a1c9038214c14df94/images/plan.png","https://raw.githubusercontent.com/cuongntr/paseo-beads-viewer/47227c7b5bb7fd98fee1652a1c9038214c14df94/images/risks.png"],"themes":[],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":true,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-09-24T20:13:32.187Z","addedAt":"2026-09-24T22:59:22+03:00","npmSecurity":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-24T20:02:03.262Z","version":"0.2.0","integrity":"sha512-PVENPID+gmT+gqV1dr7rlfTKgCAbvm0jPfPQ5CsQTCGIzAACBA5jYgrcwgU3y1oGLAdL6M5eqGeogW0FN4AI8A=="},"version":"0.2.0","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-24T20:02:03.262Z","commit":"47227c7b5bb7fd98fee1652a1c9038214c14df94"},"author":"cuongntr","license":"MIT","paseoVersionRequirement":">=0.8.0","descriptionNodes":[{"type":"text","text":"Read-only Beads console for Paseo: project progress, ready and waiting work, the critical chain, and a whole-project board, read through bv."}],"caveatNodes":[[{"type":"text","text":"Requires the bv (beads_viewer) CLI on the Paseo daemon's PATH; verified against bv v0.25.0."}],[{"type":"text","text":"Read-only by design: it never claims, closes or edits issues; do that with br or bd."}],[{"type":"text","text":"Issue detail, types and assignees need the project's br or bd CLI on the daemon's PATH."}],[{"type":"text","text":"Custom statuses from .beads/policy.yaml are shown as written, never mapped to ready or done."}],[{"type":"text","text":"Projects over 2000 issues load all open work but only some closed issues, and the panel says so."}],[{"type":"text","text":"Composer attachment search covers at most 4 recently active Beads workspaces."}]],"manifest":{"id":"beads-viewer","requirements":{"paseo":">=0.8.0"}},"repoMeta":{"stars":0,"defaultBranch":"main","pushedAt":"2026-09-24T09:02:18Z"},"owner":{"login":"cuongntr","avatarUrl":"https://avatars.githubusercontent.com/u/6338052?v=4"},"installNotesHtml":"
paseo plugin add cuongntr/paseo-beads-viewer\npaseo plugin ls beads-viewer    # expect beads-viewer running\n
\n

Update to the latest release with paseo plugin update beads-viewer. If the panel does not\nappear, paseo plugin logs beads-viewer shows why; the most common cause is bv missing from\nthe daemon's PATH.

\n

Releases before 0.2.0 used the plugin id paseo-beads and the npm package paseo-beads. That id\nbelongs to another plugin on paseo.cafe, so this one is now beads-viewer. If you installed an\nearlier release, remove it first with paseo plugin remove paseo-beads.

\n

To run a local checkout instead:

\n
npm install && npm run typecheck && npm test\npaseo plugin install /absolute/path/to/paseo-beads-viewer\n
\n

After editing source, run paseo plugin reload beads-viewer.

","limitationsNotesHtml":"","readmeText":"# beads-viewer\n\nA read-only Beads console for Paseo workspaces. For the workspace you are in it shows how far\nalong the project is per parent issue, what is in progress, what can start now, how the project's\nown labels spread over open work, and the critical chain of dependencies; a whole-project board\nby work state;\nexecution tracks; risks; issue search; Markdown-rendered issue detail; and a composer attachment\nsource for Beads issues.\n\nThe plugin never invokes a mutating `br` or `bd` command. There is no claim, close,\nupdate, or create path in the code. `bv` may refresh its own compatibility export while\nloading a `bd`/Dolt workspace, so `bv` calls are serialized per workspace.\n\n## Screenshots\n\nShown on a made-up demo project.\n\n**Overview**: progress per parent, what is in progress, held and ready now, the project's labels\nover open work, and the critical chain.\n\n![Overview](images/overview.png)\n\n**Board**: one column per work state in the order work moves, filtered by parent or label, each\ncolumn with its definition.\n\n![Board](images/board.png)\n\n**Plan**: `bv`'s parallel execution tracks, containers left out.\n\n![Plan](images/plan.png)\n\n**Risks**: stuck and parked work, alerts by severity, and the keystones that unblock the most.\n\n![Risks](images/risks.png)\n\n## Requirements\n\n- Paseo `>=0.8.0` (daemon and app).\n- The [`bv`](https://github.com/Dicklesworthstone/beads_viewer) analysis CLI on the daemon machine's `PATH`.\n Verified against `bv v0.25.0`.\n- A project that uses Beads through `br` or `bd`. The tracker CLI matching the project must\n also be on the daemon `PATH` for issue detail and for issue types and assignees; everything\n else works without it.\n\nEverything else degrades gracefully: a missing `bv`, a workspace without a `.beads` source,\nand an empty-but-healthy project are three distinct, clearly labelled states.\n\n## Install\n\n```bash\npaseo plugin add cuongntr/paseo-beads-viewer\npaseo plugin ls beads-viewer # expect beads-viewer running\n```\n\nUpdate to the latest release with `paseo plugin update beads-viewer`. If the panel does not\nappear, `paseo plugin logs beads-viewer` shows why; the most common cause is `bv` missing from\nthe daemon's `PATH`.\n\nReleases before 0.2.0 used the plugin id `paseo-beads` and the npm package `paseo-beads`. That id\nbelongs to another plugin on paseo.cafe, so this one is now `beads-viewer`. If you installed an\nearlier release, remove it first with `paseo plugin remove paseo-beads`.\n\nTo run a local checkout instead:\n\n```bash\nnpm install && npm run typecheck && npm test\npaseo plugin install /absolute/path/to/paseo-beads-viewer\n```\n\nAfter editing source, run `paseo plugin reload beads-viewer`.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm test\n```\n\nMobile audit — a hit here is a bug:\n\n```bash\nrg -n \"document\\.|window\\.|localStorage|navigator\\.|<[a-z]+[ >]|className=|onClick=\" client/\n```\n\n## What it contributes\n\n| Contribution | Where |\n| --- | --- |\n| Workspace panel `beads` (\"Beads Viewer\") | Workspace tab bar and the Explorer |\n| Command Center: **Open Beads Viewer** | Workspace context |\n| Command Center: **Refresh Beads Viewer** | Workspace context; re-reads `bv` then opens the panel |\n| Slash command `/beads` | Opens the panel for the current workspace |\n| Slash command `/bead ` | Opens the panel with that issue selected |\n| Attachment source **Beads issue** | Composer attachment picker |\n\n## Security and read-only behaviour\n\n- Only the daemon-side `server/` code touches Node, the process table, or the filesystem.\n Client code imports no Node module.\n- Subprocesses are spawned with `spawn` using a **literal argv** and an absolute executable\n path resolved by scanning `PATH` directly. `shell` is never enabled, so no input can be\n interpreted as a shell operator.\n- The working directory always comes from Paseo's own workspace record\n (`paseo.workspaces.ref(id).refresh()`), never from client input, and must be an existing\n absolute directory.\n- Only an explicit allowlist of read-only commands can run: `bv --version`,\n `bv --robot-triage`, `bv --robot-plan`, `bv --robot-alerts`, `bv --robot-graph`,\n `bv --robot-search`,\n ` --db list --status all --fields id,issue_type,assignee --format csv`,\n and ` --db show --json -- `. `br` reads also pass\n `--no-auto-import --no-auto-flush`. Bare `bv` is never invoked. Neither tracker argv takes any\n user input beyond the validated route and, for `show`, a pattern-checked issue id.\n- The search query is whitespace-collapsed, control-character-stripped, length-bounded, and\n passed as a single argv value. Issue ids are pattern-checked and passed after `--` so an id\n can never be read as a flag.\n- `bv` calls clear inherited `BEADS_DIR`, `BEADS_DB`, `BEADS_JSONL`, and `BD_DB` values so\n daemon-level environment configuration cannot redirect a workspace read. Tracker detail calls set those\n variables only to the validated route.\n- Every subprocess has a timeout and an output size cap, and is killed when either is\n exceeded. Unavailable binary, timeout, non-zero exit, oversized output, and malformed JSON\n are reported as distinct error codes. Plugin cleanup kills any process still running.\n- Plugin code never parses or writes `.beads/*.jsonl` or a Beads SQLite/Dolt database. It reads\n only `.beads/metadata.json` to bind tracker identity to `bv`'s selected source; issue data comes\n from CLI output. `bv` itself may refresh a `bd` compatibility export, so its calls are serialized.\n- `bv --robot-*` is the authority for ranking, recommendations, execution tracks, alerts, cycle\n detection, and velocity. The plugin derives only each issue's work state (from its status and\n its still-open blockers) and the longest remaining dependency chain, because `bv`'s own counts\n treat dependency-blocked work as unblocked and containers as ready; see the design doc. `bv` and its `source_authority`, freshness, and `data_hash` are shown as\n reported.\n- Only short-lived normalized command results are cached (15 s for the dashboard, 2 min for\n tracker identity and its validated route), invalidated purely by expiry. No derived graph is\n ever cached.\n\n## Limitations\n\n- Read-only by design. Claiming, closing, and editing issues stay in `br`/`bd`.\n- Issue detail requires an exact tracker and database route. The plugin checks `bv`, then the\n selected source's `.beads/metadata.json`; if identity or routing remains inconclusive, detail\n reads are disabled rather than guessed.\n- Attachment search has no workspace context, so it scans a bounded set of recently active\n Paseo workspaces, searches at most 4 Beads-enabled ones, and returns at most 8 items. An\n issue in a workspace outside that window will not appear.\n- Search relevance, ranking, and analysis semantics are entirely `bv`'s; the plugin only\n reshapes them.\n- Statuses, readiness values, and alert severities are treated as opaque strings, so a newer\n `bv` renders without a plugin update but without bespoke styling for new values.\n- The panel serves any Beads project, so it interprets only what Beads and `bv` define and what\n the data's structure says. Statuses are Beads' built-in set (`open`, `in_progress`, `hooked`,\n `blocked`, `deferred`, `draft`, `pinned`, `closed`, `tombstone`); a custom status declared in a\n project's `.beads/policy.yaml` is shown verbatim under **Other status**, not guessed to be ready\n or done. Groups follow parent links, never type names or id patterns. Labels are the project's\n own vocabulary: they are shown and counted as written, a label carried by every open item is\n set aside as uninformative, and no label is given a meaning — so there is no built-in \"needs a\n human\". To keep agents off some work, use `bv`'s own `BV_ROBOT_NOT_READY_LABELS`, which the\n panel's `bv` reads inherit.\n- Work states, in Beads' own terms (Ready and Waiting match `br ready` and `br blocked`):\n **Ready** — status `open`, and nothing it depends on is still open. **Waiting** — status\n `open`, but a dependency, or one of its parent's, is still open; a parent's dependency on its\n own children does not count. **In progress** — `in_progress` or `hooked`. **Held** — status\n set by hand to `blocked`, `deferred`, `draft` or `pinned`. **Other status** — a custom status.\n **Done** — `closed`. Each Board column shows its definition under its title.\n- The **Board** is a plain board: one column per work state in the order work moves — Ready,\n Waiting, In progress, Held and Other status (each only when non-empty), and Done (only with\n **Show done**) — each column\n one list that scrolls on its own, with no swimlanes. A **Filter** narrows every column at once\n to one parent's subtree or one of the project's labels; each card names its parent. On a phone\n the columns become a state picker over one list. Issues that other issues name as parent are\n filter options and card context, never cards. Each column renders at most 60 cards with the\n rest reported as `+N more`, and a project past 2000 issues drops closed issues from the payload\n first and says so. If the graph read fails, the panel falls back to the triage and plan\n working set and says so. It is read-only: no drag, no drop, no status change.\n- Issue prose renders through a bounded in-repo Markdown subset (headings h1–h3, lists, task\n items, quotes, rules, code, bold, italic, links). HTML, images, and tables are not rendered,\n and link targets are shown as text — the panel never opens a URL.\n"}