What does the Beads AI skill do?

Tracks complex, multi-session work using the Beads issue tracker and dependency graphs, and provides persistent memory that survives conversation compaction. Use when work spans multiple sessions, has complex dependencies, or needs persistent context across compaction cycles. Trigger with phrases like "create task for", "what's ready to work on", "show task", "track this work", "what's blocking", or "update status".

Why use Beads on TypingMind?

Because you install it once and use it with any model. Beads is plain Markdown rather than provider-specific code, so the same skill runs on GPT-5, Claude, Gemini, Grok, or a local model — and you can switch model mid-chat without it breaking. TypingMind runs on your own API keys, so you pay providers directly instead of a per-seat subscription, and your skills and chats stay in your own storage.

How do I install Beads in TypingMind?

Open Plugins → Skills → Install from GitHub in TypingMind and paste https://github.com/ynulihao/AgentSkillOS/tree/main/data/skill_seeds/beads. TypingMind reads its SKILL.md and bundles its files and installs it as a skill you can enable per chat.

Which AI models can use Beads?

Any model you connect in TypingMind. AI skills are plain Markdown instructions rather than provider-specific code, so GPT, Claude, Gemini, Grok, and local models can all load this skill when a request matches it.

How many AI models can I use with Beads?

As many as you like. As long as a model supports skills, you can use Beads with it — GPT, Claude, Gemini, Grok, DeepSeek, Mistral, Llama and more — all on TypingMind with your own API keys.

Is the Beads AI skill free?

Yes. It is published on GitHub by ynulihao under the MIT license. You only pay your own AI provider for the tokens you use.

An AI skill is a reusable instruction bundle that teaches an AI model how to do one specific task. It follows the open Agent Skills format: a SKILL.md file with a name and description, plus any scripts, templates or reference files the model may need. The model reads the instructions only when your request matches the skill, so an installed skill costs nothing until it is used.

How are AI skills different from plugins or MCP servers?

A plugin or MCP server gives a model new tools to call — code that runs somewhere and returns a result. An AI skill gives the model knowledge and process instead: how to approach a task, which steps to follow, what good output looks like. Skills are plain Markdown, so they need no server, no API key and no runtime, and they work with any model.

Beads by ynulihao — AI Skill for Any LLM

Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.

Overview

bd (beads) replaces markdown task lists with a dependency-aware graph stored in git. Unlike TodoWrite (session-scoped), bd persists across compactions and tracks complex dependencies.

Key Distinction:

bd: Multi-session work, dependencies, survives compaction, git-backed
TodoWrite: Single-session tasks, linear execution, conversation-scoped

Core Capabilities:

📊 Dependency Graphs: Track what blocks what (blocks, parent-child, discovered-from, related)
💾 Compaction Survival: Tasks persist when conversation history is compacted
🐙 Git Integration: Issues versioned in .beads/issues.jsonl, sync with bd sync
🔍 Smart Discovery: Auto-finds ready work (bd ready), blocked work (bd blocked)
📝 Audit Trails: Complete history of status changes, notes, and decisions
🏷️ Rich Metadata: Priority (P0-P4), types (bug/feature/task/epic), labels, assignees

When to Use bd vs TodoWrite:

❓ "Will I need this context in 2 weeks?" → YES = bd
❓ "Could conversation history get compacted?" → YES = bd
❓ "Does this have blockers/dependencies?" → YES = bd
❓ "Is this fuzzy/exploratory work?" → YES = bd
❓ "Will this be done in this session?" → YES = TodoWrite
❓ "Is this just a task list for me right now?" → YES = TodoWrite

Decision Rule: If resuming in 2 weeks would be hard without bd, use bd.

Prerequisites

Required:

bd CLI: Version 0.34.0 or later installed and in PATH
Git Repository: Current directory must be a git repo
Initialization: bd init must be run once (humans do this, not agents)

Verify Installation:

bash
bd --version  # Should return 0.34.0 or later

First-Time Setup (humans run once):

bash
cd /path/to/your/repo
bd init  # Creates .beads/ directory with database

Optional:

BEADS_DIR environment variable for alternate database location
Daemon for background sync: bd daemon --start

