Working with AI

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:

$XPO_AGENT_IDENTITY env var — operator-controlled, wins if set. Use this when you want a fixed, predictable identity regardless of which agent connects.
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.
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 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

Key	Default	Description
`supervisor.agent`	`claude`	Agent for evaluation steps (spec review, context planning, implementation review).
`supervisor.model`	`sonnet`	Model override for the supervisor. Optional — omit to use the agent's default.
`coder.agent`	`claude`	Agent for implementation.
`coder.model`	—	Model override for the coder. Optional — omit to use the agent's default.
`max_retries`	`3`	Max attempts before the issue is marked BLOCKED with feedback attached.
`test_cmd`	—	Shell command to verify the implementation. When omitted, the Testing phase is skipped with a hint to configure it. `xpo init` writes it as a comment.
`timeout`	`30m`	Max wall-clock time per drive run. Prevents runaway sessions.

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.