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)
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-1, myproject-2). It's derived from your folder name when you run xpo init, but you can change it anytime.

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 marked DONE by the end of a cycle automatically roll forward. Completed 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, completing the last child automatically moves the parent to DONE (if it was DOING).

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

Drive (autonomous agents)

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

Configuration for the xpo drive autonomous agent loop. The supervisor handles evaluation steps — spec analysis, context gathering, and review. The coder handles implementation. If the coder fails, it retries up to max_retries times before marking the issue BLOCKED.

The test_cmd is the shell command run to verify the implementation. If omitted, the supervisor agent detects the project's test setup automatically.

See AI Agents for the full drive workflow.

Permissions

permissions:
  roles:
    admin: ["*"]
    member: ["issue.read", "issue.create", "issue.update", "issue.comment", "issue.start"]
    viewer: ["issue.read"]
  users:
    alice@example.com: admin
    bob@example.com: member

Role-based access control, only enforced in Distributed Mode. When this block is absent, all authenticated users have full access. Use ["*"] to grant all capabilities to a role.

Available capabilities

issue.read, issue.create, issue.update, issue.comment, issue.start, issue.merge, issue.delete, issue.link

Remote

remote:
  url: https://xpo.example.com

Configuration for connecting to a remote xpo server. The token is usually populated automatically by xpo login in the user config (~/.config/xpo/user.yaml) — you don't need to set it by hand.

See Distributed Mode for server setup.

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