loom CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

⚠️ KNOWLEDGE-FIRST: Your Knowledge Brief already quotes what retrieval judged relevant. Pull more with loom knowledge context --query. Open a file under doc/loom/knowledge/ only when a pull comes back empty; then read the tier-1 summary for the area, and only the tier-2 topics you touch.

Project Overview

Loom is a self-propelling agent orchestration CLI written in Rust. It coordinates Claude Code sessions across git worktrees, enabling parallel task execution with automatic crash recovery and context handoffs.

This is an unreleased project under active development NO BACKWARDS COMPATIBILTY OR MIGRATION ROUTINES SHOULD BE ADDED AT THIS STAGE.

Build Commands

cd loom
cargo build                    # Development build
cargo build --release          # Release build
cargo test                     # Run all tests
cargo test stage_transitions   # Run single test file
cargo test --test e2e          # Run end-to-end tests
cargo clippy -- -D warnings    # Lint with warnings as errors
cargo fmt --check              # Check formatting

Tests use serial_test for isolation - many tests cannot run in parallel.

Architecture

Source Layout (loom/src/)

main.rs              CLI entry point (clap-based command definitions)
lib.rs               Module exports

commands/            Command implementations (init, run, status, stage, etc.)
daemon/              Unix socket server for IPC (protocol.rs, server.rs)
orchestrator/
  core/              Main orchestrator loop and state machine
  terminal/          Terminal window spawning abstraction
  monitor/           Session health monitoring and context tracking
  signals/           Signal generation for agent communication
  auto_merge.rs      Git merge automation
  retry.rs           Failure retry with backoff
models/
  stage/             Stage state machine (types.rs, transitions.rs)
  session/           Session lifecycle tracking
plan/
  parser.rs          Markdown plan document parser
  schema/            YAML metadata validation
  graph/             Execution DAG building
fs/                  File operations for the .loom/work/ state directory
git/                 Git operations (worktrees, branches, merges)
verify/              Acceptance criteria execution