Skip to content
2AMLogicPublic

About

Agent Orchestration

Resources

Contributing

Security policy

Stars

13 stars

Watchers

0 watching

Forks

Latest commit

 

History

15,739 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Loom

codecov GitHub Release

AI-powered development orchestration using your forge as the coordination layer.

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

What Loom optimizes for — and when it's the wrong tool. Loom is tuned for unattended correctness over long horizons: code you can leave running overnight and still trust in the morning. Its gates (Curator, Judge, Doctor, merge-risk holds, buildGate) buy that guarantee at the cost of latency.

If you need to ship in hours with a human watching continuously, Loom is the wrong tool. Work in live agent sessions instead of dispatching sweeps, write fewer tests, merge without a review round-trip, and patch symptoms rather than root causes. See Latency vs. Reliability for why that recipe is right there and wrong everywhere else.

Supported Forges: GitHub | Gitea — Loom auto-detects your forge from the git remote URL. A forge abstraction layer — defaults/scripts/lib/forge-helpers.sh for shell scripts, plus the Rust loom-daemon/src/forge_*.rs modules for the daemon — makes the workflow identical regardless of forge.

Quick Start

Loom's operating modes distinguish fleet operation, an isolated local daemon, and operator-directed sessions. That document records the intended support contract, current gaps in running without a daemon installed, and the planned separation of CLI tools from the work engine.

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

# Start autonomous development on a single issue from Claude Code
cd /path/to/your/repo
# In Claude Code:
/loom:sweep 42

For multiple issues in one session, pass them all to sweep:

# In Claude Code:
/loom:sweep 42 43 44          # waves of parallel builders
/loom:sweep all               # the whole open backlog

For continuous multi-account batches, run the loom-daemon (Tier 2) and enqueue with mcp__loom__dispatch_sweep — one detached, token-rotated sweep per issue.

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                    Human (Tier 3)                               │
│  Write issues, review PRs, merge what you approve               │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────┐
│        Tier 2: loom-daemon + GitHub Actions cron                │
│  loom-daemon dispatches per-issue sweeps (mcp__loom__*)         │
│  .github/workflows/loom-*.yml runs support roles on cron        │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────┐
│        Tier 1: /loom:sweep <issue>                              │
│  Single-issue lifecycle: Curator → Builder → Judge → Doctor →   │
│  Merge. Checkpoints survive crashes.                            │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────┐
│                    Workers (Tier 0)                             │
│  /loom:builder, /loom:judge, /loom:curator, /loom: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.

Loom State Machine

Loom coordinates its agents entirely through labels. The full label graph below — four lanes (issue, PR, proposal, epic supervisor), the role that fires each edge, and the epic fork-join barriers — is hand-maintained documentation kept in sync with the code by reviewers, not regenerated from a model.

The epic-supervisor lane is the one lane with a Rust implementation: loom-daemon/src/epic_state.rs's epic_transition_table() is authoritative for its five states and five edges, and loom-daemon/tests/epic_state_invariants.rs asserts its structural invariants directly (state count, sole terminal state, edge count, barrier hygiene). The five epic:* states are derived — they all ride the single loom:epic label and are computed by the daemon-native epic supervisor, so no new labels are minted. Edges marked "creates issues" are the ones the #3707 issue-filing mutex must serialize.

