loom CLI & loom mcp reference

Loom exposes one inbound control bus with two faces. Use whichever fits your context — they route to the same operations over the unix socket at $LOOM_SOCK:

• loom <subcommand> — shell out from inside a pane. Always available; the pane’s child gets LOOM_SOCK / LOOM_PANE / LOOM_BIN injected and the CLI on PATH.
• loom mcp tools — model-native tools, if the MCP server is wired into your agent. Same ops, same routing.

Panes are addressed by their display name (get names from list). These commands only work from a process launched inside a Loom pane; outside Loom ($LOOM_PANE empty) they are inert no-ops by design.

loom CLI

# Panes
loom list                                   # every pane: name, live/dead, workspace, * = focused
loom send <pane> <text...> [--no-enter]     # type text into a pane, Enter by default
loom send <pane>                            # no text → reads stdin (pipe-friendly)
loom spawn [--name N] [--cwd D] <command...>  # open a new pane running a command
loom read <pane> [-n LINES]                 # capture the tail of a pane's scrollback (default 50, max 2000)
loom broadcast [--workspace W] [--no-enter] [--dry-run] <text...>   # send to every live pane
loom focus <pane>                           # switch to the pane's workspace and focus it

# Signalling
loom attention [pane] [--clear]             # raise/drop a pane's amber "needs you" border
loom status [pane] <text...> | [pane] --clear   # set/clear a pane's short status label
loom role [pane] <name> | [pane] --clear    # tag a pane's role (targetable as role:<name>)

# Fleet coordination
loom note set|get|list|del <key> [value...] [-w WS]   # the shared per-project blackboard
loom claim <path>                           # advisory file lock ("I'm working here")
loom release <path> [--force]               # release a claim (--force breaks someone else's)
loom claims                                 # list current claims (path + holder)
loom hold <path>                            # gate a path behind a human
loom gate [pane] [--reason R] | --clear | --list   # hold a pane's inbound bus input
loom ask <pane> <question...> [--timeout S]   # request/response RPC; waits for a reply (default 300s)
loom reply <id> <answer...>                 # answer an ask (id from the "[loom ask #N ...]" prompt)

# Task board
loom card add <title...> [-p PROMPT] [-c CMD] [-w WS]   # add a To-do card to the task board
loom card list [-w WS]                          # list cards: id, title, status
loom card move <id> <todo|done|failed> [-w WS]  # move a card between lanes
loom card drain <on|off> [--cap N] [-w WS]      # auto-dispatch To-do cards, keeping N panes busy

# Agents
loom hooks [--print] | --install [--user|--project]   # install Claude Code lifecycle hooks

Details & gotchas

• send — everything after the pane name is joined with spaces and typed, then Enter. Use --no-enter to leave the line unsubmitted. With no text it reads stdin, so echo "prompt" | loom send Cleo and git log | loom send Cleo work.
• spawn — the first non-flag token starts the command; everything after it is taken verbatim (dashes included), so loom spawn --name worker claude --resume works. End flag parsing with -- to be explicit: loom spawn --name w -- claude --resume. Returns the spawned pane’s name.
• read — an explicit, requested read of scrollback (-n/--lines to bound it). Loom still never watches the stream; you asked for a snapshot.
• broadcast — fans text to every live pane in the active workspace (-w targets another). Agent-driven only — there is no human broadcast bar.
• attention / status / role — with no pane argument they target your own pane ($LOOM_PANE), so an agent can flag itself blocked, label what it’s doing, or tag its role. Lead with -- if the text starts with a dash. The attention border clears when the pane is focused. A role is a routing target: loom send role:reviewer ….
• note — the shared per-workspace blackboard (set / get / list / del), stored under the project’s .loom/. Agents leave each other durable key/value notes.
• claim / release / claims / hold — advisory file locks so agents don’t collide; hold gates a path harder. Surfaced in the Fleet panel.
• gate — hold a pane’s inbound bus input behind a human (--reason to explain, --list to see gated panes, --clear to release). Honoring holds is a Settings toggle (on by default).
• ask / reply — a blocking request/response between panes. ask waits for an answer (default timeout 300s) and exits non-zero on timeout; reply <id> answers, using the id from the [loom ask #N …] prompt.
• card — the operator’s task board, a docked Kanban. Cards are project-scoped in the repo’s .loom/board.json, so they travel with the repo. card add returns the new card’s id; a worker closes its own card with card move <id> done. Only the operator dispatches a card into a pane; an agent can create, list, and move cards but not spawn from one.
• card drain — arms the board’s auto-drainer: while on, Loom keeps dispatching top To-do cards into fresh panes until In-progress reaches --cap (default 3), then refills a slot as each finishes. This is the swarm loop. Drain is session-only (never persisted).
• hooks — prints or installs the Claude Code hooks profile (--install --project is the default; --user installs into ~/.claude/settings.json). Idempotent. The profile wires six lifecycle events — SessionStart, UserPromptSubmit, PostToolUse (edits), Notification, Stop, SessionEnd — onto Loom’s Session/Task/Approval model. The agent pushes its state; Loom never parses output. See Agents, MCP & hooks.

loom mcp tools

The same operations as first-class tools (target is a pane display name):

Tool	Args	Does
list_panes	—	List every pane (name, workspace, focused, live).
send_text	target, text, enter?=true	Type text into one pane.
spawn_pane	command, name?, cwd?	Open a new pane running command.
read_pane	target, lines?=50 (max 2000)	Read the tail of a pane’s scrollback.
broadcast	text, enter?=true, workspace?	Send to every live pane in a workspace.
focus_pane	target	Reveal & focus a pane, switching workspace.
flag_attention	target?=self, clear?=false	Raise/drop a pane’s amber border.
set_status	target?=self, text?	Set a pane’s status label (empty text clears).
card_add	title, prompt?, command?=claude, workspace?	Add a To-do card; returns its id.
card_list	workspace?	List cards (id, title, status: todo|dispatched|done|failed).
card_move	id, status (todo|done|failed), workspace?	Move a card between lanes.
card_drain	on, cap?=3, workspace?	Auto-dispatch To-do cards, keeping cap panes busy.

flag_attention and set_status default to your own pane ($LOOM_PANE) when target is omitted. card_* default to your pane’s workspace when workspace is omitted.

Common patterns

# Delegate a task to a peer
loom send Cleo "run the integration suite and report back"

# Spin up a helper agent, then brief it
loom spawn --name reviewer --cwd /repo claude
loom send reviewer "review the diff on branch X"

# Flag yourself blocked so the human notices
loom attention
loom status "waiting on API key"

# Queue work, then launch the swarm on it
loom card add "Migrate auth to v2" -p "port src/auth to the v2 API and run the suite"
loom card drain on --cap 4

Keep it courteous: send / broadcast type into another terminal — prefer --no-enter if a human should review before it runs.