How Loom works
Define your build and test commands in workflow YAML, validate the file, and run it locally. Loom records job and step results in linked runtime files that you can inspect when a command fails.
The flow
2
Run loom check to validate the workflow structure and write a validation receipt.
3
Run loom run --local to execute jobs on the host or in Docker containers and
record their results.
The pointer chain
For a run with runtime artifacts, read logs_dir from the receipt and open pipeline/manifest.json beneath it. Follow the job manifest's pointers to the selected event stream.
For a script failure, the pipeline manifest identifies the failing job and its manifest. The job manifest's failing_step_events_path points to the failed script entry's output. For a system failure, use the job manifest's section pointers. A pointer locates the evidence; diagnosing the cause can require reading the output or checking other inputs.
Configuration and setup errors can occur before these files exist. If Loom exits without a receipt, start with its terminal error. The diagnostics ladder covers both paths.
What you get back
logs_dir for locating runtime files.Indexes of jobs, steps, and system sections, with statuses and paths to their output.
Using the evidence
You and your agent can read the same artifacts. Manifests identify the files to inspect; command output can still require interpretation. File sizes depend on the workflow and its output.
To share a run, provide the receipt and relevant runtime files, with enough path context to resolve their links. Some paths are local or absolute, so a pathname alone is not a portable bundle. See what to share.