grafana

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

Loom solves these problems with three integrated components:

| Component | Purpose |

| ------------ | ------------------------------------------------ |

| loom CLI | Manages persistent work state across sessions |

| Agents | 4 specialized AI agents (2 Opus, 2 Sonnet) |

| Skills | Reusable knowledge modules loaded dynamically |

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

```bash

# 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.

| Concept | Description |

| ------------ | -------------------------------------------------- |

| Plan | Parent container for stages, lives in doc/plans/ |

| Stage | A unit of work within a plan, with dependencies |

| Session | A Claude Code instance executing a stage |

| Worktree | Git worktree for parallel stage isolation |

| Handoff | Context dump when session exhausts context |

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:

| Level | Usage | Action |

| ------ | ------ | ------------------------------- |

| Green | < 50% | Normal operation |

| Yellow | 50-64% | Prepare handoff soon |

| Red | >= 65% | Create handoff, start fresh |

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

```text

┌─────────────────────────────────────────────────────────────┐

│ 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 │ │

│ └─────────────────────────────────────────────────────┘ │

└──────────────