Skip to main content

How Loom works

Define your build and test commands in workflow YAML, validate the file, and run it locally. Loom records job, step and command results in two JSONL files that you can inspect when a command fails.

The flow​

1
AuthorDefine jobs and scripts in YAML. Use includes and templates when you need to share configuration.

2

Validate

Run loom check to validate the workflow structure and write a validation receipt.

3

Execute

Run loom run --local to execute jobs on the host or in Docker containers and record their results.

4
DiagnoseRead state records, then match the failed operation's IDs in event messages.

Read state, then events​

Each recorded run writes state.jsonl and events.jsonl beneath .loom/.runtime/runs/<run_id>/. Use the ID printed by loom run:

loom logs <run_id> --state
loom logs <run_id> --json

Find the failed operation in state, then match its context IDs in event messages. Provider preparation can fail before a command starts, so its diagnostic may have only a job ID. MCP clients can use loom_read_run and loom_read_events, with job_id and stream filters for messages.

Configuration errors can prevent recording from starting. If no run files were created, use the terminal error. See the diagnostics ladder.

What you get back​

State recordsWorkflow, job, step and command transitions in state.jsonl.
Event records

Contextual messages and stdout/stderr in events.jsonl, with timestamps and IDs.

Declared artifactsConfigured output files stored separately beneath .loom/.runtime/artifacts/.

Using the evidence​

You and your agent read the same two recording files. IDs connect state to event messages; command output still requires interpretation. File sizes depend on the workflow and its output.

To share a run, provide its ID, relevant state records and a short reviewed event excerpt. See what to share.