USP

Powered by Dolt, it offers version-controlled SQL with native branching and cell-level merge, ensuring zero-conflict multi-agent workflows. Its semantic "memory decay" compacts old tasks, optimizing context window usage.

Use cases

• 01Managing long-horizon AI agent tasks
• 02Tracking dependencies and blockers in multi-agent workflows
• 03Persistent project memory across sessions
• 04Context recovery after conversation compaction
• 05Collaborative task management for coding projects

Detected files (5)

• internal/templates/skills/beads/SKILL.mdskill
  Show content (2146 bytes)

  ---
  name: beads
  description: Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking.
  ---
  
  # Beads
  
  Use Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work.
  
  ## First Step
  
  Run:
  
  ```bash
  bd prime
  ```
  
  If that prints nothing, check whether the repository has an active Beads workspace:
  
  ```bash
  bd where
  ```
  
  ## Preferred Route
  
  Use the `bd` CLI when shell access is available. It is the most compact and direct Beads interface.
  
  ## Core CLI Workflow
  
  1. Find work:
  
  ```bash
  bd ready
  bd list --status=open
  bd list --status=in_progress
  ```
  
  2. Inspect before editing:
  
  ```bash
  bd show <id>
  ```
  
  3. Claim work atomically:
  
  ```bash
  bd update <id> --claim
  ```
  
  4. Create durable follow-up work when implementation reveals new tasks:
  
  ```bash
  bd create "Short title" --description="Why this exists and what needs to be done" --type=task --priority=2
  ```
  
  5. Close completed work:
  
  ```bash
  bd close <id> --reason="Completed"
  ```
  
  ## What Belongs In Beads
  
  Use Beads for:
  
  - shared project tasks
  - blockers and dependencies
  - discovered follow-up work
  - work that must survive thread reset, compaction, or handoff
  - status that another person or agent should be able to resume
  
  Use agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state.
  
  ## Rules
  
  - Do not create markdown TODO files as the source of truth when Beads is available.
  - Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead.
  - Prefer `--json` when parsing `bd` output programmatically.
  - If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing.
  - Do not auto-close or mutate tasks unless the work is actually complete.
  

