iloom

VS Code extension now available! Run il vscode to install. Get the recap panel to see AI decisions, risks, and assumptions in real-time, plus the loom explorer to manage and switch between active projects and tasks.

Links to key sections

How It Works • Installation • Configuration • Advanced Features • Swarm Mode • Telemetry • Limitations • Contributing

How can your team trust the code your AI wrote, when you don't?

Your agent just shipped a 2,000-line PR. Why did it restructure that module? What assumptions did it make about the auth flow? Nobody knows. The reasoning evaporated when the chat session ended, and now your teammate is staring at a diff with zero context. Good luck getting that reviewed.

iloom persists the AI's analysis, plans, decisions, and risks as comments in your issue tracker. Not chat logs you'll never reopen. Not markdown files littering the repo. Your actual tracker, where your team can see what happened and why. That mountain of code you're sending for review? Now it comes with the reasoning behind it.

This matters because to get the most out of agents, you need to be multitasking across several of them. iloom gives every task its own isolated environment (git worktree, DB branch, unique port), and because all the reasoning is persisted, you can context-switch between tasks without losing the thread. The VS Code extension lets you catch up with any agent in seconds. Your teammates can pick up where you left off without a briefing.

When a task outgrows one agent, il plan decomposes it into child issues with dependencies, and swarm mode launches parallel agents to execute them, each in its own worktree, running the full iloom workflow. You can one-shot entire features, entire products, and stay aligned. The VS Code extension gives you a Kanban board and dependency graph so you can see what's running, what's blocked, and what's done. The only real limit is your imagination. And maybe your Claude subscription.

Quick Start

iloom uses your existing Claude subscription to build a shared mental model of your task.

 # 1. Install iloom
 npm install -g @iloom/cli
 
 # 2. Authenticate (iloom uses the GitHub CLI) 
 gh auth login 
 
 # 3. Start a Loom 
 # Spins up an isolated environment (Git worktree, DB branch, unique port).
 # Analyzes the issue, plans the work, and documents the plan in issue comments.
 il start 25 

 # ... You, the iloom agents and Claude build the feature together in the isolated environment ...
 
 # 4. Finish & Merge  # Validates code, generates session summary, merges, and cleans up.
 il finish

The iloom Difference: il start doesn't merely create a branch. It launches a multi-agent workflow that surfaces assumptions and creates a structured plan in your issue tracker before you even need to look at your IDE.

How It Works: The Multi-Agent Workflow

When you run il start, iloom orchestrates specialized AI agents. Each has a specific role and writes structured output to issue comments, creating permanent project knowledge.

1. The Agents

Instead of a single generic prompt, iloom uses a pipeline of specialized agents:

• Enhancer: Expands brief one-liners into detailed requirements with acceptance criteria.

• Evaluator: Assesses complexity and routes to the appropriate workflow:

  • Simple: Combines analysis and planning into one step for efficiency.

  • Complex: Separates deep analysis from detailed planning for thorough coverage.

• Analyzer: Explores the problem space before any code is written. This agent investigates the codebase to understand existing patterns, examines third-party library APIs and capabilities, and researches technical approaches. The result is a comprehensive analysis that informs the planning phase—leading to significantly better implementation plans than jumping straight to code.

• Planner: Creates an execution plan with parallelization analysis—identifying which steps can run concurrently vs. sequentially. Plans reference specific files and line numbers, making them actionable and precise.

• Implementer: Executes the plan using the context established in the previous steps. For complex tasks, multiple implementers can run in parallel on independent steps.

• Swarm Orchestrator: For epics with child issues, iloom enters swarm mode—launching parallel agent teams that implement each child issue autonomously in its own worktree, respecting dependency order.

2. Interactive Control

You are in the loop at every stage. You can review the AI's analysis, edit the plan in GitHub/Linear, and adjust course before implementation begins.

• Default Mode: You approve each phase (Enhance → Plan → Implement).

• --one-shot Mode: Automate the pipeline with different levels of control.

• --yolo Mode: Feeling lucky? Shorthand for --one-shot=bypassPermissions - full automation without prompts.

3. The Environment

Each loom is a fully isolated container for your work:

• Git Worktree: A separate filesystem at ~/project-looms/issue-25/. No stashing, no branch switching overhead.

• Database Branch: (Neon support) Schema changes in this loom are isolated—they won't break your main environment or your other active looms.

• Environment Variables: Each loom has its own environment files (.env, .env.local, .env.development, .env.development.local). Uses development by default, override with DOTENV_FLOW_NODE_ENV. See Secret Storage Limitations for frameworks with encrypted credentials.

  When inside a loom shell (il shell), the following environment variables are automatically set:

  | Variable | Description | Example | |----------|-------------|---------| | ILOOM_LOOM | Loom identifier for PS1 customization | issue-87 | | ILOOM_COLOR_HEX | Hex color assigned to this loom (if available) | #dcebff |

  ILOOM_COLOR_HEX is useful for downstream tools that want to visually distinguish looms. For example, a Vite app can read it via import.meta.env.VITE_ILOOM_COLOR_HEX to tint the UI. See Vite Integration Guide for details.

• Unique Runtime:

  • Web Apps: Runs on a deterministic port (e.g., base port 3000 + issue #25 = 3025). Optionally supports Docker mode for frameworks that don't respect PORT.

  • CLI Tools: Creates an isolated binary copy (e.g., my-tool-25). You can run issue #25's version of your CLI alongside issue #99's version without conflicts. (Fun fact: iloom was built with iloom using this feature).

• Context Persistence: All reasoning is stored in issue comments. This makes the "why" behind the code visible to your teammates and your future self.

Command Reference

| Command | Alias | Description | | ------ | ----- | -----| | il start | new | Create loom, run analysis agents, and launch IDE. Auto-detects epics with child issues for swarm mode. | | il commit | c | Commit all files with issue reference (Refs #N or Fixes #N). | | il finish | dn | Validate tests/lint, commit, handle conflicts, and merge/PR. | | il cleanup | remove | Safely remove a loom and its database branch without merging. | | il list | | Show active looms for current project. --finished for archived, --all for active + archived, --global for looms across all projects. JSON output includes swarmIssues and dependencyMap for epic looms. | | il projects | | List configured projects (JSON output). | | il spin | | Launch Claude inside the current loom with context auto-detected. In epic looms, enters swarm mode with parallel agent orchestration. | | il open | run | Open loom in browser (web) or run your CLI tool. | | il vscode | | Install iloom VS Code extension and open workspace in VS Code. | | il dev-server | dev | Start dev server in foreground for a workspace. | | il build | | Run the build script for a workspace. | | il lint | | Run the lint script for a workspace. | | il test | | Run the test script for a workspace. | | il compile | typecheck | Run the compile or typecheck script for a workspace. | | il add-issue | a | Create and AI-enhance a new issue without starting work yet. | | il plan | | Launch interactive planning session to decompose epics into child issues. | | il contribute | | Fork, clone, and set up a GitHub repo for contribution (defaults to iloom-cli). | | il init | config | Interactive configuration wizard. | | il feedback | f | Submit bug reports/feedback