Quick Start

This guide gets you from zero to a running BeadSpec session in under five minutes.

Prerequisites

• bd installed and on your PATH (see Installation)
• BeadSpec installed

Recommended companions

BeadSpec is fully usable with just bd. We recommend also installing OpenSpec if you work with structured feature specs — it unlocks the Changes view and proposal browser. Ruflo is optional and adds cross-session agent memory features. Both can be enabled or disabled at any time in Settings → Features.

See Optional Integrations for installation pointers.

1. Create or open a Beads project

If you don't have a Beads project yet, create one:

mkdir my-project && cd my-project
bd init

This creates a .beads/ directory with a Dolt database inside.

If you have an existing project, just navigate to its directory.

2. Launch BeadSpec

Open BeadSpec from your Applications folder, Launchpad, or Start Menu. On first launch it will ask you to open a project folder — select the directory containing the .beads/ folder.

3. Explore your issues

The task list shows all issues from your Beads project, grouped by status by default. Use the filter bar at the top to narrow down by assignee, label, priority, or any custom field.

4. Create your first issue

From the task list: press N (when no input is focused) to open a new issue dialog.

Quick Capture (fastest): use the global keyboard shortcut to open a floating capture window without switching apps:

• macOS: ⌘⇧N
• Windows/Linux: Ctrl+Shift+N

(The shortcut can be changed in Settings → Quick Capture.)

5. Open the dependency graph

Click the Graph tab in issue detail (or press G from anywhere in the app when no input is focused) to see an interactive dependency graph.

6. Switch projects

Use File → Open Project (or the project switcher in the sidebar) to open another Beads project. Each project gets its own isolated database connection.

What's next?

• Keyboard shortcuts — learn the full shortcut list
• Views — understand All, Focus, Ready, Health, and Changes views
• Workspace Tabs — multi-tab and split-pane layout
• Optional Integrations — OpenSpec and Ruflo
• Relationship with bd — understand what BeadSpec does vs what bd does