vi-beads

by @t3chn in Development

# Install this skill:

npx skills add t3chn/codex-skills --skill "vi-beads"

Install specific skill from multi-skill repository

# Description

Git-backed issue tracker for multi-session work with dependencies and persistent memory across session boundaries. Use when work spans multiple sessions, has blockers/dependencies, or needs context recovery after context loss.

# SKILL.md

name: vi-beads
description: "Git-backed issue tracker for multi-session work with dependencies and persistent memory across session boundaries. Use when work spans multiple sessions, has blockers/dependencies, or needs context recovery after context loss."

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.

bd vs update_plan

bd (persistent)	update_plan (ephemeral)
Multi-session work	Single-session tasks
Complex dependencies	Linear execution
Survives compaction	Conversation-scoped
Git-backed, team sync	Local to session

Decision test: "Will I need this context in 2 weeks?" → YES = bd

When to use bd:
- 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)

When to use update_plan:
- Single-session linear tasks
- Simple checklist for immediate work
- All context is in current conversation
- Will complete within current session

Prerequisites

bd --version  # Requires v0.34.0+

bd CLI installed and in PATH
Git repository (bd requires git for sync)
Initialization: bd init run once (humans do this, not agents)

CLI Reference

Run bd prime for AI-optimized workflow context (auto-loaded by hooks).
Run bd <command> --help for specific command usage.

Essential commands: bd ready, bd create, bd show, bd update, bd close, bd sync

Session Protocol

bd ready — Find unblocked work
bd show <id> — Get full context
bd update <id> --status in_progress — Start work
Add notes as you work (critical for compaction survival)
bd close <id> --reason "..." — Complete task
bd sync — Persist to git (always run at session end)

Sync Branch (Protected main, worktrees)

If your repo uses protected branches or git worktree, configure a dedicated sync branch so bd can commit/push beads data without touching your current branch.

Recommended (team/shared, version-controlled): add to .beads/config.yaml:

sync-branch: beads-sync

Other options:
- Per-user default for all repos: ~/.config/bd/config.yaml (sync-branch: ...)
- Temporary override: BEADS_SYNC_BRANCH=...
- Legacy/DB-backed: bd config set sync.branch <branch> (also updates sync-branch in config.yaml when possible)

Advanced Features

Feature	CLI	Resource
Molecules (templates)	`bd mol --help`	MOLECULES.md
Chemistry (pour/wisp)	`bd pour`, `bd wisp`	CHEMISTRY_PATTERNS.md
Agent beads	`bd agent --help`	AGENTS.md
Async gates	`bd gate --help`	ASYNC_GATES.md
Worktrees	`bd worktree --help`	WORKTREES.md

Resources

Resource	Content
BOUNDARIES.md	bd vs update_plan detailed comparison
CLI_REFERENCE.md	Complete command syntax
DEPENDENCIES.md	Dependency system deep dive
INTEGRATION_PATTERNS.md	update_plan and tool integration
ISSUE_CREATION.md	When and how to create issues
MOLECULES.md	Proto definitions, component labels
PATTERNS.md	Common usage patterns
RESUMABILITY.md	Compaction survival guide
STATIC_DATA.md	Database schema reference
TROUBLESHOOTING.md	Error handling and fixes
WORKFLOWS.md	Step-by-step workflow patterns
AGENTS.md	Agent bead tracking (v0.40+)
ASYNC_GATES.md	Human-in-the-loop gates
CHEMISTRY_PATTERNS.md	Mol vs Wisp decision tree
WORKTREES.md	Parallel development patterns

Full Documentation

bd prime: AI-optimized workflow context
GitHub: github.com/steveyegge/beads

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.