Skip to content
fleet

Running agents in a workspace

Updated

Agents report status and work with issues, pull requests, and CI through the fleet-agent MCP server. They call tools supplied by their harness, not shell commands. The MCP connection needs no URL, ship name, repo, or workspace input: the harness working directory supplies the context.

The visible fleet CLI (fleet client, fleet ship, fleet bridge) remains for the human or process managing the fleet. The harness starts the hidden fleet agent-mcp transport itself; agents should neither invoke it nor drive fleet-management commands.

How MCP finds the workspace

Section titled “How MCP finds the workspace”

The ship writes an atlas.json discovery file to the root of its fleet directory, containing its local port. Workspaces sit two levels below that, at <fleetDirectory>/<repo>/<name>.

The stdio adapter walks up from the harness working directory until it finds atlas.json, reads the port, and derives the workspace identity from the first two path segments below that root. It reads the opaque token inherited from the workspace’s tmux session and forwards MCP traffic to http://localhost:<port>/workspaces/<repo>/<name>/mcp.

The consequences are worth knowing:

  • It works from any subdirectory of the workspace, not just its root.
  • It only works on the machine the ship runs on. There is no remote mode.
  • Outside a workspace the adapter does not start, so no fleet-agent tools are exposed.

After upgrading from a Fleet release that predates the MCP transport, deactivate and reactivate any workspace that was already active. The ship warns at startup when it finds a legacy tmux session without a workspace MCP credential.

  • The MCP server is bound to the discovered workspace; tools cannot select a different repo or workspace.
  • It is local-only. The adapter always connects to localhost on the ship.

Start a session

Section titled “Start a session”

Call agent_init once when the harness session starts:

{
  "model": "claude-opus-4-8",
  "provider": "anthropic",
  "harness": "claude-code"
}

All three inputs are required, non-empty free-form strings. They are recorded and displayed, not validated against a list. They appear in the GUI’s workspace and repo tables as MODEL / PROVIDER / HARNESS.

The tool seeds the status to idle with a generated description; calling it again resets the session.

The workspace must be active — the agent status is attached to its tmux session. On an inactive workspace, init fails with workspace not active. Activate it first with fleet client activate, or from the GUI.

Report and read status

Section titled “Report and read status”

Call agent_status whenever the phase changes:

{
  "state": "building",
  "description": "Adding the retry path to the upstream client"
}

description is required. Keep it a short human-readable summary of what you’re doing right now — the skill asks for roughly 100–200 characters. It is what a human watching the dashboard reads.

agent_status requires agent_init in the same session; without one it fails with agent not initialized. The model, provider, and harness from init are preserved across every update.

Call the read-only agent_status_get tool with no input to inspect the current status. It returns null before initialization.

The states

Section titled “The states”
State Use when
idle nothing is in progress, or the work is finished
planning investigating the codebase or designing, before editing
building actively writing or changing code
verifying running tests, builds, or other checks
awaiting blocked, or the work is up for review and you need input

Any other value is rejected by the tool schema.

When to update

Section titled “When to update”

Update on every phase change — that’s the whole point of the field. Concretely:

  • Flip to verifying when you start running tests, not after they pass.
  • Flip to awaiting before you present a question, a plan, or an approval request to the user. The skill makes this mandatory, and it must complete before you present the question — don’t run the two in parallel.
  • Flip back to the state matching your real phase the moment work resumes.
  • Flip to idle when you’re done.

A stale status is worse than none: the dashboard is the only signal a human watching a dozen workspaces has.

Status lifetime

Section titled “Status lifetime”

Agent status is in-memory runtime state on the ship, tied to the workspace’s tmux session. It is not written to disk. Deactivating or deleting the workspace clears it, and a restarted ship starts with no agent attached to anything. Every status change is broadcast on the ship’s event stream as workspace.agent_status_changed and flows up through the bridge to the GUI in real time.

A typical session

Section titled “A typical session”
  1. The harness starts the MCP adapter and activates the fleet-agent skill.
  2. The agent calls agent_init, then pulls the latest branch with git.
  3. It calls agent_status with planning, building, and verifying as the work moves through those phases.
  4. It commits and pushes its branch itself.
  5. It calls agent_status with idle and a final description.

The workspace is a real clone and the agent owns its git state end to end: pull before starting, commit in logical chunks, and push the branch yourself. No process in Fleet commits or pushes on an agent’s behalf.

Section titled “Related”