beads

tmux-beads-loops

Credit: This project is a fork of Beads by Steve Yegge (https://github.com/steveyegge/beads).

tmux-beads-loops is a tmux-first orchestration layer on top of Beads for multi-agent coding loops.

Purpose

Coordinate multiple coding agents in tmux panes with a shared task graph and isolated git worktrees.

What It Does

• Registers a manager pane, exports tmux-aware env vars, and routes worker notifications back to the manager.
• Adds a safe delegate helper for manager → worker commands (sends Enter and avoids self-targeting).
• Wraps spawned workers so startup bootstrap and finish notifications work for Codex/Claude/OpenCode consistently.
• Creates and cleans per-agent worktrees with predictable branch naming.
• Bootstraps Claude, Codex, and OpenCode sessions to share the same hook behavior.

Loop Flow

1. Start a single tmux agent in a manager window.
2. Use that agent to define steps and decide which additional agents to spawn.
3. Spawn new panes for Claude/Codex/OpenCode in the same tmux session (manager window).
4. Workers claim tasks in Beads and notify the manager via tmux.
5. Manager delegates to workers via delegate.sh (same tmux session).

Note: If you use clauded/codexd aliases, ensure they point to the CLI you expect.

Suggested commands (same session):

scripts/tmux-beads-loops/spawn-agent.sh claude
scripts/tmux-beads-loops/delegate.sh --window claude-1 -- "bd ready"

Pane defaults (aliases supported):

TMUX_BEADS_CLAUDE_CMD=clauded TMUX_BEADS_CODEX_CMD=codexd \
  scripts/tmux-beads-loops/spawn-agent.sh claude --split v --name claude-1

Auto-bootstrap (manager only):

TMUX_BEADS_BOOTSTRAP_TOTAL=4 \
TMUX_BEADS_CLAUDE_CMD=clauded TMUX_BEADS_CODEX_CMD=codexd \
codexd

Manual bootstrap:

scripts/tmux-beads-loops/bootstrap.sh --total 4

Note: tmux panes require splits, but this keeps everything in the same window (no new windows).

How It Works

• Uses tmux global options (like @beads_manager + @beads_manager_pane) to track the manager window + pane.
• Defaults to pane spawns; set --mode window if you prefer new windows.
• Uses per-agent git worktrees and disables the beads daemon for safety (BEADS_NO_DAEMON=1).
• Tracks tasks with the bd CLI, optionally on a dedicated metadata branch.

Works With

tmux, git worktrees, Beads (bd), Claude CLI, Codex CLI, and OpenCode (via wrapper).

Value

Durable task coordination, fewer context handoff mistakes, and a predictable manager/worker loop.

Status

Beta at best. Scripts and hooks may change; review before use and avoid critical production workflows.

Docs

See docs/TMUX_BEADS_LOOPS.md for the tmux workflow, hooks, and scripts.

Below is the upstream Beads README for reference.

bd - Beads

Distributed, git-backed graph issue tracker for AI agents.

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

⚡ Quick Start

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

# Initialize (Humans run this once)
bd init

# Tell your agent
echo "Use 'bd' for task tracking" >> AGENTS.md

🛠 Features

• Git as Database: Issues stored as JSONL in .beads/. Versioned, branched, and merged like code.
• Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
• Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.
• Invisible Infrastructure: SQLite local cache for speed; background daemon for auto-sync.
• Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.

📖 Essential Commands

Command	Action
bd ready	List tasks with no open blockers.
bd create "Title" -p 0	Create a P0 task.
bd dep add <child> <parent>	Link tasks (blocks, related, parent-child).
bd show <id>	View task details and audit trail.

🔗 Hierarchy & Workflow

Beads supports hierarchical IDs for epics:

• bd-a3f8 (Epic)
• bd-a3f8.1 (Task)
• bd-a3f8.1.1 (Sub-task)

Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects.

📦 Installation