autopilotctl forge

April 2, 2026 ยท View on GitHub

This is the current programmatic control surface for the internal Forge MVP in openagents.

Use it when you need to drive the shared Probe-backed coding session from a script, another agent, or a second terminal without going through the desktop chat UI.

It is intentionally narrow. It covers the shared-session seam that is already real:

  • discover visible hosted Forge sessions
  • attach the current desktop shell to a hosted shared session
  • inspect the current participant and controller state
  • request, accept, force-take, or annotate controller handoff

It does not try to expose every future Forge object. Evidence, delivery, campaign, bounty, and settlement flows still live primarily in the desktop shell.

It is also standalone for the current Forge lane. If no running desktop-control target is reachable and you did not pass --base-url plus --auth-token, autopilotctl forge ... will autostart a no-window Forge host and then run the requested command against it.

Requirements

  • a running autopilot-desktop instance with desktop control enabled, or a no-window Forge host
  • a valid autopilotctl manifest or the default manifest path
  • the Probe-backed Forge lane enabled in the desktop app
  • shared hosted session state already visible to the app

If those conditions are not true, autopilotctl forge ... will fail honestly instead of inventing hidden state.

Quick Start

Standalone discovery from a terminal:

autopilotctl forge hosted sessions --json

That command tries the resolved desktop-control manifest first. If the target is missing or stale, it starts the hidden Forge host and waits for the control endpoint to become reachable.

List visible hosted Forge sessions:

autopilotctl forge hosted sessions

Attach the current desktop shell to a shared hosted session:

autopilotctl forge hosted attach-shared forge-session-1

Inspect the active shared-session state:

autopilotctl forge status

Request control from another operator:

autopilotctl forge handoff request "taking over repo triage"

Accept an outstanding request on the current session:

autopilotctl forge handoff accept "accepted from desktop-b"

Standalone Host

The no-window runtime is:

autopilot_headless_forge

Manual startup is still supported when you want explicit lifecycle control:

cargo run -p autopilot-desktop --bin autopilot_headless_forge -- \
  --manifest-path /tmp/openagents-forge-desktop-control.json

Then point autopilotctl at it:

autopilotctl --manifest /tmp/openagents-forge-desktop-control.json forge hosted sessions

The hidden Forge host disables Codex by default. Use --enable-codex only if you intentionally want the no-window runtime to keep the Codex lane alive too.

The repo-owned smoke entrypoint is:

scripts/autopilot/headless-forge-smoke.sh

That script verifies:

  • autopilotctl forge hosted sessions --json autostarts the hidden Forge host
  • the no-window host writes the requested manifest
  • the command returns valid structured JSON
  • Forge commands fail honestly with a typed no-thread reason when no shared session is active yet

Command Reference

Status

autopilotctl forge status
autopilotctl forge status --thread-id <probe-session-id>

Shows the current shared-session view for the active or named Probe thread, including:

  • shared session id
  • Probe session id
  • current controller
  • local desktop role
  • participant roster
  • pending handoff request
  • recent collaboration timeline

Hosted Session Discovery

autopilotctl forge hosted sessions
autopilotctl forge hosted sessions --json

Lists the hosted Forge sessions that the current desktop shell knows about.

Each entry includes the shared-session id, Probe session id, repo/workspace context when available, participant count, controller label, and hosted runtime status.

Hosted Attach

autopilotctl forge hosted attach-shared <shared-session-id>
autopilotctl forge hosted attach-probe <probe-session-id>

Attaches the current desktop shell to an existing hosted Forge session and loads the matching Probe session through the same app-owned attach flow used by the UI.

Use attach-shared when you have the Forge shared-session id.

Use attach-probe when you only have the Probe session id.

Handoff Control

autopilotctl forge handoff status
autopilotctl forge handoff request <summary>
autopilotctl forge handoff accept <summary>
autopilotctl forge handoff take <summary>
autopilotctl forge handoff note <summary>
autopilotctl forge handoff human <summary>
autopilotctl forge handoff agent <summary>

All handoff commands also accept:

--thread-id <probe-session-id>

Use them like this:

  • status
    • read the current controller, pending request, and recent events
  • request
    • ask for control without forcing it
  • accept
    • accept the pending request and record the transfer
  • take
    • force control transfer when recovery or operator intervention requires it
  • note
    • append a collaboration note without changing control
  • human
    • mark the session as explicitly human-controlled
  • agent
    • mark the session as explicitly agent-controlled

JSON Output

The Forge CLI supports the normal global JSON flag after the subcommand chain.

Examples:

autopilotctl forge hosted sessions --json
autopilotctl forge status --json
autopilotctl forge handoff status --json

Use JSON output when another agent or script needs to read the shared-session state directly instead of scraping text output.

Common Flows

Discover And Attach

autopilotctl forge hosted sessions
autopilotctl forge hosted attach-shared <shared-session-id>
autopilotctl forge status

Ask Another Operator To Hand Off

autopilotctl forge handoff request "taking over fix verification"
autopilotctl forge handoff status

Accept A Handoff On The Current Desktop

autopilotctl forge handoff accept "accepted on laptop"
autopilotctl forge status

Force Recovery When The Previous Controller Is Gone

autopilotctl forge handoff take "desktop-a offline; resuming incident response"
autopilotctl forge status

Leave An Audit Note Without Changing Control

autopilotctl forge handoff note "rebased branch and re-ran targeted tests"

Current Boundary

This CLI is the right interface for the current internal team use case:

  • multiple teammates discover the same hosted coding session
  • one teammate attaches from their desktop shell
  • the team can see who currently controls the session
  • the team can request or force a controller handoff
  • the team can leave typed collaboration notes

If you need higher-level Forge product objects beyond that boundary, use the desktop shell until those surfaces are promoted into autopilotctl.