{"id":"beads-board","repo":"jmkelly/paseo-beads-board","url":"https://github.com/jmkelly/paseo-beads-board","package":"paseo-beads-board","npm":{"package":"paseo-beads-board","version":"0.1.1","integrity":"sha512-gcJa6jjn7Zm+hnOIhllhdN+zzQLzCUvQE48PZRx0uR3z2/niE+bigtpmnmtTpj2xEsrTdxfzRSOKvWceGcemJA==","publishedAt":"2026-09-28T12:31:47.474Z","downloadsLast30Days":0},"name":"beads-board","description":"Kanban board for the beads (bd) issue tracker inside Paseo, with a workspace panel, sidebar surface, and composer attachment source.","categories":["productivity"],"platforms":[],"caveats":["Requires the beads `bd` CLI on the daemon host; set PASEO_BEADS_BD_BIN if it is not on PATH.","Server code runs `bd` as the daemon user and can modify any beads database that user can reach.","Pre-1.0 release: versions are 0.x, so a minor bump may contain breaking changes.","No drag and drop: move beads with the status buttons in the bead detail sheet.","Board only; beads-web's GitOps, PR, memory, and worktree panels are not included.","Boards load at most 5000 beads per project, and long bead text is fetched on demand."],"images":["https://raw.githubusercontent.com/jmkelly/paseo-beads-board/2a501e7caa780ae85ed02aa49d8d3a01add0e6d8/images/bead-detail.png","https://raw.githubusercontent.com/jmkelly/paseo-beads-board/2a501e7caa780ae85ed02aa49d8d3a01add0e6d8/images/board-closed-column.png","https://raw.githubusercontent.com/jmkelly/paseo-beads-board/2a501e7caa780ae85ed02aa49d8d3a01add0e6d8/images/board.png","https://raw.githubusercontent.com/jmkelly/paseo-beads-board/2a501e7caa780ae85ed02aa49d8d3a01add0e6d8/images/create-bead.png"],"themes":[],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":true,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-09-28T13:25:38.677Z","addedAt":"2026-09-28T16:20:36+03:00","npmSecurity":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-28T13:25:21.577Z","version":"0.1.1","integrity":"sha512-gcJa6jjn7Zm+hnOIhllhdN+zzQLzCUvQE48PZRx0uR3z2/niE+bigtpmnmtTpj2xEsrTdxfzRSOKvWceGcemJA=="},"version":"0.1.1","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-28T13:25:21.577Z","commit":"2a501e7caa780ae85ed02aa49d8d3a01add0e6d8"},"author":"James Kelly","license":"MIT","paseoVersionRequirement":">=0.8.0","descriptionNodes":[{"type":"text","text":"Kanban board for the beads (bd) issue tracker inside Paseo, with a workspace panel, sidebar surface, and composer attachment source."}],"caveatNodes":[[{"type":"text","text":"Requires the beads "},{"type":"text","text":"bd","code":true},{"type":"text","text":" CLI on the daemon host; set PASEO_BEADS_BD_BIN if it is not on PATH."}],[{"type":"text","text":"Server code runs "},{"type":"text","text":"bd","code":true},{"type":"text","text":" as the daemon user and can modify any beads database that user can reach."}],[{"type":"text","text":"Pre-1.0 release: versions are 0.x, so a minor bump may contain breaking changes."}],[{"type":"text","text":"No drag and drop: move beads with the status buttons in the bead detail sheet."}],[{"type":"text","text":"Board only; beads-web's GitOps, PR, memory, and worktree panels are not included."}],[{"type":"text","text":"Boards load at most 5000 beads per project, and long bead text is fetched on demand."}]],"manifest":{"id":"beads-board","requirements":{"paseo":">=0.8.0"}},"repoMeta":{"stars":0,"defaultBranch":"main","pushedAt":"2026-09-28T12:32:54Z"},"owner":{"login":"jmkelly","avatarUrl":"https://avatars.githubusercontent.com/u/124026?v=4"},"installNotesHtml":"

Paseo 0.9 and newer install from npm:

\n
paseo plugin install npm:paseo-beads-board\n
\n

Pin a specific release when you do not want to track the latest one:

\n
paseo plugin install npm:paseo-beads-board@0.1.0\n
\n

Paseo 0.8 installs from the repository:

\n
paseo plugin add jmkelly/paseo-beads-board\n
\n

The daemon must have plugins enabled. Check with paseo daemon status --json; the file is\n<home>/config.json and needs a root \"pluginsEnabled\": true, followed by paseo reload.

\n

From a clone of this repository:

\n
npm install\nnpm run typecheck\nnpm test\npaseo plugin install /absolute/path/to/paseo-beads-board\npaseo plugin ls\npaseo plugin logs beads-board\n
\n

Source changes need paseo plugin reload beads-board. After installing, open Beads board in\nthe sidebar, pick a project, and the board appears.

","limitationsNotesHtml":"","readmeText":"# Beads board for Paseo\n\nA Paseo plugin that turns the [beads](https://github.com/steveyegian/beads) `bd` CLI into a\nkanban board inside Paseo, inspired by [beads-web](https://github.com/weselow/beads-web).\n\n> **Pre-1.0.** Releases are `0.x`, following semver's pre-1.0 convention: features and fixes bump\n> the patch version, but a minor bump may still contain breaking changes until the plugin API and\n> the board settle at `1.0.0`. Pin an exact version if you do not want to track the latest release.\n\nThe board is rendered by the Paseo app (React Native, so desktop, browser, iOS, and Android all\nwork) and every data operation runs the `bd` CLI in a subprocess on the daemon host. Install the\nplugin on each host you want a board for; Paseo shows one sidebar item with a host picker and the\nselected host serves its own projects.\n\n## Screenshots\n\n![The beads board inside Paseo, with Open, In Progress, and In Review columns](./images/board.png)\n\n
\nMore screenshots\n\n![The same board with the Closed column enabled](./images/board-closed-column.png)\n\n![Bead detail: move between columns, edit fields, and read comments](./images/bead-detail.png)\n\n![Creating a bead against any discovered beads database](./images/create-bead.png)\n\n
\n\n## Features\n\n- **Project discovery** — scans Paseo projects and workspaces on the host for an initialized beads\n database, plus any extra paths you add in settings. Worktrees that share a database are collapsed\n onto it, so each project is listed once.\n- **Kanban board** — Open / In Progress / In Review / Closed, with the same status mapping as\n beads-web (`blocked`, `deferred`, `pinned` show as badges on Open; `hooked` shows on In\n Progress; `tombstone` is hidden).\n- **Epics** — child beads are grouped under their parent with a progress bar, like beads-web.\n- **Blocked detection** — a bead is blocked when an unresolved dependency is still open, or its\n status is `blocked`.\n- **Mutations** — create beads (with a project dropdown covering every discovered beads database),\n move them between columns, edit title/description/notes/priority/assignee, close and reopen, and\n add comments. Each mutation shells out to `bd`.\n- **Bead detail** — full text (`bd show`), relations, and comments (`bd comments`).\n- **Workspace panel** — the same board as a workspace tab, preselected to the workspace's project.\n- **Composer attachment source** — attach a bead to a prompt from any composer.\n- **Host settings** — extra project paths, refresh interval, closed-column default.\n\n## Requirements\n\n- Paseo 0.8.0 or newer, on the daemon host and the connected app.\n- The [beads](https://github.com/steveyegian/beads) `bd` CLI on the **daemon host's `PATH`**, so the\n plugin can shell out to it. Set `PASEO_BEADS_BD_BIN` in the daemon environment if the binary\n lives somewhere unusual.\n\nPlugins are trusted, unsandboxed code. This plugin's server code runs `bd` in the daemon user's\naccount, so it can read and change the beads databases that user can reach. Review the source\nbefore installing it on a machine you care about.\n\n## Install\n\nPaseo 0.9 and newer install from npm:\n\n```bash\npaseo plugin install npm:paseo-beads-board\n```\n\nPin a specific release when you do not want to track the latest one:\n\n```bash\npaseo plugin install npm:paseo-beads-board@0.1.0\n```\n\nPaseo 0.8 installs from the repository:\n\n```bash\npaseo plugin add jmkelly/paseo-beads-board\n```\n\nThe daemon must have plugins enabled. Check with `paseo daemon status --json`; the file is\n`/config.json` and needs a root `\"pluginsEnabled\": true`, followed by `paseo reload`.\n\nFrom a clone of this repository:\n\n```bash\nnpm install\nnpm run typecheck\nnpm test\npaseo plugin install /absolute/path/to/paseo-beads-board\npaseo plugin ls\npaseo plugin logs beads-board\n```\n\nSource changes need `paseo plugin reload beads-board`. After installing, open **Beads board** in\nthe sidebar, pick a project, and the board appears.\n\n## Using the board\n\n- **Move a bead** — open it and use the status buttons in the detail sheet. There is no drag and\n drop (see [Limitations](#limitations)).\n- **Create a bead** — the *New bead* button on the board; the project dropdown lists every\n discovered beads database.\n- **Add a bead to a prompt** — type in the composer and pick the **Beads** attachment source, then\n search by id or title.\n- **Per-host preferences** — **Settings → Beads board** controls extra project paths, the refresh\n interval, and whether the Closed column is shown. Preferences are host-scoped and shared by every\n client connected to that daemon.\n\n## Layout\n\n```text\npaseo-plugin.json plugin id, description, supported Paseo versions\nindex.client.tsx surface, sidebar item, workspace panel, settings screen, commands, attachment source\nindex.server.ts RPC handlers + host settings registration\nshared/beads.ts Zod contracts, RPC definitions, status -> column mapping\nshared/settings.ts host-scoped preferences document\nshared/attachments.ts composer attachment source\nserver/bd.ts `bd` process execution helpers\nserver/beads.ts raw bd JSON -> board normalization (parents, blockers, epic progress)\nserver/handlers.ts project discovery and every RPC handler\nclient/hooks.ts TanStack Query hooks and mutations\nclient/board/ board screen, columns, cards, detail/create/picker modals\ntests/ unit tests for the status mapping and board normalization\n```\n\n## RPCs\n\n| RPC | Runs |\n| ---------------- | --------------------------------------- |\n| `beads.projects` | `bd status --json`, `bd count --json --status inreview`, `bd where --json` |\n| `beads.board` | `bd list`, `bd statuses --json`, `bd where --json` |\n| `beads.show` | `bd show --json`, `bd comments --json` |\n| `beads.create` | `bd create --json` |\n| `beads.update` | `bd update` / `bd close` / `bd reopen` |\n| `beads.comment` | `bd comment` |\n| `beads.search` | `bd list --json --brief --all` |\n\nDiscovery uses the daemon's Paseo API (`projects.list()`, `workspaces.list()`) to find candidate\ndirectories, and a directory appears on the board when `.beads` holds an initialized database\n(`config.yaml`, `metadata.json`, or `issues.db`) — directly, or within four parent levels. Each\ndatabase is listed once however many Paseo worktrees point at it, and the counts come from `bd`'s\nown `status` summary rather than a full issue list.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm test\npaseo plugin install /absolute/path/to/paseo-beads-board\npaseo plugin reload beads-board\n```\n\nKeep the plugin ID (`beads-board`) and the npm version in `package.json` in step: Paseo 0.9\ninstalls the npm package, and the paseo.cafe catalog uses the published version as the plugin's\nupdate identity, so every release needs a version bump and an `npm publish`. While the plugin is\npre-1.0, bump with `npm version patch` for fixes and `npm version minor` for anything that may\nchange existing behaviour.\n\n## Limitations\n\n- This plugin is pre-1.0 (`0.x`). A minor version bump may contain breaking changes, so pin a\n version if you are depending on today's behaviour.\n- The `bd` CLI must be installed on each daemon host you install this plugin on; a missing binary\n surfaces as an error on the board and in `paseo plugin logs beads-board`.\n- No drag and drop. React Native plugin code has no gesture-handler dependency, so cards move\n through the status buttons in the detail sheet.\n- No GitOps, PR, memory, or worktree panels: this plugin covers the beads board itself, unlike\n beads-web.\n- Beads are always read with `bd list --brief`; long text is fetched on demand with `bd show`, so\n very large boards briefly load in two passes.\n- Board data is capped at 5000 beads per load; larger databases show a truncated board.\n- Status names come from each database (`bd statuses --json`), so a database that has renamed\n `in_progress` will move beads to whatever status currently maps to that column.\n\n## Contributing\n\nIssues and pull requests are welcome at\n. Please run `npm run typecheck` and\n`npm test` before opening a pull request.\n\n## License\n\n[MIT](./LICENSE)\n"}