Agent integrations

For an agent to report status, two things have to be true: its harness must connect the workspace’s MCP tools, and the agent must know when and how to use them.

Fleet ships both. A skill (fleet-agent) carries the instructions, and a small harness integration detects a fleet workspace, starts the internal fleet agent-mcp stdio adapter, and injects a mandatory “activate the fleet-agent skill” instruction. A ship installs both into the agent’s home directory every time it starts.

Note

This page is about the integrations Fleet owns: fleet-agent and its startup plugins ship inside the fleet binary, are installed at ship startup, are repaired with fleet ship plugin, and are the same on every fleet.

Skills and plugins you write are a different mechanism — put them in the armory, a directory on the bridge that every ship pulls and installs. Fleet never writes to the armory, and fleet ship plugin doctor does not report on it; use fleet client armory ships for that.

What happens at ship startup

fleet ship installs the skill and the plugins before it begins serving. The install is best-effort: if it fails, the ship logs a warning and keeps going — it never blocks the ship from coming up.

Fleet startup could not install agent skills: <detail>. Fix the reported path, then run fleet ship plugin install all.

Preserved conflicts are reported the same way, one line per file:

Fleet startup preserved conflicting claude-code integration file: /home/you/.claude/skills/fleet-agent/SKILL.md. Run fleet ship plugin install claude-code --force to replace it.

Installation is keyed off the provider’s config directory: a provider is only touched if its config root (~/.claude, ~/.config/opencode, ~/.copilot, ~/.codex) already exists. Fleet does not create a config root for a tool you haven’t installed.

Supported providers

Provider	Skill	Harness integration
claude-code	~/.claude/skills/fleet-agent/SKILL.md	~/.claude/skills/fleet-agent-bootstrap/
opencode	~/.config/opencode/skills/fleet-agent/SKILL.md	~/.config/opencode/plugins/fleet-agent.js
copilot	~/.copilot/skills/fleet-agent/SKILL.md	~/.copilot/hooks/fleet-agent-session-start.json
codex	~/.codex/skills/fleet-agent/SKILL.md and ~/.agents/skills/fleet-agent/SKILL.md	none

Codex gets the skill in two places — its own directory and the shared ~/.agents location — but no automatic MCP or startup integration: it has no drop-in plugin directory and needs manual configuration and trust. A Codex agent has the skill available, but its MCP server and activation must be configured separately.

The claude-code plugin is a small directory tree: a .claude-plugin/plugin.json manifest, a hooks/hooks.json declaring a SessionStart hook, an executable hooks/activate-fleet-skill.sh, and a .mcp.json that starts fleet agent-mcp.

What the integrations do

Each integration declares a local fleet-agent MCP server whose stdio command is fleet agent-mcp. Claude Code reads that declaration from the plugin’s .mcp.json, Copilot reads ~/.copilot/mcp-config.json, and the OpenCode plugin adds it to the session configuration. The harness starts the adapter itself.

The session-start side checks that fleet is on PATH, runs fleet agent-mcp --identify, and validates the result as one repo/name pair. Only then does it inject an instruction naming the workspace and requiring the agent to activate the fleet-agent skill before doing anything else.

The guards matter: a session started outside a workspace gets no instruction, and an adapter started there exits without exposing tools. Nothing leaks into the model’s context.

The skill itself is the source of truth for agent behaviour — the MCP tools, the status states, and the git expectations. See Running agents.

Check the install state

fleet ship plugin doctor

This is read-only. It reports, per provider, whether the provider’s CLI is on PATH and what state the skill and plugin files are in:

fleet-agent skill & plugin status

claude-code
  cli    ✓ found    claude → ~/.local/bin/claude
  skill  ✓ current  ~/.claude/skills/fleet-agent/SKILL.md
  plugin ✓ current  ~/.claude/skills/fleet-agent-bootstrap

State	Meaning
✓ current	installed and matching what this ship would write
~ outdated-owned	Fleet’s file, but from an older version — reinstall to update
! conflict/unmanaged	present but not written by Fleet, or edited since
✗ missing	the provider is installed, the file is not
- absent	the provider’s config directory doesn’t exist

fleet ship plugin doctor does not start a ship — it’s safe to run anywhere.

Install or repair by hand

fleet ship plugin install claude-code
fleet ship plugin install all

The argument is one of claude-code, opencode, copilot, codex, or all. Anything else exits with an error listing the valid values.

The command re-runs the same installers the ship runs at boot and prints one line per file:

skill   claude-code  unchanged  /home/you/.claude/skills/fleet-agent/SKILL.md
plugin  claude-code  installed  /home/you/.claude/skills/fleet-agent-bootstrap

Status	Meaning
installed	the file did not exist and was written
updated	Fleet’s own file was replaced with new content
unchanged	already byte-identical
adopted	the file already existed with exactly the right content, so Fleet claimed ownership of it without writing
conflict	the file exists but Fleet doesn’t own it — left untouched

Naming a single provider that isn’t installed on the machine is not an error:

opencode: not installed on this machine (config directory missing); nothing to do.

Conflicts and --force

Fleet tracks every file it writes in an ownership manifest at ~/.config/autosmith/fleet-ship/managed-files-v1.json, recording each path’s expected content hash and mode. A file whose content doesn’t match what Fleet recorded — because you edited it, or because it was never Fleet’s — is a conflict.

Conflicts are never overwritten silently. The file is preserved, the command reports it, and the process exits non-zero:

Conflict: /home/you/.claude/skills/fleet-agent/SKILL.md is user-managed or was modified; preserved. Review it, then run fleet ship plugin install claude-code --force to replace it.

The non-zero exit is deliberate: it makes a conflict visible in a provisioning script that would otherwise ignore the message.

Once you’ve reviewed the file, --force replaces it and claims it for Fleet:

fleet ship plugin install claude-code --force

Caution

--force discards your version of the conflicting file. Copy anything you want to keep out of it first — Fleet keeps no backup.

--force only overrides content conflicts. Fleet still refuses to write through a symlink, to replace a non-regular file, or to touch anything outside the home directory, forced or not. Those raise errors rather than being overridden.

Related

• The Armory — distributing skills, plugins, and dotfiles you write to every ship.
• Running agents — the workflow the skill teaches.
• Agents — the status model.
• CLI reference — fleet ship plugin flags.