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
- Start a single tmux agent in a manager window.
- Use that agent to define steps and decide which additional agents to spawn.
- Spawn new panes for Claude/Codex/OpenCode in the same tmux session (manager window).
- Workers claim tasks in Beads and notify the manager via tmux.
- 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
dbmcco