How does Fleet name each agent's tmux session?

Fleet derives the session name from the repository and the agent name and exposes it to the agent as the `FLEET_SESSION` environment variable. You can always read the exact name from `tmux list-sessions` or from that variable inside the session.

If an agent crashes, does Fleet restart it automatically?

No. The watcher is not an agent supervisor and does not respawn dead sessions. Work is re-dispatched through the reactive event chain or the PR reconciler, which start a fresh agent session on the next cycle.

Does attaching to a session interrupt the agent?

No. Attaching with `tmux attach` lets you observe the live session, and detaching with `Ctrl-b d` leaves it running. The agent only stops if you run `fleet agent stop` or kill the tmux session.

How to Manage AI Agents with tmux Using Fleet

Name: Fleet
Author: Fleet

Most AI agent platforms hide the running process behind a web UI or a daemon you cannot inspect. When something goes wrong, you are left reading logs after the fact with no way to see what the agent is doing right now. Running each agent as a plain tmux session flips that around: every agent is a durable, attachable terminal you can look inside at any moment.

Fleet runs every Claude Code agent as its own tmux session. There is no agent supervisor process to babysit and no container runtime — just tmux, which has kept terminal sessions alive across disconnects for two decades. This guide shows how Fleet names sessions, how to attach to a live agent and read its output, and what actually happens when an agent crashes.

Before you start

tmux installed and available on your PATH
Fleet binary installed (`curl -fsSL https://fleetctl.ai/install | sh`)
Claude Code (`claude`) installed and authenticated
A Git repository with a `.fleet/config.yaml` and at least one agent created

Understand why Fleet uses tmux

Fleet does not run agents inside a daemon process or a container. Each agent is a tmux session running the Claude CLI. tmux gives you three things for free: durability (the session survives an SSH disconnect or a closed terminal), inspectability (you can attach and watch the agent work live), and simplicity (no supervisor process to monitor, no Docker layer). Because the session is the agent, there is nothing extra to keep alive.

# tmux is the only runtime dependency for agent sessions.
# Verify it is installed:
tmux -V

# Fleet checks for it as part of its prerequisites:
fleet doctor

Start an agent and let Fleet create its session

Use fleet agent start <name> to launch an already-created agent. Fleet opens a dedicated tmux session for it and injects the agent's environment — including FLEET_SESSION, which holds the exact tmux session name. The agent's role, department, and trigger context are set as environment variables on the same session so the Claude Code process knows who it is.

# Start a single agent by its DB name:
fleet agent start backend-dev

# Each agent gets its own tmux session. The session name is
# exposed to the agent as the FLEET_SESSION environment variable.

List running agents from session state

Run fleet status to see which agents are active. Fleet does not store a running/stopped flag in its database — status is computed at runtime by checking whether the agent's tmux session exists (tmux.HasSession). That means fleet status can never drift out of sync with reality: if the session is gone, the agent is reported as stopped, full stop.

fleet status

# JSON form for scripting:
fleet status --json

# Cross-check against tmux directly if you want:
tmux list-sessions

Attach to a live agent to inspect it

Because each agent is a real tmux session, you can attach to one and watch Claude Code work in real time — reading files, running tests, opening a PR. Find the session name from the agent's FLEET_SESSION value (or from tmux list-sessions) and attach with the standard tmux command. Detach with the tmux prefix followed by d (default Ctrl-b d) — detaching does NOT stop the agent, it keeps running.

# See session names:
tmux list-sessions

# Attach to inspect a running agent live:
tmux attach -t <session-name>

# Detach without stopping the agent:
#   press Ctrl-b then d

Read agent output without attaching

If you only want to read what an agent has produced so far without taking over its terminal, capture the visible pane contents instead of attaching. This is non-intrusive and scriptable — useful for a monitoring loop or a quick check on progress. The decision-level history is also available through fleet log, but a pane capture shows the raw scrollback.

# Dump the current pane contents of an agent's session:
tmux capture-pane -p -t <session-name>

# For the structured decision trail instead of raw output:
fleet log --agent backend-dev --since 1h

Stop agents cleanly

Stopping an agent terminates its tmux session. Stop a single agent by name, or stop every running agent at once when you need to bring the fleet down. Because status is session-derived, a stopped session immediately shows as stopped in fleet status — there is no stale state to reconcile.

# Stop one agent:
fleet agent stop backend-dev

# Stop every running agent:
fleet agent stop --all

# Confirm the sessions are gone:
fleet status

Know what happens when an agent crashes

If an agent's tmux session dies — a crash, an OOM kill, a host reboot — the watcher does NOT respawn it. The watcher is not an agent supervisor. Instead, work re-enters the fleet through the reactive event chain: the underlying GitHub label or fabric event is still unsatisfied, so the next watcher poll (or the PR reconciler) re-dispatches the work to a fresh agent session. You recover work by re-triggering the chain, not by relaunching a dead process.

# After a crash, the session is simply gone:
fleet status        # shows the agent as stopped

# Re-dispatch happens through the chain, e.g. by ensuring the
# triggering label is still present on the issue/PR. The watcher
# (or PR reconciler) starts a fresh session on its next cycle.
fleet watcher status

Common pitfalls

Detaching from a session and stopping an agent are different actions. `Ctrl-b d` detaches and leaves the agent running; only `fleet agent stop` (or killing the tmux session) actually ends it. New tmux users frequently kill an agent by reflexively closing the window.
The watcher does not restart crashed agent sessions. If you expect a dead agent to come back on its own, you will wait forever — recovery happens by re-dispatching work through the reactive chain or the PR reconciler, not by the watcher relaunching the process.
Renaming an agent in `.fleet/config.yaml` changes its derived session name, so Fleet treats it as a new agent. The old tmux session can linger orphaned until you kill it. Use `fleet status` and `tmux list-sessions` to spot strays after a rename.
Attaching with `tmux attach` shares the terminal with the agent. If you type into the pane, you are typing into the agent's Claude Code session. Attach to observe; avoid sending keystrokes unless you intend to interact with the agent.
On a remote server, agent sessions persist across SSH disconnects (that is the point of tmux), but the watcher daemon must also survive your logout. Start it so it daemonizes (`fleet watcher start --supervised`) rather than as a foreground process tied to your shell.

When Fleet is the right tool

Fleet's tmux model is the right fit when you want full local visibility into what your agents are doing and prefer durable, inspectable processes over an opaque managed runtime. It runs anywhere tmux runs — a laptop, a dev server, a bare-metal box — with no Docker and no daemon to babysit.

It is a worse fit if you specifically want managed auto-healing where a crashed agent is automatically restarted in place. Fleet deliberately does not do that: a crashed session stays down and work is re-dispatched through the reactive chain. If you need a single agent to keep retrying a task in the same process forever, a tmux-per-agent model is not what you want.