# Beads

> Use beads (bd) for persistent task tracking in coding projects. A git-backed issue tracker designed for AI agents with dependency graphs, hierarchical tasks, and multi-agent coordination.

- **Type:** Skill
- **Install:** `agentstack add skill-block-agent-skills-beads`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [block](https://agentstack.voostack.com/s/block)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [block](https://github.com/block)
- **Source:** https://github.com/block/agent-skills/tree/main/beads

## Install

```sh
agentstack add skill-block-agent-skills-beads
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

This skill teaches effective use of **beads** (`bd`), a distributed git-backed issue tracker designed for AI agents. Use beads to track tasks, manage dependencies, and coordinate work across sessions.

## Getting Started

First, check if beads is available and initialized:

```bash
# Check if bd is installed
bd version

# Check if current project has beads initialized
bd status
```

**If `bd` is not installed**, ask the user which installation method they prefer:
- **npm:** `npm install -g @beads/bd`
- **Homebrew:** `brew install beads` (macOS)
- **Go:** `go install github.com/steveyegge/beads/cmd/bd@latest`

Do not install without user confirmation, as these are global system packages.

**If not initialized in the project**, run:
```bash
bd init
```

For personal use on shared projects (won't commit to repo):
```bash
bd init --stealth
```

For contributors on forked repos (routes to separate planning repo):
```bash
bd init --contributor
```

## Essential Commands

| Command | Purpose |
|---------|---------|
| `bd ready` | List tasks with no open blockers (what to work on next) |
| `bd create "Title" -p 1` | Create a task (priority 0-3, lower = higher priority) |
| `bd show ` | View task details and dependencies |
| `bd list` | List all open issues |
| `bd close ` | Mark task as complete |
| `bd update  --status in_progress` | Update task status |
| `bd dep add  ` | Create dependency (child blocked by parent) |
| `bd sync` | Force immediate sync to git |

**Always use `--json` flag** for machine-readable output when parsing results.

## Task Hierarchy

Beads supports hierarchical IDs for organizing work:

- `bd-a3f8` — Epic (large feature)
- `bd-a3f8.1` — Task under epic
- `bd-a3f8.1.1` — Sub-task

Create hierarchical tasks:
```bash
bd create "Epic: User Authentication" -t epic -p 1
bd create "Implement login flow" -p 1 --parent bd-a3f8
```

## Session Workflow

### Starting a Session

```bash
# See what's ready to work on
bd ready --json

# Pick a task and mark it in progress
bd update  --status in_progress

# View full details
bd show  --json
```

### During Work

```bash
# Create new tasks as you discover them
bd create "Fix edge case in validation" -p 2

# Add dependencies
bd dep add  

# Update task with notes
bd update  --notes "Found issue with timezone handling"
```

### Ending a Session ("Land the Plane")

When finishing work, complete ALL these steps:

```bash
# 1. File issues for remaining work
bd create "TODO: Add integration tests" -p 2

# 2. Close completed tasks
bd close  --reason "Completed"

# 3. Sync and push (MANDATORY)
git pull --rebase
bd sync
git push

# 4. Verify push succeeded
git status  # Must show "up to date with origin"

# 5. Identify next task for follow-up
bd ready --json
```

**CRITICAL**: Always push before ending a session. Unpushed work causes coordination problems in multi-agent workflows.

## Important Rules

### DO use `bd update` with flags
```bash
bd update  --description "new description"
bd update  --title "new title"  
bd update  --design "design notes"
bd update  --notes "additional notes"
bd update  --acceptance "acceptance criteria"
bd update  --status in_progress
```

### DO NOT use `bd edit`
The `edit` command opens an interactive editor (`$EDITOR`) which AI agents cannot use. Always use `bd update` with flags instead.

### DO sync before ending sessions
```bash
bd sync  # Forces immediate export, commit, and push
```

Without `bd sync`, changes sit in a 30-second debounce window and may not be committed.

### DO include issue IDs in commit messages
```bash
git commit -m "Fix auth validation bug (bd-abc)"
```

This enables `bd doctor` to detect orphaned issues.

## Dependency Types

```bash
# Hard blocker - child cannot start until parent is done
bd dep add   --type blocks

# Soft link - related but not blocking  
bd dep add   --type related

# Parent-child - hierarchical relationship
bd dep add   --type parent-child
```

## Handling Merge Conflicts

If conflicts occur in `.beads/issues.jsonl`:

```bash
# Accept remote version
git checkout --theirs .beads/issues.jsonl

# Re-import to database
bd import -i .beads/issues.jsonl

# Continue with your work
```

## Git Hooks (Recommended)

Install hooks for automatic sync:

```bash
bd hooks install
```

This prevents stale JSONL problems by auto-syncing on commit, merge, push, and checkout.

## MCP Server Alternative

For tighter integration, beads also offers an MCP server (`beads-mcp`) that provides tools directly to your agent. Install via:

```bash
pip install beads-mcp
```

The CLI (`bd`) and MCP server work with the same underlying database.

## Quick Reference

```bash
# What should I work on?
bd ready

# Create a task
bd create "Fix bug in login" -p 1

# Start working
bd update bd-xyz --status in_progress

# Done working
bd close bd-xyz --reason "Completed"
bd sync
git push
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [block](https://github.com/block)
- **Source:** [block/agent-skills](https://github.com/block/agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-block-agent-skills-beads
- Seller: https://agentstack.voostack.com/s/block
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.