Agents, MCP & hooks

Loom is built for agents to operate it. This guide covers the CLI agents Loom knows out of the box, the loom mcp tools (so a model can drive panes natively), and loom hooks (so an agent’s lifecycle shows up in Loom without Loom ever reading its output).

Supported agents

Loom recognizes several CLI agents by their launch command and shows them as one-click chips in the new-workspace wizard, each with its own badge and border tint:

Claude Code (claude), OpenAI Codex (codex), Google Gemini (gemini), GitHub Copilot (copilot), Amazon Q (q chat), Aider (aider), and Cursor (cursor-agent).

Detection is launch-command only — Loom never inspects output to identify an agent, keeping panes byte-opaque. You can run any other CLI too; it just won’t get a special badge. Claude panes additionally resume their conversation across restarts (Settings → resume agent sessions).

The `loom mcp` tools

Every control-bus operation is also a first-class MCP tool. Wire the loom mcp server into your agent and it can drive the environment natively. The everyday tools:

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?`, `dry_run?`	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 clears).
`set_role`	`target?`=self, `role?`	Tag a pane’s role.
`card_add` / `card_list` / `card_move` / `card_drain`	—	Drive the task board.

Plus the fleet-coordination tools — board_* (blackboard), claim_file / release_file / hold_file / list_claims, gate_pane / list_gates, and ask_pane / reply_ask — covered in Coordinating a fleet. Coordination tools default-scope to the caller’s own pane and workspace unless you pass target / workspace.

Lifecycle hooks — `loom hooks`

Because Loom never parses output, it can’t tell when an agent starts working, finishes, or needs approval by watching the screen. Instead the agent pushes those transitions, and Loom models them as Sessions, Tasks, and Approvals.

For Claude Code, loom hooks wires that up:

loom hooks                       # print the recommended hooks profile
loom hooks --install             # merge it into .claude/settings.json (project, the default)
loom hooks --install --user      # merge into ~/.claude/settings.json instead

--install is idempotent — running it twice is safe. It installs a profile that maps Claude Code’s lifecycle events onto Loom’s model:

Claude Code event	Loom transition
`SessionStart`	Session starts
`UserPromptSubmit`	A Task begins (titled with the prompt)
`PostToolUse` (edits)	Task update (notes the file touched)
`Notification`	An Approval is requested
`Stop`	The Task ends
`SessionEnd`	The Session ends

Each event calls a small internal bridge that pushes the transition over the bus. The bridge is silent, always succeeds, and no-ops outside Loom — so the same hooks are safe to install globally.

Why this matters

With hooks installed, the rest of Loom gets real signals to work with:

The task board auto-closes a dispatched card when its pane’s Task ends — no output-watching required.
card drain can keep --cap panes busy because it has a true end-of-task signal to refill on.
A pane raises its own attention border when it’s blocked on an approval, and the “Needs you” strip lets you answer inline (see The Fleet panel).

A minimal agent setup

# 1. Let the agent's lifecycle flow into Loom
loom hooks --install

# 2. (If your agent speaks MCP) point it at the loom mcp server so it can drive panes.

# 3. Now an agent can coordinate: delegate, spawn helpers, flag itself blocked, close its card.
loom send Cleo "run the suite"
loom card move card7 done