Loom

AI-powered development orchestration using GitHub as the coordination layer.

Loom spawns AI agents that claim issues, implement features, review PRs, and merge code—all coordinated through GitHub labels. Your only job: write issues, review PRs, merge what you like.

Quick Start

# Clone and install to your repository
git clone https://github.com/rjwalters/loom
cd loom
./install.sh /path/to/your/repo

# Start autonomous development
cd /path/to/your/repo
/loom

Or download Loom.app for the GUI.

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                    Human (Layer 3)                              │
│  Write issues, review PRs, merge what you approve               │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────┐
│                    Loom Daemon (Layer 2)                        │
│  /loom - Monitors pipeline, spawns shepherds, generates work    │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────┐
│                    Shepherds (Layer 1)                          │
│  /shepherd <issue> - Orchestrates: Curator → Builder → Judge    │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────┐
│                    Workers (Layer 0)                            │
│  /builder, /judge, /curator, /doctor - Execute single tasks     │
└─────────────────────────────────────────────────────────────────┘

Label-driven workflow:

• loom:issue → Ready for implementation
• loom:building → Being worked on
• loom:review-requested → PR ready for review
• loom:pr → Approved, ready to merge

See WORKFLOWS.md for complete label documentation.

Features

Autonomous Orchestration

• Signal-based shepherd IPC for deterministic, reliable execution
• Stuck agent detection with automatic kill-and-retry recovery
• Rate limit resilience with exponential backoff
• Activity-based completion detection

Quality Gates

• Acceptance criteria verification before PR creation
• Automated code review with /judge
• PR conflict resolution with /doctor
• Main branch validation with /auditor

Developer Experience

• Git worktree isolation per issue
• Simple CLI: /shepherd 42 monitors a single issue end-to-end via the daemon
• MCP integration for programmatic control (19 tools)
• Graceful shutdown: touch .loom/stop-daemon

Installation

Requirements

• macOS (Linux support planned)
• Git repository
• tmux (brew install tmux)
• Claude Code for AI agents

Install Options

Interactive installer:

./install.sh /path/to/your/repo

Direct initialization:

./loom-daemon init /path/to/your/repo

GUI application: Download from Releases

What Gets Installed

your-repo/
├── .loom/
│   ├── config.json      # Terminal configuration
│   ├── roles/           # Agent role definitions
│   └── scripts/         # Helper scripts
├── .claude/commands/    # Slash commands
├── .github/labels.yml   # Workflow labels
└── CLAUDE.md            # AI context document

Usage

Daemon Mode (Fully Autonomous)

/loom              # Start continuous orchestration
/loom --force      # Aggressive mode (auto-promotes proposals)

The daemon monitors your pipeline, spawns shepherds for ready issues, and triggers support roles (architect, hermit, auditor) on schedule.

Single-Issue Mode

To orchestrate one issue end-to-end, start the daemon first, then use /shepherd:

# In a terminal outside Claude Code
./.loom/scripts/start-daemon.sh

# Then in Claude Code
/shepherd 42         # Orchestrate issue through full lifecycle
/shepherd 42 --merge # Same, but auto-merge after Judge approves

/shepherd writes a signal to the daemon and then monitors progress — it requires the daemon to be running.

Individual Agent Commands

Run worker agents directly (no daemon required):

/builder 42        # Implement issue 42
/judge 123         # Review PR #123
/curator 42        # Enhance issue with technical details
/doctor 123        # Fix PR feedback or conflicts

Worktree Workflow

# Create isolated worktree for issue
./.loom/scripts/worktree.sh 42
cd .loom/worktrees/issue-42

# Work, commit, push
git push -u origin feature/issue-42
gh pr create --label "loom:review-requested"

Documentation

| Guide | Description | |-------|-------------| | Quickstart Tutorial | 10-minute hands-on walkthrough | | CLI Reference | Full command documentation | | Troubleshooting | Debug common issues | | WORKFLOWS.md | Label-based coordination | | DEVELOPMENT.md | Contributing to Loom |

Architecture

| Document | Description | |----------|-------------| | System Overview | Architecture and data flow | | ADR Index | Architecture decision records | | MCP Tools | Programmatic control interface |

Agent Roles

| Role | Purpose | Mode | |------|---------|------| | /loom | System orchestration, work generation | Continuous daemon | | /shepherd | Issue lifecycle orchestration (requires daemon) | Per-issue | | /builder | Implement features and fixes | Manual | | /judge | Review pull requests | Autonomous | | /curator | Enhance and organize issues | Autonomous | | /architect | Create architectural proposals | Autonomous | | /hermit | Identify simplification opportunities | Autonomous | | /doctor | Fix PR feedback and conflicts | Manual | | /champion | Evaluate proposals, auto-merge PRs | Autonomous | | /auditor | Validate main branch builds | Autonomous |

Development

# Clone and setup
git clone https://github.com/rjwalters/loom
cd loom
pnpm install

# Run development server
pnpm app:dev

# Run tests
cargo test --workspace

# Build release
pnpm app:build

See DEVELOPMENT.md for complete guidelines.

Bootstrap New Projects

# In the Loom repository
/imagine a CLI tool for managing dotfiles

Creates a new GitHub repo with Loom pre-installed and initial roadmap.

License

MIT License © 2025 Robb Walters