Getting Started

Starting Guide

This guide walks you through a real first session with Exponential — from installation to your first agent-driven implementation. By the end, you'll have a working backlog, a visual board, and an agent that can read and execute your specs.

Install

curl -fsSL https://getxpo.dev/install.sh | bash

One binary. No Node, no Docker, no database. See Installation for other methods.

Initialize a project

Inside any project directory:

xpo init

This creates a .xpo/ directory that lives alongside your code. If the project is a git repository, your backlog gets full git superpowers — branching, merging, versioning, and offline-first collaboration. But xpo init works in any directory, git or not.

You can also run the built-in doctor command to validate your installation and fix any outstanding gaps:

xpo doctor

Capture some work

Start by adding a few issues to your backlog:

xpo add "Set up OAuth2 login" --label feature
xpo add "Fix session timeout on mobile" --label bug
xpo add "Refactor auth middleware" --label improvement

Issues start in BACKLOG. You can add a description, assignee, story points, and more — but for now, titles and labels are enough to get moving.

Open the board

xpo board

Your browser opens the Exponential web interface. You can interact with your backlog, click to edit details, press Cmd/Ctrl + K to jump to any issue. Hit C to create a new issue from anywhere in the app. To learn more about the available keyboard shortcuts, you can press the ? key.

Work an issue yourself

Pick an issue and start it:

xpo start <id>

This moves the issue to DOING. In a git repository, it also creates a feature branch so the issue and the code travel together.

Do the work, commit as usual, then review what you've built:

xpo review <id>

This shows the unified diff of your branch right in the terminal — commits, files changed, and the full diff. You can also review visually in the web board's PR view, which shows the same information in a richer format.

When you're happy, close the loop:

xpo merge <id>

This merges your branch back to main and marks the issue DONE — one command, clean history. Without git, use xpo done <id> to mark it shipped.

Set up your agent

To let AI agents see and manage your backlog, wire up the MCP server. Create a .mcp.json at your repo root:

{
  "mcpServers": {
    "xpo": {
      "command": "xpo",
      "args": ["mcp"]
    }
  }
}

Restart your editor (or run /mcp in Claude Code). Your agent now has structured tools to list, create, update, and link issues — no shell parsing, no screen scraping. For the full setup — agent identity, CLAUDE.md, and drive configuration — see the Working with AI guide.

Now add your agent to the mix

Everything above is the familiar flow — you've been doing it for years with other tools. Here's where Exponential goes further.

Say you want to add team notifications to your app. You have a rough idea, not a spec. Capture it:

xpo add "Team notifications" --label epic

Now, instead of sitting down to write stories and specs yourself, start a conversation with your agent:

You: I just added an epic for team notifications. Can you read it
     and help me design the feature and break it into stories?

Agent: I've read the epic. Let me explore the codebase to understand
       the current architecture...

       I can see you have a User model, an event system in
       internal/events/, and the web UI uses SSE for real-time
       updates. A few questions before I decompose this:

       1. Which events should trigger notifications — assignments,
          mentions, status changes, comments, all of these?
       2. In-app only, or also email/webhook?
       3. Should users be able to configure their preferences
          per-event-type?

You: All four event types. In-app only for now, but design the
     model so we can add email later. Yes to per-event preferences.

Agent: Good. I'll design it as a NotificationPreference model with
       per-user, per-event-type toggles, and a Notification model
       that the feed reads from. Let me break this into stories...

       I've created 5 child issues under the epic:

       • myapp-f1 "Notification preferences model" (3 pts)
       • myapp-f2 "In-app notification feed endpoint" (5 pts)
       • myapp-f3 "Trigger notifications on assignment" (2 pts)
       • myapp-f4 "Trigger notifications on @mention" (3 pts)
       • myapp-f5 "Notification badge in web UI" (2 pts)

       I've set dependencies — f3 and f4 depend on f1 (they need
       the preferences model to check settings), and f5 depends on
       f2 (badge needs the feed). The first two have no blockers,
       so I've moved them to PLANNED.

       Want me to start on the preferences model?

You: Yes, go ahead.

That entire conversation was powered by xpo. The agent read the epic, asked design questions, created five stories with descriptions and estimates, mapped dependencies, and promoted the unblocked ones — all through the MCP tools. No copy-paste from a doc into a tracker. The planning conversation is the tracker.

Refine on the board

Before handing anything off, open the board to see what the agent created:

Your epic now has five child stories with estimates, dependencies, and statuses. This is your moment to shape things:

Re-order — drag stories to set the priority you want. The preferences model should come first since everything depends on it.
Adjust — maybe the feed endpoint feels too big at 5 points. Click to open it, split it further, or adjust the scope.
Add context — leave a comment on the mention story: "We use a custom markdown parser in pkg/md — make sure @mention detection hooks into that, not a new regex." Details like these are what turn a good spec into a great one.
Check dependencies — switch to the Dependencies view to make sure the graph looks right. Nothing should be blocked that doesn't need to be.

When you're happy with the plan, it's time to execute.

Let the agent execute

Let the agent pick the next unblocked story and implement it:

xpo drive --no-merge

Without specifying a particular issue, xpo drive picks the highest-priority PLANNED story with no blockers automatically. The --no-merge flag leaves the branch for your review instead of merging immediately.

The agent reads the spec (including your comments), gathers context from the codebase, implements the change, and reports back. While it works, you can keep planning the next stories or reviewing the board. For a deeper look at what happens inside the loop — the supervisor/coder split, test gates, and how trust builds over time — see Agentic Drive.

Review and ship

When the agent is done, open the board and click the story to see the PR view — commits, files changed, and the full diff in a richer format than the terminal.

Read through the changes. If something needs adjustment, leave a comment on the issue and run xpo drive again — the agent picks up where it left off with your feedback.

When the implementation looks good, hit Squash & Merge in the web UI. The branch merges, the issue moves to DONE, and the epic's progress bar updates. On to the next story.

The full loop

That's the Exponential workflow — familiar at the core, transformed by collaboration:

Capture — rough ideas to BACKLOG, just a title is enough
Design — refine the idea collaboratively with your agent
Decompose — the agent breaks it into precise, dependency-mapped stories
Prioritize — re-order, adjust scope, leave comments for the agent on the board
Execute — xpo drive picks the top story and implements it
Review — check the diff in the PR view, leave feedback if needed
Ship — squash & merge, watch the epic progress update

Humans decompose and direct. Agents execute and report. One backlog, one workflow, one history.

What to explore next

Core Concepts — the philosophy behind Exponential: why specs matter, how Agile evolves, what "issues as code" gives you
Working with AI — the full guide to human-agent collaboration, writing specs, and autonomous drive
Web UI — the board, dashboard, keyboard shortcuts
Cycles — set up sprints with velocity tracking and burndowns

NextCore Concepts