Project Configuration

Settings live in .xpo/config.yaml, created by xpo init. View the current configuration with:

xpo config

Precedence

Configuration is resolved in this order (highest priority first):

1. Environment variables — prefixed with XPO_, dots become underscores (e.g. XPO_AUTO_COMMIT=true, XPO_CHAT_AGENT=codex). Every key can be set this way; list keys take a comma-separated value. Map keys, such as labels, can only be set in a config file.
2. Project config — .xpo/config.yaml, committed to git
3. User config — ~/.config/xpo/user.yaml, per-user, not committed

Core

prefix: myproject
name: My Project
auto_commit: false
editor: nvim
user: "Alice <alice@example.com>"

These are the foundational settings for your project. The prefix determines how issue IDs look (e.g. myproject-a1b2c3). xpo init suggests one from your folder name, but you can change it anytime. Store it without a trailing dash — xpo adds the separator itself, and normalizes older configs that still have one.

auto_commit controls whether xpo writes are committed to git automatically. When false (the default), changes accumulate in the working tree for you to commit on your own schedule. Set it to true for automatic commits after every change — convenient for solo work, but for teams, manual commits let you batch related changes.

Estimation

estimation_system: fibonacci
count_unestimated: true

Story points quantify effort. The estimation_system determines which scale is available — both for xpo estimate on the CLI and the estimate picker in the web board. When count_unestimated is true, children without an explicit estimate count as 1 point toward the parent's rollup.

Available scales

The shirt system stores numeric values internally but renders as t-shirt sizes. Both forms work as input — xpo estimate <id> M and xpo estimate <id> 3 are equivalent.

Cycles

cycles:
  enabled: true
  duration: 2w
  start_day: monday
  anchor_date: "2025-01-06"

Cycles give your team a regular sprint rhythm with automatic rollover and velocity tracking. When enabled, issues not in a terminal status by the end of a cycle automatically roll forward. Closed issues retain their original cycle ID so historical metrics stay accurate.

The anchor_date pins cycle numbering to a specific date — useful for aligning with an existing sprint calendar. If omitted, xpo anchors to the nearest start_day before now.

See Cycles for usage.

Labels

default_labels:
  - bug
  - feature
  - epic
  - improvement
  - chore

labels:
  bug: "#e11d48"
  feature: "#2563eb"
  epic: "#7c3aed"
  improvement: "#0891b2"

Labels are freeform tags for categorizing issues. default_labels controls which labels appear in the web board's label picker. labels maps label names to CSS hex colors — entries here override the built-in colors for that label.

See Labels for usage.

Contributors

contributors:
  - "Alice <alice@example.com>"
  - "Bob <bob@example.com>"

Team members available for assignment in the web board's assignee picker. Each entry must be in "Name <email>" format.

See Contributors for details.

Automations

automations:
  first_start: true
  last_completed: true

Automations propagate status changes between parent and child issues. When first_start is enabled, starting any child automatically moves the parent to DOING. When last_completed is enabled and the last child reaches a terminal status (DONE, CANCELED, or DUPLICATE), the parent automatically moves to DONE.

See Parent & Sub-Issues for how these interact with the issue hierarchy.

Drive (autonomous agents)

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

Configuration for the xpo drive autonomous agent loop. Both supervisor and coder are nested objects with an agent key and an optional model override.

See AI Agents for the full drive workflow.

Agent chat

chat:
  agent: claude
  model: opus

Defaults for the board's agent chat. The model and effort pickers in the composer override them per chat.

Style

style:
  theme: default

UI theming for the web board.

Troubleshooting

Validate your configuration and fix common issues:

xpo doctor

Upgrade the data model after updating xpo:

xpo migrate