stateDiagram-v2
    state "Issue lane" as lane_issue {
        s_new : new
        s_loom_triage : loom:triage
        s_loom_curating : loom:curating
        s_loom_curated : loom:curated
        s_loom_issue : loom:issue
        s_loom_building : loom:building
        s_closed : closed
    }
    state "PR lane" as lane_pr {
        s_loom_review_requested : loom:review-requested
        s_loom_changes_requested : loom:changes-requested
        s_loom_pr : loom:pr
        s_merged : merged
    }
    state "Proposal lane" as lane_proposal {
        s_loom_architect : loom:architect
        s_loom_hermit : loom:hermit
        s_loom_auditor : loom:auditor
    }
    state "Epic supervisor lane (derived — loom:epic)" as lane_epic {
        s_epic_needs_decomp : epic:needs_decomp
        s_epic_designed : epic:designed
        s_epic_active : epic:active
        s_epic_phase_join : epic:phase_join
        s_epic_done : epic:done
    }
    [*] --> s_new
    s_new --> s_loom_triage : Human
    s_loom_triage --> s_loom_curating : Curator
    s_loom_curating --> s_loom_curated : Curator
    s_loom_curated --> s_loom_issue : Human
    s_loom_issue --> s_loom_building : Builder
    s_loom_building --> s_loom_review_requested : Builder
    s_loom_building --> s_closed : Champion
    s_loom_review_requested --> s_loom_pr : Judge
    s_loom_review_requested --> s_loom_changes_requested : Judge
    s_loom_changes_requested --> s_loom_review_requested : Doctor
    s_loom_pr --> s_merged : Champion
    s_new --> s_loom_architect : Architect · creates issues
    s_new --> s_loom_hermit : Hermit · creates issues
    s_new --> s_loom_auditor : Auditor · creates issues
    s_loom_architect --> s_loom_issue : Champion
    s_loom_architect --> s_closed : Champion
    s_loom_hermit --> s_loom_issue : Champion
    s_loom_hermit --> s_closed : Champion
    s_loom_auditor --> s_loom_issue : Champion
    s_loom_auditor --> s_closed : Champion
    s_new --> s_epic_needs_decomp : Architect
    s_epic_needs_decomp --> s_epic_designed : Champion · creates issues
    s_epic_designed --> s_epic_active : Champion
    s_epic_active --> s_epic_phase_join : Supervisor · barrier: fork-join: current phase complete
    s_epic_phase_join --> s_epic_active : Supervisor · barrier: advance: dispatch next phase
    s_epic_phase_join --> s_epic_done : Supervisor · barrier: join: all phases complete
    s_closed --> [*]
    s_merged --> [*]
    s_epic_done --> [*]
Loading

Features

Autonomous Orchestration

  • Rust loom-daemon DispatchSweep 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 /loom:judge
  • PR conflict resolution with /loom:doctor
  • Main branch validation with /loom:auditor

Forge-Agnostic

  • Works with GitHub and Gitea out of the box
  • Auto-detects forge from git remote URL
  • Forge abstraction layer (forge-helpers.sh + loom-daemon/src/forge_*.rs)
  • Forge-neutral caching layer for API efficiency

Developer Experience

  • Git worktree isolation per issue
  • Simple slash command: /loom:sweep 42 runs a single issue end-to-end
  • MCP integration for programmatic control (22 tools)
  • Crash-safe checkpoints: restart /loom:sweep N to resume from the last completed phase

Forge Support

Loom's forge abstraction layer — defaults/scripts/lib/forge-helpers.sh plus the Rust loom-daemon/src/forge_listing.rs, forge_cached_list.rs, forge_parser.rs, and forge_cmd.rs modules — provides a unified interface across forges. All orchestration features — label-driven workflows, issue claiming, PR review, auto-merge — work identically on both platforms.

Feature GitHub Gitea
Label-based workflow Yes Yes
Issue/PR operations Yes Yes
CI status checks Yes Yes (Actions API + commit status)
Auto-merge Yes (merge queue) Yes (poll-and-merge fallback)
Branch protection Yes Yes
Authentication gh auth login or GH_TOKEN GITEA_TOKEN or FORGE_TOKEN
Forge detection Automatic from remote URL Automatic from remote URL

See Forge Authentication for setup details.

Installation

Requirements

  • macOS or Linux. Every release publishes loom-daemon binaries for aarch64-apple-darwin, x86_64-unknown-linux-gnu, and aarch64-unknown-linux-gnu, plus a multi-arch ghcr.io/rjwalters/loom-worker image — macOS is the primary development platform, Linux is the primary fleet-worker platform.
  • Git repository
  • tmux (brew install tmux)
  • bash >= 4 (brew install bash on macOS; stock macOS ships 3.2)
  • Claude Code for AI agents

