Loom

Loom is an agent orchestration system for Claude Code. It coordinates AI agent sessions across git worktrees, enabling parallel task execution with automatic crash recovery and context handoffs. When context runs low, agents externalize their state and signal fresh sessions to continue seamlessly.

The Problem

AI agent sessions hit hard limits:

• Context exhaustion - Long tasks exceed the context window
• Lost state - Work-in-progress vanishes when sessions end
• Manual handoffs - Resuming requires re-explaining context and decisions
• No coordination - Multiple agents cannot easily pass work between each other

The Solution

Loom solves these problems with three integrated components:

Together, they implement the Signal Principle: "If you have a signal, answer it." Agents check for pending signals on startup and resume work automatically.

Quick Start

# Install
curl -fsSL https://raw.githubusercontent.com/cosmix/loom/main/install.sh | bash

# Initialize and run
cd /path/to/project
loom init doc/plans/my-plan.md   # Initialize with a plan
loom run                          # Start daemon and execute stages
loom status                       # Live dashboard (Ctrl+C to exit)
loom stop                         # Stop the daemon

Loom creates git worktrees for parallel stages and spawns Claude Code sessions in terminal windows automatically.

Core Concepts

The Signal Principle

On every session start, agents:

1. Check .work/signals/ for pending work matching their role
2. If a signal exists, load context and execute immediately
3. If no signal, ask the user what to do

This creates continuity across sessions without manual intervention.

Context Management

Agents monitor context usage and create handoffs before hitting limits:

Stages can customize their budget via context_budget (1-100%, default: 65%).

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        loom run                             │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│              Daemon Process (background)                    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Unix Socket - CLI connections, live updates        │    │
│  └─────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Orchestrator Loop (every 5s)                       │    │
│  │  - Poll stage/session files                         │    │
│  │  - Start ready stages in terminal windows           │    │
│  │  - Detect crashed sessions, generate handoffs       │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
      ┌─────────┐    ┌─────────┐    ┌─────────┐
      │ Terminal│    │ Terminal│    │ Terminal│
      │ stage-1 │    │ stage-2 │    │ stage-3 │
      └─────────┘    └─────────┘    └─────────┘

State Directory

All state lives in .work/ as structured files:

project/
├── .work/                    # Loom state (version controlled)
│   ├── config.toml           # Active plan, settings
│   ├── stages/               # Stage state files
│   ├── sessions/             # Session tracking
│   ├── signals/              # Agent assignments
│   └── handoffs/             # Context dumps
├── .worktrees/               # Git worktrees for parallel stages
└── doc/plans/                # Plan documents

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/cosmix/loom/m

...