reeds

Reeds

Autonomous multi-task development loops powered by Beads issue tracking and subagent isolation.

What is Reeds?

Reeds connects Beads (git-based issue tracker) with Claude's Task tool for autonomous task execution. It provides:

• Task Orchestration: Main agent queries Beads for ready tasks
• Subagent Isolation: Each task is implemented by a fresh subagent (no context pollution)
• Iteration Control: Own stop hook handles looping
• Dependency Awareness: Respects Beads' dependency system

Architecture

Main Agent (orchestrator)
  │
  ├─→ bd ready --limit 1 (get next task)
  │
  ├─→ bd show <task-id> (get details)
  │
  ├─→ Task tool → task-implementer agent
  │     │
  │     └─→ Implements task in isolated context
  │         Returns summary when done
  │
  ├─→ bd close <task-id> --reason "summary"
  │
  ├─→ Output: <promise>TASK COMPLETE: <id></promise>
  │
  └─→ Claude attempts to stop...
        │
        └─→ Stop Hook intercepts
              │
              ├─→ Parses transcript for promises
              ├─→ Increments iteration counter
              ├─→ Re-injects prompt: "Get next task"
              │
              └─→ Loop continues until REEDS COMPLETE

Prerequisites

• Claude Code CLI installed
• Beads initialized in your project (bd init)
• bd CLI available in PATH
• jq for JSON processing

Installation

cd ~/.claude/plugins
git clone https://github.com/rikdc/reeds

Restart Claude Code to load the plugin.

Usage

Start a Loop

/reeds:reeds-start [--max-iterations N]

This will:

1. Validate Beads is initialized
2. Show ready task count
3. Start the autonomous task loop

Options:

• --max-iterations N - Stop after N iterations (default: 30)

Check Status

/reeds:reeds-status

Shows Reeds loop state and Beads task statistics.

Cancel Loop

/reeds:reeds-cancel

Stops the autonomous loop by setting the state file to inactive.

How It Works

1. Setup: /reeds:reeds-start creates .claude/reeds-state.local.md with iteration tracking
2. Orchestration: Main agent runs bd ready to get tasks
3. Delegation: Each task is passed to the task-implementer subagent
4. Isolation: Subagent runs in clean context, implements task, returns summary
5. Closure: Main agent runs bd close with the summary
6. Iteration: Stop hook detects when Claude tries to stop, re-injects loop prompt
7. Completion: Loop ends when bd ready returns nothing

How Iteration Control Works

Reeds uses a promise protocol and a stop hook to maintain the autonomous loop across multiple agent turns.

Promise Markers

The orchestrator outputs special markers that the stop hook detects:

Marker	Meaning
<promise>TASK COMPLETE: <id></promise>	Current task finished, get next task
<promise>REEDS COMPLETE</promise>	No more tasks, terminate loop

Stop Hook Behavior

When Claude attempts to stop, the stop hook (scripts/stop-hook.sh) intercepts:

1. Parses the transcript for promise markers
2. If TASK COMPLETE: Clears current task, re-injects prompt to get next task
3. If REEDS COMPLETE: Sets state to inactive, allows exit
4. If neither: Re-injects prompt to continue current task
5. Increments iteration counter and checks against max

State Machine

┌─────────────┐
│  No Task    │◄───────────────────────────────┐
└──────┬──────┘                                │
       │ bd ready returns task                 │
       ▼                                       │
┌─────────────┐                                │
│ Implementing│──── TASK COMPLETE ────────────►│
└──────┬──────┘                                │
       │ bd ready returns nothing              │
       ▼                                       │
┌─────────────┐                                │
│   Complete  │ REEDS COMPLETE → exit          │
└─────────────┘

Example Workflow

# Initialize a project with Beads
cd my-project
bd init

# Create some tasks
bd create "Set up project structure" --priority 1
bd create "Implement core feature" --priority 2
bd create "Add tests" --priority 3

# Open in Claude Code
claude

# Start the autonomous loop
/reeds:reeds-start --max-iterations 20

Claude will work through each task using subagents, closing them as completed, until no ready tasks remain.

Skills

/prd-to-beads

Convert a PRD (Product Requirements Document) to Beads tasks:

/prd-to-beads path/to/prd.md

Creates an epic with child tasks for each user story, with proper dependencies.

Project Structure