Instructions

Session Start Protocol

Every session, start here:

Step 1: Check for Ready Work

bash
bd ready

Shows tasks with no open blockers, sorted by priority (P0 → P4).

What this shows:

Task ID (e.g., myproject-abc)
Title
Priority level
Issue type (bug, feature, task, epic)

Example output:


claude-code-plugins-abc [P1] [task] open
  Implement user authentication

claude-code-plugins-xyz [P0] [epic] in_progress
  Refactor database layer

Step 2: Pick Highest Priority Task

Choose the highest priority (P0 > P1 > P2 > P3 > P4) task that's ready.

Step 3: Get Full Context

bash
bd show <task-id>

Displays:

Full task description
Dependency graph (what blocks this, what this blocks)
Audit trail (all status changes, notes)
Metadata (created, updated, assignee, labels)

Step 4: Start Working

bash
bd update <task-id> --status in_progress

Marks task as actively being worked on.

Step 5: Add Notes as You Work

bash
bd update <task-id> --notes "Completed: X. In progress: Y. Blocked by: Z"

Critical for compaction survival: Write notes as if explaining to a future agent with zero conversation context.

Note Format (best practice):


COMPLETED: Specific deliverables (e.g., "implemented JWT refresh endpoint + rate limiting")
IN PROGRESS: Current state + next immediate step
BLOCKERS: What's preventing progress
KEY DECISIONS: Important context or user guidance

Task Creation Workflow

When to Create Tasks

Create bd tasks when:

User mentions tracking work across sessions
User says "we should fix/build/add X"
Work has dependencies or blockers
Exploratory/research work with fuzzy boundaries

Basic Task Creation

bash
bd create "Task title" -p 1 --type task

Arguments:

Title: Brief description (required)
Priority: 0-4 where 0=critical, 1=high, 2=medium, 3=low, 4=backlog (default: 2)
Type: bug, feature, task, epic, chore (default: task)

Example:

bash
bd create "Fix authentication bug" -p 0 --type bug

Create with Description

bash
bd create "Implement OAuth" -p 1 --description "Add OAuth2 support for Google, GitHub, Microsoft. Use passport.js library."

Epic with Children

bash
# Create parent epic
bd create "Epic: OAuth Implementation" -p 0 --type epic
# Returns: myproject-abc

# Create child tasks
bd create "Research OAuth providers" -p 1 --parent myproject-abc
bd create "Implement auth endpoints" -p 1 --parent myproject-abc
bd create "Add frontend login UI" -p 2 --parent myproject-abc

Update & Progress Workflow

Change Status

bash
bd update <task-id> --status <new-status>

Status Values:

open - Not started
in_progress - Actively working
blocked - Stuck, waiting on something
closed - Completed

Example:

bash
bd update myproject-abc --status blocked

Add Progress Notes

bash
bd update <task-id> --notes "Progress update here"

