Loop engineering for agentic software delivery.
An open delivery harness that helps Claude Code, Codex, OpenCode, and other coding agents finish larger software tasks without losing state.
Simplified Chinese · Technical Report · Use Cases · Quick Start · How to Use · Context Routing · FAQ · Team
⭐ If Loom is useful to you, give it a star and help more developers find it.
Coding agents are good at writing code. They are less reliable at finishing the whole job: they lose context, skip checks, and leave handoffs unclear.
Loom is an open-source harness that runs beside the agent you already use. It keeps the work moving through a simple loop: plan, build, test, fix, preview, and hand off.
Loom saves the important project state: requirements, task progress, test results, runtime facts, and repair notes. If a session stops, the next run can continue from where things left off.
Use Loom when a task is too big for a single prompt: feature work, deployment, review, repair, preview, or a handoff that needs evidence.
- Upcoming: V-SEFM, a verifier model for software delivery, is in progress. Details later.
- Jul 2026: Loom moved its MCP runtime from TypeScript to Rust to make the core smaller and faster.
- Jul 2026: Loom now supports Godot projects through Godot MCP. Setup guide
Coding agents can generate websites and apps quickly. The rough part is keeping them on track after the first pass: preserving requirements, checking the work, fixing failures, and resuming after a stopped session.
Longer tasks tend to fail in familiar ways:
| Failure mode | Loom response |
|---|---|
| Partial completion | Tasks are bounded and must write explicit results before Loom routes the next step. |
| Goal drift | Scope and architecture decisions are saved and reused across sessions. |
| Self-check bias | Review and repair run as separate steps with recorded evidence. |
| Repeated context loading | Agents read compact project and task state instead of reloading the whole repo. |
| Handoff gaps | Reports, logs, previews, and repair history make the final state inspectable. |
AI coding has made demos cheap. A single prompt can get you a web page, a prototype, or a personal tool.
Shipping the same work is different. You still need requirements, architecture choices, tests, runtime setup, fixes, preview evidence, and a handoff someone can trust.
Loom focuses on that gap. It gives existing agents a delivery loop and a place to store progress, so a task can survive failed checks, context compaction, and a new session.
The goal is simple: fewer rebuilt sessions, fewer half-finished agent runs, and more software that reaches a verifiable finish.
| Capability | What it changes |
|---|---|
| Stateful delivery protocol | Turns a one-shot coding session into a resumable delivery loop backed by .loom/ state, request refs, result files, review records, repair requests, and handoff evidence. |
| Requirement intelligence | Converts loose prompts into confirmed scope, business rules, lifecycle coverage, UI operation paths, and acceptance details that planning, execution, and review must preserve. |
| Architecture and system design | Turns the accepted technical baseline and repository facts into implementation-facing decisions for boundaries, behavior, data ownership, runtime responsibilities, NFR targets, ADRs, and failure modes. These decisions become compact ids that planning, execution, review, and repair can carry forward. |
| API contracts | Defines structured interfaces, request and response models, validation, error behavior, collection policies, and compatibility rules when they are actually in scope. Frontend tasks, integration checks, runtime probes, and deploy consume the accepted API contract instead of guessing paths or prefixes. |
| Stack-aware implementation guidance | Selects only the language, framework, persistence, and frontend references owned by the current task from the accepted Technical Baseline. The code and framework references provide repository adaptation, implementation patterns, verification expectations, and anti-patterns without loading unrelated stacks or reselecting technology. |
| Engineering contracts | Carries runtime, code-quality, and task ownership decisions as structured contracts instead of relying on repeated prompt reminders. |
| Production UI guidance | Pushes UI quality to the generation side with surface decisions, scenario references, layout density, style asset plans, token expectations, forbidden content rules, and desktop/mobile evidence. |
| Targeted context routing | Lets agents read field groups, reference profiles, task contracts, and repair context instead of repeatedly loading broad files or entire artifacts. |
| Task-scoped execution | Splits delivery into bounded tasks with source refs, write boundaries, verification intent, result templates, and continuation rules. |
| Verification and review discipline | Applies language/framework-specific testing guidance only when the task owns the evidence, uses review references to assess specification and implementation quality, and adds Playwright browser closure only for explicitly assigned browser behavior. Runtime failures remain environment evidence rather than being misreported as code defects. |
| Review and repair loop | Separates implementation from validation through review signals, TaskResult evidence, repair contracts, multi-target repair routing, and re-verification. |
| Runtime and deploy readiness | Prepares local Docker Compose previews with topology-aware services, build contexts, environment rules, ports, health checks, logs, and repair boundaries. |
| Knowledge-guided clarification | Lets teams register local domain docs as named knowledge sources, build searchable local indexes, and pull only matching chunks into the right clarification step. |
| Multi-agent MCP protocol | Runs the same delivery state machine through Codex, Claude Code, OpenCode, and future MCP-capable agents. |
The technical guidance behind this path is organized under plugins/shared/loom/references/tech/: architecture (arch), API design (api), language and SQL implementation (code), backend and frontend frameworks (backend and frontend), review (review), and Playwright verification (test/playwright). These are not loaded as one large skill. Loom derives a task-scoped selection from accepted technical facts and task ownership, then passes only the selected references into the relevant architecture, planning, execution, review, or browser-closure request.
High-level context path:
Your coding agent / app
(Codex, Claude Code, OpenCode, future agents...)
|
| delivery goal . repo context . logs . tests . preview evidence
v
+----------------------------------------------------------------------------+
| Loom (project-local delivery state; full artifacts stay in .loom/) |
|----------------------------------------------------------------------------|
| Dynamic workflow router -> Request manifest -> Agent read plan |
| | |
| |- requestReadPlan grouped required reads |
| |- MCP field resources targeted retrieval |
| |- write targets authorized artifact I/O |
| `- action result next tool + compact view |
| |
| Task contracts . evidence windows . fullLogRef . review/repair/resume state |
+----------------------------------------------------------------------------+
|
| compact instruction + selected field groups + retrieval path
v
Agent turn / LLM context
- One supported coding agent installed locally: Codex, Claude Code, or OpenCode
- Docker for
loom deploy
Install Loom for the coding agent you use. The installer detects your OS and CPU, downloads the matching release package, verifies the package .sha256 asset, installs the Rust MCP server, bundles the Python algorithm runtime, writes the agent MCP registration, refreshes the local plugin, and runs loom-setup doctor.
Codex:
curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent codexClaude Code:
curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent claude-codeOpenCode:
curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent opencodeAll supported agents on the same machine:
curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent allWindows PowerShell:
Invoke-WebRequest https://github.com/valkor-ai/loom/releases/latest/download/install.ps1 -OutFile install.ps1
.\install.ps1 -Agent codex
.\install.ps1 -Agent claude-code
.\install.ps1 -Agent opencode
.\install.ps1 -Agent allRun the same install command again to upgrade. The installer removes Loom-owned legacy CLI plugin artifacts before installing the MCP runtime. If it finds files it cannot prove are Loom-owned, it stops and tells you what to remove manually instead of overwriting user files.
For local validation from a repository checkout, use the same installer in local build mode:
./install.sh --agent codex --local-buildThis builds the Rust MCP server and setup binary, writes the same release package layout, then installs through loom-setup and runs doctor. Use this path after local bug fixes so the installer, package layout, MCP registration, and plugin refresh are verified together.
After installing or updating an agent plugin, open a new agent session in the target project so the refreshed MCP registration and plugin files are loaded.
To verify the install without starting a delivery, use the Loom command inside your coding agent:
@loom status # Codex
/loom status # Claude Code and OpenCode
status is read-only. In a project that has not used Loom yet, STATE_NOT_INITIALIZED is a valid smoke-check result: it means the plugin command is available and no delivery has been started.
You normally do not initialize .loom/ by hand. Starting a delivery from the agent, such as @loom build ... or /loom build ..., initializes the project-local delivery state when needed.
Loom is meant to be used through the local plugin inside your coding agent. Use @loom in Codex and /loom in Claude Code or OpenCode. The Rust MCP server is started by the agent MCP registration; users do not start it by hand.
Knowledge sources are optional, but they are useful when your delivery work depends on product rules, domain notes, design standards, operating procedures, or other local reference material.
Loom treats knowledge sources as clarification aids, not as requirements by themselves. During requirement clarification, Loom searches enabled and successfully built knowledge indexes, reads only matching chunks for the current clarification step, and turns useful findings into user-visible questions or confirmation points.
Run knowledge commands from the coding agent session for the project you are working on. The examples below show Codex with @loom; in Claude Code and OpenCode, use the same subcommands with /loom.
Add a new knowledge source:
@loom knowledge add --name product-rules ~/Documents/product-rules
@loom knowledge build product-rules
--name is required and must be unique. A source can include one file, many files, one directory, many directories, or a mix of files and directories. Currently supported formats are .md, .txt, .json, .yaml, .yml, .pdf, and .docx.
Update an existing knowledge source's registered paths:
@loom knowledge update product-rules --add-path ~/Documents/new-rules.md
@loom knowledge update product-rules --remove-path ~/Documents/old-rules.md
@loom knowledge update product-rules --replace-paths ~/Documents/current-rules
@loom knowledge build product-rules
If the files inside an already registered path changed, run build again. You do not need update unless the path set changes.
Resume an unfinished semantic knowledge build:
@loom knowledge resume product-rules
Use resume when a knowledge build stopped before publishing, for example after reopening a coding-agent session or when a multi-pack semantic build did not finish. It does not rebuild the source; it finds the next unfinished semantic pack and lets the agent continue until the index is published.
Review and manage existing knowledge sources:
@loom knowledge list
@loom knowledge status product-rules
@loom knowledge pending product-rules
@loom knowledge discard product-rules
Disable a source without deleting it:
@loom knowledge disable product-rules
@loom knowledge enable product-rules
Remove a source registration and its local Loom index:
@loom knowledge remove product-rules
remove does not delete your original documents. It only removes Loom's registration, pending queue, and built index for that knowledge source.
Start from your coding agent with its Loom command surface:
Codex:
@loom build a visitor registration system
@loom continue
@loom review
@loom deploy
Claude Code and OpenCode:
/loom build a visitor registration system
/loom continue
/loom review
/loom deploy
In all agents, the command starts the same Loom MCP delivery protocol. The plugin routes the request to Loom tools and follows the structured next action returned by the MCP server.
For new delivery requests, the explicit plan subcommand is equivalent to a bare request: @loom plan build ... matches @loom build ..., and /loom plan build ... matches /loom build ....
Use continue whenever you want Loom to resume or advance the current delivery safely. This is the right first action after reopening an agent session, after an interruption, after a tool action succeeds but the agent does not keep going, or when you are not sure which step is next.
@loom continue # Codex
/loom continue # Claude Code and OpenCode
Agent plugins set the Loom routing environment for you. Use the agent command surface for normal work; Loom's product runtime is the MCP server installed by loom-setup.
Loom runs as a local MCP delivery state machine. The agent does not decide the whole workflow from memory; it asks Loom for the next request, reads only the declared fields, writes the expected artifact, submits it back, and lets Loom validate and route the next step.
- Start or resume from
.loom/state. - Clarify and confirm scope, optionally using registered knowledge sources.
- Build the delivery baseline: repository context, technical baseline, planning contract, and architecture artifact.
- Convert contracts into task plans with ownership, read groups, write boundaries, verification intent, and result templates.
- Execute bounded tasks through the agent, then write a TaskResult with evidence.
- Let Loom validate, normalize, persist, and route from the submitted artifact.
- Review through structured signals, then route code repair, task-plan repair, architecture repair, or manual review when needed.
- Prepare local deployment previews with runtime facts, Compose topology, environment rules, logs, and repair boundaries when
deployis requested. - Continue or hand off from saved state; the next session or another agent can resume without rebuilding the delivery context.
| Need | Command or file |
|---|---|
| Check Loom plugin availability | @loom status in Codex, or /loom status in Claude Code and OpenCode |
| Install or upgrade Codex plugin | curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent codex |
| Install or upgrade Claude Code plugin | curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent claude-code |
| Install or upgrade OpenCode plugin | curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent opencode |
| Install or upgrade all supported plugins | curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent all |
| Run a local deployment preview | @loom deploy in Codex, or /loom deploy in Claude Code and OpenCode |
How is Loom different from CLAUDE.md, AGENTS.md, or .cursorrules?
Those files are useful entry points, but they tend to become large prompts. Loom adds stateful delivery routing, task artifacts, review results, repair requests, deployment evidence, and MCP tools around them.
What happens if a delivery is interrupted?
Loom stores project-local delivery state under .loom/, including context, task plans, result records, review notes, repair requests, and deployment evidence. Reopen the agent session and run @loom continue in Codex or /loom continue in Claude Code and OpenCode; Loom will route the next step from the saved delivery state.
Does Loom deploy to production?
Not yet. Production deployment will be added later. Current deployment support focuses on local Docker Compose previews, validation, logs, and repair guidance.
If you need to remove Loom from one local agent, use loom-setup:
~/.loom/bin/loom-setup uninstall --agent codex
~/.loom/bin/loom-setup uninstall --agent claude-code
~/.loom/bin/loom-setup uninstall --agent opencodeTo remove all local Loom agent plugins from this machine:
~/.loom/bin/loom-setup uninstall --allTo remove Loom user-level runtime data, including installed runtimes and user-level knowledge indexes:
~/.loom/bin/loom-setup purgeuninstall keeps project-local .loom/ delivery state. purge is intentionally broader and should be used only when you want to remove Loom's user-level runtime and indexes from this machine.
After uninstalling a plugin, open a new agent session so that agent reloads its local command/plugin state.
Loom is informed by adjacent work in coding-agent skills, agentic engineering workflows, and software engineering evaluation:
- Matt Pocock's Skills - Practical agent skills for requirement clarification, domain language, debugging, TDD, and handoff discipline.
- SWE-bench - Real-world software engineering tasks used to evaluate coding agents.
Loom is open source under the Apache License 2.0.