Install Options

Interactive installer:

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

Direct initialization (loom-daemon as an installed/built binary on your PATH — note loom-daemon/ in this repo is the crate directory, not an executable, so there is no ./loom-daemon to run):

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

What Gets Installed

your-repo/
├── .loom/
│   ├── config.json      # Terminal configuration
│   ├── config/          # Additional config data (e.g. skill-routes.json)
│   ├── roles/           # Agent role definitions
│   ├── runtimes/        # Runtime adapter manifests
│   ├── scripts/         # Helper scripts
│   ├── hooks/           # Guard hooks (PreToolUse)
│   ├── docs/            # Reference documentation
│   └── bin/             # CLI entry point (loom)
├── .claude/commands/loom/  # Slash commands
├── .github/labels.yml   # Workflow labels
└── CLAUDE.md            # AI context document

The installer also makes user-level changes outside your repo (--dry-run lists them):

  • the loom-daemon binary in ~/.local/bin (override with LOOM_DAEMON_BIN_DIR), keeping the previous one as loom-daemon.previous
  • a mirror of the defaults payload in ~/.local/share/loom-daemon/defaults (override with LOOM_DAEMON_DEFAULTS_DIR)
  • user-scope guard hooks in ~/.claude/settings.json, after a settings.json.loom-backup-<timestamp> backup

Usage

Single-Issue Mode

To orchestrate one issue end-to-end from inside Claude Code:

/loom:sweep 42          # Curator → Builder → Judge → Doctor → Merge
/loom:sweep --prs 123   # PR-set mode: Judge / Doctor → Judge / Merge from an open-PR set

From a script:

claude -p "/loom:sweep 42" --dangerously-skip-permissions

For a full Builder-through-Merge lifecycle from an interactive Codex parent session, launch Codex explicitly with:

codex --dangerously-bypass-approvals-and-sandbox

Warning: this flag disables both Codex approval prompts and the Codex sandbox. Use it only in an environment where you accept that trust boundary for Loom's network, git, worktree, daemon-socket, and process operations.

For non-mutating Curator or Judge investigation, use a read-only session instead:

codex --sandbox read-only --ask-for-approval never

The read-only posture cannot claim issues, edit labels, build in worktrees, create PRs, or merge; restart Codex with the full-lifecycle posture before performing those operations. These flags configure only the interactive parent session. They do not configure Codex workers dispatched by loom-daemon; that policy is tracked in #4478. See the Codex guardrail-parity document for the runtime trust-boundary comparison.

Sweep is self-contained — there is no separate daemon to start. Checkpoints under .loom/sweep-checkpoint/ survive crashes; restarting the sweep resumes from the last completed phase.

Multi-Issue Mode (loom-daemon, Tier 2)

For autonomous multi-account batches, run the Rust loom-daemon and enqueue sweeps against it from any Claude Code session:

mcp__loom__dispatch_sweep    # detach one token-rotated sweep per issue
mcp__loom__list_sweeps       # inspect running sweeps
mcp__loom__cancel_sweep      # cancel a running sweep

Each dispatched sweep runs in its own detached process and picks its own OAuth token via spawn-claude.sh for multi-account rotation. By default the daemon is not a work generator — work arrives only via dispatch_sweep and the cron workflows. Three opt-in, default-off subsystems let it generate its own work when enabled: the autonomous work finder, the epic supervisor, and the role runner. Periodic support roles run either through that daemon-native role runner (autonomous.roleRunner.enabled=true, preferred — same rotated token pool as sweeps) or through the GitHub Actions cron workflows for Champion / Curator / Judge / Auditor / Guide (opt-in per workflow, single static key, no rotation). See .loom/docs/daemon-reference.md for the full MCP surface and the autonomous config block.

The legacy spawn-loop.sh was removed in v0.11.0 — use loom-daemon + mcp__loom__dispatch_sweep instead. See the migration guide.

