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 state.jsonl and events.jsonl. Context IDs connect a run to its jobs, steps and commands so you or an AI agent can identify a failed operation and its output.

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

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

How the diagnostic files connect​

The printed run ID selects .loom/.runtime/runs/<run_id>/. Its state.jsonl contains lifecycle transitions; events.jsonl contains contextual messages and stdout/stderr.

Read loom logs <run_id> --state, then loom logs <run_id> --json. MCP clients use loom_read_run and loom_read_events, with exact job_id and stream filters for messages. Command output can require interpretation: one test command can report several failures. If recording could not start, use the terminal error.

Run IDs, timestamps, paths and output vary between runs. Both files can grow with the workflow and its output. Declared artifacts are retained separately under .loom/.runtime/artifacts/<run_id>/jobs/<job-id>/. See Runtime logs for the fields and path rules.

Inspecting and sharing results​

For you

  • Find the failed state and match its operation IDs in event messages.

  • Share the run ID, relevant state records and a short reviewed event excerpt so a teammate can investigate 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 JSONL state records to identify the operation to inspect.

  • Use MCP event filters to select a job or stream. The amount of context needed depends on the failure.

  • Use the run ID and documented state and event fields.
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​