Agent Configuration

When agents work alongside your team, they need the same things a new teammate needs: context about how the project works, a clear identity so you can tell who did what, and guardrails that keep them productive without surprises.

Agent instructions

The most impactful thing you can do is give your agent an instruction file — CLAUDE.md for Claude Code, AGENTS.md for Codex and OpenCode. This file is the agent's onboarding doc — it tells the agent how your team works with xpo, what's expected before starting code changes, and what habits to follow.

A good instruction file covers:

• Read the backlog (xpo list) before starting work
• Search for existing issues and prior decisions (list with a match, rationale) before filing a new one
• Ensure a backing task exists for every piece of work
• Set issues to DOING before making code changes
• File new bugs and findings as issues instead of fixing them silently
• Mark issues DONE only after human review

You don't have to write this from scratch. xpo init writes the xpo workflow rules into the instruction file for each agent you select, registers the MCP server, and installs the xpo workflow skill where the agent supports skills:

Managed blocks

xpo only owns its own section of an instruction file. That section sits between markers like:

<!-- xpo:begin 1.3.0 sha256:3f9a1c2b7e4d -->
…xpo workflow rules…
<!-- xpo:end -->

Everything outside the markers is yours — add build commands, conventions, and project context freely. Installed skills end with a similar <!-- xpo:skill … --> marker.

When a new xpo release changes the template, xpo doctor reports Instructions out of date or Skill out of date, and xpo init or xpo doctor --fix refreshes them. If you edited inside the managed section, you're offered replace / keep / diff instead of a silent overwrite.

Agent identity

When multiple agents (or a mix of humans and agents) work on the same backlog, you need to know who did what — and who is accountable for it. xpo separates the two:

• The principal is the person an agent works for — the configured xpo user (typically from your git config). Issues are always assigned to a person, never to an agent: when an agent calls start, the issue is assigned to its principal.
• The agent is recorded as via. On the board, anything an agent did shows the person's name with a dashed underline, and hovering it reveals the agent: "Claude Code for Alice". This applies to the activity timeline, comments, the inbox, the dashboard feed, artifacts and the assignee. The CLI spells it out: "Alice (via Claude Code)".

The board's Worked by filter (Agent / Human) in Issues, My Issues, and Notifications lets you see which work agents did.

The agent's identity is resolved in this order:

1. $XPO_AGENT_IDENTITY env var — operator-controlled, wins if set. Use this when you want a fixed, predictable identity regardless of which agent connects.
2. MCP clientInfo — automatically provided by the editor during the MCP handshake. This is how Claude Code, Cursor, and other MCP clients identify themselves without configuration.
3. The configured xpo user — the same default the CLI uses, typically derived from your git config.

For teams running multiple agents, setting a fixed identity per agent keeps the audit trail clean. Use an agent@… email address — xpo recognizes identities whose address starts with agent@ as agents and attributes their work to the principal:

{
  "mcpServers": {
    "xpo": {
      "command": "xpo",
      "args": ["mcp"],
      "env": {
        "XPO_AGENT_IDENTITY": "Claude Code <agent@workstation.local>"
      }
    }
  }
}

Drive configuration

xpo drive uses two agents with distinct roles. The supervisor handles the thinking work — evaluating whether specs are implementation-ready, planning which files and patterns matter, and reviewing the finished implementation against the spec. The coder handles the doing — receiving the plan and writing the actual code.

This separation is deliberate. The agent that writes the code should never be the one that decides whether the code is good enough. By default both roles use claude, but you can assign different models or even different tools to each role — a fast, cheap model for supervision and a thorough one for implementation, or the reverse.

The model subkey is optional and overrides which Claude model the agent uses. The supervisor defaults to sonnet for speed and cost — it does evaluation work, not code generation, so a smaller model is a good fit.

Configuration file

These defaults live in .xpo/config.yaml so you don't have to pass flags every time:

drive:
  supervisor:
    agent: claude
    model: sonnet
  coder:
    agent: claude
  max_retries: 3
  timeout: 30m
  # test_cmd: make test

Test command handling

When no test_cmd is configured, the Testing phase is skipped entirely — the supervisor still reviews the diff, but there's no binary pass/fail gate. You'll see a hint in the output suggesting you set drive.test_cmd in .xpo/config.yaml or pass --test-cmd on the command line.

When a configured test command fails with an exit code other than 1 (e.g. 127 for command not found, 2 for a Makefile error), it's treated as a configuration problem rather than a test failure. The Testing phase is skipped for that attempt instead of consuming a retry — there's no point retrying implementation when the test harness itself is broken.

Agent chat

The board's agent chat runs your local Claude Code or Codex with your own settings, in the project root, and follows the same instruction file and xpo skill. Set its default agent and model with chat.agent and chat.model (see Project Configuration).

Further reading

• Agent Chat — chat with an agent in the board, and let it work an issue in Work Mode
• Agentic Drive — how the five-phase loop works, the trust gradient, and common pitfalls
• Writing Specs — how to write specs that agents can execute reliably
• MCP Server — set up the MCP server so agents can access your backlog