Individual Agent Commands

Run worker agents directly (no daemon required):

/loom:builder 42        # Implement issue 42
/loom:judge 123         # Review PR #123
/loom:curator 42        # Enhance issue with technical details
/loom: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
ADR Index Architecture decision records
Roadmap Where the project stands and what comes next
MCP Tools Programmatic control interface

Repository Layout

Directory Contents
mcp-loom/ Unified Loom MCP server for Claude Code integration
2AMLogic/loom-ui Fleet observability backend (Cloudflare Workers) and web dashboard (moved out of this repo)
loom-api/ REST API server for external access to Loom analytics data
examples/ Example Loom workspace configurations
quickstarts/ Pre-configured project templates for common use cases
docker/ loom-worker pinned base image for fleet workers

Agent Roles

Role Purpose Mode
/loom:sweep Single-issue lifecycle orchestration (Curator → Merge) Per-issue
loom-daemon + mcp__loom__dispatch_sweep Multi-issue detached dispatch (Tier 2) Continuous, opt-in
/loom:builder Implement features and fixes Manual
/loom:judge Review pull requests Cron via GH Actions
/loom:curator Enhance and organize issues Cron via GH Actions
/loom:architect Create architectural proposals Manual (cadence #3381)
/loom:hermit Identify simplification opportunities Manual (cadence #3381)
/loom:doctor Fix PR feedback and conflicts Manual
/loom:champion Evaluate proposals, auto-merge PRs Cron via GH Actions
/loom:guide Triage the issue queue (tier labels, unblocking, WORK_PLAN) Cron via GH Actions
/loom:auditor Validate main branch builds Cron via GH Actions
/loom:driver Plain shell environment — no autonomous role behavior Manual

Development

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

# Run the daemon in dev mode
./scripts/dev-daemon.sh

# Run tests
cargo test --workspace

# Build release daemon
cargo build --package loom-daemon --release

See DEVELOPMENT.md for complete guidelines.

Releasing

Releases are driven by /repo:release — install repo for the release command. It runs the full methodology (pre-flight/CI gate, CHANGELOG completeness and version-drift gates, semver decision, tag, GitHub Release) and detects and honors Loom's bundled scripts/version.sh as its first-priority version tool:

./scripts/version.sh bump patch --tag   # underlying mechanics; /repo:release orchestrates these
git push origin main --tags
gh release create vX.Y.Z --title "vX.Y.Z" --notes "Release notes..."

You rarely need to cut a release by hand. .github/workflows/release.yml releases a green main commit automatically (a workflow_run on CI; the tag is created at the commit CI tested), and a hand-created Release triggers the same workflow. VERSION itself is bumped by version-bump-on-merge.yml at most once per RELEASE_MIN_INTERVAL (default 24 h), so published releases lag unreleased main and not every version gets a tag; see .loom/docs/release-cadence.md. Release notes are generated by GitHub; CHANGELOG.md is kept as the historical record.

The workflow cross-builds loom-daemon for aarch64-apple-darwin, x86_64-unknown-linux-gnu, and aarch64-unknown-linux-gnu, and uploads each platform's binary plus a .sha256 checksum file as Release assets. Linux artifacts get a keyless cosign signature (.sig + .pem); the macOS artifact is Developer ID codesigned only when the signing secrets are configured (the workflow skips signing loudly otherwise). loom-daemon-update.sh verifies integrity on install. A signature identifies the build; it is not evidence that the code was reviewed or is safe to roll to a fleet. Each platform builds in its own CI job, so one platform failing to build never silently drops that platform's artifact from an otherwise-"successful" run.

Bootstrap New Projects

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

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

Built with Loom

If your project was built with Loom, you can add a badge to your README:

Built with Loom

[![Built with Loom](https://img.shields.io/badge/Built_with-Loom-blue?logo=github)](https://github.com/rjwalters/loom)

License

MIT License © 2025 Robb Walters

About

Agent Orchestration

Resources

Contributing

Security policy

Stars

13 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages