claude-fleet-control

name	claude-fleet-control
description	Use when driving or checking on Claude Code sessions managed by claude-fleet over its MCP control server — listing/spawning sessions across machines, nudging or inspecting a running session, recovering a stuck/frozen/RAM-heavy session, or reviewing a session's worktree changes.

Controlling claude-fleet

claude-fleet runs long-lived Claude Code sessions in tmux across machines (mac, mefistos, hetzner). Its MCP server exposes tools to observe and act on those sessions. The tool descriptions tell you what each does; this skill is the workflow that ties them together — the parts that aren't obvious.

The core loop: act, wait, observe

send_prompt only types text + Enter into the session's terminal. It does not return the reply. Claude needs a few seconds to respond, and the output is the live tmux screen, not a clean transcript. So driving a session is a loop:

1. send_prompt(session_id, text) — send the instruction.
2. Wait (~3–8s; longer for heavy work) before reading.
3. capture_session(session_id) — read the pane. Pass scrollback_lines (e.g. 200) when you need more than the visible screen.
4. If the reply is incomplete or Claude is still working (streaming text, a spinner), wait and capture again. Repeat until you see Claude's input prompt box / a bare > with no activity (idle) or your task is done.

Always get session_id from list_sessions first. By default it returns slim summary rows — id, host_alias, tmux_name, project_id, worktree_id, status, claude_status, stuck_kind, lost_at, is_controller — enough to pick a target without blowing past MCP token caps on a big fleet. To get the rich auto-derived fields:

• peer_status(session_id) — adds current_activity (REPL footer line like "Sketching") and context_pct (percent of context window used) for one session in one call.
• list_sessions { summary: false } — full SessionRow for every match (current_activity, context_pct, pr_url, notes, …). Use sparingly.

Scope the call with optional filters (any combination): host_alias, project_id, status, claude_status. Ghosts are hidden by default — pass include_lost: true to surface them (required before recreate_session can resurrect one).

Useful fields visible in the default summary:

• claude_status — working / idle / stuck / unknown
• stuck_kind — auth_menu / confirmation / none
• lost_at — non-null = ghost (lost from tmux)
• is_controller — true on the calling session once you've registered (see below)

Orient with fleet_health / list_hosts / list_projects when you don't yet know what exists.

Spawning a session — new_session

new_session { host_alias, project_id, name } starts a session in an existing project — add worktree_id to land in a specific worktree, or omit it for the project root. To start work on a fresh branch, pass new_worktree: "<branch>" instead of worktree_id: it creates a new git worktree + branch. By default the branch forks from the repo's default branch; pass base_branch: "dev" to fork from another branch (it falls back to the default branch if dev doesn't exist on that host). Remote hosts auto-clone the repo if it's missing.

Plain-shell sessions — new_shell_session

new_session runs Claude Code in the pane. When you want a raw shell — to run a dev server, watch a build, exec ad-hoc commands — use new_shell_session { host_alias, project_id, name, worktree_id?, new_worktree?, base_branch?, start_command? } instead. Same project/worktree plumbing (remote auto-clones, new_worktree forks a branch, etc.), but the pane is an interactive login shell.

start_command runs once before the shell drops to an interactive prompt; the pane stays alive after it exits, so the session survives even if the command is cargo run and you Ctrl+C it. Use it for "leave this running":

new_shell_session { host_alias: "mefistos", project_id: 7,
                    name: "ppt-web-dev", start_command: "pnpm dev:ppt" }

You steer a shell session the same way you steer a Claude one:

