Agent integration
Agents read state.jsonl to identify a failed workflow, job, step or command, then match its IDs in events.jsonl. Use loom_list_runs to discover recorded runs and choose an exact run ID. MCP loom_read_run returns ordered states; loom_read_events supports exact job_id and stream filters, plus all: true for complete matches or tail and max_lines for smaller excerpts. Both tools read the same files as loom logs.
This guide sets up the full agent integration stack: CLI, MCP server, Cursor skill, and a starter prompt for creating and validating a workflow.
What you'll set up
Install the CLI and MCP server
Follow the canonical release-install procedure. Choose an immutable release version and its matching reviewed installer revision. Do not fetch the installer from main, omit the version, or pass latest.
This installs both loom (CLI) and loom-mcp (MCP server) to ~/.local/bin. Verify the installation:
loom version
loom-mcp --help
The executable command reference lists supported loom-mcp command-line options.
If ~/.local/bin is not on your PATH, follow the guidance printed by the installer.
Load the Loom Workflows skill
The Loom Workflows skill teaches your Cursor agent how to use Loom as the control plane for repo automation. It covers:
- When to use Loom MCP tools vs the CLI
- How to create, validate, compile, and run workflows
- How to triage failures using structured artifacts
- Discovery order for existing repo entrypoints
The canonical skill lives at skills/loom-workflows/SKILL.md. Its Cursor copy at
.cursor/skills/loom-workflows/SKILL.md and portable plugin copy at
plugins/loom-workflows/skills/loom-workflows/SKILL.md are byte-identical.
The dedicated loom-workflows Agent Plugin packages that skill for Codex and
Cursor. Use a reviewed immutable checkout and retain its revision; package version
0.1.0 identifies the skill package, not the selected CLI/MCP binaries. Codex can
discover it in this repository's local Loom plugin marketplace. For Cursor, copy
the entire plugins/loom-workflows directory to
~/.cursor/plugins/local/loom-workflows, reload the window and confirm the skill
in Customize; local plugin imports must be allowed. Follow the
package installation and maintenance instructions
for the supported client steps. Discovery does not establish installation.
The package includes no binary or MCP server configuration. Install the intended
CLI/MCP pair and configure the server separately below. Within this repository,
the maintained Cursor skill is also available directly; other projects can copy
that skill directory into their .cursor/skills/ folder without a plugin.
The skill is automatically activated when your agent detects Loom-related requests like "create a workflow", "run loom", or "debug this pipeline".
Configure the MCP server
Add the following to your project's .cursor/mcp.json (create the file if it doesn't exist):
{
"mcpServers": {
"loom-mcp": {
"command": "loom-mcp",
"transport": "stdio"
}
}
}
Start the selected executable with the canonical repository root as its working directory. Use one process per repository. The optional workspace_root tool argument must be omitted or exactly equal that canonical startup directory; relative paths, symlink aliases and another checkout are rejected. Workflow paths remain repo-relative.
Restart Cursor or reload the MCP server list to pick up the new server. Discover its tools and call loom_version after a server/version change. Installing a CLI does not replace a running MCP server. A source build such as ./bin/loom tests the checkout; record its path/version separately from an official release.
Use loom_run_local for synchronous request-bound execution. For explicit
server-owned execution, call loom_start_run, retain the returned exact run ID,
and poll loom_run_status. Only loom_cancel_run for that server's owned ID can
request detached-run cancellation; inspect the eventual terminal outcome.
Concurrent starts are independent. Server shutdown cancels and joins owned work.
A restart preserves recorded evidence but does not recover active ownership.
Synchronous calls may exceed client timeouts; timeout alone proves neither
cancellation nor completion, so inspect the exact recorded outcome before retrying.
One-click setup with Cursor deeplink
Open this link to launch Cursor with a pre-filled prompt that creates a Loom workflow for your repo:
Clicking the deeplink opens Cursor with a prompt that instructs your agent to discover repo entrypoints and create a Loom workflow around them. You review and confirm before anything executes.
Verify your setup
Call loom_version from the MCP client and compare it with the selected executable. Example response (the value depends on the build):
{ "version": "v2.0.0" }
If the MCP server is not reachable, confirm that loom-mcp is on your PATH and .cursor/mcp.json is valid JSON.
Codex workflow reminders
This repository includes project-local Codex reminders in .codex/hooks.json,
implemented by scripts/agent-hooks/codex.mjs. Node and Git must be on the client
PATH. Open a trusted checkout, inspect the hook definitions in Codex /hooks,
and trust the current definitions before starting a new session. Changes to a
hook definition require another review. See the
official Codex hook contract.
In a linked Git worktree, Codex discovers hook declarations from the root checkout. These commands resolve the handler in the active checkout with Git. Keep the reviewed root definition and intended active-checkout handler source coherent; a hook file present only in the linked worktree is not sufficient.
At startup, the reminder asks the agent to verify canonical cwd, intended source, actual binary path/hash/version and matching build provenance before authorized work. A development version alone does not establish source parity. The hook does not perform those checks or authorize an invocation.
After recognized direct CLI run completions and Loom MCP run/status responses, the reminder retains a validated returned run ID and distinguishes active owned work from recorded terminal outcomes. Inspect that exact ID's ordered states, scoped events and declared artifacts, then retain the evidence in the authorized journal. Missing, malformed, ambiguous or truncated identity stays silent; the hook never chooses the latest run. Recorded state does not establish liveness.
Hooks emit context only: they do not execute Loom, install, upload, mutate caches, write journals, block tools or trigger follow-up turns. Installing the portable workflow skill does not install or activate these repository-local hooks, and this integration makes no Cursor or Claude hook-parity claim.
Prompt your agent
Paste this starter prompt into Cursor:
Use the Loom skill and MCP tools to inspect existing native or GitLab workflows.
Create .loom/workflow.yml only if a new adapter is needed and in scope.
Start by discovering the repo's build entrypoints (package.json scripts,
Makefile targets, etc.), then create a thin Loom workflow that wraps them.
Validate with loom check and compile with loom compile.
For an existing GitLab pipeline, plan it directly before translating it. MCP compile/run inputs use source_format: gitlab and a versioned gitlab_context; CLI uses --workflow .gitlab-ci.yml --format gitlab and --context <repo-relative-file> when context is needed. Inspect selected jobs and diagnostics. To select exact jobs, use requested_jobs
on validation, compile or either run tool; CLI check, compile and run use
repeatable --job <exact-job-id>. Omit selection for the full workflow. Commas
are literal; the planner includes ordering and artifact prerequisites without
bypassing rules. Inspect job_selection.requested_jobs, effective_jobs and
identity; a selected success establishes that scope rather than the whole
workflow. Unknown or unavailable IDs fail before preparation. A skipped plan or executable empty graph does not establish job execution. Validation and compilation do not execute jobs.
Review the selected workflow and plan before authorized execution. Choose targets with the provider: host jobs require darwin on macOS or linux on Linux; Docker jobs require Linux targets on either host. Keep the repository's documented execution environment. Snapshots include nonignored dirty and untracked inputs, so keep operational journals/evidence in an excluded location such as .loom/.runtime/ without discarding user files.
Your agent will use the Loom MCP tools (loom_validate, loom_compile, loom_run_local) and fall back to the CLI when MCP is unavailable.
What your agent gets
MCP tools
| Tool | Purpose |
|---|---|
loom_version | Verify toolchain |
loom_validate | Validate workflow schema |
loom_compile | Compile to Graph IR |
loom_start_run | Start server-owned local run |
loom_run_status | Observe owned or recorded outcome |
loom_cancel_run | Cancel this server’s owned run |
loom_run_local | Execute locally |
loom_list_artifacts | List declared archive members |
loom_read_artifact | Read bounded original member bytes |
loom_list_runs | Discover recorded runs |
loom_read_run | Read recorded workflow state |
loom_read_events | Read recorded event messages |
Inspect a recorded outcome
Retain the returned run ID, status, exit code and paths even when MCP transport succeeds. Failed runs can still return paths; a persisted running state is not process liveness. Read ordered states first, then request all-stream events for the failed job/step/command IDs.
loom_read_events defaults to 200 records. Compare returned_events with
total_events and complete. Use all: true for all matching records, omitting
tail and max_lines, or request a bounded tail. All supplied filters combine
with AND before limiting. Query stream: stderr separately from level: error:
ordinary stderr can be info level. Records can contain multiple physical lines,
blank lines and partial fragments. CLI loom logs <run_id> --json --all reads the
same complete matches and reports counts on stderr; --all cannot combine with
--state or --tail.
Fresh runs write state.jsonl and events.jsonl under
.loom/.runtime/runs/<run_id>/; they do not write run receipts/manifests.
Validation receipts remain supported by validation.
Declared artifacts live separately under
.loom/.runtime/artifacts/<run_id>/jobs/<job-id>/. Use loom_list_artifacts with
exact run/canonical job IDs, then loom_read_artifact with its returned
member_path and explicit encoding: text or encoding: base64. CLI equivalents
are loom artifacts list <run_id> --job <job-id> and
loom artifacts read <run_id> <member> --job <job-id> --encoding base64.
Listing defaults to 200 members (maximum 1,000); body prefixes default to 65,536
original bytes (maximum 1,048,576). Compare totals and complete/truncated;
there is no offset/pagination API. Readers validate the whole contained archive
before results; they do not read arbitrary files or redact artifact bodies.
Published/restored files use 0644: prepare an intended binary with chmod +x
and check its OS/architecture and required loader/libraries before execution.
Published bytes alone do not prove portable executables.
A cache hit still runs scripts and does not alone prove byte reuse or output
correctness. Recorded cache operation messages carry phase/result, elapsed time
and measured counts in a stable prefix; raw cache-name/key/error suffixes remain
human text. Omitted counts are unknown, not zero; nested phase durations overlap.
Compressed zstd archive bytes and Docker transport tar bytes are different domains.
Reused capture IDs do not repeat export counts; each key still performs archive
work. Preserve miss/blocked/quarantined/canceled/failed results when reporting.
Docs resources
| URI | What you get |
|---|---|
loom://docs/index | Compact discovery index |
loom://docs/<page> | Full page text |
loom://docs/<page>#<section> | Section-level text |
For the full specification, see the MCP tools reference and MCP overview.
Next steps
| Goal | Link |
|---|---|
| Run your first workflow | Hello Loom |
| Understand the artifact model | What is Loom |
| Browse the CLI | CLI overview |
| MCP tools reference | MCP tools |
| Diagnose a failing run | Diagnostics ladder |