iloom

iloom in action: Scale understanding, not just output.

Links to key sections

How It Works • Installation • Configuration • Advanced Features • Limitations

Built For Modern Tools...

...To Solve A Very Modern Problem

The promise of AI-assisted development is profound: write more code, ship features faster. But there is a hidden cost. AI agents write code quickly, but they struggle to stay in sync with their humans.

The hard part isn't generating code, it's maintaining the shared mental model of why that code exists. When you rely on ephemeral chat windows, friction piles up:

• You constantly re-brief the AI on the same context.

• Hidden assumptions creep in (e.g., "Why did it use Axios instead of fetch?").

• You spend more time reviewing and "babysitting" the AI than building.

The bottleneck isn't output velocity. It's maintaining alignment between human and AI at scale.

The iloom Approach: Context as Infrastructure

iloom stops the "Context Window Tetris." It treats context as a first-class concern, persisting your AI's reasoning in issue comments rather than temporary chats.

• Stop Babysitting, Start Collaborating: Instead of arguing with Claude in a chat, you review structured analysis plans in your issue tracker before a single line of code is written.

• Scale Understanding: Because every loom holds its own isolated environment (Git worktree, DB branch, local server), you can switch between 5 complex features without losing your place or your AI's context.

• Visible Reasoning: The AI's decisions are documented publicly. Your team sees the plan, and "future you" knows exactly why a decision was made.

• Automatic Session Summaries: When you finish a loom, iloom captures key insights, decisions, and lessons learned from your Claude session and posts them to the issue. These summaries become institutional knowledge that informs future tasks.

iloom is not just a tool for managing git worktrees - it's a control plane for maintaining alignment between you and your AI assistant.

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

→ Want to know how you'll benefit from iloom?

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 agents:

• Enhancer (iloom-issue-enhancer): Expands brief one-liners into detailed requirements.

• Evaluator (iloom-issue-complexity-evaluator): Determines the workflow approach:

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

  • Complex: Separates deep root-cause analysis from detailed implementation planning.

• Implementer: Executes the plan using the context established in the previous steps.

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: Feeling lucky? Automate the entire pipeline from start to finish 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.