• send_prompt(session_id, "ls -la") — types the text + Enter (it's just tmux send-keys; works equally well for a REPL or a bash prompt).
• capture_session(session_id) — reads the pane.

The escalation ladder (stuck / recreate / restart) and the controller guard both apply — shell sessions appear in list_sessions like any other.

Host clipboard — get_clipboard / set_clipboard

When you need to hand text to the human at the keyboard (or read something they just copied), use the clipboard tools. Both take a host_alias and operate on that host's system clipboard:

• get_clipboard { host_alias } — returns the current clipboard contents. An empty clipboard returns (clipboard is empty) rather than an empty block.
• set_clipboard { host_alias, content } — overwrites the clipboard. Capped at 64 KiB.

The tools probe wl-paste/wl-copy (Wayland), then xclip, then xsel (X11), then pbpaste/pbcopy (macOS) — the first installed helper wins. On a headless Linux box with no display + none of those helpers installed, the call fails with E_CLIPBOARD_UNAVAILABLE — that's a host config gap, not a bug to retry.

Identifying yourself — register_self

Before doing any session lifecycle work, call register_self { host_alias, tmux_name } once at the top of your run. This records you as the fleet controller in the store. Effects:

• list_sessions marks your row with is_controller: true so other controllers can recognise you.
• kill_session / restart_session / recreate_session will refuse to target the controller — they return E_SELF_TARGET. Pass force: true if you really mean to act on yourself (e.g. a deliberate restart).
• broadcast_prompt excludes the controller from its fan-out by default, so you never spam yourself.

Skip this only for read-only or one-shot tasks where you'll never be a plausible target.

Discover your identity programmatically — never guess the alias. tmux_name comes from tmux display-message -p '#S'; host_alias is configuration (whatever the user picked in the host picker) and is not derivable from hostname. The two diverge whenever the user renames a host, so a hostname-based fast path silently breaks. Always look up the alias:

1. tmux display-message -p '#S' — your tmux_name.
2. mcp__claude-fleet__list_sessions {} — find the row whose tmux_name matches; take its host_alias.
3. mcp__claude-fleet__register_self { host_alias: "<discovered>", tmux_name: "<#S>" }.

Same pattern the fleet-friendly-name skill uses; see it for edge cases (no matching row, multiple matches).

Recovering a misbehaving session — escalation ladder

Look before you climb. Read the row from list_sessions (or call peer_status) and use claude_status, stuck_kind, and context_pct to pick the right rung — don't recreate_session something that just needs a nudge.

Climb only as far as needed; each step is more destructive:

Symptom	Action
claude_status: stuck with stuck_kind: confirmation / auth_menu	send_prompt(session_id, "1") (or the right keystroke) to dismiss it
claude_status: idle but waiting at a prompt	send_prompt(session_id, "continue")
context_pct near 100 — the conversation is full	recreate_session resumes the same Claude id in a fresh REPL
REPL itself wedged, but tmux fine	restart_session — relaunches Claude in place
Frozen / eating RAM / needs a clean slate	recreate_session — kills + rebuilds the tmux session in the same worktree, resuming the same Claude conversation
Lost from tmux (ghost — status: "ghost"; pass include_lost: true to see them in list_sessions)	recreate_session to bring it back, or dismiss_ghost_session to drop it

recreate_session is destructive (kills the running process) but preserves the conversation via session-id resume — prefer send_prompt/restart for in-place fixes. If the target is the registered controller, pass force: true or the call refuses with E_SELF_TARGET.

Inspecting a session's work

Before reporting or acting, read the worktree (read-only): repo_changes (status), repo_diff(session_id, path) (one file's diff), repo_file, repo_tree; and git state via repo_log / repo_branches / repo_commit / repo_commit_diff.

Session timeline — session_history

Every status change, prompt send, stuck detection, kill, recreate, and peer message is appended to a per-session event log. Pull it with session_history { session_id, limit? } when you need the story of what happened — capture_session only shows the current screen.

Recorded kinds: status_change · prompt_sent · stuck · killed · recreated · message_sent · message_received. The response is newest- first; default limit is 50.

Checking what a peer is doing — peer_status

You don't need to capture_session to find out whether a peer is working, idle, or stuck. peer_status(session_id) returns the reconcile-derived fields in one call:

• claude_status — working / idle / stuck / …
• current_activity — the REPL footer line ("Sketching", "Running test", …)
• stuck_kind — auth_menu / confirmation / none
• context_pct — percent of context window used

Use it before send_message/send_prompt to avoid pinging a peer that's mid-stream, and before broadcast_prompt to pick a real status filter. For the same fields across every session, call list_sessions { summary: false } — the default summary mode omits current_activity and context_pct to keep responses inside MCP token caps.

Peer-to-peer messaging — send_message + inbox

send_prompt types text directly into a peer's REPL, which interrupts whatever they're doing. For coordination between sessions, prefer the inbox:

1. send_message { from_session_id, to_session_id, body, kind?, deliver? } — appends a row to the recipient's inbox. The from id is preserved so the receiver knows who wrote, and kind is a free tag (message / task / reply / alert).
2. The recipient calls inbox { session_id, unread_only?, mark_read? } when it's ready — newest-first, and unread rows are marked read by default.

Set deliver: true to also type the message into the peer's pane with a [msg #id from name@host]: header — useful for urgent prompts where you want both a paper trail and immediate attention. The inbox row is the source of truth; pane delivery is best-effort and delivered_to_pane / deliver_error in the response tell you what happened.

A typical exchange:

A → send_message(from=A, to=B, body="please review PR #42", kind="task")
B → inbox(session_id=B)                # reads, marks read
B → send_message(from=B, to=A, body="LGTM", kind="reply", deliver=true)
A → inbox(session_id=A)                # or sees the pane line directly

For one-to-many work use broadcast_prompt (next section); for one-to-one coordination prefer send_message.

Broadcasting to many sessions — broadcast_prompt

When the same instruction needs to reach every matching work session, broadcast_prompt { host?, project_id?, status?, prompt, submit? } is the fan-out. The filter is AND-combined; omit a field to leave it open:

• host — only sessions on this host alias
• project_id — only sessions in this project (from list_projects)
• status — only sessions whose claude_status matches (e.g. "idle")

The call returns a per-session result vector (sent / failed counts + each target's outcome) so you can see who got it. Two implicit guardrails: only work sessions are eligible (background sessions are skipped), and the registered controller is excluded — so you never broadcast to yourself.

Typical use: broadcast_prompt { status: "idle", prompt: "git pull && pnpm test" } to wake every idle worker. Use peer_status/list_sessions first to set a realistic status filter — broadcasting to working sessions interrupts them mid-stream.

Headless work

For unattended tasks use new_bg_session(host, name, prompt) and check progress with peek_session(session_id). (peek_session on an interactive session returns an informational message — interactive sessions have no background job; use capture_session for those.)

Recovering from MCP errors

Three error classes, three different responses — do not blanket-retry:

• Application errors (E_NOTFOUND, E_SELF_TARGET, E_LOCK, E_VALIDATION, …): the call reached the server and the server said no. Surface immediately, then re-sync state before any retry. The canonical re-sync calls are list_sessions, list_hosts, list_projects, list_worktrees — they return fresh truth from the store. E_NOTFOUND on a session id usually means the row moved (ghost, recreated, renamed); list_sessions { include_lost: true } surfaces ghosts so recreate_session can revive them.

• Transient transport errors (timeout, connection drop, 5xx): retry once after a short wait, then re-sync state. The MCP server is local (or via reverse tunnel) and recovers quickly. If the second attempt also fails, surface — don't loop.

• Destructive ops (kill_session, safe_kill_session, recreate_session, restart_session, delete_worktree, remove_host, dismiss_ghost_session): never auto-retry. A timeout doesn't mean the op didn't happen — it may have succeeded server-side and the response was lost. Re-sync first (list_sessions/list_hosts/list_worktrees), confirm the actual state, then decide whether to act again.

Self-healing pattern — when a tool that takes a session_id errors with E_NOTFOUND, your in-memory id is stale. Call list_sessions (or related_sessions { session_id } if you have a sibling id) to find the current row before retrying. Do not loop the same id.

Common mistakes

• Reading right after send_prompt → empty/partial output. Wait first, then capture_session; loop.
• Treating capture_session as a transcript — it's the current screen; use scrollback_lines for history.
• Jumping to recreate_session for a session that just needed a nudge — try send_prompt / restart_session first.
• Auto-retrying a destructive op after a timeout — the op may have succeeded; re-sync state first (see "Recovering from MCP errors" above).