valkor-ai/loom

Start Here

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 all

For a single agent, Windows, or a local checkout, see Quick Start.

What Loom Does

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.

Loom applies recursive self-improvement (RSI) to this loop: test and review findings guide the next repair, and the updated result is checked again.

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.

Delivery Model

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.

News

• 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

Context Routing

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

Prerequisites

• One supported coding agent installed locally: Codex, Claude Code, or OpenCode
• Docker for loom deploy

Quick Start

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 codex

Claude Code:

curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent claude-code

OpenCode:

curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent opencode

All supported agents on the same machine:

curl -fsSL https://github.com/valkor-ai/loom/releases/latest/download/install.sh | bash -s -- --agent all

Windows 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 all

Run 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-build

This 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.

How to Use

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.

Use Knowledge Sources

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.

Run Delivery

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.

How It Works

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.

1. Start or resume from .loom/ state.
2. Clarify and confirm scope, optionally using registered knowledge sources.
3. Build the delivery baseline: repository context, technical baseline, planning contract, and architecture artifact.
4. Convert contracts into task plans with ownership, read groups, write boundaries, verification intent, and result templates.
5. Execute bounded tasks through the agent, then write a TaskResult with evidence.
6. Let Loom validate, normalize, persist, and route from the submitted artifact.
7. Review through structured signals, then route code repair, task-plan repair, architecture repair, or manual review when needed.
8. Prepare local deployment previews with runtime facts, Compose topology, environment rules, logs, and repair boundaries when deploy is requested.
9. Continue or hand off from saved state; the next session or another agent can resume without rebuilding the delivery context.

Learn More

FAQ

Uninstalling Loom

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 opencode

To remove all local Loom agent plugins from this machine:

~/.loom/bin/loom-setup uninstall --all

To remove Loom user-level runtime data, including installed runtimes and user-level knowledge indexes:

~/.loom/bin/loom-setup purge

uninstall 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.

Related Work

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.

Supported By

Star History

License

Loom is open source under the Apache License 2.0.