Appends to existing notes field (doesn't replace).

Change Priority

bash
bd update <task-id> -p 0  # Escalate to critical

Add Labels

bash
bd label add <task-id> backend
bd label add <task-id> security

Labels provide cross-cutting categorization beyond status/type.

Dependency Management

Add Dependencies

bash
bd dep add <child-id> <parent-id>

Meaning: <parent-id> blocks <child-id> (parent must be completed first).

Dependency Types:

blocks: Parent must close before child becomes ready
parent-child: Hierarchical relationship (epics and subtasks)
discovered-from: Task A led to discovering task B
related: Tasks are related but not blocking

Example:

bash
# Deployment blocked by tests passing
bd dep add deploy-task test-task  # test-task blocks deploy-task

View Dependencies

bash
bd dep list <task-id>

Shows:

What this task blocks (dependents)
What blocks this task (blockers)

Circular Dependency Prevention

bd automatically prevents circular dependencies. If you try to create a cycle, the command fails.

Completion Workflow

Close a Task

bash
bd close <task-id> --reason "Completion summary"

Best Practice: Always include a reason describing what was accomplished.

Example:

bash
bd close myproject-abc --reason "Completed: OAuth endpoints implemented with Google, GitHub providers. Tests passing."

Check Newly Unblocked Work

After closing a task, run:

bash
bd ready

Closing a task may unblock dependent tasks, making them newly ready.

Close Epics When Children Complete

bash
bd epic close-eligible

Automatically closes epics where all child tasks are closed.

Git Sync Workflow

All-in-One Sync

bash
bd sync

Performs:

Export database to .beads/issues.jsonl
Commit changes to git
Pull from remote (merge if needed)
Import updated JSONL back to database
Push local commits to remote

Use when: End of session, before handing off to teammate, after major progress.

Export Only

bash
bd export -o backup.jsonl

Creates JSONL backup without git operations.

Import Only

bash
bd import -i backup.jsonl

Imports JSONL file into database.

Background Daemon

bash
bd daemon --start  # Auto-sync in background
bd daemon --status # Check daemon health
bd daemon --stop   # Stop auto-sync

Daemon watches for database changes and auto-exports to JSONL.

Find & Search Commands

Find Ready Work

bash
bd ready

Shows tasks with no open blockers.

List All Tasks

bash
bd list --status open           # Only open tasks
bd list --priority 0            # Only P0 (critical)
bd list --type bug              # Only bugs
bd list --label backend         # Only labeled "backend"
bd list --assignee alice        # Only assigned to alice

Show Task Details

bash
bd show <task-id>

Full details: description, dependencies, audit trail, metadata.

Search by Text

bash
bd search "authentication"      # Search titles and descriptions
bd search login --status open   # Combine with filters

Find Blocked Work

bash
bd blocked

Shows all tasks that have open blockers preventing them from being worked on.

Project Statistics

bash
bd stats

Shows:

Total issues by status (open, in_progress, blocked, closed)
Issues by priority (P0-P4)
Issues by type (bug, feature, task, epic, chore)
Completion rate

Complete Command Reference

Command	When to Use	Example
FIND COMMANDS
`bd ready`	Find unblocked tasks	User asks "what should I work on?"
`bd list`	View all tasks (with filters)	"Show me all open bugs"
`bd show <id>`	Get task details	"Show me task bd-42"
`bd search <query>`	Text search across tasks	"Find tasks about auth"
`bd blocked`	Find stuck work	"What's blocking us?"
`bd stats`	Project metrics	"How many tasks are open?"
CREATE COMMANDS
`bd create`	Track new work	"Create a task for this bug"
`bd template create`	Use issue template	"Create task from bug template"
`bd init`	Initialize beads	"Set up beads in this repo" (humans only)
UPDATE COMMANDS
`bd update <id>`	Change status/priority/notes	"Mark as in progress"
`bd dep add`	Link dependencies	"This blocks that"
`bd label add`	Tag with labels	"Label this as backend"
`bd comments add`	Add comment	"Add comment to task"
`bd reopen <id>`	Reopen closed task	"Reopen bd-42, found regression"
`bd rename-prefix`	Rename issue prefix	"Change prefix from bd- to proj-"
`bd epic status`	Check epic progress	"Show epic completion %"
COMPLETE COMMANDS
`bd close <id>`	Mark task done	"Close this task, it's done"
`bd epic close-eligible`	Auto-close complete epics	"Close epics where all children done"
SYNC COMMANDS
`bd sync`	Git sync (all-in-one)	"Sync tasks to git"
`bd export`	Export to JSONL	"Backup all tasks"
`bd import`	Import from JSONL	"Restore from backup"
`bd daemon`	Background sync manager	"Start auto-sync daemon"
CLEANUP COMMANDS
`bd delete <id>`	Delete issues	"Delete test task" (requires --force)
`bd compact`	Archive old closed tasks	"Compress database"
REPORTING COMMANDS
`bd stats`	Project metrics	"Show project health"
`bd audit record`	Log interactions	"Record this LLM call"
`bd workflow`	Show workflow guide	"How do I use beads?"
ADVANCED COMMANDS
`bd prime`	Refresh AI context	"Load bd workflow rules"
`bd quickstart`	Interactive tutorial	"Teach me beads basics"
`bd daemons`	Multi-repo daemon mgmt	"Manage all beads daemons"
`bd version`	Version check	"Check bd version"
`bd restore <id>`	Restore compacted issue	"Get full history from git"

Output

This skill produces:

Task IDs: Format <prefix>-<hash> (e.g., claude-code-plugins-abc, myproject-xyz)

Status Summaries:


5 open, 2 in_progress, 1 blocked, 47 closed

Dependency Graphs (visual tree):


myproject-abc: Deploy to production [P0] [blocked]
  Blocked by:
    ↳ myproject-def: Run integration tests [P1] [in_progress]
    ↳ myproject-ghi: Fix failing tests [P1] [open]

Audit Trails (complete history):


2025-12-22 10:00 - Created by alice (P2, task)
2025-12-22 10:15 - Priority changed: P2 → P0
2025-12-22 10:30 - Status changed: open → in_progress
2025-12-22 11:00 - Notes added: "Implemented JWT auth..."
2025-12-22 14:00 - Status changed: in_progress → blocked
2025-12-22 14:01 - Notes added: "Blocked: API endpoint returns 503"

Error Handling

Common Failures

1. `bd: command not found`

Cause: bd CLI not installed or not in PATH Solution: Install from https://github.com/steveyegge/beads

bash
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Or via npm
npm install -g @beads/bd

# Or via Homebrew
brew install steveyegge/beads/bd

2. `No .beads database found`

Cause: beads not initialized in this repository Solution: Run bd init (humans do this once, not agents)

bash
bd init  # Creates .beads/ directory

3. `Task not found: <id>`

Cause: Invalid task ID or task doesn't exist Solution: Use bd list to see all tasks and verify ID format

bash
bd list                    # See all tasks
bd search <partial-title>  # Find task by title

4. `Circular dependency detected`

Cause: Attempting to create a dependency cycle (A blocks B, B blocks A) Solution: bd prevents circular dependencies automatically. Restructure dependency graph.

bash
bd dep list <id>  # View current dependencies

5. Git merge conflicts in `.beads/issues.jsonl`

Cause: Multiple users modified same issue Solution: bd sync handles JSONL conflicts automatically. If manual intervention needed:

bash
# View conflict
git status

# bd provides conflict resolution tools
bd sync --merge  # Attempt auto-resolution

6. `Database is locked`

Cause: Daemon or another process has exclusive lock Solution: Restart daemon or wait for lock to release

bash
bd daemon --stop
bd daemon --start

7. Sync failures

Cause: Network issues, authentication failures, or git configuration Solution: Check git remote access and credentials

bash
git fetch  # Test connectivity
git status # Verify repo state

Examples

Example 1: Multi-Session Feature (Epic with Children)

User Request: "We need to implement OAuth, this will take multiple sessions"

Agent Response:

bash
# Create epic
bd create "Epic: OAuth Implementation" -p 0 --type epic
# Returns: claude-code-plugins-abc

# Create child tasks
bd create "Research OAuth providers (Google, GitHub, Microsoft)" -p 1 --parent claude-code-plugins-abc
# Returns: claude-code-plugins-abc.1

bd create "Implement backend auth endpoints" -p 1 --parent claude-code-plugins-abc
# Returns: claude-code-plugins-abc.2

bd create "Add frontend login UI components" -p 2 --parent claude-code-plugins-abc
# Returns: claude-code-plugins-abc.3

# Add dependencies (backend must complete before frontend)
bd dep add claude-code-plugins-abc.3 claude-code-plugins-abc.2

# Start with research
bd update claude-code-plugins-abc.1 --status in_progress

Result: Work structured, ready to resume after compaction.

Example 2: Tracking Blocked Work

Scenario: Agent discovers API is down during implementation

Agent Actions:

bash
# Mark current task as blocked
bd update claude-code-plugins-xyz --status blocked --notes "API endpoint /auth returns 503, reported to backend team"

# Create blocker task
bd create "Fix /auth endpoint 503 error" -p 0 --type bug
# Returns: claude-code-plugins-blocker

# Link dependency (blocker blocks original task)
bd dep add claude-code-plugins-xyz claude-code-plugins-blocker

# Find other ready work
bd ready
# Shows tasks that aren't blocked - agent can switch to those

Result: Blocked work documented, agent productive on other tasks.

Example 3: Session Resume After Compaction

Session 1:

bash
bd create "Implement user authentication" -p 1
bd update myproject-auth --status in_progress
bd update myproject-auth --notes "COMPLETED: JWT library integrated. IN PROGRESS: Testing token refresh. NEXT: Rate limiting"
# [Conversation compacted - history deleted]

Session 2 (weeks later):

bash
bd ready
# Shows: myproject-auth [P1] [task] in_progress

bd show myproject-auth
# Full context preserved:
#   - Title: Implement user authentication
#   - Status: in_progress
#   - Notes: "COMPLETED: JWT library integrated. IN PROGRESS: Testing token refresh. NEXT: Rate limiting"
#   - No conversation history needed!

# Agent continues exactly where it left off
bd update myproject-auth --notes "COMPLETED: Token refresh working. IN PROGRESS: Rate limiting implementation"

Result: Zero context loss despite compaction.

Example 4: Complex Dependencies (3-Level Graph)

Scenario: Build feature with prerequisites

bash
# Create tasks
bd create "Deploy to production" -p 0
# Returns: deploy-prod

bd create "Run integration tests" -p 1
# Returns: integration-tests

bd create "Fix failing unit tests" -p 1
# Returns: fix-tests

# Create dependency chain
bd dep add deploy-prod integration-tests      # Integration blocks deploy
bd dep add integration-tests fix-tests        # Fixes block integration

# Check what's ready
bd ready
# Shows: fix-tests (no blockers)
# Hides: integration-tests (blocked by fix-tests)
# Hides: deploy-prod (blocked by integration-tests)

# Work on ready task
bd update fix-tests --status in_progress
# ... fix tests ...
bd close fix-tests --reason "All unit tests passing"

# Check ready again
bd ready
# Shows: integration-tests (now unblocked!)
# Still hides: deploy-prod (still blocked)

Result: Dependency chain enforces correct order automatically.

Example 5: Team Collaboration (Git Sync)

Alice's Session:

bash
bd create "Refactor database layer" -p 1
bd update db-refactor --status in_progress
bd update db-refactor --notes "Started: Migrating to Prisma ORM"

# End of day - sync to git
bd sync
# Commits tasks to git, pushes to remote

Bob's Session (next day):

bash
# Start of day - sync from git
bd sync
# Pulls latest tasks from remote

bd ready
# Shows: db-refactor [P1] [in_progress] (assigned to alice)

# Bob checks status
bd show db-refactor
# Sees Alice's notes: "Started: Migrating to Prisma ORM"

# Bob works on different task (no conflicts)
bd create "Add API rate limiting" -p 2
bd update rate-limit --status in_progress

# End of day
bd sync
# Both Alice's and Bob's tasks synchronized

Result: Distributed team coordination through git.

Resources

When to Use bd vs TodoWrite (Decision Tree)

Use bd when:

✅ Work spans multiple sessions or days
✅ Tasks have dependencies or blockers
✅ Need to survive conversation compaction
✅ Exploratory/research work with fuzzy boundaries
✅ Collaboration with team (git sync)

Use TodoWrite when:

✅ Single-session linear tasks
✅ Simple checklist for immediate work
✅ All context is in current conversation
✅ Will complete within current session

Decision Rule: If resuming in 2 weeks would be hard without bd, use bd.

Essential Commands Quick Reference

Top 10 most-used commands:

Command	Purpose
`bd ready`	Show tasks ready to work on
`bd create "Title" -p 1`	Create new task
`bd show <id>`	View task details
`bd update <id> --status in_progress`	Start working
`bd update <id> --notes "Progress"`	Add progress notes
`bd close <id> --reason "Done"`	Complete task
`bd dep add <child> <parent>`	Add dependency
`bd list`	See all tasks
`bd search <query>`	Find tasks by keyword
`bd sync`	Sync with git remote

Session Start Protocol (Every Session)

Run bd ready first
Pick highest priority ready task
Run bd show <id> to get full context
Update status to in_progress
Add notes as you work (critical for compaction survival)

Database Selection

bd uses .beads/ directory by default.

Alternate Database:

bash
export BEADS_DIR=/path/to/alternate/beads
bd ready  # Uses alternate database

Multiple Databases: Use BEADS_DIR to switch between projects.

Advanced Features

For complex scenarios, see references:

Compaction Strategies: {baseDir}/references/ADVANCED_WORKFLOWS.md
- Tier 1/2/ultra compaction for old closed issues
- Semantic summarization to reduce database size
Epic Management: {baseDir}/references/ADVANCED_WORKFLOWS.md
- Nested epics (epics containing epics)
- Bulk operations on epic children
Template System: {baseDir}/references/ADVANCED_WORKFLOWS.md
- Custom issue templates
- Template variables and defaults
Git Integration: {baseDir}/references/GIT_INTEGRATION.md
- Merge conflict resolution
- Daemon architecture
- Branching strategies
Team Collaboration: {baseDir}/references/TEAM_COLLABORATION.md
- Multi-user workflows
- Worktree support
- Prefix strategies

Full Documentation

Complete reference: https://github.com/steveyegge/beads

Existing detailed guides:

{baseDir}/references/CLI_REFERENCE.md - Complete command syntax
{baseDir}/references/WORKFLOWS.md - Detailed workflow patterns
{baseDir}/references/DEPENDENCIES.md - Dependency system deep dive
{baseDir}/references/RESUMABILITY.md - Compaction survival guide
{baseDir}/references/BOUNDARIES.md - bd vs TodoWrite detailed comparison
{baseDir}/references/STATIC_DATA.md - Database schema reference

Progressive Disclosure: This skill provides essential instructions for all 30 beads commands. For advanced topics (compaction, templates, team workflows), see the references directory. Slash commands (/bd-create, /bd-ready, etc.) remain available as explicit fallback for power users.

Publisher	ynulihao
Repository	`AgentSkillOS`
Skill name	`beads`
Stars	612
Forks	76
Bundled files	11
License	MIT
Links	Skill source Repository

Overview

Installation

Install in TypingMind

Install in another agent

Use it in TypingMind

Works with any AI model

Skill instructions

Beads - Persistent Task Memory for AI Agents

Overview

Prerequisites

Instructions

Session Start Protocol

Step 1: Check for Ready Work

Step 2: Pick Highest Priority Task

Step 3: Get Full Context

Step 4: Start Working

Step 5: Add Notes as You Work

Task Creation Workflow

When to Create Tasks

Basic Task Creation

Create with Description

Epic with Children

Update & Progress Workflow

Change Status

Add Progress Notes

Change Priority

Add Labels

Dependency Management

Add Dependencies

View Dependencies

Circular Dependency Prevention

Completion Workflow

Close a Task

Check Newly Unblocked Work

Close Epics When Children Complete

Git Sync Workflow

All-in-One Sync

Export Only

Import Only

Background Daemon

Find & Search Commands

Find Ready Work

List All Tasks

Show Task Details

Search by Text

Find Blocked Work

Project Statistics

Complete Command Reference

Output

Error Handling

Common Failures

1. bd: command not found

2. No .beads database found

3. Task not found: <id>

4. Circular dependency detected

5. Git merge conflicts in .beads/issues.jsonl

6. Database is locked

7. Sync failures

Examples

Example 1: Multi-Session Feature (Epic with Children)

Example 2: Tracking Blocked Work

Example 3: Session Resume After Compaction

Example 4: Complex Dependencies (3-Level Graph)

Example 5: Team Collaboration (Git Sync)

Resources

When to Use bd vs TodoWrite (Decision Tree)

Essential Commands Quick Reference

Session Start Protocol (Every Session)

Database Selection

Advanced Features

Full Documentation

Bundled files

Frequently asked questions

Related AI Skills

Set up your own AI workspace now

1. `bd: command not found`

2. `No .beads database found`

3. `Task not found: <id>`

4. `Circular dependency detected`

5. Git merge conflicts in `.beads/issues.jsonl`

6. `Database is locked`