• Unique Runtime:

  • Web Apps: Runs on a deterministic port (e.g., base port 3000 + issue #25 = 3025).

  • 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.
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 and paths.
il projects		List configured projects (JSON output).
il spin		Launch Claude inside the current loom with context auto-detected.
il open	run	Open loom in browser (web) or run your CLI tool.
il dev-server	dev	Start dev server in foreground for a workspace.
il add-issue	a	Create and AI-enhance a new issue without starting work yet.
il init	config	Interactive configuration wizard.
il feedback	f	Submit bug reports/feedback directly from the CLI.
il update		Update iloom CLI to the latest version.

For detailed documentation including all command options, flags, and examples, see the Complete Command Reference.

Configuration

1. Interactive Setup (Recommended)

The easiest way to configure iloom is the interactive wizard. It guides you through setting up your environment (GitHub/Linear, Neon, IDE).

You can even use natural language to jump-start the process:

# Standard wizard
il init 

# Natural language wizard
il init "set my IDE to windsurf and help me configure linear"

2. Manual Configuration

Settings are loaded in this order (highest priority first):

1. CLI Flags: il start --permissionMode=acceptEdits

2. Local Overrides: .iloom/settings.local.json (gitignored; for API keys & local preferences)

3. Project Settings: .iloom/settings.json (committed; for shared team defaults)

4. Global Settings: ~/.config/iloom-ai/settings.json (for user-specific defaults)

Key Settings Example

This example shows how to configure a project-wide default (e.g., GitHub remote) while keeping sensitive keys (Linear API token) or personal preferences (IDE choice) local.

.iloom/settings.json (Committed)

{
  "mainBranch": "main",
  "issueManagement": {
    "provider": "github"
  },
  "capabilities": {
    "web": {
      "basePort": 3000
    },
    "database": {
      "databaseUrlEnvVarName": "DATABASE_URL"
    }
  },
  "databaseProviders": {
    "neon": {
      "projectId": "fantastic-fox-3566354"
    }
  }
}

.iloom/settings.local.json (Gitignored)

{
  "issueManagement": {
    "linear": {
      "apiToken": "lin_api_..." // Only if using Linear
    }
  },
  "workflows": {
    "issue": {
      "permissionMode": "acceptEdits" // Control Claude Code permissions
    }
  },
  "spin": {
    "model": "opus" // Claude model for spin orchestrator: opus (default), sonnet, or haiku
  },
  "summary": {
    "model": "sonnet" // Claude model for session summaries: sonnet (default), opus, or haiku
  }
}

Merge Behavior

Control how il finish handles your work. Configure in .iloom/settings.json:

{
  "mergeBehavior": {
    "mode": "local"  // "local", "github-pr", or "github-draft-pr"
  }
}

Mode	Description
local	(Default) Merge directly into main branch locally. Fast-forward merge, no PR created.
github-pr	Push branch and create a GitHub PR on il finish. Worktree cleanup is optional.
github-draft-pr	Create a draft PR immediately on il start. On il finish, the PR is marked ready for review. Recommended for contributions to forked repos.

When to use github-draft-pr:

• Contributing to forks: When you don't are contributing to a forked repo use this mode to create the PR from your fork immediately, allowing iloom's agents to post workflow comments directly to the PR instead of writing to the upstream repo's issues (which may not be appreciated by the repo owners).
• CI runs on your branch during development (draft PRs trigger CI on most repos)
• Your team requires PRs for all changes (no direct merges to main)
• You want reviewers to see progress before the work is complete

Integrations

Issue Trackers

iloom supports the tools you already use. Unless you use JIRA.

Provider	Setup	Notes
GitHub	gh auth login	Default. Supports Issues and Pull Requests automatically.
Linear	il init	Requires API token. Supports full read/write on Linear issues.

IDE Support

iloom creates isolated workspace settings for your editor. Color synchronization (visual context) only works best VS Code-based editors.

• Supported: VS Code, Cursor, Windsurf, Antigravity, WebStorm, IntelliJ, Sublime Text.

• Config: Set your preference via il init or il start --set ide.type=cursor.

Advanced Features

Child Looms (Nested Contexts)

Sometimes a task spawns sub-tasks, or you get interrupted by an urgent bug while deep in a feature. Child looms let you create a workspace within a workspace.

When to use:

• Breaking down a massive feature into smaller PRs.

• Fixing a bug discovered during feature work without losing context.

How it works: If you run il start 42 while inside loom-25, iloom asks if you want to create a child loom.

• Inheritance: The child inherits the database state and git branch from the parent (not main).

• Structure

    ~/my-project-looms/
    ├── feat-issue-25-auth/           # Parent Loom
    └── feat-issue-25-auth-looms/     # Child Looms Directory
      ├── fix-issue-42-bug/         # Child Loom (inherits from #25)
      └── feat-issue-43-subtask/    # Another Child Loom

CLI Tool Development

iloom provides first-class support for building CLI tools. When you start a loom for a CLI project, iloom creates workspace-specific binaries so you can test each issue's version independently.

> il start 52 # Working on CLI feature in issue 52 

> my-cli-52 --version  # Test issue 52's version 

> il start 137  # Switch to different CLI issue

> my-cli-137 --help    # Test issue 137's version

# Original binary still works from main branch
> my-cli --version     # Unaffected by other looms' CLIs

System Requirements & Limitations

This is an early-stage product.

Requirements:

• ✅ OS: macOS (Fully supported). ⚠️ Linux/Windows are untested.

• ✅ Runtime: Node.js 16+, Git 2.5+.

• ✅ AI: Claude CLI installed. A Claude Max subscription is recommended (iloom uses your subscription).

Project Support:

• ✅ Node.js Web Projects: First-class support via package.json scripts (dev, test, build).

• ✅ Node.js CLI Tools: Full support with isolated binary generation.

• ⚠️ Other Stacks: Python/Go/Rust etc. can work via generic package.json scripts, but are not natively supported yet.

See all known limitations on GitHub. If you're feeling left out - you're absolutely right! The best way to complain about something is to fix it. So...

Contributing

We (Claude and I) welcome contributions! We've made it easy to get started — iloom can even set up its own dev environment.

iloom contribute   # Handles forking, cloning, and setting up the dev environment automatically.

All PRs should be created with iloom or include detailed context. When you run iloom contribute, it configures iloom to create a draft PR as soon as you start work. As you work, iloom posts the AI's analysis, implementation plan, and progress directly to that draft PR—giving reviewers full context before the code is even ready for review. If you're not using iloom, please provide equivalent detail in your PR.

New contributors should start with issues labeled starter-task. For details, see our Contributing Guide.

License & Name

iloom comes from "illuminate" (illuminating the AI coding process) and "intelligent loom" (weaving artificial and human intelligence together).

License: Business Source License 1.1

• ✅ Free to use for any internal or commercial project.

• ❌ You cannot resell iloom itself as a product or SaaS.

• Converts to Apache 2.0 on 2029-01-01.

See LICENSE for complete terms.