iloom Command Reference

Complete documentation for all iloom CLI commands, options, and flags.

Core Workflow Commands
- il start
- il commit
- il finish
- il rebase
- il cleanup
- il list
Context & Development Commands
- il spin
- il open
- il vscode
- il dev-server
- il build
- il lint
- il test
- il compile
- il install-deps
- il summary
- il shell
Planning Commands
- il plan
Issue Management Commands
Swarm Mode (Epic Orchestration)
Configuration & Maintenance

Core Workflow Commands

il start

Create an isolated loom workspace with complete AI-assisted context establishment.

Aliases: new, create, up

Usage:

il start <issue-number>
il start <pr-number>
il start <branch-name>
il start "<issue-description>"

Arguments:

<issue-number> - GitHub or Linear issue number (e.g., 25)
<pr-number> - GitHub pull request number (e.g., 42)
<branch-name> - Existing git branch name
<issue-description> - Free-form description to create a new issue (quoted string)

Options:

Flag	Values	Description
`--one-shot`	`default`, `noReview`, `bypassPermissions`	Automation level for Claude CLI workflow
`--yolo`	-	Shorthand for `--one-shot=bypassPermissions` (autonomous mode)
`--dangerously-skip-permissions`	-	Skip Claude permission prompts without skipping workflow gates (composable with `--one-shot`)
`--complexity`	`trivial`, `simple`, `complex`	Override complexity evaluation (persists in loom metadata)
`--effort`	`low`, `medium`, `high`, `max`	Set effort level for Claude (persists in loom metadata)
`--child-loom`	-	Force create as child loom (skip prompt, requires parent loom)
`--no-child-loom`	-	Force create as independent loom (skip prompt)
`--epic`	-	Force create as epic loom with child issues (skip prompt; ignored if no children)
`--no-epic`	-	Skip epic loom creation even if issue has children (ignored if no children)
`--claude` / `--no-claude`	-	Enable/disable Claude integration (default: enabled)
`--code` / `--no-code`	-	Enable/disable VS Code launch (default: enabled)
`--dev-server` / `--no-dev-server`	-	Enable/disable dev server in terminal (default: enabled)
`--terminal` / `--no-terminal`	-	Enable/disable terminal without dev server (default: disabled)
`--create-only`	-	Create workspace only: skip Claude, IDE, terminal, dev server (shorthand for `--no-claude --no-code --no-terminal --no-dev-server`)
`--body`	`<text>`	Body text for issue (skips AI enhancement)

One-Shot Modes:

default - Standard behavior with approval prompts at each phase
noReview - Skip phase approval prompts, but respect permission settings
bypassPermissions - Full automation, skip all permission and approval prompts (use with caution!)

Complexity Override:

The --complexity flag skips the complexity evaluation agent entirely and routes the workflow directly based on the specified value:

trivial - Simplest workflow path, minimal analysis
simple - Combined analysis and planning in a single step
complex - Full multi-step analysis, planning, and review phases

The override follows a two-level model:

il start --complexity - Persists the complexity value in loom metadata. All subsequent il spin sessions for this loom will use the stored complexity unless explicitly overridden.
il spin --complexity - Overrides the stored complexity for the current session only. The loom metadata is not modified, so the next il spin without --complexity reverts to the stored value (or runs the evaluator if none was stored).

Effort Override:

The --effort flag controls Claude's reasoning depth:

low - Quick, straightforward implementation with minimal overhead
medium - Balanced approach with standard implementation and testing
high - Comprehensive implementation with extensive testing and documentation
max - Maximum capability with deepest reasoning (Opus 4.6 only; silently downgrades to high on other models)

The override follows the same two-level model as complexity:

il start --effort - Persists the effort value in loom metadata. All subsequent il spin sessions for this loom will use the stored effort unless explicitly overridden.
il spin --effort - Overrides the stored effort for the current session only. The loom metadata is not modified.

When no effort is configured anywhere (CLI flag, metadata, or settings), the environment variable is not set, deferring to Claude Code's own default behavior (which respects any /effort session setting the user has configured).

Workflow Phases:

The il start command orchestrates multiple AI agents:

Fetch - Retrieves issue/PR details from GitHub or Linear
Epic Detection - Checks for child issues; prompts for epic loom creation (or uses --epic/--no-epic flags). If creating as epic, fetches child issue details and builds dependency map.
Enhance (conditional) - Expands brief issues into detailed requirements
Evaluate - Assesses complexity and determines workflow approach (Simple vs Complex)
Analyze (complex issues only) - Investigates root causes and technical constraints
Plan - Creates implementation roadmap
- Complex issues: Detailed dedicated planning phase
- Simple issues: Combined analysis + planning in one step
Environment Setup - Creates worktree, database branch, environment variables. For epic looms, stores child issue details and dependency map in metadata.
Launch - Opens IDE with color theme and starts development server

Examples:

# Start work on GitHub issue #25
il start 25

# Start work on Linear issue ILM-42
il start ILM-42

# Create a new issue and start work
il start "Add dark mode toggle to settings"

# Start with full automation (skip all prompts)
il start 25 --one-shot=bypassPermissions

# Start with full automation using shorthand
il start 25 --yolo

# Force create as child loom when working inside another loom
il start 42 --child-loom

# Create independent loom even when inside another loom
il start 99 --no-child-loom

# Start an epic loom (auto-detect children, prompt for confirmation)
il start 100

# Force epic mode (skip prompt)
il start 100 --epic

# Force normal loom even if issue has children
il start 100 --no-epic

# Skip complexity evaluation and treat as simple
il start 25 --complexity=simple

# Skip complexity evaluation and run full automation
il start 25 --complexity=complex --yolo

# Skip permission prompts only (keep workflow gates active)
il start 25 --dangerously-skip-permissions

# Skip permission prompts and workflow gates
il start 25 --dangerously-skip-permissions --one-shot=noReview

Notes:

When run from inside an existing loom, prompts to create a child loom (unless flags override)
Creates isolated environment: Git worktree, database branch, unique port
All AI analysis is posted as issue comments for team visibility
Color codes the VS Code window for visual context switching
When an issue has child issues, prompts whether to create an epic loom (use --epic/--no-epic to skip the prompt). These flags are silently ignored if the issue has no children.
Epic looms store child issue details and the dependency map in metadata for use by swarm mode during il spin

il commit

Commit all uncommitted files with an issue reference trailer.

Alias: c

Usage:

il commit [options]

Must be run from within a loom directory.

Options:

Flag	Description
`-m`, `--message <text>`	Custom commit message (skips Claude generation)
`--fixes`	Use "Fixes #N" trailer instead of "Refs #N" (closes the issue)
`--no-review`	Skip commit message review prompt
`--json`	Output result as JSON (implies `--no-review`)
`--json-stream`	Stream JSONL output; runs Claude headless for validation fixes (implies `--no-review`, mutually exclusive with `--json`)

Behavior:

Auto-detects issue number from current worktree path
Stages all uncommitted files (git add -A)
Generates commit message using Claude (or uses -m message if provided)
Appends issue reference trailer:
- Default: Refs #N (references issue without closing)
- With --fixes: Fixes #N (closes the issue when merged)
Prompts for review (unless --no-review or --json)
Commits with the generated message

Trailer Behavior:

Trailer	Effect	When to Use
`Refs #N`	References issue, keeps it open	Work-in-progress commits during development
`Fixes #N`	Closes issue when commit is merged to default branch	Final commit that completes the issue

Examples:

# Basic usage (auto-detect issue, Refs trailer)
il commit

# With custom message
il commit -m "Add authentication service"

# Mark this commit as fixing the issue
il commit --fixes

# Skip review prompt
il commit --no-review

# JSON output for scripting (implies --no-review)
il commit --json

# Combine flags
il commit -m "Final implementation" --fixes --no-review

Example Commit Messages:

With Claude generation:

Add user authentication endpoints

- Implement login endpoint with JWT tokens
- Add password hashing with bcrypt
- Create user registration flow

Refs #425

With --fixes flag:

Add user authentication endpoints

- Implement login endpoint with JWT tokens
- Add password hashing with bcrypt
- Create user registration flow

Fixes #425

JSON Output Format:

{
  "success": true,
  "commitHash": "a1b2c3d",
  "message": "Add user authentication endpoints...",
  "filesChanged": 5,
  "issueNumber": "425",
  "trailerType": "Refs"
}

Notes:

Use il commit for intermediate commits during development
Use il commit --fixes or il finish when completing the issue
The --json flag is useful for CI/CD pipelines and scripting
If not in an issue/PR worktree, --fixes prints a warning and is ignored

il finish

Validate, commit, merge, and cleanup a loom workspace with AI-assisted error resolution.

Alias: dn

Usage:

il finish [options]

Must be run from within a loom directory.

Options:

Flag	Description
`-f`, `--force`	Skip confirmation prompts
`-n`, `--dry-run`	Preview actions without executing
`--pr`	Treat input as PR number
`--skip-build`	Skip post-merge build verification
`--no-browser`	Skip opening PR in browser (pr and draft-pr modes)
`--cleanup`	Clean up worktree after finishing (default in local mode)
`--no-cleanup`	Keep worktree after finishing (default in pr and draft-pr modes)
`--review`	Review commit message before committing (default: auto-commit without review)

Merge Behavior Modes:

