Beads

Beads for Obsidian

A tiny, desktop-only Obsidian plugin that renders a live, clickable pane for the Beads (bd) issue tracker — and does real integration: click any issue to edit it in a tab, as YAML frontmatter + a markdown body, and save straight back to bd.

No Obsidian + Beads plugin existed before this one — it fills a genuine gap for anyone who tracks work in bd and lives in Obsidian.

Features

• 🗂️ Ready-first, tabbed pane — a native ItemView with Ready · In progress · Blocked · Closed tabs (each with a live count), so you open straight to what you can do right now. Only the active tab hits bd, and each paginates with Load more, so the pane opens fast even with thousands of closed issues. Blocked rows show a ⛓ n hint.
• ✏️ Edit in a tab — click a row and the bead opens like a note (not a popup): a YAML frontmatter block for the fields (title, type, priority, status — set it to closed to close, or back to open to reopen) and a markdown body for the description. Save (or ⌘/Ctrl-S) writes only the changed fields via bd update; broken frontmatter is reported, never silently dropped. Blocked by / Blocks dependencies and the comment thread (rendered markdown) show below.
• ⚡ Quick capture — Beads: Capture a bead (or the + in the pane) opens a box: type a title and press Enter for the fast path, or set type / priority / description first (bd create).
• 📄 Live beads code blocks — embed a query in any note (Dataview-style) and get the same clickable rows inline. See Embedding queries.
• 🔢 Status-bar count — an ambient ● N ready even when the pane is closed.
• 🔄 Auto-refresh — on a configurable interval and whenever the .beads directory changes on disk (so external bd edits show up).
• ⚙️ Near-zero setup — if your vault folder itself contains a .beads/, the project root auto-fills on first load.

Requirements

• Obsidian desktop — the plugin shells out to a local binary via Node's child_process, which is unavailable on mobile. isDesktopOnly is set.
• The bd CLI — install Beads and make sure bd is on your PATH (or set an explicit path in settings).

Installation

Community plugins (once accepted)

Settings → Community plugins → Browse → search "Beads" → Install → Enable.

Manual

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Copy them into <your-vault>/.obsidian/plugins/beads-pane/.
3. Reload Obsidian and enable Beads under Community plugins.

Usage

1. Open Settings → Beads and set Project root to a directory that contains a .beads/ database (auto-filled if your vault folder has one). Click Test connection to confirm bd is reachable.
2. Open the pane: click the list-checks ribbon icon, or run "Beads: Open Beads pane" from the command palette. Switch tabs (Ready / In progress / Blocked / Closed) and use Load more to page through long lists.
3. Click a row to open the bead in an editor tab. Edit the YAML frontmatter (title, type, priority, status — set it to closed to close, or back to open to reopen) and the markdown body (the description), then Save (or ⌘/Ctrl-S). Dependencies and the comment thread show below.
4. Capture new work anytime with "Beads: Capture a bead" (bind it to a hotkey) or the + in the pane header.

Embedding queries in notes

Put a fenced beads code block in any note to render a live, clickable list right where you're thinking. One directive per line:

```beads
ready
```

```beads
query: status=open AND priority<=1
limit: 10
```

Accepted directives:

Embeds re-run when the note renders (and after you close an issue from one) — never on a timer — and share a global read cache, so many blocks won't hammer bd.

Settings

Troubleshooting

• "bd binary not found" / the pane is empty and Test connection fails. GUI-launched apps often don't inherit your shell PATH, so the default bd can't be resolved. Run which bd in a terminal and paste the full path into Settings → Beads → bd binary path.
• "No bd database here." The project root must be a directory that contains a .beads/ folder. Point it at your bd project (not necessarily your vault).
• bd won't close a blocked issue. It won't close an issue that still has open blockers; the error is shown as a notice. Close its blockers first (the editor tab lists them under Blocked by — click one to jump to it).
• The pane didn't update after a CLI change. It refreshes on an interval and when .beads/ changes on disk; hit the refresh icon to force it.

Security

• The plugin runs the bd binary you configure, in the project root you configure — the same trust model as the Shell commands plugin. Point it only at a bd you trust.
• Commands are invoked with execFile and an argument array — never a shell string — so issue IDs and other values can't inject shell metacharacters.
• Issue titles and descriptions render as plain text (never HTML) in the pane, so a bead authored elsewhere and synced in can't inject markup. Comment threads in the editor render through Obsidian's own MarkdownRenderer — the same sanitized path as any note. Data-controlled values are also passed after a -- sentinel (or as --flag=value) so they can't be reparsed as bd flags.
• The plugin runs bd against whatever .beads/ your project root points at (including an auto-detected vault-local one). It never executes anything from the dataset — but that means you trust bd's own parsing of that database, as with any bd invocation.

Development

npm install
npm run dev     # esbuild watch → main.js
npm run build   # typecheck + production bundle

To test against a real vault, symlink or copy main.js, manifest.json, and styles.css into <vault>/.obsidian/plugins/beads-pane/.

Prior art (inspiration)

• Taitava/obsidian-shellcommands — the canonical desktop-only child_process pattern.
• Beads — bd --help, bd list --json, bd show --json, bd close.
• High-star pane/view plugins (Kanban, Tasks, Dataview) for ItemView and workspace-leaf conventions.

License

MIT © Rome-1