Loom Developer & User Guide

> ALL AGENTS: READ THIS SECTION FIRST. > This document is the authoritative reference for debugging, observability, > and system introspection in Loom. Every agent — regardless of role — MUST > use the tools and workflows described below when diagnosing issues, verifying > work, or monitoring system health. Do NOT guess at system state; query it.

The single fastest way to understand system state: `bash loomctl status # health + agents + beads + providers in one call loomctl log recent # last 20 log entries from the DB (dispatcher, actionloop, actions) loomctl analytics velocity # commit/push/build/test funnel — are changes flowing? `

` Is the system healthy? └─ loomctl status → check health.status, providers.healthy, agents.working Are agents executing work? └─ loomctl log recent → look for [actionloop] "Iteration N/M" entries └─ loomctl analytics stats → check total_requests and tokens_by_user Are commits being created? └─ loomctl analytics velocity → commits_attempted, pushes_attempted └─ docker compose logs loom | grep "Auto-checkpoint\|Auto-push" Is dispatch working? └─ loomctl log recent → look for [dispatcher] entries └─ Key skip reasons: already_inflight, already_run, cooldown_after_failure What is a specific agent doing? └─ loomctl agent show <agent-id> └─ DB query: SELECT * FROM logs WHERE agent_id='<id>' ORDER BY timestamp DESC LIMIT 20; What happened to a specific bead? └─ loomctl bead show <bead-id> └─ DB query: SELECT * FROM logs WHERE bead_id='<id>' ORDER BY timestamp DESC LIMIT 20; `

| Command | Subcommands | Purpose | |---------|------------|---------| | loomctl status | — | Aggregated health, agents, beads, providers | | loomctl agent | list, show | Agent state and details | | loomctl bead | list, show, create, update, delete, claim, poke | Bead CRUD and redispatch | | loomctl project | list, show | Project listing | | loomctl provider | list, show, register, delete | Provider management | | loomctl log | recent, stream, export | DB-stored logs (dispatcher, actionloop, actions) | | loomctl metrics | cache, events, patterns, prometheus | Observability metrics | | loomctl analytics | stats, costs, velocity, logs, export | Cost, token, and velocity tracking | | loomctl event | list, activity, stream | Event bus history and live SSE | | loomctl conversation | list, show | Agent conversation sessions (requires project_id via API) | | loomctl workflow | list, show, start, executions, analytics | Workflow management and analytics | | loomctl config | show, export | Server configuration | | loomctl export | — | Full database export to JSON | | loomctl import | — | Database import from JSON |