Autopilot Runners

Autopilot runners are AI coding agents that pick up staged action items, implement the changes, and push the results to your target branch. DevSpec supports Claude Code (persistent, always-on polling), Cursor (interactive extension, command-palette driven), Antigravity (ephemeral, single-invocation with skills), and Grok Build (ephemeral, single-invocation with skills). All produce identical results — the difference is how they run.

Runner types

Persistent runners (Claude Code) run continuously in the background, polling for new work every few seconds. They show as "online" or "offline" on the dashboard. Interactive runners (Cursor) live as a Cursor extension and process one item per command-palette invocation, with full agent context for ad-hoc steering. Ephemeral runners (Antigravity, Grok Build) process one item per invocation and exit. They show as "last active X minutes ago" on the dashboard. All runner types read the same project settings and merge to the same target branch.

Prerequisites

Before setting up a runner, complete the "From Conversation to Deployment" guide — you need a deployment branch, CI/CD pipeline, and DevSpec project configured. You also need an MCP token from DevSpec (Settings → Autopilot or Settings → MCP Tokens).

Option A: Claude Code (persistent runner)

Claude Code runs as a long-lived polling loop on your machine. It continuously watches for staged action items, claims them, implements changes in isolated git worktrees, runs tests, and pushes to your target branch.

Step 1: Install the plugin

• Install Claude Code if you have not already (https://claude.ai/code).
• Install the DevSpec Autopilot plugin: run /install-plugin in Claude Code and point it to the devspec-autopilot plugin, or install from the marketplace.

Step 2: Configure MCP connection

// Add to your .mcp.json (project root or ~/.claude/.mcp.json)
{
  "mcpServers": {
    "devspec": {
      "type": "http",
      "url": "https://staging.devspec.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dvs_your_token_here"
      }
    }
  }
}

Step 3: Configure project settings

• In DevSpec, go to your project Settings → CLI Plugin Settings.
• Set Target Branch to your deployment branch (e.g., staging).
• Enable Auto-push and Auto-merge.
• Set Branch Prefix (e.g., work/action-item-).
• Optionally configure test commands (typecheck, unit tests) and protected paths.

Step 4: Start the runner

# In Claude Code, run:
/autopilot.start

# The runner will poll for work and process items automatically.
# Use /autopilot.status to check the current state.
# Use /autopilot.stop to stop the polling loop.

Targeting and filtering what a runner picks up (Claude Code)

By default /autopilot.start processes items assigned to you plus the unassigned pool, highest-priority first, and keeps polling until you stop it. Flags let you narrow that: run only a specific list of items, scope to a teammate's staged items, filter by who created the work, or process everything staged once and exit. Flags can be combined freely (e.g. --mine --drain).

Run only specific items, in order (targeted mode)

# Pass action item IDs (comma-separated). The runner processes
# ONLY these items, in the order given, then exits — it never
# touches any other staged items.
/autopilot.start --items=ID1,ID2,ID3

# Grab an item's ID from its detail-page URL or the action items list.

--items implies drain mode: the loop exits cleanly once the last listed item finishes (success or failure), with no idle polling afterward. If a listed item is no longer staged — already implemented, dismissed, or assigned exclusively to someone else — it is skipped and the runner moves on; it never force-claims another user's work. IDs must be valid UUIDs, or the runner stops before starting.

Scope by assignee

• --mine — only items assigned to you, plus unassigned items. This is the default.
• --assigned-to=<user_id> — run a specific teammate's staged items (their items plus unassigned items).
• --all — all staged work: every item you can see, regardless of who it is assigned to.

Scope by creator

# Only items authored by a specific user. Layers on top of the
# assignee filter — when both are set, both must match.
/autopilot.start --created-by=<user_id>

--created-by is ANDed on top of the assignee filter, so --created-by=<user_id> on its own only returns items that are both authored by you and assigned to you (or unassigned). It does not, by itself, mean "everything I created".

Common recipe: everything I created, regardless of assignee

# Process only the items YOU authored, no matter who they are
# assigned to. --all clears the default assignee filter so
# --created-by is the only thing narrowing the staged work.
/autopilot.start --all --created-by=<your_user_id>

You need both flags: without --all, the default assignee filter (--mine) is still ANDed in, so items you created but assigned to a teammate are skipped. There is no "staged" flag — the runner only ever fetches and claims staged work, so --created-by already means "staged items I created".

Process everything staged, then stop

# Process everything staged once and exit on the first idle
# cycle, instead of polling indefinitely:
/autopilot.start --drain

# Combine freely — e.g. drain only your own staged items:
/autopilot.start --mine --drain

Option B: Antigravity (ephemeral runner)

Antigravity is Google's coding agent (CLI agy and desktop). It processes one action item per invocation via DevSpec skills. Run it manually for continuous on-demand processing. It reads the same project settings as Claude Code and merges to the same target branch.

Windows users: Prefer ; instead of && when chaining shell commands if your shell is PowerShell.

Step 1: Install Antigravity

Install the Antigravity CLI (agy) and/or the desktop app from antigravity.google.

Step 2: Connect the DevSpec MCP server

Antigravity uses the serverUrl key (not url / httpUrl).

CLI — merge into ~/.gemini/antigravity-cli/mcp_config.json:

{
  "mcpServers": {
    "devspec": {
      "type": "http",
      "serverUrl": "https://staging.devspec.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dvs_your_token_here"
      }
    }
  }
}

Desktop — Settings → MCP → Add server (HTTP), paste the same serverUrl and Authorization: Bearer … header.

Use a read-write token from You → Connections. At go-live, switch the host to https://devspec.ai/api/mcp.

Step 3: Install the DevSpec skills

From the DevSpec Antigravity plugin:

./scripts/install.sh                  # installs into ./.agents/skills
# or globally:
./scripts/install.sh --global         # ~/.gemini/antigravity/skills

Skills include devspec-work, devspec-brainstorm, devspec-autopilot, autopilot-status, and more.

Step 4: Process an item

In Antigravity (CLI or desktop), from your project directory:

# Work a specific item:
/devspec-work <action-item-id>

# Or process the next staged item:
Use the devspec-autopilot skill

Step 5: Continuous processing (optional)

Re-run the autopilot skill (or schedule a CLI invocation if you wrap agy for your environment) every N minutes. Antigravity is ephemeral — each run processes one item and exits; there is no always-on poll loop.

Option C: Cursor (interactive extension)

The DevSpec Autopilot extension for Cursor adds command-palette entries for each workflow. Each command loads a curated SKILL.md prompt and copies it to your clipboard so you can paste it into Cursor chat — the agent then orchestrates the rest using the DevSpec MCP server. Best for engineers who want to run autopilot interactively from the editor with full agent visibility.

Note: Cursor does not support a background polling loop like Claude Code's /autopilot:start. Use one-shot Process next staged item — run again per item, or pass --items=uuid1,uuid2 for a targeted batch.

Step 1: Install the extension

