Lista Beads

Browse, manage, and act on Beads issues without leaving VS Code. Beads is a distributed, git-backed graph issue tracker built for AI agents and developer workflows — it lives in your repo alongside your code, with no external service required.

Table of Contents

• Requirements
• Getting Started
• Features
  • Beads Tree View
  • View Modes
  • Issue Detail Panel
  • Dashboard
  • Dependency Management
  • Dolt Sync
  • Dependency Graph
  • Pinned Beads
  • CodeLens
  • Wisps
  • Formulas
  • Export & Search
  • Stale Issue Management
  • Azure DevOps Integration
  • Tracker Sync (Multi-Tracker Integration)
• Settings
• Commands
• Troubleshooting
• Publishing

Requirements

• VS Code 1.87 or later

• Beads CLI (bd) installed and on your PATH

  brew install beads
  # or: npm install -g @beads/bd
  

Getting Started

1. Install Lista Beads from the VS Code Marketplace.
2. Open any workspace that contains a Beads repository (one with a .beads/ directory).
3. Click the Beads icon in the Activity Bar — your issues appear instantly.

New to Beads? Initialize a database in your project:

bd init
bd create "My first task" --type task

Features

Beads Tree View

Browse all your beads in a rich, filterable tree. Issues are grouped by type and decorated with priority badges, status icons, and assignee information at a glance.

• Filter by type, status, assignee, or free-text search via Beads: Filters. Filters persist for the session and can be stacked.
• Save & load filter presets for quick switching between filter configurations.
• Inline actions — start, close, defer, reopen, or assign a bead directly from the tree without opening a detail panel.
• Search — click the search icon in the toolbar or use Beads: Search Beads to find beads by keyword.
• Create a new bead from any selected editor text via Beads: Create Bead from Selection.
• Delete beads via the context menu; multi-select is supported with cascade or orphan options for dependents.
• Quick Open (Beads: Quick Open) — fuzzy-search picker for fast navigation.
• Pagination — large lists are paginated (configurable via listaBeads.pageSize); click Load More to expand.
• Auto-refresh on disk changes or on a configurable polling interval (listaBeads.autoRefreshInterval).

Tip: Set listaBeads.filterTypes to [] to show all issue types, or narrow it down to just ["task"] to focus your work.

View Modes

The toolbar provides two independent toggles that change how beads are displayed:

• Hierarchy view ($(type-hierarchy) icon) — switches from the default "By status" grouping (Status → Type → Issues) to a parent/child hierarchy (Epics → Features → Tasks). Any issue with children becomes collapsible; standalone issues appear at the root. Closed and deferred beads are automatically hidden so the tree focuses on active work — active children of completed parents are promoted to root level. Toggle again to return to status view.
• Ready view ($(pass) icon) — filters to only show unblocked issues (no active blockers) using bd ready semantics. Combines with hierarchy view — you can see ready issues in tree form. The icon fills in when active.

Both toggles persist across window reloads (stored per-workspace).

Issue Detail Panel

Click any bead to open a rich detail panel with full description, metadata, status, priority, assignee, labels, timeline, and linked dependencies — all rendered in a clean webview that adapts to panel size. URLs in descriptions and comments are clickable, and bead ID references (e.g. lista-beads-xxxx) auto-link for quick cross-bead navigation.

Dashboard

The Dashboard panel provides a unified overview of your Beads workspace:

• Dolt Sync bar — remote sync status with interactive Push / Pull buttons (see Dolt Sync)
• Key metrics — total issues, ready count, 7-day velocity
• Closed in the Last 14 Days — sparkline bar chart
• Recent Activity — latest events across the workspace
• Status & Type breakdowns — distribution at a glance
• Team — active swarm agents and top assignees
• Convoys — active convoy progress bars; click any convoy to open it in the detail view and see its child beads
• Worktrees — git worktree listing linked to beads via task/ branch naming
• Formulas — available workflow formulas

Refresh with Beads: Refresh Dashboard.

Dependency Management

Manage bead dependencies directly from the tree view context menu:

• Add Dependency… — right-click any issue → select a blocker from a searchable list of all beads
• Remove Dependency… — right-click any issue → pick an existing dependency to remove

Dependencies are stored via bd dep add/remove and visible in the Dependency Graph and the detail panel.

Dolt Sync

When your .beads/ database has a Dolt remote configured, Lista Beads shows sync status and provides push/pull controls:

• Dashboard sync bar — shows in-sync status or pending change counts with ↑ Push and ↓ Pull buttons. Includes a server indicator (⛁ host:port/db) so you can verify which remote you're connected to
• Push to Remote / Pull from Remote — commands available from the dashboard or the command palette
• Auto-check on open — optionally check for pending remote changes when the workspace opens (listaBeads.doltAutoSyncCheck)

Dependency Graph

Visualize how your beads relate to each other with an interactive graph.

Use Beads: Show Dependency Graph (or the graph icon in the Beads view title bar) to open the dependency graph panel. Nodes are color-coded by status; click any node to open the detail panel for that bead.

Pinned Beads

Pin frequently-accessed beads to keep them at the top of the tree view. Pinned beads are shown in a dedicated section above the type groups.

• Pin — via the inline icon on any bead, or Beads: Pin Current Bead from the command palette
• Unpin — via the inline icon on a pinned bead

CodeLens

Lista Beads surfaces bead references directly in your code via CodeLens:

• Status icons alongside bead IDs referenced in comments or commit messages (listaBeads.codeLensStatusIcons)
• Quick actions — inline Done and View actions for referenced beads (listaBeads.codeLensShowQuickActions)

Wisps