Behavior depends on the mergeBehavior.mode setting in your iloom configuration:

local (default):

Detects uncommitted changes and auto-commits
Runs validation pipeline: typecheck, lint, tests
If failures occur, launches Claude to help fix issues
Rebases on main branch
Validates fast-forward merge is possible
Merges to main
Installs dependencies in main
Runs post-merge build verification
Cleans up worktree and database branch

pr:

Same validation pipeline as local mode
Pushes branch to remote
Creates GitHub pull request
Opens PR in browser (unless --no-browser or openBrowserOnFinish: false)
Prompts for cleanup (or use --cleanup/--no-cleanup flags)

draft-pr:

Same validation pipeline as local mode
Removes placeholder commit and pushes final commits
Marks draft PR as ready for review
Opens PR in browser (unless --no-browser or openBrowserOnFinish: false)
Prompts for cleanup (or use --cleanup/--no-cleanup flags)

Examples:

# Standard finish workflow
il finish

# Preview what will happen without executing
il finish --dry-run

# Finish and skip confirmation prompts
il finish --force

# Create PR and keep worktree for additional changes
il finish --no-cleanup

# Create PR without opening browser
il finish --no-browser

Migration Conflict Handling:

For Payload CMS projects, iloom automatically detects and handles migration conflicts:

Identifies migration file conflicts
Launches Claude to help resolve discrepancies
Validates schema consistency

Browser Opening Configuration:

By default, il finish opens the PR in your browser after creation (pr mode) or marking ready (draft-pr mode). To disable this permanently, set openBrowserOnFinish to false in your settings:

{
  "mergeBehavior": {
    "mode": "pr",
    "openBrowserOnFinish": false
  }
}

Browser opening is also suppressed in --json mode and --dry-run mode.

Notes:

Claude assists with fixing any test, typecheck, or lint failures
Automatically generates commit message from issue context
Handles merge conflicts with AI assistance
Cleans up all resources: worktree, database branch, dev server

il rebase

Rebase current loom branch on the main branch with AI-assisted conflict resolution.

Usage:

il rebase [options]

Must be run from within a loom directory.

Options:

Flag	Description
`-f`, `--force`	Skip confirmation prompts
`-n`, `--dry-run`	Preview actions without executing

Workflow:

Fetches latest changes from main branch
Attempts to rebase current branch
If conflicts occur, launches Claude to help resolve
Validates resolution and completes rebase

Examples:

# Rebase with confirmation prompt
il rebase

# Rebase and skip confirmation
il rebase --force

# Preview rebase without executing
il rebase --dry-run

Notes:

Useful when main branch has advanced and you need to sync
Claude provides context-aware conflict resolution assistance
Safe to run multiple times

il cleanup

Remove one or more loom workspaces without merging.

Aliases: remove, clean

Usage:

il cleanup [options] [identifier]

Arguments:

[identifier] - Branch name or issue number to cleanup (auto-detected if omitted)

Options:

Flag	Description
`-l`, `--list`	List all worktrees
`-a`, `--all`	Remove all worktrees (interactive confirmation)
`-i`, `--issue`	Cleanup by issue number
`-f`, `--force`	Skip confirmations and force removal
`--dry-run`	Show what would be done without doing it
`--archive`	Archive metadata instead of deleting (preserves loom in `il list --finished`)

Workflow:

Identifies matching loom(s)
Confirms deletion (unless forced)
Removes Git worktree
Deletes database branch (if configured)
Removes loom directory

Examples:

# Cleanup specific loom by issue number
il cleanup 25

# Cleanup by issue number explicitly
il cleanup -i 25

# List all worktrees
il cleanup --list

# Preview cleanup without executing
il cleanup 25 --dry-run

# Remove all worktrees (interactive)
il cleanup --all

# Force cleanup without confirmation
il cleanup 25 --force

# Archive metadata instead of deleting (keeps loom visible in il list --finished)
il cleanup 25 --archive

Safety:

Checks for uncommitted changes and warns
Cannot cleanup currently active loom
Database branches are safely deleted

il list

Display all active loom workspaces with their details.

Usage:

il list [options]

Options:

Flag	Description
`--json`	Output as JSON
`--finished`	Show only finished looms
`--all`	Show both active and finished looms

Output includes:

Issue/PR number and title
Branch name
Loom directory path
Development server port (for web projects)
CLI binary name (for CLI projects)
Database branch name (if configured)
Current status (active, has uncommitted changes, etc.)
Finish time (for finished looms with --finished or --all)
Swarm lifecycle state (state) for child looms in swarm mode
Swarm issues and dependency map for epic looms (JSON output only)

JSON Output - Epic Loom Fields:

When using --json, epic looms include additional fields:

Field	Type	Description
`state`	`string \| null`	Swarm lifecycle state: `pending`, `in_progress`, `code_review`, `done`, or `failed`. `null` for non-swarm looms.
`swarmIssues`	`array`	Array of child issues with enriched state. Only present for epic looms.
`dependencyMap`	`object`	Dependency DAG. Keys are issue numbers, values are arrays of blocking issue numbers. Only present for epic looms.

Each entry in swarmIssues has:

Field	Type	Description
`number`	`string`	Issue number with prefix (e.g., `"#123"` for GitHub, `"ENG-123"` for Linear)
`title`	`string`	Issue title
`url`	`string`	Issue URL
`state`	`string \| null`	Current lifecycle state (`pending`, `in_progress`, `code_review`, `done`, `failed`) or `null`
`worktreePath`	`string \| null`	Path to the child's worktree, or `null` if not yet created

Examples:

# List all active looms (default)
il list

# List only finished looms
il list --finished

# List both active and finished looms
il list --all

# Output as JSON
il list --json

# Output example:
# Active Looms:
# ──────────────────────────────────────────────────────
#  #25  feat-add-dark-mode
#       ~/my-project-looms/feat-issue-25-dark-mode/
#       Port: 3025 | DB: br-issue-25
#
#  #42  fix-authentication-bug
#       ~/my-project-looms/fix-issue-42-auth/
#       Port: 3042 | DB: br-issue-42

Context & Development Commands

il spin

Launch Claude CLI with auto-detected loom context.

Usage:

il spin [options]

Options:

Flag	Values	Description
`--one-shot`	`noReview`, `bypassPermissions`	Automation level (same as `il start`)
`--yolo`	-	Shorthand for `--one-shot=bypassPermissions` (autonomous mode)
`--complexity`	`trivial`, `simple`, `complex`	Override complexity evaluation (session-only, does not persist)
`--effort`	`low`, `medium`, `high`, `max`	Set effort level for Claude (session-only, does not persist)
`-p, --print`		Enable print/headless mode for CI/CD (uses `bypassPermissions`)
`--output-format`	`json`, `stream-json`, `text`	Output format for Claude CLI (requires `--print`)
`--verbose`		Enable verbose output (requires `--print`)
`--set`	`key=value`	Override settings using dot notation (repeatable). Same as global `--set` flag.
`--skip-cleanup`		Skip automatic cleanup of child worktrees in swarm mode

Behavior:

Inside a loom: Launches Claude with that loom's context preloaded
Inside an epic loom: Enters swarm mode — creates child worktrees and launches orchestrator with parallel agent teams
Outside a loom: Launches Claude with general project context

Context Loading:

When launched from inside a loom, Claude receives:

Issue/PR description and all comments
AI-generated enhancement, analysis, and planning
Current file tree and recent changes
Environment details (port, database branch, etc.)

Swarm Mode (Epic Looms):

When il spin detects an epic loom (created via il start --epic or by confirming the epic prompt), it enters swarm mode instead of launching a standard Claude session:

Fetches/refreshes child data - Re-fetches child issue details and dependency map from the issue tracker
Creates child worktrees - One worktree per child issue, branched off the epic branch, with dependencies installed
Configures swarm agents - Sets up the orchestrator and worker agents for the epic and all child worktrees
Launches orchestrator - Starts the swarm orchestrator session

The orchestrator then:

Analyzes the dependency DAG to identify initially unblocked issues
Spawns parallel worker agents for all unblocked child issues simultaneously
Each worker receives full issue context and implements its assigned issue autonomously
Completed work is rebased and fast-forward merged into the epic branch for clean linear history
Newly unblocked issues are spawned as their dependencies complete
Failed children are isolated and do not block unrelated issues

Child Worktree Cleanup:

After each child agent's work is successfully merged into the epic branch, the orchestrator automatically runs il cleanup --archive on the child worktree to archive its metadata and remove the worktree and branch from disk. Archived child looms remain visible via il list --finished. Failed children are preserved for debugging and can be inspected manually.

To disable automatic cleanup and keep all child worktrees after swarm completion, use the --skip-cleanup flag:

il spin --skip-cleanup

Post-Swarm Code Review:

After all child agents complete and their work is merged into the epic branch, the orchestrator automatically runs a full code review using the iloom-code-reviewer agent. This catches cross-cutting issues that individual child agents miss because they each only see their own changes, not the integrated result.

If the review finds issues, they are automatically fixed before the final commit. The review is non-blocking -- if the reviewer or fix agent fails, the swarm continues to finalization without interruption. Only a single review-fix pass is performed (no re-review loops).

Post-swarm review is enabled by default. To disable it, set spin.postSwarmReview to false in your settings:

{
  "spin": {
    "postSwarmReview": false
  }
}

Or via CLI override:

il spin --set spin.postSwarmReview=false

Examples:

# Launch Claude with current loom context
il spin

# Launch with full automation
il spin --one-shot=bypassPermissions

# Launch with full automation using shorthand
il spin --yolo

# Headless mode for CI/CD pipelines (outputs to stdout)
il spin --print

# Headless mode with JSON output format
il spin --print --output-format=json

# Keep child worktrees after swarm mode completes
il spin --skip-cleanup

# Override complexity for this session only
il spin --complexity=trivial

# Override complexity with full automation
il spin --complexity=complex --yolo

il open

Open loom in browser (web projects) or run configured CLI tool (CLI projects).

Alias: run

Usage:

il open [identifier]

Arguments:

[identifier] - Optional issue number or loom identifier
If omitted and inside a loom, opens current loom
If omitted outside a loom, prompts for selection

Behavior by Project Type:

Web Projects:

Opens development server in default browser
Uses the loom's unique port (e.g., http://localhost:3025)

CLI Projects:

Runs the loom-specific binary
Executes with any additional arguments passed

Examples:

# Open current loom
il open

# Open specific loom by issue number
il open 25

# For CLI projects, run with arguments
il open 25 --help
il open 25 --version

# Pass environment variables to the dev server
il open 25 --env DEBUG=true --env API_URL=http://localhost:8080

Options:

Option	Description
`-e, --env <KEY=VALUE>`	Environment variable to pass to the dev server (repeatable). Same behavior as `il dev-server --env`.

il vscode

Install the iloom VS Code extension and open a workspace in VS Code.

Usage:

il vscode [identifier]

Arguments:

[identifier] - Optional issue number, PR number, or branch name
If omitted, auto-detects from current directory or branch

Behavior:

Checks if VS Code CLI (code) is available
Parses identifier or auto-detects from current directory/branch
Finds the corresponding worktree
Installs the iloom VS Code extension (if not already installed)
Opens VS Code at the worktree path

Examples:

# Auto-detect from current directory
il vscode

# Open workspace for issue #45
il vscode 45

# Open workspace for Linear issue
il vscode ENG-123

# Open workspace for branch
il vscode feat/my-feature

Notes:

Requires VS Code CLI (code) to be available in PATH
Automatically installs the iloom VS Code extension if not present
Works with any loom workspace (issue, PR, or branch-based)

il dev-server

Start development server in foreground for a workspace.

Alias: dev

Usage:

il dev-server [identifier] [options]

Arguments:

[identifier] - Optional issue number, PR number, or branch name
If omitted and inside a loom, starts dev server for current loom
If omitted outside a loom, prompts for selection

Behavior:

Resolves the target loom
Loads environment variables from .env files
Executes dev script from package.json or .iloom/package.iloom.json
Runs in foreground (useful for debugging and manual testing)

Examples:

# Start dev server for current loom
il dev-server

# Start dev server for specific issue
il dev-server 25

# Start dev server for a branch
il dev-server feat/my-branch

Options:

Option	Description
`--json`	Output result as JSON
`-e, --env <KEY=VALUE>`	Environment variable to pass to the dev server (repeatable). In Docker mode, these become `--env` flags on `docker run`; in native mode, they are injected into the process environment. CLI `--env` values override settings-level `dockerRunEnv` for the same key.

Notes:

Runs in foreground to see server output and errors
Use Ctrl+C to stop the server
Respects sourceEnvOnStart setting for environment loading

Docker Dev Server Mode

By default, il dev-server runs your dev server as a native process. For frameworks that ignore the PORT environment variable (e.g., Angular CLI), you can use Docker mode to remap ports via Docker's -p flag.

Prerequisites:

Docker must be installed and the Docker daemon must be running
A Dockerfile in your project (or a custom path configured)

Configuration:

Set capabilities.web.devServer to "docker" in your .iloom/settings.json:

{
  "capabilities": {
    "web": {
      "protocol": "https",
      "devServer": "docker",
      "dockerFile": "./Dockerfile",
      "containerPort": 4200,
      "dockerBuildArgs": {
        "NODE_ENV": "development"
      },
      "dockerBuildSecrets": {
        "npmrc": "~/.npmrc"
      },
      "dockerRunArgs": ["-v", "./src:/app/src"],
      "dockerRunEnv": {
        "DEBUG": "true"
      }
    }
  }
}

Configuration Fields:

Field	Type	Default	Description
`protocol`	`"http"` \| `"https"`	`"http"`	Protocol for dev server URLs. Set to `"https"` if your app serves over HTTPS (e.g., Angular with `ssl: true`). Applies to all dev server modes (native process and Docker).
`devServer`	`"process"` \| `"docker"`	`"process"`	Dev server execution mode. `"process"` runs natively, `"docker"` runs inside a Docker container with port mapping.
`dockerFile`	`string`	`"./Dockerfile"`	Path to the Dockerfile relative to the worktree root. Only used when `devServer` is `"docker"`.
`containerPort`	`number`	Auto-detected	Port the application listens on inside the Docker container. If not set, iloom attempts to detect it from `EXPOSE` directives in the built Docker image (via `docker image inspect`), falling back to Dockerfile parsing.
`dockerBuildArgs`	`Record<string, string>`	-	Build arguments passed to `docker build` (e.g., `{"NODE_ENV": "development"}`).
`dockerBuildSecrets`	`Record<string, string>`	-	Secret files to mount during `docker build` via BuildKit `--secret` flag. Keys are secret IDs, values are source file paths (supports `~` expansion). Example: `{"npmrc": "~/.npmrc"}` translates to `--secret id=npmrc,src=$HOME/.npmrc`.
`dockerRunArgs`	`string[]`	-	Additional flags passed to `docker run`. Use this for volume mounts, user mapping, and other Docker options.
`dockerRunEnv`	`Record<string, string>`	-	Environment variables passed as `--env` to `docker run` (e.g., `{"NODE_ENV": "development"}`). These can be overridden at invocation time with `il dev-server --env KEY=VALUE`.

How Port Mapping Works:

Each loom workspace gets a unique port calculated as basePort + issue/PR number (e.g., issue #25 gets port 3025). In Docker mode:

The Docker image is built from your Dockerfile
The container runs with -p <workspace-port>:<container-port>
Your app runs on containerPort inside the container (e.g., 4200 for Angular)
Docker maps that to the workspace port on the host (e.g., 3025)
You access the app at http://localhost:3025 (or https:// if protocol is set to "https") as usual

This means frameworks that hardcode their listen port work correctly -- Docker handles the port translation transparently.

Container Naming:

Containers are named iloom-dev-<identifier> where the identifier is derived from the issue/PR number or branch name. Special characters (slashes, etc.) are replaced with hyphens.

Known Limitations:

Single-container only: Docker mode runs a single container from your Dockerfile. Docker Compose (docker-compose.yml) multi-service stacks are not yet supported. If your app depends on external services (Redis, Postgres, etc.), run them separately or use a self-contained Dockerfile.
macOS file watching: Docker Desktop on macOS uses VirtioFS for bind mounts. Hot reload frameworks may not detect file changes reliably through VirtioFS. If your dev server's hot reload stops working, enable polling mode via dockerRunEnv:
```
{
  "dockerRunEnv": { "CHOKIDAR_USEPOLLING": "true" }
}
```
This is a Docker Desktop limitation, not an iloom limitation.
Anonymous node_modules volume: The container's node_modules are isolated from the host's. If you add or update dependencies, you must rebuild the Docker image (docker build) for the changes to take effect inside the container.
Container orphaning on crash: If the iloom process is killed with SIGKILL (e.g., kill -9), detached containers may remain running. Use docker ps to check and docker rm -f to clean up:
```
# List any orphaned iloom containers
docker ps --filter "name=iloom-dev-"

# Force-remove all orphaned iloom containers
docker rm -f $(docker ps -q --filter "name=iloom-dev-")
```
Normal cleanup via il cleanup, il finish, or Ctrl+C handles container shutdown automatically.
runArgs is passed verbatim: Flags provided in dockerRunArgs are forwarded directly to docker run without validation. You are responsible for the correctness of any flags you pass.

il build

Run the build script for a workspace.

Usage:

il build [identifier]

Arguments:

[identifier] - Optional issue number, PR number, or branch name
If omitted and inside a loom, builds current loom
If omitted outside a loom, prompts for selection

Behavior:

Resolves the target loom or current workspace
Loads environment variables from .env files
Executes build script from:
- .iloom/package.iloom.json (highest priority)
- package.json (fallback for Node.js projects)
Exits with non-zero code if build fails

Script Resolution:

Scripts are resolved in this order:

scripts.build in .iloom/package.iloom.json (if exists)
scripts.build in package.json (if exists)

Examples:

# Build current loom (auto-detected)
il build

# Build specific issue
il build 25

# Run in specific loom workspace
cd ~/my-project-looms/feat-issue-42-feature/
il build

Supported Projects:

Language	Build Command	Configuration source
Node.js (npm)	`npm run build`	`package.json` scripts
Node.js (pnpm)	`pnpm build`	`package.json` scripts
Node.js (yarn)	`yarn build`	`package.json` scripts
Rust	`cargo build --release`	`.iloom/package.iloom.json`
Python (pip)	`pip install -e .`	`.iloom/package.iloom.json`
Python (poetry)	`poetry install`	`.iloom/package.iloom.json`
Ruby	`bundle install`	`.iloom/package.iloom.json`
Go	`go build ./...`	`.iloom/package.iloom.json`

Notes:

Works with any language/framework via .iloom/package.iloom.json
Environment variables are automatically loaded before execution
Build failures are reported with exit codes for CI/CD integration

il lint

Run the lint script for a workspace.

Usage:

il lint [identifier]

Arguments:

[identifier] - Optional issue number, PR number, or branch name
If omitted and inside a loom, lints current loom
If omitted outside a loom, prompts for selection

Behavior:

Resolves the target loom or current workspace
Loads environment variables from .env files
Executes lint script from:
- .iloom/package.iloom.json (highest priority)
- package.json (fallback for Node.js projects)
Exits with non-zero code if linting fails

Script Resolution:

Scripts are resolved in this order:

scripts.lint in .iloom/package.iloom.json (if exists)
scripts.lint in package.json (if exists)

Examples:

# Lint current loom (auto-detected)
il lint

# Lint specific issue
il lint 25

# Validate code style in feature branch
il lint feat/my-feature

Supported Linters:

Language	Typical Command	Configuration source
JavaScript/TypeScript	`eslint .`	`.iloom/package.iloom.json` or `package.json`
Python	`pylint src/`	`.iloom/package.iloom.json`
Rust	`cargo clippy`	`.iloom/package.iloom.json`
Ruby	`rubocop`	`.iloom/package.iloom.json`
Go	`golangci-lint run`	`.iloom/package.iloom.json`

Notes:

Works with any linter via .iloom/package.iloom.json
Environment variables are automatically loaded before execution
Lint failures are reported with exit codes for CI/CD integration

il test

Run the test script for a workspace.

Usage:

il test [identifier]

Arguments:

[identifier] - Optional issue number, PR number, or branch name
If omitted and inside a loom, tests current loom
If omitted outside a loom, prompts for selection

Behavior:

Resolves the target loom or current workspace
Loads environment variables from .env files
Executes test script from:
- .iloom/package.iloom.json (highest priority)
- package.json (fallback for Node.js projects)
Exits with non-zero code if tests fail

Script Resolution:

Scripts are resolved in this order:

scripts.test in .iloom/package.iloom.json (if exists)
scripts.test in package.json (if exists)

Examples:

# Run tests for current loom (auto-detected)
il test

# Run tests for specific issue
il test 25

# Test feature branch
il test feat/my-feature

Supported Test Frameworks:

Language	Typical Command	Configuration
JavaScript/TypeScript	`vitest run` or `jest`	`.iloom/package.iloom.json` or `package.json`
Python	`pytest`	`.iloom/package.iloom.json`
Rust	`cargo test`	`.iloom/package.iloom.json`
Ruby	`bundle exec rspec`	`.iloom/package.iloom.json`
Go	`go test ./...`	`.iloom/package.iloom.json`

Notes:

Works with any test framework via .iloom/package.iloom.json
Environment variables are automatically loaded before execution
Test failures are reported with exit codes for CI/CD integration

il compile

Run the compile or typecheck script for a workspace.

Alias: typecheck

Usage:

il compile [identifier]
il typecheck [identifier]

Arguments:

[identifier] - Optional issue number, PR number, or branch name
If omitted and inside a loom, compiles current loom
If omitted outside a loom, prompts for selection

Behavior:

Resolves the target loom or current workspace
Loads environment variables from .env files
Executes compile/typecheck script from:
- .iloom/package.iloom.json (highest priority)
- package.json (fallback for Node.js projects)
Exits with non-zero code if compilation/typecheck fails

Script Resolution:

Scripts are resolved in this order:

scripts.compile in .iloom/package.iloom.json (if exists)
scripts.typecheck in .iloom/package.iloom.json (if exists)
scripts.compile in package.json (if exists)
scripts.typecheck in package.json (if exists)

Examples:

# Typecheck current loom (auto-detected)
il compile

# Or using the typecheck alias
il typecheck

# Typecheck specific issue
il compile 25

# Validate types in feature branch
il typecheck feat/my-feature

Supported Languages:

Language	Typical Command	Configuration
TypeScript	`tsc --noEmit`	`.iloom/package.iloom.json` or `package.json`
Python	`mypy src/`	`.iloom/package.iloom.json`
Rust	`cargo check`	`.iloom/package.iloom.json`
Go	`go build ./...` (no-op compile)	`.iloom/package.iloom.json`

Notes:

Works with any compiler/type checker via .iloom/package.iloom.json
Useful for catching type errors without running full test suite
Environment variables are automatically loaded before execution
Compilation failures are reported with exit codes for CI/CD integration

il install-deps

Install dependencies for a workspace.

Usage:

il install-deps [identifier]
il install-deps [identifier] --no-frozen

Arguments:

[identifier] - Optional issue number, PR number, or branch name
If omitted and inside a loom, installs for current loom
If omitted outside a loom, prompts for selection

Options:

--no-frozen - Allow lockfile updates (by default uses frozen/locked lockfiles)

Behavior:

Resolves the target loom or current workspace
Checks for install scripts in order of precedence:
- .iloom/package.iloom.local.json scripts.install (highest priority)
- .iloom/package.iloom.json scripts.install
- package.json scripts.install
If no install script found, falls back to Node.js lockfile detection:
- pnpm-lock.yaml → pnpm install --frozen-lockfile
- package-lock.json → npm ci
- yarn.lock → yarn install --frozen-lockfile
Silently skips if no install mechanism is found

Examples:

# Install deps for current loom (auto-detected)
il install-deps

# Install deps for a specific issue
il install-deps 42

# Install deps allowing lockfile updates
il install-deps --no-frozen

Supported Languages:

Language	Typical Command	Configuration
Node.js	`pnpm install`, `npm ci`, `yarn install`	Auto-detected from lockfiles
Ruby	`bundle install`	`.iloom/package.iloom.json`
Python	`poetry install`, `pip install -r requirements.txt`	`.iloom/package.iloom.json`
Rust	`cargo fetch`	`.iloom/package.iloom.json`
Go	`go mod download`	`.iloom/package.iloom.json`

Notes:

By default uses frozen lockfiles to prevent unintended dependency changes
Use --no-frozen when you intentionally want to update the lockfile
Non-Node.js projects should define an install script in .iloom/package.iloom.json
Install failures exit with non-zero code for CI/CD integration

il summary

Generate a summary of the Claude Code session for the current or specified loom.

Usage:

il summary [identifier] [options]

Arguments:

[identifier] - Optional issue number, PR number, or branch name
If omitted, auto-detects current loom from working directory

Options:

Flag	Description
`--with-comment`	Post the summary as a comment to the issue/PR
`--json`	Output as JSON (for programmatic use)

Behavior:

Auto-detects loom if no identifier provided
Generates deterministic session ID if not in metadata
Invokes Claude to reflect on the session and generate insights
Prints summary to stdout (or outputs JSON with --json)
Optionally posts as issue comment with --with-comment

Output includes:

Key themes from the development session
Insights and learnings
Decisions made and rationale
Challenges resolved
Lessons learned

Examples:

# Generate summary for current loom
il summary

# Generate summary for specific issue
il summary 25

# Generate and post as comment to issue
il summary --with-comment

# Output as JSON for scripting
il summary --json

# Combine: specific issue, post comment, JSON output
il summary 42 --with-comment --json

JSON Output Format:

{
  "success": true,
  "summary": "## iloom Session Summary\n...",
  "sessionId": "abc-123-def",
  "issueNumber": "42",
  "branchName": "feat/issue-42-feature",
  "loomType": "issue"
}

Notes:

For branch-type looms, --with-comment is silently ignored (no issue to post to)
Summary generation uses the Claude haiku model for speed
Session summaries are also auto-generated during il finish (configurable via generateSummary setting)

il shell

Open an interactive shell with workspace environment variables loaded.

Alias: terminal

Usage:

il shell [identifier]

Arguments:

[identifier] - Optional issue number, PR number, or branch name
If omitted, auto-detects current loom from working directory

Behavior:

Resolves the target loom (from identifier or current directory)
Detects appropriate shell for your platform
If sourceEnvOnStart is enabled in settings, loads all dotenv-flow environment variables
Opens interactive shell with environment ready
Prints summary of workspace and loaded environment

Shell Detection (Cross-Platform):

The shell is selected in this order:

ILOOM_SHELL environment variable (if set)
SHELL environment variable (Unix/macOS)
COMSPEC environment variable (Windows)
Default: /bin/bash (Unix) or cmd.exe (Windows)

Environment Variables Loaded:

When sourceEnvOnStart is enabled, loads dotenv-flow pattern files:

.env
.env.local
.env.{NODE_ENV}
.env.{NODE_ENV}.local

Additionally sets:

ILOOM_LOOM - The loom identifier (useful for PS1 customization)

Examples:

# Open shell for current loom (auto-detected from cwd)
il shell

# Open shell for specific issue
il shell 25

# Open shell for specific PR
il shell 42

# Open shell for branch-based loom
il shell feat/my-feature

# Using the terminal alias
il terminal 25

Notes:

Useful for running ad-hoc commands with proper environment
Great for debugging or using tools not covered by il dev-server
Environment persists for the entire shell session
Exit shell normally (Ctrl+D or exit) to return

Planning Commands

il plan

Launch an interactive planning session with an Architect persona to decompose features into child issues.

Usage:

il plan [prompt] [options]
il plan <issue-number> [options]

Arguments:

[prompt] - Optional initial planning prompt or topic for fresh planning mode
<issue-number> - Issue identifier to decompose (GitHub: #123 or 123, Linear: ENG-123)

Operating Modes:

Mode	Trigger	Description
Fresh Planning	`il plan` or `il plan "topic"`	Start a new planning session for a feature or epic
Decomposition	`il plan 123` or `il plan #123`	Break down an existing issue into child issues

Options:

Flag	Values	Description
`--model <model>`	`opus`, `sonnet`, `haiku`, `opus[1m]`, `sonnet[1m]`	Model to use (default: from settings `plan.model`, falls back to 'opus[1m]'). The `[1m]` variants use the 1M context window. `opus[1m]` requires a Max or Team plan.
`--one-shot <mode>`	`default`, `noReview`, `bypassPermissions`	One-shot automation mode (`noReview` skips confirmation gates; `bypassPermissions` skips both gates and permission prompts)
`--dangerously-skip-permissions`	-	Skip Claude permission prompts without skipping confirmation gates (composable with `--one-shot`)
`--autonomous`	-	Alias for `--one-shot=bypassPermissions` (backwards compat)
`--yolo`	-	Full autonomy shorthand: `--one-shot=bypassPermissions` + `--auto-swarm`
`--auto-swarm`	-	Auto-start swarm after planning: plan → start --epic → spin
`--planner <provider>`	`claude`, `gemini`, `codex`	AI provider for planning (default: from settings `plan.planner`, falls back to 'claude')
`--reviewer <provider>`	`claude`, `gemini`, `codex`, `none`	AI provider for plan review (default: from settings `plan.reviewer`, falls back to 'none')
`--effort`	`low`, `medium`, `high`, `max`	Set effort level for Claude (default: from settings `plan.effort`)
`-p, --print`	-	Enable print/headless mode for CI/CD (implies autonomous + `bypassPermissions`)
`--output-format`	`json`, `stream-json`, `text`	Output format for Claude CLI (requires `--print`)
`--verbose`	-	Enable verbose output (requires `--print`)

Flag Behavior Matrix:

Flag	Confirmation Gates	Permission Prompts	Auto-Swarm
`--dangerously-skip-permissions`	Active	Skipped	No
`--one-shot=noReview`	Skipped	Active	No
`--one-shot=bypassPermissions`	Skipped	Skipped	No
`--autonomous` (alias)	Skipped	Skipped	No
`--auto-swarm`	Active	Active	Yes
`--yolo`	Skipped	Skipped	Yes

All flags are composable. For example:

--dangerously-skip-permissions --auto-swarm skips permission prompts and auto-starts the swarm but keeps confirmation gates active.
--dangerously-skip-permissions --one-shot=noReview skips both permission prompts and confirmation gates.

Behavior:

Loads settings to detect issue provider (GitHub/Linear) and model preference
If an issue identifier is provided, fetches issue details, existing children, and dependencies
Launches Claude with Architect persona
Architect helps decompose features using brainstorming patterns
At session end, creates parent epic issue if none provided, and child issues with dependencies

Fresh Planning Mode:

Start a new planning session from scratch:

# Interactive session - Claude asks what you want to plan
il plan

# Provide a topic upfront
il plan "Build user authentication system"

Decomposition Mode:

Break down an existing issue into child issues:

# GitHub issue
il plan 42
il plan "#42"

# Linear issue
il plan ENG-123

In decomposition mode, the Architect:

Fetches the parent issue's title, body, and existing comments
Retrieves any existing child issues and dependencies
Helps you identify additional sub-tasks
Creates child issues with proper parent-child relationships

Multi-AI Provider Support:

Configure different AI providers for planning and review phases:

# Use Gemini for planning with Claude review
il plan --planner gemini --reviewer claude "Add OAuth support"

# Use Claude for planning with no review
il plan --planner claude --reviewer none "Fix login flow"

# Use Codex for both phases
il plan --planner codex --reviewer codex "Refactor database layer"

Autonomous Mode (--yolo):

Skip all permission prompts and proceed automatically:

# Autonomous fresh planning
il plan --yolo "Add GitLab integration"

# Autonomous decomposition
il plan --yolo 42

Warning: Autonomous mode will create issues and dependencies without confirmation. Use with caution - it can make irreversible changes to your issue tracker.

`--auto-swarm`

Enables fully autonomous execution: decompose an issue into child tasks, create an epic workspace, and launch swarm mode — all in one command with no manual intervention.

Usage:

# Decompose existing issue and auto-start swarm
il plan --auto-swarm 42

# Fresh planning with auto-swarm
il plan --auto-swarm "Build user authentication system"

Behavior:

--auto-swarm is independent of --one-shot and --dangerously-skip-permissions
Combine with --yolo for fully autonomous operation (no gates, no permission prompts)
Pipeline: plan → start --epic → spin (swarm mode)
If no child issues are created, falls back to a normal autonomous loom

Environment Variables:

ILOOM_HARNESS_SOCKET: Optional. Path to an external harness socket (e.g., provided by VS Code extension). If not set, the CLI creates its own harness server.

Error Handling:

If the plan phase fails or exits without signaling completion, the pipeline aborts
If il start fails, the pipeline aborts with an error
Spin phase uses standard swarm error handling

Available MCP Tools in Session:

Category	Tools
Issue Management	`create_issue`, `create_child_issue`, `get_issue`, `get_child_issues`, `get_comment`, `create_comment`
Dependency Management	`create_dependency`, `get_dependencies`, `remove_dependency`
Codebase Exploration	Read, Glob, Grep, Task
Web Research	WebFetch, WebSearch
Git Commands	`git status`, `git log`, `git branch`, `git remote`, `git diff`, `git show`

Configuration:

Settings file (.iloom/settings.json):

{
  "plan": {
    "model": "opus",
    "planner": "claude",
    "reviewer": "none",
    "waveVerification": true
  }
}

Setting	Values	Default	Description
`plan.model`	`opus`, `sonnet`, `haiku`, `opus[1m]`, `sonnet[1m]`	`opus[1m]`	Claude model for the planning session. The `[1m]` variants use the 1M context window. `opus[1m]` requires a Max or Team plan.
`plan.planner`	`claude`, `gemini`, `codex`	`claude`	AI provider for generating plans
`plan.reviewer`	`claude`, `gemini`, `codex`, `none`	`none`	AI provider for reviewing plans
`plan.waveVerification`	`true`, `false`	`true`	Generate verification child issues between dependency waves

Wave Verification:

When plan.waveVerification is enabled (the default), the planner generates verification child issues between dependency waves in the DAG. A "wave" is a set of issues that run in parallel at the same depth in the dependency graph. Verification issues sit between waves to catch integration mismatches early -- they compile the combined changes, run tests, and verify that shared contracts between parallel issues are compatible. This is a plan-time decision: the planner either includes verification tasks in the DAG or omits them entirely.

To disable wave verification:

{
  "plan": {
    "waveVerification": false
  }
}

Examples:

# Fresh planning - interactive session
il plan

# Fresh planning - with a topic
il plan "Build user authentication system"

# Fresh planning - with specific model
il plan --model sonnet "Add payment processing"

# Decomposition mode - break down existing issue
il plan 42

# Decomposition mode - Linear issue
il plan ENG-123

# Multi-AI provider - Gemini plans, Claude reviews
il plan --planner gemini --reviewer claude "Add OAuth support"

# Autonomous mode - skip all prompts
il plan --yolo "Add GitLab integration"

# Combine options
il plan --yolo --planner gemini --model sonnet 42

# Headless mode for CI/CD pipelines (outputs to stdout)
il plan --print "Add feature X"

# Headless mode with JSON output format
il plan --print --output-format=json 42

# Auto-swarm - fully autonomous pipeline from planning to swarm
il plan --auto-swarm 42

# Auto-swarm - fresh planning with auto-swarm
il plan --auto-swarm "Build user authentication system"

Notes:

Must be run from a git repository with a remote configured
Creates parent epic + child issues following "1 issue = 1 loom = 1 PR" pattern
Architect sets up blocking dependencies between child issues
Does NOT create a loom workspace (use il start after planning)
First run may trigger il init wizard if repository is not configured

Issue Management Commands

il issues

List open issues and open (non-draft) pull requests from the configured issue tracker as JSON. PRs are always fetched from GitHub regardless of the configured issue tracker.

Usage:

il issues [options] [project-path]

Arguments:

[project-path] - Path to project root. Auto-detected from current directory or worktree if omitted.

Options:

Flag	Description	Default
`--json`	Output as JSON (default behavior)	`true`
`--limit <n>`	Maximum number of items to return (combined issues + PRs)	`100`
`--sprint <name>`	Jira only: filter by sprint name (e.g., `"Sprint 17"`) or `"current"` for the active sprint	-
`--mine`	Show only issues and PRs assigned to the authenticated user	`false`

Output Format:

[
  {
    "id": "123",
    "title": "Issue title",
    "updatedAt": "2026-02-08T00:00:00Z",
    "url": "https://github.com/org/repo/issues/123",
    "state": "open",
    "type": "issue"
  },
  {
    "id": "456",
    "title": "[PR] PR title",
    "updatedAt": "2026-02-09T00:00:00Z",
    "url": "https://github.com/org/repo/pull/456",
    "state": "open",
    "type": "pr"
  }
]

Fields:

type - Either "issue" or "pr". PRs also have a [PR] prefix in their title for human-readable output.

Behavior:

Returns open/active issues and open, non-draft pull requests
Issues and PRs are merged, sorted by most recently updated, and truncated to the --limit
Draft PRs are excluded (filtered client-side after over-fetching from GitHub)
PRs are always fetched from GitHub, even when the issue tracker is Linear
If PR fetching fails due to expected errors (auth, rate limit, network), issues are returned without PRs
Results are cached on disk with a 2-minute TTL for fast repeated calls
Cache is stored in ~/.config/iloom-ai/cache/ and keyed per project + provider
Works from worktrees (resolves settings from the correct project root)
For issues on GitHub: uses gh issue list with --search sort:updated-desc
For issues on Linear: uses @linear/sdk with team key filter from settings
For issues on Jira: uses Jira REST API with JQL, excluding statuses listed in doneStatuses (default: ["Done"])
--sprint is Jira-only. When used with other providers, a warning is logged and the flag is ignored.
--sprint current uses Jira's openSprints() JQL function to match the active sprint
--sprint "Sprint 17" filters to a specific named sprint
--mine works across all providers: GitHub uses --assignee @me for both issues and PRs, Linear uses the SDK's assignee: { isMe: { eq: true } } filter, and Jira uses currentUser() JQL
For PRs: uses gh pr list --state open with draft filtering

Examples:

# List issues and PRs from current project
il issues

# List issues and PRs with a limit
il issues --limit 50

# List issues and PRs from a specific project path
il issues /path/to/project

# Filter to only PRs using jq
il issues | jq '.[] | select(.type == "pr")'

# Filter to only issues using jq
il issues | jq '.[] | select(.type == "issue")'

# Jira: show issues in the current sprint
il issues --sprint current

# Jira: show issues in a specific sprint
il issues --sprint "Sprint 17"

# Show only my issues and PRs (works with any provider)
il issues --mine

# Jira: my issues in the current sprint
il issues --sprint current --mine

# GitHub/Linear: my assigned issues and PRs
il issues --mine --limit 25

Notes:

Designed for programmatic use by the VS Code extension
Uses the CLI's existing settings merging logic (env vars, settings.json, settings.local.json)
Follows the same pattern as il list --json and il projects --json

il add-issue

Create and AI-enhance a new issue without starting a loom.

Alias: a

Usage:

il add-issue [options] "<description>"

Arguments:

<description> - Brief or detailed issue description

Options:

--body <text> - Pre-formatted body text (skips AI enhancement)

Workflow:

Creates issue in configured tracker (GitHub or Linear)
Runs enhancement agent to expand description (unless --body provided)
Posts enhancement as issue comment
Opens issue in browser

Examples:

# Create a new issue
il add-issue "Add dark mode toggle to settings"

# Create issue with more detail
il add-issue "Users report authentication fails after password reset. Need to investigate token refresh flow."

# Create issue with pre-formatted body (skips AI enhancement)
il add-issue "Add dark mode toggle" --body "## Requirements
- Toggle in settings page
- Persist preference in localStorage

## Acceptance Criteria
- User can switch between light and dark mode"

Notes:

Does NOT create a loom workspace
Useful for backlog grooming and planning
Enhancement makes issues more actionable for future work
Use --body when you already have detailed requirements written
Use il start <issue-number> later to begin work

il enhance

Apply AI enhancement agent to an existing issue.

Usage:

il enhance [options] <issue-number>

Arguments:

<issue-number> - Existing issue number from GitHub or Linear

Options:

Flag	Description
`--no-browser`	Skip browser opening prompt
`--author`	GitHub username to tag in questions (for CI usage)

Workflow:

Fetches existing issue
Analyzes current description and comments
Generates enhanced requirements and context
Posts enhancement as new issue comment
Opens issue in browser (unless --no-browser)

Examples:

# Enhance existing issue
il enhance 42

# Enhance without opening browser
il enhance 42 --no-browser

# Enhance and tag specific user in questions
il enhance 42 --author acreeger

# Useful for issues created before iloom adoption
il enhance 127

Notes:

Does not modify original issue description
Posts enhancement as a separate comment
Can be run multiple times as issue evolves
Does NOT create a loom workspace
Useful for CI/automation with --no-browser and --author flags

Swarm Mode (Epic Orchestration)

Swarm mode provides automatic, parallel execution of epic issues by coordinating a team of AI agents. Each child issue is implemented in its own isolated worktree by a dedicated agent, with all work merged back into the epic branch.

Prerequisites

Decompose the epic into child issues using il plan <epic-number> or by manually creating child issues
Set up dependencies between child issues (blocking relationships) so the orchestrator knows execution order
Claude CLI must be installed with a Claude Max subscription (swarm mode runs multiple agents)

Lifecycle States

Each child issue in swarm mode tracks its progress through lifecycle states:

State	Description
`pending`	Child worktree created, waiting for dependencies to complete
`in_progress`	Agent is actively implementing the issue
`code_review`	Implementation complete, under review
`done`	Successfully implemented and merged to epic branch
`failed`	Implementation failed or blocked by a failed dependency

Triggering Swarm Mode

Swarm mode is a two-step process:

Step 1: Create the epic loom

il start 100          # Auto-detect children, prompt for epic mode
il start 100 --epic   # Force epic mode
il start 100 --no-epic # Force normal loom (ignore children)

When creating an epic loom, il start:

Checks for child issues via the configured issue tracker
Fetches full details (title, body, URL) for each child issue
Builds the dependency map by querying blocking relationships between siblings
Stores all child data and the dependency map in loom metadata

Step 2: Launch swarm mode

il spin

When il spin detects an epic loom, it automatically enters swarm mode.

Dependency Map Format

The dependency map is a JSON object representing a directed acyclic graph (DAG). Keys are child issue numbers (as strings), values are arrays of issue numbers that must complete before the key issue can start.

{
  "101": [],
  "102": ["101"],
  "103": ["101"],
  "104": ["102", "103"]
}

In this example:

Issue 101 has no dependencies (starts immediately)
Issues 102 and 103 both depend on 101 (start in parallel after 101 completes)
Issue 104 depends on both 102 and 103 (starts after both complete)

Only sibling dependencies (between child issues of the same epic) are included. External blockers are filtered out.

How Agents Work

Each child agent runs in complete isolation:

The orchestrator spawns a worker for each child issue, passing its issue number, title, worktree path, and issue body
The worker implements the issue autonomously in its own worktree (branched off the epic branch)
On completion, the worker reports back to the orchestrator with status and summary

Worker Model Configuration:

The swarm worker agent defaults to opus. The swarm orchestrator defaults to opus[1m]. To override, configure them via .iloom/settings.json:

{
  "agents": {
    "iloom-swarm-worker": {
      "model": "haiku"
    }
  }
}

You can also set a different model for the spin orchestrator when running in swarm mode using swarmModel:

{
  "spin": {
    "model": "sonnet",
    "swarmModel": "opus"
  }
}

In this example, spin.model (sonnet) is used when spin runs in issue, PR, or branch mode, while spin.swarmModel (opus) is used when spin runs in swarm mode. If swarmModel is not set, the orchestrator defaults to opus[1m] in swarm mode (Balanced mode default) — it does not fall back to spin.model. Note that spin.swarmModel only affects the spin orchestrator itself — it does not affect swarm worker agents or phase agents.

Phase Agent Model Overrides (Swarm Mode):

You can configure different models for individual phase agents when they run inside swarm workers. This is useful for cost optimization (e.g., using a lighter model for enhancement but a heavier model for implementation).

Each agent supports a swarmModel field for a clean, per-agent swarm model override:

{
  "agents": {
    "iloom-issue-implementer": { "model": "opus", "swarmModel": "sonnet" },
    "iloom-issue-complexity-evaluator": { "model": "haiku", "swarmModel": "haiku" }
  }
}

If swarmModel is set for an agent, it overrides the agent's model in swarm mode. If no swarmModel is set, the Swarm Quality Mode defaults apply (see below) — not the agent's base model. This separation is intentional: swarms run many agents in parallel and costs scale quickly, so swarm model choices should always be explicit.

Important: Changing an agent's model only affects non-swarm mode (single-issue looms via il start). To change an agent's model in swarm mode, use swarmModel or choose a different Swarm Quality Mode.

With the configuration above:

Agent	Non-swarm mode	Swarm mode
`iloom-issue-implementer`	`opus` (settings)	`sonnet` (swarmModel)
`iloom-issue-complexity-evaluator`	`haiku` (settings)	`haiku` (swarmModel)
`iloom-issue-analyzer`	`opus` (default)	`opus` (default)

Example using the --set flag:

# Set per-agent swarmModel
il spin --set agents.iloom-issue-implementer.swarmModel=sonnet

# Set spin orchestrator model for swarm mode
il spin --set spin.swarmModel=sonnet

Per-Agent Artifact Review Override (Swarm Mode):

Each agent supports a swarmReview field to control whether artifact review runs in swarm mode, independent of the base review setting:

{
  "agents": {
    "iloom-issue-planner": { "review": true, "swarmReview": false },
    "iloom-issue-analyze-and-plan": { "review": true, "swarmReview": false }
  }
}

In swarm mode, only swarmReview is used — it defaults to false if not set (the base review value is ignored). This means artifact review is off by default in swarm mode for speed and cost, and must be explicitly opted into with swarmReview: true. In non-swarm mode, the base review flag is used as usual.

With the configuration above:

Agent	Non-swarm mode	Swarm mode
`iloom-issue-planner`	review enabled (`review: true`)	review disabled (`swarmReview: false`)
`iloom-issue-analyze-and-plan`	review enabled (`review: true`)	review disabled (`swarmReview: false`)
`iloom-issue-analyzer`	review disabled (default)	review disabled (default)

Example using the --set flag:

# Disable planner review in swarm mode
il spin --set agents.iloom-issue-planner.swarmReview=false

# Enable planner review in swarm mode (when base review is disabled)
il spin --set agents.iloom-issue-planner.swarmReview=true

Swarm Quality Mode:

During il init, you'll be asked to choose a swarm quality mode that tunes the trade-off between reasoning quality and speed/cost:

Mode	Focus	Models used	Best for
Maximum Quality	Deepest reasoning, best analysis	Opus[1m] orchestrator; Opus everywhere else (complexity evaluator stays Haiku)	Complex epics, critical features
Balanced (default)	Strong reasoning at a practical pace	Opus[1m]: orchestrator. Opus: worker, analyzer, analyze-and-plan. Sonnet: planner, implementer, enhancer, code-reviewer. Haiku: complexity evaluator	Most tasks
Fast & Cheap	Quick iterations, lowest cost	Haiku everywhere	Simple tasks, rapid prototyping

The complexity evaluator always stays on Haiku regardless of mode, since it performs a simple classification task that does not benefit from a larger model.

Example settings for each mode:

Maximum Quality:

{
  "spin": { "swarmModel": "opus[1m]" },
  "agents": {
    "iloom-swarm-worker": { "model": "opus" },
    "iloom-issue-analyzer": { "swarmModel": "opus" },
    "iloom-issue-planner": { "swarmModel": "opus" },
    "iloom-issue-implementer": { "swarmModel": "opus" },
    "iloom-issue-enhancer": { "swarmModel": "opus" },
    "iloom-issue-analyze-and-plan": { "swarmModel": "opus" },
    "iloom-code-reviewer": { "swarmModel": "opus" },
    "iloom-issue-complexity-evaluator": { "swarmModel": "haiku" }
  }
}

Balanced (recommended default):

{
  "spin": { "swarmModel": "opus" },
  "agents": {
    "iloom-swarm-worker": { "model": "opus" },
    "iloom-issue-analyzer": { "swarmModel": "opus" },
    "iloom-issue-planner": { "swarmModel": "sonnet" },
    "iloom-issue-implementer": { "swarmModel": "sonnet" },
    "iloom-issue-enhancer": { "swarmModel": "sonnet" },
    "iloom-issue-analyze-and-plan": { "swarmModel": "opus" },
    "iloom-code-reviewer": { "swarmModel": "sonnet" },
    "iloom-issue-complexity-evaluator": { "swarmModel": "haiku" }
  }
}

Fast & Cheap:

{
  "spin": { "swarmModel": "haiku" },
  "agents": {
    "iloom-swarm-worker": { "model": "haiku" },
    "iloom-issue-analyzer": { "swarmModel": "haiku" },
    "iloom-issue-planner": { "swarmModel": "haiku" },
    "iloom-issue-implementer": { "swarmModel": "haiku" },
    "iloom-issue-enhancer": { "swarmModel": "haiku" },
    "iloom-issue-analyze-and-plan": { "swarmModel": "haiku" },
    "iloom-code-reviewer": { "swarmModel": "haiku" },
    "iloom-issue-complexity-evaluator": { "swarmModel": "haiku" }
  }
}

These modes only affect swarm behavior — non-swarm sessions continue using each agent's base model setting.

To configure, run il init — you'll be asked during setup, or you can change it later in the advanced configuration section.

Effort Configuration

Effort levels control Claude's reasoning depth.

Valid effort levels: low, medium, high, max

When no effort is configured, iloom does not set the environment variable, deferring to Claude Code's own default (which respects any /effort session setting the user has configured).

Global Effort Settings:

Configure default effort levels for spin and plan commands in .iloom/settings.json:

{
  "spin": {
    "effort": "high"
  },
  "plan": {
    "effort": "high"
  }
}

Swarm Orchestrator Effort:

Set the effort level for the swarm orchestrator using spin.swarmEffort. This defaults to medium when not configured:

{
  "spin": {
    "effort": "high",
    "swarmEffort": "medium"
  }
}

In this example, spin.effort (high) is used when spin runs in single-issue mode, while spin.swarmEffort (medium) is used for the swarm orchestrator.

Per-Agent Effort Overrides:

Each agent supports effort and swarmEffort fields, following the same pattern as model overrides:

{
  "agents": {
    "iloom-issue-analyzer": { "effort": "high", "swarmEffort": "high" },
    "iloom-issue-implementer": { "effort": "high", "swarmEffort": "medium" },
    "iloom-issue-complexity-evaluator": { "effort": "low", "swarmEffort": "low" }
  }
}

effort overrides the agent's effort level in non-swarm mode
swarmEffort overrides the agent's effort level in swarm mode

Default Swarm Effort Levels:

When no user configuration is provided, swarm agents use these defaults:

Agent	Default Swarm Effort
`iloom-issue-analyzer`	`high`
`iloom-issue-analyze-and-plan`	`high`
`iloom-issue-planner`	`high`
`iloom-issue-implementer`	`medium`
`iloom-issue-enhancer`	`medium`
`iloom-code-reviewer`	`medium`
`iloom-issue-complexity-evaluator`	`high`

Effort Resolution Order:

Effort is resolved with the following priority (highest first):

CLI flag (--effort)
Loom metadata (set via il start --effort)
Settings (spin.effort / plan.effort)
No effort set (defers to Claude Code default)

Example using the --set flag:

# Set spin effort
il spin --set spin.effort=high

# Set swarm orchestrator effort
il spin --set spin.swarmEffort=medium

# Set per-agent effort
il spin --set agents.iloom-issue-implementer.effort=high

# Set per-agent swarm effort
il spin --set agents.iloom-issue-implementer.swarmEffort=medium

Merge Strategy

When a child agent completes successfully:

The orchestrator navigates to the epic worktree
Rebases the child's branch onto the epic branch and fast-forward merges for clean linear history
If merge conflicts occur, a subagent is spawned to resolve them
If conflict resolution fails, the merge is aborted and the child is marked as failed
The child's metadata state is updated to done
Any newly unblocked children are spawned

Failure Handling

Swarm mode is designed to maximize throughput despite individual failures:

Failed agents are marked as failed but do not halt the orchestrator
Downstream dependencies of a failed child are also marked as failed (with reason: blocked by failed dependency)
Unrelated children continue executing normally
Merge conflicts that cannot be auto-resolved cause the child to be marked failed; the merge is aborted cleanly
A final summary reports the status of all children with success/failure counts

File Structure

During swarm mode, the following files are created:

~/project-looms/
├── epic-issue-100/                    # Epic worktree
│   └── .claude/
│       └── agents/
│           ├── iloom-swarm-worker.md              # Worker agent with full iloom workflow
│           ├── iloom-swarm-issue-implementer.md   # Swarm agent definitions
│           └── ...
├── issue-101/                         # Child worktree (branched off epic)
│   ├── .claude/
│   │   └── agents/                    # Copied from epic worktree during setup (not committed)
│   │       ├── iloom-swarm-worker.md
│   │       ├── iloom-swarm-issue-implementer.md
│   │       └── ...
│   └── iloom-metadata.json            # state: pending -> in_progress -> done
├── issue-102/                         # Another child worktree
│   └── iloom-metadata.json
└── ...

Swarm agent files are not committed to the repository.

Configuration & Maintenance

il init / il config

Interactive configuration wizard powered by Claude.

Aliases: init, config, configure

Usage:

il init [description]
il config [description]

Arguments:

[description] - Optional natural language description of what to configure

Workflow:

Without description (standard wizard):

Detects project type and existing configuration
Guides through all configuration options
Creates/updates .iloom/settings.json and .iloom/settings.local.json
Sets up .gitignore entries
Validates configuration

With description (natural language):

Claude interprets your intent
Focuses on specific configuration areas
Makes targeted updates

Examples:

# Standard interactive wizard
il init

# Natural language configuration
il init "set my IDE to windsurf and help me configure linear"
il init "switch to pr merge mode"
il init "configure neon database with project ID abc-123"

Configuration Areas:

Issue tracker (GitHub/Linear/Jira)
Database provider (Neon)
IDE preference (VS Code, Cursor, Windsurf, etc.)
Merge behavior (local, pr, draft-pr)
Permission modes
Project type (web app, CLI tool, etc.)
Base port for development servers
Environment variable names

GitHub Advanced Settings:

The following GitHub settings can be configured in .iloom/settings.json under issueManagement.github:

Setting	Type	Default	Description
`remote`	string	`"origin"`	Git remote name used for GitHub operations
`defaultLabels`	string[]	`[]`	Labels to automatically apply to issues created by iloom agents. Merged with any labels the agent supplies (configured first, then agent-supplied, case-sensitive dedupe). Example: `["ai-generated", "needs-triage"]`. Labels must already exist on the target repository — `gh` errors if an unknown label is supplied.

Jira Advanced Settings:

The following Jira settings can be configured in .iloom/settings.json under issueManagement.jira:

Setting	Type	Default	Description
`host`	string	(required)	Jira instance URL (e.g., `"https://yourcompany.atlassian.net"`)
`username`	string	(required)	Jira username or email address
`apiToken`	string	(required)	Jira API token (store in `settings.local.json`)
`projectKey`	string	(required)	Jira project key (e.g., `"PROJ"`, `"ENG"`)
`boardId`	string	-	Jira board ID for sprint filtering
`transitionMappings`	object	-	Map iloom states to Jira transition names (e.g., `{"In Review": "Start Review"}`)
`defaultIssueType`	string	`"Task"`	Issue type name for creating issues (e.g., `"Task"`, `"Story"`, `"Bug"`)
`defaultSubtaskType`	string	`"Subtask"`	Issue type name for creating child issues (e.g., `"Subtask"`, `"Sub-task"`)
`doneStatuses`	string[]	`["Done"]`	Status names to exclude from `il issues` output
`defaultLabels`	string[]	`[]`	Labels to automatically apply to issues created by iloom agents. Merged with any labels the agent supplies (configured first, then agent-supplied, case-sensitive dedupe). Example: `["ai-generated", "needs-triage"]`. Jira labels cannot contain whitespace — iloom rejects offending labels with a clear error before calling the API.

Note: Different Jira instances may use different issue type names. If issue creation fails with a 400 error, check your Jira project's available issue types and configure defaultIssueType and defaultSubtaskType accordingly.

Version Control (VCS) Provider Settings:

iloom supports multiple version control providers for PR operations. By default, GitHub is used via the gh CLI. For BitBucket Cloud, configure the following in .iloom/settings.json:

Setting	Type	Default	Description
`versionControl.provider`	`"github"` \| `"bitbucket"`	`"github"`	VCS provider for PR operations
`versionControl.bitbucket.username`	string	(required)	BitBucket username
`versionControl.bitbucket.apiToken`	string	(required)	BitBucket API token (store in `settings.local.json`)
`versionControl.bitbucket.workspace`	string	(auto-detected)	BitBucket workspace slug
`versionControl.bitbucket.repoSlug`	string	(auto-detected)	Repository slug
`versionControl.bitbucket.reviewers`	string[]	-	Usernames to add as PR reviewers

Example Configuration:

.iloom/settings.json:

{
  "versionControl": {
    "provider": "bitbucket",
    "bitbucket": {
      "username": "your-username",
      "workspace": "your-workspace",
      "reviewers": ["reviewer1", "reviewer2"]
    }
  }
}

.iloom/settings.local.json (gitignored):

{
  "versionControl": {
    "bitbucket": {
      "apiToken": "your-api-token"
    }
  }
}

Supported Provider Combinations:

GitHub Issues + GitHub VCS (default)
GitHub Issues + BitBucket VCS
Linear Issues + BitBucket VCS
Jira Issues + BitBucket VCS

Note: Draft PR mode (mergeBehavior.mode: "draft-pr") is GitHub-only. BitBucket does not support draft pull requests.

il update

Update iloom CLI to the latest version.

Usage:

il update [options]

Options:

Flag	Description
`--dry-run`	Show what would be done without actually updating

Workflow:

Checks npm registry for latest version
Compares with currently installed version
If update available, installs latest version
Displays changelog/release notes

Examples:

# Check for updates and install if available
il update

# Preview update without installing
il update --dry-run

Notes:

Uses npm global install under the hood
Preserves your configuration files
Safe to run at any time

il feedback

Submit bug reports or feature requests directly to the iloom repository.

Alias: f

Usage:

il feedback [options] "<description>"

Arguments:

<description> - Natural language description of feedback (must be >50 chars with >2 spaces)

Options:

Flag	Description
`--body`	Body text for feedback (added after diagnostics)

Workflow:

Creates new issue in iloom-cli repository
Opens issue in browser for you to add context
Within minutes, iloom's enhancement agent processes your feedback
Issue is prioritized and reviewed

Examples:

# Report a bug
il feedback "The worktree cleanup seems to leave temp files behind"

# Request a feature
il feedback "Add support for GitLab issue tracking"

# Report unexpected behavior
il feedback "Tests fail on finish but Claude doesn't launch to help fix"

Best Practices:

Be specific about what you expected vs. what happened
Include environment details (OS, Node version) for bugs
Mention the command or workflow that had issues
Suggest improvements or alternative approaches

il contribute

Fork, clone, and set up a GitHub repository for contribution (defaults to iloom-cli).

Usage:

il contribute [repository]

Arguments:

[repository] - GitHub repository to contribute to (defaults to iloom-cli)
- Full URL: https://github.com/owner/repo
- Short URL: github.com/owner/repo
- Owner/repo: owner/repo

Workflow:

Forks the repository to your GitHub account (if not already forked)
Clones your fork locally
Sets up upstream remote to track the original repository
Configures iloom settings:
- Sets issueManagement.github.remote to upstream
- Sets mergeBehavior.mode to draft-pr

Examples:

# Set up iloom development environment (default)
il contribute

# Contribute to any GitHub repository
il contribute "https://github.com/n8n-io/n8n"
il contribute "github.com/vercel/next.js"
il contribute "facebook/react"

Notes:

Requires GitHub CLI (gh) to be authenticated
Creates fork if it doesn't exist
Sets up draft-pr mode so PRs are created immediately when you start work
Draft PRs receive iloom's AI analysis and planning comments, giving maintainers full context
For iloom contributions, see CONTRIBUTING.md for detailed guidelines

il telemetry

Manage anonymous usage telemetry settings.

Usage:

il telemetry <subcommand>

Subcommands:

Subcommand	Description
`off`	Disable anonymous usage telemetry. No data will be collected or sent.
`on`	Re-enable anonymous usage telemetry.
`status`	Show current telemetry state (enabled/disabled) and the anonymous identifier.

Examples:

# Disable telemetry
il telemetry off

# Re-enable telemetry
il telemetry on

# Check current telemetry status
il telemetry status

First-Run Disclosure:

On first run, iloom displays a disclosure message informing you that anonymous telemetry is enabled by default and how to opt out. This message is shown once and not repeated.

Privacy:

For details on what data is and is not collected, see the Telemetry section in the README.

Global Flags

Some flags work across multiple commands:

Flag	Commands	Description
`--one-shot`	`start`, `spin`, `plan`	Automation level for Claude workflows
`--yolo`	`start`, `spin`, `plan`	Shorthand for `--one-shot=bypassPermissions` (autonomous mode)
`--dangerously-skip-permissions`	`start`, `plan`	Skip Claude permission prompts without skipping workflow gates
`--force`, `-f`	`finish`, `rebase`	Skip confirmation prompts
`--dry-run`, `-n`	`finish`, `rebase`	Preview without executing
`--help`, `-h`	All commands	Display command help
`--version`, `-v`	All commands	Display iloom version

Environment Variables

iloom respects these environment variables:

Variable	Description	Default
`ILOOM_SETTINGS_PATH`	Override default settings file location	`~/.config/iloom-ai/settings.json`
`ILOOM_NO_COLOR`	Disable colored output	`false`
`ILOOM_DEBUG`	Enable debug logging	`false`
`ILOOM_DEV_SERVER_TIMEOUT`	Dev server startup timeout in milliseconds	`180000` (180 seconds)
`CLAUDE_API_KEY`	Claude API key (if not using Claude CLI)	-
`JIRA_HOST`	Jira instance URL (MCP server)	-
`JIRA_USERNAME`	Jira username/email (MCP server)	-
`JIRA_API_TOKEN`	Jira API token (MCP server)	-
`JIRA_PROJECT_KEY`	Jira project key (MCP server)	-
`JIRA_DEFAULT_ISSUE_TYPE`	Default issue type for Jira issue creation (MCP server)	`"Task"`
`JIRA_DEFAULT_SUBTASK_TYPE`	Default subtask type for Jira child issue creation (MCP server)	`"Subtask"`

Additional Resources

Main README - Overview and quick start
Configuration Guide - Detailed configuration options
Troubleshooting Guide - Common issues and solutions
Contributing Guide - How to contribute to iloom

FilesExpand file tree

iloom-commands.md

Latest commit

History

iloom-commands.md

File metadata and controls

iloom Command Reference

Table of Contents

Core Workflow Commands

il start

il commit

il finish

il rebase

il cleanup

il list

Context & Development Commands

il spin

il open

il vscode

il dev-server

Docker Dev Server Mode

il build

il lint

il test

il compile

il install-deps

il summary

il shell

Planning Commands

il plan

--auto-swarm

Issue Management Commands

il issues

il add-issue

il enhance

Swarm Mode (Epic Orchestration)

Prerequisites

Lifecycle States

Triggering Swarm Mode

Dependency Map Format

How Agents Work

Effort Configuration

Merge Strategy

Failure Handling

File Structure

Configuration & Maintenance

il init / il config

il update

il feedback

il contribute

il telemetry

Global Flags

Environment Variables

Additional Resources

`--auto-swarm`