Loom — AI-assisted workflow for VS Code

Document-native workflow for AI-assisted development.

🎬 Workflow demo — chat → idea → design → plan → do-step → done, with the document graph building node-by-node in the sidebar.

Loom turns your project into a structured collaboration surface between you and AI. Instead of a chat window that forgets everything, you get a document-driven loop:

chat → idea → design → req → plan → implement → done

Every stage is a Markdown document. The AI reads them, writes to them, and tracks progress through them — across sessions, without losing context.

🧭 New to Loom? Which way is for you → — the four ways to run Loom (Guided · Power terminal · Pure agent · Automation) and how to pick yours.

🔗 Get Loom: GitHub repo · CLI on npm · VS Code Marketplace · Open vsx

📚 Guides: Ways to use Loom · Core concepts & workflow · Extension User Guide · CLI / Claude Code Guide

💬 Feedback appreciated. Using Loom? Tell me how it's going — I'm always looking for ways to improve it. I'd like to know what worked and what got in the way. Click the Feedback button in the status bar or run loom feedback; it opens a prefilled GitHub issue you edit before sending. Opt-in, nothing sent automatically.

Why Loom

Loom started as a hand-built habit: while developing the .NET library REslava.Result, I got tired of ephemeral AI chats that forgot every decision between sessions, so I began keeping ideas, designs, plans, and requirements as persistent Markdown — grouped by feature, so the AI always had the right context. Loom automates that.

Traditional AI chat:          Loom:
  knowledge drifts & dies       knowledge becomes artifacts
                                artifacts become context
                                context drives implementation

The part that matters most isn't the loop — it's how Loom decides what the AI sees. A graph of typed docs, scope-loaded ctx summaries, reference docs with conditional requires_load / load_when, locked requirements (include / exclude / constrain), and a Context panel that shows the exact bundle before you launch. The AI's memory is structural, not conversational. → How context works

Install — one click, no CLI

1. Install this extension from the VS Code Marketplace (search Loom AI, publisher reslava).
2. Open a folder and click Initialize Loom in the Loom panel.

That's it. The Loom engine is bundled inside the extension and runs on VS Code's own runtime — no npm install, no global loom command, no Node to set up. Initializing creates .loom/ (config + the CLAUDE.md AI session contract), loom/ (your doc workspace), and .mcp.json (so an AI agent can drive Loom too).

1-click, always-current, zero-config. The AI agent Loom launches runs the same bundled engine as the extension — never a separate global loom that could drift — so your agent is always the version you installed. And when you update the extension, your session rules and config refresh themselves on the next open. Nothing to re-run, nothing to keep in sync.

📚 New here? → Getting Started — install to your first idea in five minutes.

Three ways to run Loom

Loom is one engine with three delivery surfaces. Pick the one that fits — you don't need all three.

The extension is the recommended default; the CLI/MCP path serves agents and hosts the extension can't reach. → Architecture: delivery surfaces

Connect an AI agent

Want a coding agent (Claude Code, Cursor, …) to drive Loom directly? loom install (or the extension's Initialize) already wrote .mcp.json to your project root, using a pinned npx command so the agent needs no global install:

{
  "mcpServers": {
    "loom": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@reslava/loom@<version>", "mcp"]
    }
  }
}

