Loom

Agent Workspace engine and runtime for coding agents. Share, apply, and run a single primary agent plus its operating context -- instructions, skills, prompts, MCP servers, hooks, repos, and data -- across GitHub Copilot, Claude Code, and Cursor.

Loom lets teams maintain reusable Agent Workspaces in a GitHub repository and apply them with a single chat command. No database, no server -- just Git and GitHub Pages.

Demo

https://github.com/user-attachments/assets/8c937a54-cd23-45e6-9eb8-f7e2c86ec3f6

Three primary use cases

Loom is being built to serve three lanes on a shared foundation. Per RFC #115, each lane has its own epic; the substrate (apply, validate, renderers, workspace materialization, agent discovery, runtime contract) is tracked under foundation epic #117.

| Lane | What it does | Tracking | |---|---|---| | 1. loom-shuttle (orchestration) | Hub agents drive fully-equipped specialist Copilot CLI agents as conversational peers from any MCP host (VS Code Copilot Chat, Claude Code, Cursor, another Copilot CLI). Preserves skills, per-agent installed workspace, and developer-interactive sessions -- things VS Code's native subagents can't deliver. | #109 (epic), #77 | | 2. loom-eval (benchmarking) | Empirically evaluate custom agents under varying conditions: model A vs B, with/without subagents, prompt variants, skill variants, MCP variants. Move agent design from vibes to evidence. | #110 (epic), #83 | | 3. loom-runner (headless / watch) | Loom owns the reusable execution contract -- workspace creation, apply, MCP/auth, headless Copilot CLI execution, timeout, artifacts, session/result metadata -- that consumers like aegis and dobby-watch build on with their own triggers, scheduling, and post-processing. | #111 (epic), #112 | | Foundation (substrate) | Shared Agent Workspace resolver, loom apply, adapters, renderers, workspace materialization (including repo- and binary-backed MCP servers), agent discovery, skill staging, and the runtime logging / progress contract that all three lanes depend on. | #117 (epic) |

Why Loom?

Coding agents (Copilot, Claude Code, Cursor) rely on workspace-level configuration: instruction files, skill definitions, MCP servers, prompt files, and repository references. Teams often need to share and reuse these configurations across projects:

• Onboarding -- new team members get a ready-to-go agent workspace in seconds
• Consistency -- shared instructions and skills stay in sync across projects
• Multi-target support -- one Agent Workspace renders to Copilot, Claude Code, or Cursor format
• Personal setups -- host your own Agent Workspaces on a personal GitHub repo
• Runtime -- same Agent Workspace runs interactively (loom chat), headlessly (loom run), as a live specialist (loom-shuttle), or as benchmark trials (loom-eval)

Quick Start

1. Install

npm install -g @agent-loom/loom

2. Set up a registry

loom registry add my-workspaces https://github.com/<your-org>/<your-agent-workspaces>

3. Search and apply Agent Workspaces

In your coding agent's chat (Copilot, Claude Code, etc.):

Search for available Loom Agent Workspaces

Apply the functions-dev Agent Workspace to this workspace

The agent handles the whole workflow — searching, selecting, and applying the Agent Workspace to your rendered workspace.

Apply or run an Agent Workspace

An Agent Workspace is materialized before it runs. loom apply renders the Agent Workspace into the target directory. loom run resolves the same loom.yaml source model, stages the rendered workspace safely, launches the primary agent, and captures structured artifacts (SESSION:, REPORT:, PROGRESS:). Both commands use the primary agent declared in agent: agents/main.agent.md.

# Materialize the Agent Workspace into the current directory
loom apply ./workspaces/functions-dev --output .

# Headless one-shot against the same Agent Workspace model
loom run ./workspaces/functions-dev --prompt "investigate failing test" --work-dir ./work

# Interactive picker (TTY only)
loom

Install for fast / durable launch

When you want an agent always available regardless of cwd, install it once:

loom install ./workspaces/functions-dev
                                # renders under ~/.loom/teams/<reg>/<key>/,
                                # clones referenced repos, indexes in
                                # ~/.loom/agents.yaml

loom agents                     # list installed agents (reads ~/.loom/agents.yaml)
loom agents --all               # browse available agents across registries

loom uninstall ./workspaces/functions-dev
                                # remove from the installed-agents index
                                # (drops the team dir when the last agent
                                # for the Agent Workspace is uninstalled; pass
                                # --keep-team-dir to retain it)

Maintenance and diagnostics:

loom doctor                     # health check: node / git / runtimes / registries / ~/.loom layout / agent frontmatter lint

