loom

command module
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 12, 2026 License: AGPL-3.0 Imports: 26 Imported by: 0

README

Loom CI GitHub Release

Loom is a terminal app that manages multiple Claude Code, Codex, Gemini (and other local agents including Aider) in separate workspaces, allowing you to work on multiple tasks simultaneously.

Origin

Loom was forked from smtg-ai/claude-squad at v1.0.17 (April 2026) and has diverged substantially since. See 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
Installation

Loom installs as the loom binary.

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:

curl -fsSL https://raw.githubusercontent.com/aidan-bailey/loom/main/install.sh | bash -s -- --name <your-binary-name>
Prerequisites
Usage
Usage:
  loom [directory] [flags]
  loom [command]

Available Commands:
  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)
  version     Print the version number of loom
  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   Select workspace by name (bypasses auto-detection)

Run the application with:

loom

NOTE: The default program is claude and we recommend using the latest version.

Using Loom with other AI assistants:

  • For Codex: Set your API key with export OPENAI_API_KEY=<your_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 - Stash. Stashes changes and pauses the session
  • 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. 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:

{
  "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 simple TUI interface for easy navigation and management
License

AGPL-3.0

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
Package account manages the extra Claude Code accounts loom can launch sessions under.
Package account manages the extra Claude Code accounts loom can launch sessions under.
Package app is the Bubble Tea application layer: the controller that owns the home model, routes keyboard input, and composes the ui view components.
Package app is the Bubble Tea application layer: the controller that owns the home model, routes keyboard input, and composes the ui view components.
cmd
Package cmd holds `loom workspace migrate` and the subprocess seam the rest of Loom shells out through.
Package cmd holds `loom workspace migrate` and the subprocess seam the rest of Loom shells out through.
Package config owns Loom's on-disk configuration, app state, profile catalog, and workspace registry.
Package config owns Loom's on-disk configuration, app state, profile catalog, and workspace registry.
Package core is loom's session model: the loaded workspaces and their instances, and everything that acts on them without a terminal: loading and saving, reconcile and the sweeps, the lifecycle operations and their completions, the health tick and the background jobs.
Package core is loom's session model: the loaded workspaces and their instances, and everything that acts on them without a terminal: loading and saving, reconcile and the sweeps, the lifecycle operations and their completions, the health tick and the background jobs.
rpc
Package rpc carries core.Core over a connection (daemon stage 2): newline-delimited JSON frames, a Server serving a core.Loop, and a Client implementing core.Core.
Package rpc carries core.Core over a connection (daemon stage 2): newline-delimited JSON frames, a Server serving a core.Loop, and a Client implementing core.Core.
rpc/internal/gen
Package gen generates core/rpc's wire code from core.Core (core/iface.go): every method's parameter and result types, the method table, the server's dispatch, and the client's methods.
Package gen generates core/rpc's wire code from core.Core (core/iface.go): every method's parameter and result types, the method table, the server's dispatch, and the client's methods.
rpc/internal/gen/cmd command
Command cmd writes core/rpc/methods_gen.go from core/iface.go.
Command cmd writes core/rpc/methods_gen.go from core/iface.go.
internal
cli
Package cli holds the `loom workspace` and `loom account` subcommands, which are clients of the loom daemon (daemon stage 3C+4), and the daemon half of `loom reset` (Reset).
Package cli holds the `loom workspace` and `loom account` subcommands, which are clients of the loom daemon (daemon stage 3C+4), and the daemon half of `loom reset` (Reset).
daemon
Package daemon runs `loom serve`, the process that owns a global config dir's sessions (daemon stage 3B), and finds it for its clients.
Package daemon runs `loom serve`, the process that owns a global config dir's sessions (daemon stage 3B), and finds it for its clients.
devsandbox
Package devsandbox creates and drives isolated loom dev environments: a named directory holding a dev build, a toy workspace repo, seeded config, and a private tmux server, so a dev loom can run from inside a loom pane without touching the host's sessions or state.
Package devsandbox creates and drives isolated loom dev environments: a named directory holding a dev build, a toy workspace repo, seeded config, and a private tmux server, so a dev loom can run from inside a loom pane without touching the host's sessions or state.
exec
Package exec provides the shared subprocess-runner interface used by the rest of the codebase to invoke git, gh, and tmux without binding production call sites to os/exec directly.
Package exec provides the shared subprocess-runner interface used by the rest of the codebase to invoke git, gh, and tmux without binding production call sites to os/exec directly.
testenv
Package testenv keeps test binaries off the developer's real loom and Claude state.
Package testenv keeps test binaries off the developer's real loom and Claude state.
testpty
Package testpty gives tests a stand-in for a tmux attach client's PTY.
Package testpty gives tests a stand-in for a tmux attach client's PTY.
Package keys defines the enumerated KeyName values that identify built-in actions and the GlobalkeyBindings map used to render them in the menu bar.
Package keys defines the enumerated KeyName values that identify built-in actions and the GlobalkeyBindings map used to render them in the menu bar.
Package log is Loom's centralized logging surface.
Package log is Loom's centralized logging surface.
Package review holds the comment model and on-disk store for the workbench review tab.
Package review holds the comment model and on-disk store for the workbench review tab.
Package script provides a sandboxed Lua scripting surface that binds keys in the TUI to actions.
Package script provides a sandboxed Lua scripting surface that binds keys in the TUI to actions.
Package session owns the core domain: a running AI coding agent represented by the Instance type.
Package session owns the core domain: a running AI coding agent represented by the Instance type.
agent
Package agent consolidates program-specific knowledge for the supported coding agents (claude, aider, gemini, etc.).
Package agent consolidates program-specific knowledge for the supported coding agents (claude, aider, gemini, etc.).
claudetmp
Package claudetmp finds, archives and restores the per-session temp directory Claude Code keeps outside the worktree: <root>/<encoded cwd>/<session id>/{scratchpad,tasks}/.
Package claudetmp finds, archives and restores the per-session temp directory Claude Code keeps outside the worktree: <root>/<encoded cwd>/<session id>/{scratchpad,tasks}/.
files
Package files provides filesystem enumeration helpers for the file explorer overlay.
Package files provides filesystem enumeration helpers for the file explorer overlay.
git
Package git encapsulates the per-session git worktree: creation, diff stats, push, and cleanup.
Package git encapsulates the per-session git worktree: creation, diff stats, push, and cleanup.
github
Package github reads GitHub state through the gh CLI for loom's session cards and issue picker.
Package github reads GitHub state through the gh CLI for loom's session cards and issue picker.
hooks
Package hooks is loom's side of the Claude Code hooks it registers at launch: the per-instance folder layout, the settings file and hook command, and the scan that turns the files the hooks write into Events.
Package hooks is loom's side of the Claude Code hooks it registers at launch: the per-instance folder layout, the settings file and hook command, and the scan that turns the files the hooks write into Events.
launch
Package launch is a Claude session's launch options and their composition into (and decoding from) the agent command line: remote control, permission mode, model, effort, plus the options that never reach the command line (Headroom proxy, the 1h cache TTL, the branch prefix, the account).
Package launch is a Claude session's launch options and their composition into (and decoding from) the agent command line: remote control, permission mode, model, effort, plus the options that never reach the command line (Headroom proxy, the 1h cache TTL, the branch prefix, the account).
subagent
Package subagent tracks the subagents and agent-team teammates a Claude session has spawned, from the hook events session/hooks collects.
Package subagent tracks the subagents and agent-team teammates a Claude session has spawned, from the hook events session/hooks collects.
tmux
Package tmux manages the tmux sessions that drive each agent.
Package tmux manages the tmux sessions that drive each agent.
vt
Package vt defines Loom's pane-display abstraction.
Package vt defines Loom's pane-display abstraction.
tools
claudemd command
Command claudemd holds the repo's docs to the conventions the root CLAUDE.md sets out.
Command claudemd holds the repo's docs to the conventions the root CLAUDE.md sets out.
fakeagent command
Command fakeagent is a deterministic, token-free stand-in for an AI coding agent, used by loom's dev sandbox (tools/loomdev).
Command fakeagent is a deterministic, token-free stand-in for an AI coding agent, used by loom's dev sandbox (tools/loomdev).
loomdev command
Command loomdev manages isolated loom dev sandboxes so a dev build can be run, driven, and screenshotted from inside loom without touching the host loom's tmux sessions or state.
Command loomdev manages isolated loom dev sandboxes so a dev build can be run, driven, and screenshotted from inside loom without touching the host loom's tmux sessions or state.
ui
Package ui holds Loom's Bubble Tea view components.
Package ui holds Loom's Bubble Tea view components.
overlay
Package overlay implements the modal dialogs layered above the main TUI — the text-input overlay for new instances and prompts, the confirmation overlay for destructive actions, and the branch, profile, and workspace pickers.
Package overlay implements the modal dialogs layered above the main TUI — the text-input overlay for new instances and prompts, the confirmation overlay for destructive actions, and the branch, profile, and workspace pickers.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL