Keep software delivery moving.
Loom is an open delivery harness for Claude Code, Codex, OpenCode, and other coding agents.
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.
| I want to... | In Codex | In Claude Code / OpenCode |
|---|---|---|
| Build a feature or app | @loom build Add a team settings page |
/loom build Add a team settings page |
| Resume an interrupted delivery | @loom continue |
/loom continue |
| Review and repair a change | @loom review |
/loom review |
| Validate a local preview | @loom deploy |
/loom deploy |
Install Loom once for every supported agent on this machine:
curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent allFor a single agent, Windows, or a local checkout, see Quick Start.
Loom runs beside the coding agent you already use and turns a larger change into a delivery loop: clarify the scope, plan the work, build it, run checks, repair failures, preview the result, and leave a handoff.
The project-local .loom/ directory keeps requirements, task progress, results, runtime facts, and repair history. A new session can pick up the actual state of the work instead of reconstructing it from chat history.
Loom is for work that needs more than a generated first pass: a feature, a review, a deployment, a repair, or a change someone else must be able to inspect and continue.
See delivered examples for the kinds of projects Loom has run end to end.
| Stage | Loom keeps |
|---|---|
| Scope and design | Confirmed requirements, decisions, and task boundaries |
| Execution | Task-specific context, write targets, and recorded results |
| Verification | Tests, runtime checks, previews, and review findings |
| Repair and handoff | Repair requests, re-verification, and the project state for the next person or session |
Loom selects technical references and context for the current task rather than loading the entire repository or a large generic skill into every turn. The shared references cover architecture, APIs, language and framework work, review, and browser verification.
- 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
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, creates an isolated Python runtime for Loom's algorithms, 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.