Wisps are structured, step-by-step workflow guides generated from Beads formulas. They appear as a collapsible Active Wisps section in the tree view, with each step shown as a child node.

• Inline progress — each wisp shows a compact progress bar (3/7 ███░░░░░░░ 43%) with the current step title
• Actionable steps — current and ready steps are highlighted with distinct colors and context menus
• Complete a step — click the checkmark icon on the step node, or run Beads: Complete Step.
• Squash a wisp — via Beads: Wisp Actions → Squash: condenses the wisp into a digest record.
• Burn a wisp — via Beads: Wisp Actions → Burn: discards the wisp.

The wisps section stays visible across molecule transitions to prevent tree churn, and uses fast-path refresh (~100ms) when wisp steps change.

My Work

The My Work section appears automatically when you have in-progress beads assigned to you. It detects your identity from git config and shows all your claimed beads in one place — no need to dig through the full issue tree.

Create a wisp from the terminal:

bd mol wisp create <formula-name> [--var key=value ...]

Formulas

Formulas are reusable .formula.toml workflow templates stored in .beads/formulas/. They drive Wisp creation and help standardize recurring workflows across your team.

• Beads: Run Workflow Formula — browse formulas, fill in variables, and launch a new wisp from inside VS Code
• Beads: Instantiate Formula — create a new formula instance directly

Export & Search

• Beads: Export — export filtered beads as JSONL, Markdown, or Obsidian notes
• Beads: Search Beads — fuzzy search across all beads
• Beads: Show Orphaned Beads — find beads referenced in commits but missing from the tracker

Stale Issue Management

Beads that go without activity for a configurable period are flagged as stale:

• Beads: Show Stale Issues — filter the tree to show only stale beads
• Beads: Close All Stale Issues — batch-close all stale beads
• Configure the threshold with listaBeads.staleDays (default: 14 days)
• Get a warning when stale count reaches listaBeads.staleWarnThreshold (default: 20)

Azure DevOps Integration

Connect Lista Beads to Azure DevOps to see your ADO work items alongside your beads, and bridge the gap between the two systems.

• Browse Epics, Features, Stories, Bugs, and Tasks in the ADO Work Items panel.
• Search ADO items with Beads: Search ADO Work Items.
• Create a bead from any ADO item via the context menu.
• Bulk import ADO items using the import action in the ADO view title bar.
• Group the ADO view by type, state, or assignee via listaBeads.adoGroupBy.
• Set Max Items — adjust the query limit quickly from the ADO view title bar without opening settings.

Set up your PAT securely: Run Beads: Set ADO PAT to store your Personal Access Token in VS Code's encrypted secret storage. Do not put your PAT in settings.json.

ADO Configuration

Tracker Sync (Multi-Tracker Integration)

The Tracker Sync panel provides bidirectional sync with external issue trackers through the bd CLI. All five supported trackers appear in a unified sidebar view:

Setup: Configure each tracker via the bd config CLI — run Beads: Configure Tracker from the Tracker Sync panel for guidance.

Features:

• Sync — Pull, push, or full bidirectional sync per tracker
• Sync All — Sync all configured trackers in one action
• Status — See connection status, last sync time, and pending items at a glance
• Progress — Notification progress bar during sync operations
• Dedup — Prevents duplicate syncs for the same tracker

Note: The Tracker Sync panel replaces the browse-and-import workflow from the legacy ADO panel. Configure ADO via bd config and use bd ado sync instead of the direct REST client.

Settings

General

Stale Issues

CodeLens

Dolt Sync

Swarm / Team

ADO-specific settings are listed in the Azure DevOps Integration section above.

Commands

Navigation

Actions

Filters

Wisps & Formulas

Dashboard & Sync

Maintenance

Tracker Sync

Azure DevOps

Troubleshooting

bd command not found

Ensure the Beads CLI is installed and on your PATH. After installing, restart VS Code so it picks up the updated environment.

# Verify the CLI is reachable:
which bd && bd --version

If bd is installed in a non-standard location, set listaBeads.bdPath to the full path (e.g. /usr/local/bin/bd).

No beads appear / .beads directory not detected

The extension looks for a .beads directory in your workspace root.

• Run bd init to create a Beads database in your project.
• If .beads lives elsewhere (e.g. in a monorepo subfolder), set listaBeads.repoPath to the absolute path of the repo that contains .beads/.

ADO Work Items view is empty or shows an error

1. Confirm listaBeads.adoOrganization and listaBeads.adoProject are set in your VS Code settings.
2. Verify that your PAT (set via Beads: Set ADO PAT) is valid, not expired, and has Read access to Work Items.
3. Open the Output panel and select Beads from the dropdown for detailed error messages.

Publishing

The extension is published to both the VS Code Marketplace and the OpenVSX Registry (used by Cursor and other compatible editors).

Prerequisites

1. VS Code Marketplace: Obtain a Personal Access Token (PAT) from Azure DevOps with Marketplace > Manage scope.
2. OpenVSX: Create an account at open-vsx.org and generate an access token. Ensure the ListaDev namespace is claimed.

Manual Publishing

# Publish to VS Code Marketplace only
npm run publish

# Publish to OpenVSX only (requires OVSX_PAT env var)
OVSX_PAT=<your-token> npm run publish:ovsx

# Publish to both
VSCE_PAT=<your-token> OVSX_PAT=<your-token> npm run publish:all

CI/CD (GitHub Actions)

A workflow at .github/workflows/publish.yml automatically publishes on version tags:

git tag v0.3.3
git push origin v0.3.3

The workflow builds, tests, packages, and publishes to both registries.

Required repository secrets: