# Loom [![CI](https://github.com/aidan-bailey/loom/actions/workflows/build.yml/badge.svg)](https://github.com/aidan-bailey/loom/actions/workflows/build.yml) [![GitHub Release](https://img.shields.io/github/v/release/aidan-bailey/loom)](https://github.com/aidan-bailey/loom/releases/latest) Loom is a terminal app that manages multiple [Claude Code](https://github.com/anthropics/claude-code), [Codex](https://github.com/openai/codex), [Gemini](https://github.com/google-gemini/gemini-cli) (and other local agents including [Aider](https://github.com/Aider-AI/aider)) in separate workspaces, allowing you to work on multiple tasks simultaneously. ### Origin > Loom was forked from [smtg-ai/claude-squad](https://github.com/smtg-ai/claude-squad) at v1.0.17 (April 2026) and has diverged substantially since. See [NOTICE.md](NOTICE.md) for details. ### Highlights - Complete tasks in the background (including yolo / auto-accept mode!) - Manage instances and tasks in one terminal window - Review changes before applying them, checkout changes before pushing them - Each task gets its own isolated git workspace, so no conflicts - Lua-scripted keymap and a workspace registry for multi-repo flows - Agents run under a background daemon, so they keep working after you quit loom, and every terminal you open shows the same sessions - Drive sessions from the shell or a script (`loom session new`, `list`, `send`, `pause`, `resume`, `kill`), and queue their heavy work against the host's CPU and memory caps (`loom job`) - Spread Claude sessions across several Claude accounts (`loom account`) - Watch and steer the fleet from an iPhone, with a notification when a session waits on you or finishes (`loom web`; see [Use Loom from Your Phone](USAGE.md#use-loom-from-your-phone)) ### Installation Loom installs as the `loom` binary. ```bash curl -fsSL https://raw.githubusercontent.com/aidan-bailey/loom/main/install.sh | bash ``` This puts the `loom` binary in `~/.local/bin`. To use a custom name for the binary: ```bash curl -fsSL https://raw.githubusercontent.com/aidan-bailey/loom/main/install.sh | bash -s -- --name ``` ### Prerequisites - [tmux](https://github.com/tmux/tmux/wiki/Installing) - [gh](https://cli.github.com/) ### Usage ``` Usage: loom [directory] [flags] loom [command] Available Commands: account Manage the Claude accounts sessions can run on completion Generate the autocompletion script for the specified shell debug Print debug information like config paths help Help about any command reset Delete a workspace's instances, tmux sessions, worktrees, and their branches (destructive) serve Run the loom daemon for this global config dir (loom starts it when needed) session Create, list and drive a workspace's sessions sweep Delete idle and paused sessions' unused Rust binaries version Print the version number of loom web Serve loom's fleet to a paired phone: enable, disable, pair, devices, revoke, status workspace Manage workspaces Flags: -h, --help help for loom --log-level string Override log level for the Structured logger (debug|info|warn|error). Takes precedence over LOOM_LOG_LEVEL. --no-scripts Skip loading ~/.loom/scripts (embedded defaults still load). Use to recover from a broken user script. -p, --program string Program to run in new instances (e.g. 'aider --model ollama_chat/gemma3:1b') -v, --version version for loom -w, --workspace string Open the named workspace (instead of the saved tabs or the startup picker) ``` Run the application with: ```bash loom ``` The first `loom` starts the loom daemon, which owns your sessions and keeps them running after you quit; see [The Loom Daemon](USAGE.md#the-loom-daemon). [USAGE.md](USAGE.md) is the full reference: every key, command and setting. NOTE: The default program is `claude` and we recommend using the latest version. Using Loom with other AI assistants: - For [Codex](https://github.com/openai/codex): Set your API key with `export OPENAI_API_KEY=` - Launch with specific assistants: - Codex: `loom -p "codex"` - Aider: `loom -p "aider ..."` - Gemini: `loom -p "gemini"` - Make this the default, by modifying the config file (locate with `loom debug`) #### Menu The menu at the bottom of the screen shows available commands: ##### Instance/Session Management - `n` - Create a new session - `N` - Create a new session with a prompt - `D` - Kill (delete) the selected session - `↑/k`, `↓/j` - Navigate between sessions ##### Actions - `i`/`ctrl-a` - Attach to the selected agent to reprompt - `ctrl-q` - Detach from session - `p` - Commit and push branch to github - `s` - Pause. Stops the session's agent, keeping its worktree - `r` - Resume a paused session - `?` - Show help menu ##### Navigation - `tab` - Toggle the overview (fleet card grid) / focus view - `]`/`[` - Jump to the next/previous agent waiting for input - `d` - Toggle the diff overlay - `q` - Quit the application - `shift-↓/↑` - scroll the active pane ### Configuration Loom stores its configuration in `~/.loom/config.json`, and a workspace's own `/.loom/config.json` overrides it. You can find the exact path by running `loom debug`. #### Migration from claude-squad On first launch, Loom renames `~/.claude-squad/` → `~/.loom/` atomically so your in-flight instances, worktrees, and scripts continue to work. Live tmux sessions with the legacy `claudesquad_` prefix are renamed to `loom_` before reconciliation so running agents keep their panes. The `CLAUDE_SQUAD_HOME`, `CLAUDE_SQUAD_LOG_LEVEL`, and `CLAUDE_SQUAD_LOG_FORMAT` environment variables are still honored as deprecated fallbacks with a one-time warning; the preferred names are `LOOM_HOME`, `LOOM_LOG_LEVEL`, and `LOOM_LOG_FORMAT`. #### Profiles Profiles let you define multiple named program configurations and switch between them when creating a new session. When more than one profile is defined, the session creation overlay shows a profile picker that you can navigate with `←`/`→`. To configure profiles, add a `profiles` array to your config file and set `default_program` to the name of the profile to select by default: ```json { "default_program": "claude", "profiles": [ { "name": "claude", "program": "claude" }, { "name": "codex", "program": "codex" }, { "name": "aider", "program": "aider --model ollama_chat/gemma3:1b" } ] } ``` Each profile has two fields: | Field | Description | |-----------|----------------------------------------------------------| | `name` | Display name shown in the profile picker | | `program` | Shell command used to launch the agent for that profile | If no profiles are defined, Loom uses `default_program` directly as the launch command (the default is `claude`). ### FAQs #### Failed to start new session If you get an error like `failed to start new session: timed out waiting for tmux session`, update the underlying program (ex. `claude`) to the latest version. ### How It Works 1. **tmux** to create isolated terminal sessions for each agent 2. **git worktrees** to isolate codebases so each session works on its own branch 3. **A daemon** (`loom serve`) that owns every session and serves every loom you open, the `loom` commands and the phone app 4. A simple TUI interface for easy navigation and management ### License [AGPL-3.0](LICENSE.md)