Lista Beads

VS Code extension to browse and manage Beads issues directly in your editor, with optional Azure DevOps integration.

Installation

From the VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "Lista Beads"
4. Click Install

From VSIX (local install)

cd lista-beads
npm install
npm run package          # creates lista-beads-*.vsix
code --install-extension lista-beads-*.vsix

Publishing (maintainers)

# One-time: create a publisher at https://marketplace.visualstudio.com/manage
# Then login:
npx vsce login <publisher-id>

# Publish:
npm run publish

Quickstart

What is Beads? Beads is a distributed, git-backed graph issue tracker optimized for AI agents and developer workflows. It stores tasks locally and syncs them seamlessly alongside your code.

30-Second Getting Started:

1. Install the CLI:

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

2. Initialize in your repo:

   bd init
   

3. Create your first bead:

   bd create "My first task" --type task
   

4. View in VS Code: Open the Beads view in the Activity Bar to see your new task!

Run locally

1. Open lista-extensions/lista-beads in VS Code.
2. Run npm install.
3. Press F5 to launch the Extension Development Host.
4. Open a workspace that contains a Beads database.
5. Open the Beads view in the Activity Bar.

Tests

• npm test

Commands

• Beads: Refresh — Reload the Beads tree view
• Beads: Filters — Open the filter picker (type, status, assignee, text)
• Beads: Clear Filters — Reset filters to defaults
• Beads: Open Issue — Open a bead in the detail panel
• Beads: Set Beads Location — Point the extension at a specific repo
• Beads: Reveal Beads Location — Show the configured repo path
• Beads: Create Bead from Selection — Create a bead from selected editor text
• Beads: Show Dependency Graph — Open the interactive dependency graph
• Beads: Wisp Actions — Squash or burn a wisp
• Beads: Complete Step — Mark a wisp step as done
• Beads: Run Formula — Pick and run a formula from your .beads/formulas/ directory
• Beads: Sync with Azure DevOps — Sync beads with ADO work items
• Beads: Set ADO PAT — Store your Azure DevOps Personal Access Token securely
• Beads: Clear ADO PAT — Remove your stored ADO PAT

The view auto-refreshes when .beads/issues.jsonl or .beads/beads.db changes.

The Beads view includes a "Beads location" row at the top that shows the repo path being used (configured listaBeads.repoPath or the current workspace). On WSL, the path shown is Linux-style; use \\wsl$ in Windows Explorer if you need the Windows view.

In the Beads list, use the issue context menu to delete a Bead. Multi-select is supported, and if dependents exist you can choose to cascade or orphan them.

Filtering

Use Beads: Filters to filter the Beads view by type, status, assignee, or text search. Filters can be combined and persist for the session. Use Beads: Clear Filters to reset to defaults.

The Beads view defaults to showing task, story, epic, and feature issues. Set listaBeads.filterTypes to change the default type filter (set it to [] to show all types).

Wisps

Wisps are structured workflow guides created from Beads formulas. They appear as a collapsible "Wisps" section in the Beads tree view, with each step listed as a child node.

• Complete a step — Click the checkmark icon on a wisp step node, or use 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 without saving.

Create wisps from the CLI:

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

Formulas

Formulas are reusable workflow templates stored as .formula.toml files in .beads/formulas/. Use Beads: Run Formula (the beaker icon in the Beads view title bar) to:

1. Browse and select from available formulas.
2. Fill in any required variables via a prompt sequence.
3. Launch the formula as a new wisp.

To create your own formula, add a .formula.toml file to .beads/formulas/ in your repo.

Azure DevOps Integration

The ADO Work Items view lists Epics, Features, Stories, Bugs, and Tasks from Azure DevOps.

• Use the ADO item context menu to create a Bead from an ADO work item.
• Use the ADO view title action to import multiple ADO items as beads at once.
• Group the ADO view by type, state, or assignee via listaBeads.adoGroupBy.

ADO Configuration

Storing your PAT securely: Use Beads: Set ADO PAT to store your Personal Access Token in VS Code's secure secret storage. Avoid putting your PAT in workspace or user settings.

Troubleshooting

bd command not found

Ensure the Beads CLI is installed and on your system PATH. You may need to restart VS Code after installing it.

No .beads directory detected

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

• Run bd init to initialize a Beads database in your project.
• If the .beads directory is elsewhere, set listaBeads.repoPath to the absolute path of the containing repository.

ADO Connection Problems

If the ADO Work Items view is empty or shows an error:

• Verify listaBeads.adoOrganization, listaBeads.adoProject, and listaBeads.adoBaseUrl are correct.
• Ensure your PAT (set via Beads: Set ADO PAT) is valid, not expired, and has read access to work items.
• Check the Output panel (select Beads in the dropdown) for detailed error messages.

Visual language

Design guidance for colors, icons, and hierarchy lives in docs/visual-language.md.