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:
- Validate Beads is initialized
- Show ready task count
- 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
- Setup:
/reeds:reeds-start creates .claude/reeds-state.local.md with iteration tracking
- Orchestration: Main agent runs
bd ready to get tasks
- Delegation: Each task is passed to the
task-implementer subagent
- Isolation: Subagent runs in clean context, implements task, returns summary
- Closure: Main agent runs
bd close with the summary
- Iteration: Stop hook detects when Claude tries to stop, re-injects loop prompt
- 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:
- Parses the transcript for promise markers
- If TASK COMPLETE: Clears current task, re-injects prompt to get next task
- If REEDS COMPLETE: Sets state to inactive, allows exit
- If neither: Re-injects prompt to continue current task
- 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