Skip to main content

What is Loom

Loom is an open-source workflow engine for running build and test jobs locally. You define the jobs in YAML and run them on the host or in Docker containers.

Loom records execution results in receipts, manifests, and event streams. These files connect a run to its jobs, script entries, and system sections, so you or an AI agent can locate the output for a failed part of the run.

How Loom works​

1
Author

Define stages, jobs, scripts, caching, and secrets in workflow YAML.

2
Validate

loom check validates the workflow structure before execution.

3
Run

loom run --local executes your workflow and writes structured artifacts.

4
Diagnose

Open the job or step output linked from the runtime manifests.

How the diagnostic files connect​

A run receipt's logs_dir locates the runtime directory. Open pipeline/manifest.json there to find the job manifests; each job manifest links to script-step and system-section event streams.

The pointers identify where to investigate; the output still needs interpretation. A failed test command, for example, can report several test failures in one script entry. Setup errors can also occur before the runtime artifacts exist, in which case you start with the terminal error.

The artifact layout follows a documented structure. Run IDs, timestamps, durations, paths, and command output vary between runs. Receipts and event streams can grow with the workflow and its output. See the runtime logs contract for the fields and path rules.

Inspecting and sharing results​

For you

  • Follow the receipt and manifests to the failed script entry or system section.

  • Share the receipt, relevant runtime files, and path context so a teammate can inspect the same run.

  • Re-run after a change and check the exit status and output to see whether it fixed the failure.

For your agent

  • Read JSON manifests to select the job and step output to inspect.

  • Retrieve the selected event stream or an excerpt. The amount of context needed depends on the failure.

  • Use the paths recorded for this run and the documented artifact schema.
Alpha 1

Loom is an evaluation-stage release. It runs locally with host and Docker-backed jobs on Linux. Contracts may change between releases. Remote execution, broader platform targets, and shared runners are planned. Check the support boundary for what Alpha 1 does and does not promise.

Get started​