Pick either path (repo: https://github.com/DevSpecAI/cursor-devspec-plugin):

From GitHub release

• Download the latest devspec-autopilot.vsix from https://github.com/DevSpecAI/cursor-devspec-plugin/releases
• In Cursor: Ctrl+Shift+P → Extensions: Install from VSIX… → select the file

From source

git clone https://github.com/DevSpecAI/cursor-devspec-plugin.git
cd cursor-devspec-plugin
npm install
npm run package   # produces devspec-autopilot.vsix

Then install the VSIX via Extensions: Install from VSIX… as above.

Step 2: Restart Cursor

After installing or updating the VSIX, restart Cursor (Ctrl+Shift+P → Developer: Reload Window). DevSpec commands and the MCP server do not load until the extension host reloads.

Step 3: Configure the connection

• Run Ctrl+Shift+P → DevSpec: Set MCP token (or click Connect on the first-run toast)
• Enter your DevSpec API URL when prompted (e.g. https://staging.devspec.ai)
• Paste your DevSpec MCP token (dvs_…) from You → Connections
• The extension writes the devspec server to ~/.cursor/mcp.json

After changing the API URL or token, always open a brand new Agent-mode chat before running a skill. Cursor binds MCP availability at chat-thread-open time, so existing chats keep the old (possibly broken) state.

Step 4: Install project rules

The extension adds always-on agent guidance at .cursor/rules/devspec.mdc — track work in DevSpec, use MCP tools proactively, tag commits.

• Automatic (default): installs when MCP connects.
• Manual: Ctrl+Shift+P → DevSpec: Install rules (git repo required).

Step 5: Configure project settings

• In DevSpec, go to your project Settings → CLI Plugin Settings.
• Same options as Claude Code / Antigravity: Target Branch, Auto-push, Auto-merge, Branch Prefix, Test Commands, Protected Paths.

Step 6: Run a workflow

Open the command palette (Ctrl+Shift+P → type "DevSpec"). Each command copies a SKILL.md prompt to your clipboard — open a fresh Agent-mode chat (Ctrl+L → New Chat), paste, and send.

Work & planning

• DevSpec: Work on action item — pick up a specific item (optional --unattended in the input prompt)
• DevSpec: Brainstorm action item — multi-round scope exploration
• DevSpec: Create action item — create a new item from the agent
• DevSpec: Continue session in local agent — hand off a DevSpec web chat session
• DevSpec: Log completed work — record ad-hoc work outside the action-item flow

Utilities

• DevSpec: Verify connection — ping mode (no git) or commit mode (setup wizard)
• DevSpec: Help — search official DevSpec product docs
• DevSpec: Link commit to item — associate a git commit with an action item
• DevSpec: Commit with tracking tag — generate a [devspec:<id>] commit message

Autopilot (one-shot)

• DevSpec Autopilot: Show status — queue counts, in-progress items, push/merge settings
• DevSpec Autopilot: Process next staged item — claim and implement the next staged item; add --items=uuid1,uuid2 in the input prompt for a targeted batch
• DevSpec Autopilot: Show history — recent completed and failed autopilot runs

Option D: Grok Build (ephemeral runner)

Grok Build processes one action item (or a listed batch) per invocation — the same ephemeral model as Antigravity. Install the DevSpec plugin for skills, then run interactively in the TUI or headless with --always-approve.

Step 1: Install Grok Build

Follow the Grok Build install instructions for your platform, then sign in (grok).

Step 2: Connect MCP and install the plugin

During validation, point MCP at staging (examples below). At go-live, switch to https://devspec.ai/api/mcp. Create the token on the same environment.

grok mcp add --transport http devspec https://staging.devspec.ai/api/mcp \
  --header "Authorization: Bearer dvs_your_token_here"

grok plugin install DevSpecAI/DevSpec-Grok-Build-Plugin --trust

Use a read-write token from You → Connections. See the MCP Endpoint doc for TOML config details.

Step 3: Run one item (interactive)

In the Grok Build TUI, from your project directory:

/devspec-work <action-item-id>

Or process the next staged item:

Use the devspec-autopilot skill

Step 4: Unattended / cron (one-shot)

cd /path/to/your/repo
grok --always-approve -p 'Use the devspec-autopilot skill'

Targeted batch:

grok --always-approve -p 'Use the devspec-autopilot skill with --items=uuid1,uuid2'

Use single quotes around the -p prompt when pasting into a terminal (double quotes are easy to mangle into “smart quotes” or leave unclosed, which makes the shell wait instead of starting Grok). --always-approve is required for fully unattended tool use. There is no always-on poll loop; schedule the command (e.g. cron) if you want continuous drain.

Plugin source and full skill list: DevSpecAI/DevSpec-Grok-Build-Plugin.

Project settings (all runners)

All runners read the same project settings from DevSpec. Configure these in your project Settings → CLI Plugin Settings:

Settings reference

• Auto-push — Push feature branches to remote after committing (default: off).
• Auto-merge — Merge feature branches into target branch after pushing (default: off). Implies auto-push.
• Target Branch — The branch to merge into (e.g., staging). Falls back to the branch the runner started on.
• Branch Prefix — Prefix for feature branches (e.g., work/action-item-).
• Test Commands — Commands to run before committing (e.g., npm run typecheck).
• Protected Paths — Files that runners should not modify (e.g., package.json, .env).
• Custom Instructions — Additional instructions that runners follow during processing.

Troubleshooting

Common issues and solutions for both runner types.

Common issues

• "No items staged" — Nothing is staged. Check DevSpec to verify action items exist with agent_activity: staged.
• "401 Unauthorized" — Your MCP token is invalid or expired. Generate a new one in DevSpec Settings.
• "Item already claimed" — Another runner claimed the same item (normal race condition). Run again to get the next item.
• "No MCP servers found" (Antigravity) — MCP config missing or skills not installed. Confirm serverUrl in ~/.gemini/antigravity-cli/mcp_config.json (or desktop MCP settings) and re-run the plugin install script.
• Grok Build MCP missing — Run grok mcp list and re-add the server; install the plugin with grok plugin install DevSpecAI/DevSpec-Grok-Build-Plugin --trust.
• Changes not merging to staging — Verify Auto-merge is enabled in project settings and Target Branch is set correctly.
• Grok Build pauses for confirmation — Use grok --always-approve -p '…' for unattended runs.
• Shell error "token && is not a valid statement separator" — You are on Windows/PowerShell. The extension handles this automatically, but if you see this error, ensure you have the latest extension version: /extensions update devspec-autopilot
• "DevSpec MCP server is not reachable from this chat" (Cursor) — Cursor caches MCP availability per chat thread. Open a brand new Agent-mode chat and re-run the skill. If it still fails, check Cursor Settings → MCP that the devspec server shows green with all tools listed.
• Cursor extension was installed but commands do not appear — Restart Cursor (Ctrl+Shift+P → Developer: Reload Window). Installing a VSIX does not reload the extension host. If the issue persists, uninstall and reinstall the VSIX.
• Project rules file missing (.cursor/rules/devspec.mdc) — Run DevSpec: Install rules from the command palette (git repo required). Default devspec.autoInstallRules is always; rules install on first MCP connect after reload.