(Legacy staged dirs from pre-#126 layouts are slated for one-time auto-prune on first launch after upgrade -- PLANNED, tracked under #297. Until #297 lands, rm -rf ~/.loom/sessions/*/workspace/ if you need to reclaim the space.)

Every launch is recorded under ~/.loom/sessions/<id>/. Inspect past runs:

loom sessions list              # recent sessions
loom sessions show <id>         # full metadata
loom sessions tag <id> bug-repro
loom sessions note <id> "this one reproduced #1234"

Escape hatch: --no-session (skip recording).

Available Skills

Loom ships with 5 skills that teach your coding agent how to use the system:

| Skill | Purpose | |-------|---------| | loom-setup | Install CLI, configure registries, verify setup | | loom-search | Search and discover Agent Workspaces across registries | | loom-apply | Apply Agent Workspaces to render workspaces | | loom-scaffold | Create new Agent Workspaces from existing projects | | loom-workspaces | Manage workspace history and navigate past projects |

All skills are bundled with the Craft catalog. Install them with npx @agent-loom/craft add <skill-name>.

How It Works

Agent Workspace registry (GitHub repo)
  ├── index.yaml              ← auto-generated Agent Workspace index
  ├── shared/                 ← reusable instructions, MCP, repos, prompts
  └── workspaces/
      └── my-agent/
          └── loom.yaml       ← kind: agent-workspace source
              ↓
          loom apply
              ↓
      ┌──── Target: Copilot ──────────────────┐
      │ .github/copilot-instructions.md        │
      │ .github/instructions/*.instructions.md │
      │ .github/agents/*.agent.md              │
      │ .github/skills/*/SKILL.md              │
      │ .github/prompts/*.prompt.md            │
      │ .vscode/mcp.json                       │
      └────────────────────────────────────────┘
      ┌──── Target: Claude Code ──────────────┐
      │ CLAUDE.md                              │
      │ .claude/agents/*.md                    │
      │ .claude/skills/*/SKILL.md              │
      │ .claude/settings.json                  │
      │ .mcp.json                              │
      └────────────────────────────────────────┘

Agent Workspaces are declarative loom.yaml files with schemaVersion: 1 and kind: agent-workspace. The source package names one primary agent: agents/main.agent.md and optional skills, prompts, instructions, hooks, mcp, repos, and data dependencies. Loom resolves the Agent Workspace, fetches any external skill content, and renders target-specific files.

Vocabulary boundaries

| Term | Meaning | |---|---| | Agent Workspace | Source package for one primary agent and the operating context it needs. | | Rendered workspace | Generated files on disk for Copilot, Claude Code, or Cursor. | | VS Code workspace | A .code-workspace editor file; not the Loom source model. | | Plugin | Optional Copilot distribution artifact; not Loom's internal source model. | | Eval | External proof plan that exercises an Agent Workspace. | | Session artifact | Output from executing an Agent Workspace. |

Agent Workspace registries

An Agent Workspace registry is a GitHub repository with a specific layout:

my-registry/
  ├── index.yaml
  ├── shared/
  │   ├── instructions/
  │   ├── mcp/
  │   ├── repos/
  │   ├── prerequisites/
  │   └── prompts/
  └── workspaces/
      ├── agent-a/
      │   └── loom.yaml
      └── agent-b/
          └── loom.yaml

Create a GitHub repository with an Agent Workspace registry layout. See the documentation for a working example with CI/CD and a GitHub Pages catalog.

Catalog UI

Registries can publish a browsable catalog site to GitHub Pages using @agent-loom/loom-ui. The catalog is a static Next.js export that displays all Agent Workspaces with their source details, built and deployed automatically via CI/CD.

Documentation

• Getting Started — Chat-based usage guide
• CLI Reference — Full command reference
• Architecture — System design and internals
• MCP Scoping Guide — Team-level vs per-agent MCP isolation (Agent Workspace authors)
• Skills Specification — How skills are defined and resolved

Packages

| Package | Description | |---------|-------------| | @agent-loom/loom | CLI + core library | | @agent-loom/loom-ui | Static catalog site generator (Next.js) |

Development

npm install
npm run build
npm test
node dist/cli.js --help

Working on a branch

To dogfood a local build globally:

cd <your-loom-worktree>
npm run build
npm link                        # exposes `loom` from this worktree on PATH
loom                            # bare TUI -- launches against your local build
loom run ./workspaces/functions-dev --prompt "investigate" --work-dir ./work
                                # or launch through the interactive picker

# When done:
npm unlink -g @agent-loom/loom  # restore the published `loom`

npm link pins loom to the current worktree path. If you switch branches or blow away node_modules, re-run npm run build (no need to re-link).

License

ISC