The agent then has access to all Loom tools (loom_create_idea, loom_do_step, loom_complete_step, etc.) and resources (loom://context/...).

The loop

1. Chat — open a chat doc, think out loud with the AI (AI Reply).
2. Idea — create one with Create Idea and flesh it out with Refine Idea, or Promote a chat straight to an idea.
3. Design — click Create Design to define how to build it.
4. Plan — click Create Plan to get a concrete step-by-step implementation list.
5. Implement — click Do Step to have the AI implement the next step, record what was done, and mark it complete.

Each stage produces a Markdown document visible in the Loom panel. Nothing disappears between sessions.

The LOOM panel

The Loom Activity Bar icon opens the Loom sidebar, which contains two views: Threads and Context.

Threads view

Shows your weaves (project areas) → threads (workstreams) → docs (idea, design, plans, chats, done docs). Buttons appear inline on a node and in its right-click menu, grouped by what they do.

A Show Roadmap toolbar toggle re-lays this view into the derived cross-weave roadmap — one Roadmap band (present + future threads in a single dependency-then-priority order, each row showing its status and, when blocked, what it's blocked on) and History (shipped plans). In roadmap mode the status filter folds to all / roadmap / history, the History band can group by thread, and drag-to-reorder spans the whole Roadmap list, writing soft priority (never overriding a hard dependency). It's all computed from the documents — no roadmap list to maintain.

Threads + Context — every weave → thread → doc (chat, idea, design, plan, req, reference, done) in one graph, each node carrying its derived state: reqs marked 🔒 locked · ✅ covered, plan step counts (3/3 · done), and staleness ⚠. The CONTEXT panel shows the exact docs — and their token cost — the AI will receive for the selected node, before you launch.	Roadmap — the same graph re-laid as the derived roadmap: present + future threads in one dependency-then-priority order (status, soft priority p20, and what each is blocked on), over a History band grouped by shipped version with date and thread.

_{Click either image to view full size.}

AI actions (run the agent):

Create & promote (structure, no AI):

Manage (state & tree):

Right-click any node for the same actions as a context menu.

Context view

Shows every document that would be loaded into the AI's context for the selected node — before you launch anything. Updates as you click around. What you see here is what the AI gets.

Reports view

Generate and browse reports synthesized from the doc graph — a project overview, architecture, decisions, or release notes for your next version — right from the panel; they're saved under loom/reports/. The release-notes report drafts your changelog from the Unreleased done plans (enriched from their done docs, framed Highlights → Added / Changed / Fixed), and the same loom report release-notes command drops into your release CI so the doc graph writes your changelog.

Each row is one doc, marked by why it's there:

Click a row to open the doc. Use the inline actions to include / exclude / reset; choices persist per target in .loom/context-prefs.json. Per-doc and total token estimates let you keep launches lean.

Send feedback

A Feedback button in the status bar (and the Loom: Send Feedback command) opens a prefilled GitHub issue carrying only Loom version, OS, and non-PII usage counts (weaves / threads / done plans / current release) — opt-in, editable before you send, nothing sent automatically.

Usage telemetry (opt-in, off by default)

Separately from feedback, Loom can send anonymous, content-free usage telemetry so we can see whether the workflow loop is used and where people stall. It is off by default; on first activation Loom asks once, and sends nothing unless you choose Enable.

• Turn on/off: click the Telemetry: On/Off item in the status bar (one click — first enable confirms what's sent), or toggle the reslava-loom.telemetry.enabled setting. Either is the kill switch.
• Sent only when on: a random install id, Loom version, OS, is_ci, the surface (extension), and fixed workflow events (workspace_activated, session_started, doc_generated/doc_refined with the doc type, plan_started, step_completed, plan_done, command_invoked, error).
• Never sent: document content, titles, slugs, paths, weave/thread names, or any PII. Events go to PostHog (EU).

A real project in Loom

ChordFlow — a Rhythm & Progression Trainer for guitar — is built with Loom from outside this extension's own repo: the same panel, driving an unrelated app.

Threads + Context — ChordFlow's music-domain weaves (CAGED system, interval lattice, octave shapes), a plan mid-implementation, and a diagnostics banner: 1 stale · 3 plan steps blocked · 11 req coverage gaps.	Roadmap — ChordFlow's derived roadmap and shipped-version history, computed from its own documents.

_{Click either image to view full size.}

AI setup

Every AI button picks its path automatically:

1. Claude Code CLI (default)

If claude is on your PATH, buttons open a persistent Loom AI terminal and run claude "<prompt>". Claude reads your Loom docs, calls the right MCP tools, and writes the result back. No API key needed — works with a Claude Pro subscription.

# Install Claude Code CLI (free with Claude Pro)
npm install -g @anthropic-ai/claude-code

2. API key / sampling (fallback)

If Claude Code CLI is not installed, the extension calls the AI provider directly via its configured API key. Set in VS Code settings:

reslava-loom.ai.apiKey  → your Anthropic / OpenAI / DeepSeek key
reslava-loom.ai.provider → anthropic | openai | deepseek

Settings

Requirements

• VS Code 1.85+ — the extension is self-contained (bundled server; no separate CLI or Node install)
• For AI actions: Claude Code (recommended — no API key) or an API key in settings

Documentation

• User Guide — concepts, the workflow loop, and how context works
• Extension User Guide — the panel, buttons, and CONTEXT view
• CLI / Claude Code Guide — driving Loom from the terminal
• Getting Started — install to first idea in five minutes
• How Loom works — the chat → design → req → plan → implement loop
• Architecture — MCP surface, doc types, frontmatter
• Staleness Model — how the tree's staleness ⚠ is decided (one directional, version-based rule)

License

MIT