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.

CLAUDE.md

The most impactful thing you can do is add a CLAUDE.md to your repo root. 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
• 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. Run xpo doctor and it generates a starter CLAUDE.md tuned to your project — including build commands, test commands, and the xpo workflow rules. Customize it from there.

The same approach works for other agents: xpo doctor can also generate instruction files for Cursor (.cursorrules), Windsurf (.windsurfrules), GitHub Copilot, Cline, and others.

Agent identity

When multiple agents (or a mix of humans and agents) work on the same backlog, you need to know who did what. Every write to the issue tracker is attributed to an identity, 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:

{
  "mcpServers": {
    "xpo": {
      "command": "xpo",
      "args": ["mcp"],
      "env": {
        "XPO_AGENT_IDENTITY": "Claude Code <[email protected]>"
      }
    }
  }
}

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 implementation and a thorough, strict one for review.

Configuration file

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

drive:
  supervisor: claude
  coder: claude
  max_retries: 3
  test_cmd: make test
  timeout: 30m

Further reading

• 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