• plugins/beads/skills/beads/SKILL.mdskill
  Show content (4838 bytes)

  ---
  name: beads
  description: >
    Dolt-powered issue tracker for multi-session work with dependencies and persistent
    memory across conversation compaction. Use when work spans sessions, has blockers,
    or needs context recovery after compaction. Trigger with "create task", "what's
    ready", "track this work", "resume after compaction". Make sure to use this skill
    whenever managing multi-session work, tracking dependencies, or recovering context.
  allowed-tools: "Read,Bash(bd:*)"
  version: "0.60.0"
  author: "Steve Yegge <steve.yegge@gmail.com>"
  license: "MIT"
  compatible-with: [claude-code, codex]
  tags: [issue-tracking, task-management, multi-session, dependencies]
  ---
  
  # 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 TodoWrite
  
  **Decision test**: "Will I need this context in 2 weeks?" YES = bd, NO = TodoWrite.
  
  | bd (persistent) | TodoWrite (ephemeral) |
  |-----------------|----------------------|
  | Multi-session, dependencies, compaction survival | Single-session linear tasks |
  | Dolt-backed team sync | Conversation-scoped |
  
  See [BOUNDARIES.md](resources/BOUNDARIES.md) for detailed comparison.
  
  ## Prerequisites
  
  ```bash
  bd --version  # Requires v0.60.0+
  ```
  
  - **bd CLI** installed and in PATH
  - **Git repository** (optional — use `BEADS_DIR` + `--stealth` for git-free operation)
  - **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 dolt push`
  
  ## Session Protocol
  
  1. `bd ready` — Find unblocked work
  2. `bd show <id>` — Get full context
  3. `bd update <id> --claim` — Claim and start work atomically
  4. Add notes as you work (critical for compaction survival)
  5. `bd close <id> --reason "..."` — Complete task
  6. `bd dolt push` — Push to Dolt remote (if configured)
  
  ## Output
  
  Append `--json` to any command for structured output. Use `bd show <id> --long` for extended metadata. Status icons: `○` open `◐` in_progress `●` blocked `✓` closed `❄` deferred.
  
  ## Error Handling
  
  | Error | Fix |
  |-------|-----|
  | `database not found` | `bd init <prefix>` in project root |
  | `not in a git repository` | `git init` first |
  | `disk I/O error (522)` | Move `.beads/` off cloud-synced filesystem |
  | Status updates lag | Use server mode: `bd dolt start` |
  
  See [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) for full details.
  
  ## Examples
  
  **Track a multi-session feature:**
  ```bash
  bd create "OAuth integration" -t epic -p 1 --json
  bd create "Token storage" -t task --deps blocks:oauth-id --json
  bd ready --json                    # Shows unblocked work
  bd update <id> --claim --json      # Claim and start
  bd close <id> --reason "Implemented with refresh tokens" --json
  ```
  
  **Recover after compaction:** `bd list --status in_progress --json` then `bd show <id> --long`
  
  **Discover work mid-task:** `bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json`
  
  ## Advanced Features
  
  | Feature | CLI | Resource |
  |---------|-----|----------|
  | Molecules (templates) | `bd mol --help` | [MOLECULES.md](resources/MOLECULES.md) |
  | Chemistry (pour/wisp) | `bd pour`, `bd wisp` | [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) |
  | Agent beads | `bd agent --help` | [AGENTS.md](resources/AGENTS.md) |
  | Async gates | `bd gate --help` | [ASYNC_GATES.md](resources/ASYNC_GATES.md) |
  | Worktrees | `bd worktree --help` | [WORKTREES.md](resources/WORKTREES.md) |
  
  ## Resources
  
  | Category | Files |
  |----------|-------|
  | **Getting Started** | [BOUNDARIES.md](resources/BOUNDARIES.md), [CLI_REFERENCE.md](resources/CLI_REFERENCE.md), [WORKFLOWS.md](resources/WORKFLOWS.md) |
  | **Core Concepts** | [DEPENDENCIES.md](resources/DEPENDENCIES.md), [ISSUE_CREATION.md](resources/ISSUE_CREATION.md), [PATTERNS.md](resources/PATTERNS.md) |
  | **Resilience** | [RESUMABILITY.md](resources/RESUMABILITY.md), [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) |
  | **Advanced** | [MOLECULES.md](resources/MOLECULES.md), [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md), [AGENTS.md](resources/AGENTS.md), [ASYNC_GATES.md](resources/ASYNC_GATES.md), [WORKTREES.md](resources/WORKTREES.md) |
  | **Reference** | [STATIC_DATA.md](resources/STATIC_DATA.md), [INTEGRATION_PATTERNS.md](resources/INTEGRATION_PATTERNS.md) |
  
  ## Validation
  
  If `bd --version` reports newer than `0.60.0`, this skill may be stale. Run `bd prime` for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth ([ADR-0001](adr/0001-bd-prime-as-source-of-truth.md)).
  

• .claude/hooks/block-interactive-cmds.shhook
  Show content (1373 bytes)

  #!/bin/bash
  # Block cp/mv/rm without -f flag to prevent interactive prompt hangs.
  #
  # Problem: macOS shell profiles often alias cp/mv/rm with -i (interactive),
  # causing AI agents to hang indefinitely waiting for y/n input they can't
  # provide. Observed in multiple polecats during swarm operations.
  #
  # Solution: Block these commands unless -f flag or alias-bypass is present.
  # The agent can easily retry with -f added.
  
  COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)
  
  for cmd in cp mv rm; do
    # Match: cmd at word boundary, followed by space and arguments
    # Skip if: -f flag present, or using 'command' builtin / absolute path / backslash
    if echo "$COMMAND" | grep -qE "(^|[;&|] *)${cmd} " && \
       ! echo "$COMMAND" | grep -qE "(^|[;&|] *)${cmd} +-[a-eg-zA-Z]*f" && \
       ! echo "$COMMAND" | grep -qE "(command +${cmd}|/bin/${cmd}|/usr/bin/${cmd})" && \
       ! echo "$COMMAND" | grep -qE "(^|[;&|] *)\\\\${cmd} "; then
      jq -n --arg cmd "$cmd" '{
        hookSpecificOutput: {
          hookEventName: "PreToolUse",
          permissionDecision: "deny",
          permissionDecisionReason: ("BLOCKED: `" + $cmd + "` without `-f` flag may hang on interactive prompts (macOS often aliases `" + $cmd + "` to `" + $cmd + " -i`). Use `" + $cmd + " -f ...` instead, or prefix with `command " + $cmd + "` to bypass aliases.")
        }
      }'
      exit 0
    fi
  done
  
  exit 0
  

• .claude/hooks/block-gh-watch.shhook
  Show content (792 bytes)

  #!/bin/bash
  # Block commands that burn through GitHub API rate limits or violate workflow.
  # The GitHub API allows 5000 requests/hour. `gh run watch` polls every 3
  # seconds (1200 req/hr), and has repeatedly exhausted the quota during
  # releases, blocking all crew members for up to an hour.
  
  COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)
  
  if echo "$COMMAND" | grep -qE 'gh run watch|gh run list.*--watch'; then
    jq -n '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: "BLOCKED: gh run watch polls every 3s and burns through the 5000/hr GitHub API rate limit. Use `gh run view <run-id>` for a single status check, or `sleep 600 && gh run view <id>` to wait and check once."
      }
    }'
    exit 0
  fi
  
  exit 0
  

• .claude-plugin/marketplace.jsonmarketplace
  Show content (333 bytes)

  {
    "name": "beads-marketplace",
    "description": "Local marketplace for beads plugin development",
    "owner": {
      "name": "Steve Yegge"
    },
    "plugins": [
      {
        "name": "beads",
        "source": "./plugins/beads",
        "description": "AI-supervised issue tracker for coding workflows",
        "version": "1.0.3"
      }
    ]
  }
  

README

# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

# Optional: install richer instructions for your agent
bd setup codex    # Codex CLI - creates/updates AGENTS.md
bd setup claude   # Claude Code - installs hooks/settings
bd setup factory  # Factory.ai Droid - creates/updates AGENTS.md

This project uses bd (beads) for issue tracking.

- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
- Use `bd remember "insight"` for persistent project memory; do not create MEMORY.md files.
- Do not use markdown TODO lists for task tracking.

brew install beads           # macOS / Linux (recommended)
npm install -g @beads/bd     # Node.js users

bd init

bd init --server

# Set up a backup destination and push
bd backup init /path/to/backup
bd backup sync

# Restore into a new project (any mode)
bd init           # or bd init --server
bd backup restore --force /path/to/backup

# Initialize without git
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

# All core commands work with zero git calls
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"