Skip to main content

Why Loom

Loom lets you keep local build and test commands in a versioned workflow and inspect their execution results through state and event records. It may be useful when you want a CLI workflow runner whose output you can also read from scripts or an AI agent.

What you can use it for​

Run local workflows

  • Define build and test jobs in YAML
  • Validate the workflow before execution
  • Run commands on the host or in Docker
  • Declare cache paths and secret references

Inspect execution results

  • Read pipeline and job status from JSON
  • Match operation IDs to a failed command
  • Read contextual messages for provider failures
  • Share the files needed to investigate a run

Finding the relevant output​

Each recorded run has state.jsonl and events.jsonl under .loom/.runtime/runs/<run_id>/. Read loom logs <run_id> --state to identify a failed operation, then match its job, step and command IDs in loom logs <run_id> --json. MCP clients read the same files through loom_read_run and loom_read_events; event reads can filter by job_id or stream.

The output still needs interpretation. A test runner can report several failures in one command, and recording may not start for an early configuration failure. Use the terminal error when no run files exist. The diagnostics ladder covers both cases.

To hand off a run, share its run ID, relevant state records and a short reviewed event excerpt. File sizes depend on the workflow and its output. See what to share.

Limits to consider​

Loom is a CLI-first, evaluation-stage release. Alpha 1 runs locally with host and Docker-backed jobs on Linux; remote execution and shared runners are planned. Its contracts may change between releases.

Read the support boundary and check the relevant provider and workflow references before adopting a capability.

See it for yourself​

Run the Hello Loom example.

Run a small workflow, introduce a failure, and inspect the files Loom writes.