Headless & CI

You tried to wire the agent into a script and the TUI got in the way. It wants to confirm permissions. It wants to draw a status bar. It’s expecting a human to type. The thing that’s effortless interactively is suddenly a fight against the loop you didn’t realise was assumed.

What you were trying to automate is the part the agent is great at when you’re driving it: triaging an incoming bug report, drafting a release-notes summary from a diff, sweeping the codebase for missing test coverage, generating a TL;DR of a long PR description. You’d love this to just happen. On the schedule. On the GitHub event. As part of CI. Without you sitting there.

Headless mode is the entry point with the human assumption removed. The same agent, the same skills, the same model - but invoked as a subprocess that takes input from stdin or a flag, produces output to stdout (often as structured JSON), and exits with a status code.

Now your nightly job, your GitHub Action, your pre-push git hook, your Slack /triage slash-handler - all of them can call the agent like any other command-line tool.

Every CLI in scope has that non-interactive surface: you pass a prompt, the agent runs its loop to completion, prints a result, and exits. There is no interactive TUI or live approval prompt; approval, sandbox, hook, and credential policy must be configured before the run. In other words: call it from a script, get a result back, and make the unattended posture explicit.

The shapes converge - all of them give you a run / exec / -p / --prompt subcommand - but the surrounding ecosystem (SDKs, GitHub Actions, structured-output formats, remote execution, async background agents) differs significantly. That’s usually what tips the decision when you’re choosing one for an automation.

Two tools go further than a local headless command. Copilot’s canonical headless surfaces are cloud agent (background, async, GitHub-native) and the copilot CLI - both non-IDE. Cursor ships three: cursor-agent headless, Cloud Agents (REST API), and Bugbot (PR reviewer).

Real-world examples of headless agent runs:

CI code review - on every PR, an Action runs the agent against the diff and posts findings as a PR comment. Catches the easy stuff before a human reviews.
Issue triage - incoming GitHub issue triggers a workflow that asks the agent to label it, link related issues, and ping the right code-owner.
Release notes - nightly, the agent reads the day’s merged PRs and drafts a CHANGELOG entry. Human edits before publishing.
Test-gap audits - scheduled job: “list every public function added this week that has no test.” Output goes to a Slack channel.
Doc freshness checks - weekly run that grep’s for TODO: verify markers and asks the agent to confirm each one against current code, opening issues for the stale ones.
Cron-style summaries - daily standup digest from git log, weekly velocity report, monthly tech-debt scan.
Embedded in tooling - a custom CLI in your repo (bin/team-tool review) that wraps the agent SDK for repeatable, parameterised flows.
Background PR work - assign a GitHub Issue to Copilot cloud agent, walk away, come back to a draft PR.

The test: if you’re describing the task to the agent in approximately the same shape every time, and the result is something a script could consume, it belongs in headless mode.

Where the posture lives

Pick a task, an output format, and a permission posture, and the same CI job assembles into that tool’s command. Watch where the posture ends up: an allowlist flag, a sandbox tier, or a config file the command never mentions.

This builder covers five tools. Pi's headless and JSON modes are documented in the foundations headless chapter.

Task

Output

Posture

claude -p "Review the changes on this branch for regressions. Be terse." \
  --bare --allowedTools "Read,Bash(git diff *)" --permission-mode dontAsk \
  --output-format json

postureThe allowlist is the guardrail - tool patterns like Bash(git diff *) scope commands, not just tools. --bare skips auto-discovery of CLAUDE.md, hooks, and MCP servers so CI behaves deterministically, and dontAsk keeps the run from hanging on an approval no one will answer.
outputOne structured object with result, session_id, cost, and usage. Capture session_id if a later run should --resume this one.
beyondFirst-party CI: anthropics/claude-code-action@v1 wraps all of this in a GitHub Action - pass any of these flags via claude_args.

Why this and not…

You want to…	Reach for	Not
Run the agent unattended from a script or CI job	Headless / `run` / `exec` / `--prompt`	Interactive TUI
Build a long-running custom automation around the agent	SDK (Claude Agent SDK / Codex SDK / OpenCode SDK)	Shelling out every time
Run the agent on a remote machine / sandboxed env	Codex Cloud, OpenCode + Docker, a hosted Claude Agent SDK application, Cursor Cloud Agents	Local headless alone
Get structured JSON output for scripts to parse	`--output-format json` / `--json` / `--format json`	Grepping plaintext
Resume a previous session non-interactively	`claude -c`/`--resume` (Claude Code), `codex exec resume` (Codex - use this, not bare `codex resume`, for scripts), session APIs in SDKs	Restarting from scratch
Run unattended and keep humans in the loop on risky actions	Headless + tight permissions + hooks	Headless with full access
Embed the agent inside another product	SDK	Wrapping the CLI binary
Trigger an agent from a GitHub Issue or `@`-mention	Copilot cloud agent	Polling for events from a local headless run

The TUI is for driving the agent. Headless mode is for the agent being driven by something else. SDKs are for the agent being part of a bigger program. Pick by how much orchestration you need around the call.

How it works in each tool

Showing: Claude Code pick a tab to change

Command: claude -p "<prompt>" (or claude --print "<prompt>").

Runs the agent loop until it produces a final answer, prints stdout, exits. Suitable for shell pipelines. From v2.1.302, -p runs with no permission mode set start in manual (default) mode: a tool call that needs approval is denied unless --allowedTools, a hook or a rule allows it, or you pass --permission-mode. Add --bare in CI so the run skips the host’s hooks, plugins, auto memory and CLAUDE.md.

CI integration: use the official Claude Code GitHub Action for the supported GitHub-native path. The Claude Agent SDK is a standalone embeddable package for applications that need programmatic control; if you use it in CI, your workflow still hosts and invokes that application.

Streaming output: --output-format json for structured output; --output-format stream-json for line-delimited streaming.

SDK packages:

npm: @anthropic-ai/claude-agent-sdk (renamed from @anthropic-ai/claude-code in late 2025)
PyPI: claude-agent-sdk

Command: codex exec "<prompt>" (alias codex e).

Session resume / fork: for CI flows where one run produces context another consumes, the form you want is codex exec resume --last "<prompt>", or codex exec resume <SESSION_ID> for a specific one. Don’t reach for the bare commands here: codex resume opens an interactive picker and codex fork opens a picker too, so neither is scriptable. To fork non-interactively use codex exec fork <SESSION_ID> "<prompt>" (a prompt is required).

Codex Cloud: codex cloud exec runs the prompt against a remote execution environment with configurable network policy - for sandboxed CI work.

GitHub Action: a first-party GitHub Action ships from OpenAI for CI/CD integration.

Codex SDK: programmatic API for orchestrating Codex from a parent program; pairs with the OpenAI Agents SDK for multi-agent flows.

Structured output: --json (alias --experimental-json) on codex exec emits newline-delimited JSON events - one per state change (thread.started, turn.completed, item.*, error, etc.). --output-schema <file> accepts a JSON Schema constraining the final response; --output-last-message -o <file> writes only the final assistant message. Streaming is the default behavior of --json. Historical issue #15451 was closed on 2026-04-03; verify the combination with MCP on the installed Codex version before relying on it. As of 2026-10.

Command: opencode run "<prompt>". Add --auto to auto-approve permission requests that are not explicitly denied (deny rules still apply).

GitHub / GitLab integrations are first-class; OpenCode publishes connectors for repo-platform workflows.

ACP (Agent Client Protocol) is the IDE/host integration layer, but is also the cleanest path for embedding OpenCode in another tool.

Docker support for containerised deployments simplifies running OpenCode in CI.

Structured output: --format json is supported on opencode run, opencode session list, and opencode db for machine-readable streams. There is no separate --output-format or schema-validation flag.

Cursor ships a real CLI whose current docs use the command agent (earlier writing calls it cursor-agent), installable via curl https://cursor.com/install -fsSL | bash.

Headless command: agent -p "<prompt>" (or --print) returns a non-interactive response. Output formats: text (default), json, stream-json, plus --stream-partial-output for delta streaming. --force (alias --yolo) allows commands unless they are explicitly denied.

Auth: CURSOR_API_KEY. The docs flag headless as suitable for batch processing, code-review scripts, and CI pipelines, but note the CLI is in beta and “security safeguards are still evolving.”

Cloud Agents API - a REST API to spawn cloud agents programmatically. Webhook-friendly, model-selectable, integrates with GitHub PRs and Linear issues out of the box. Distinct from the local agent headless run.

Bugbot is Cursor’s AI PR reviewer. Connect a repo via the Cursor dashboard; Bugbot posts inline comments on PRs (GitHub including Enterprise Server, GitLab including self-hosted, Bitbucket including Data Center, Azure DevOps Services). Per-repo modes: review every PR, run only when mentioned (cursor review or bugbot run comment), or once per PR. Publishes a GitHub check named “Cursor Bugbot” - success for clean, neutral for issues found or superseded (other platforms report a status instead, e.g. cursor-bugbot on Bitbucket). A learned rules feature lets reviewers comment @cursor remember <fact> to teach Bugbot team-specific patterns. Pricing is usage-based.

Copilot’s canonical headless surfaces are not in the IDE. Two of them:

Copilot cloud agent (formerly called cloud agent) is the canonical async / background surface. Triggers:

Assigning a GitHub Issue to Copilot
@copilot mention in a PR comment
REST/CLI surfaces: GitHub documents issue assignment and Copilot cloud-agent management APIs, but a dedicated task-dispatch endpoint is account/surface-dependent; verify the current Copilot REST reference before automating one.
“Delegate to coding agent” button in VS Code Chat

The result is a draft PR - review, request changes via comments, merge.

Copilot CLI supports headless one-shot mode:

copilot --prompt "Show me this week's commits and summarize them" runs and exits
--allow-all-tools, --allow-tool=…, --deny-tool=… for unattended permissions
Pipe-friendly; usable from shell scripts and CI jobs
Authenticates via stored credentials or a fine-grained PAT with the Copilot Requests permission

gh copilot (legacy CLI extension) - gh copilot suggest, gh copilot explain. Retired October 25, 2025; these subcommands no longer function. gh can now install and launch the standalone copilot CLI directly instead - that CLI (above) is the one to reach for, and it was never a plain command-explainer anyway: no file edits or MCP through gh copilot, but real tool calls through copilot.

Copilot in PR review. Assign Copilot as a PR reviewer; it posts inline review comments. Configurable per-repo and via org policy. Combine with cloud agent: review → suggest changes → delegate fixes to @copilot.

GitHub Actions - copilot-setup-steps.yml is itself a workflow. Community patterns also trigger cloud agent from custom Actions via documented GitHub surfaces. GitHub’s Agentic Workflows are markdown-defined Actions documented as a public preview, so treat their syntax and availability as subject to change.

Webhooks - standard GitHub webhook events fire for cloud agent PRs (pull_request, check_run). No Copilot-specific webhook namespace as of 2026-05-21.

Print mode: pi -p "<prompt>" runs one prompt non-interactively and prints the result - the basic building block for scripts and CI steps.

Structured output: --mode json switches to an event stream instead of plain text, for pipelines that need to parse tool calls, thinking, and results rather than just the final answer.

RPC mode exposes Pi as a long-running process other languages can drive over a request/response protocol, for integrations that aren’t Node/JS.

SDK: for embedding Pi’s agent loop directly inside another application rather than shelling out to the CLI.

Trust in CI: headless runs still hit the project-trust gate on a fresh checkout. Pass -a/--approve to trust for that run, or -na/--no-approve to force a no-trust posture - pick deliberately per pipeline rather than defaulting to blanket approval just to unblock a script (see Permissions).

Comparison

Aspect	Claude Code	Codex	OpenCode	Cursor	Copilot	Pi
Headless command	`claude -p`	`codex exec`	`opencode run`	`cursor-agent -p`	`copilot --prompt`	`pi -p`
Structured output	`--output-format json`	`--json` / `--experimental-json` + optional `--output-schema`	`--format json`	`json`, `stream-json`, `--stream-partial-output`	`--output-format json` (JSONL)	`--mode json`
Streaming output	`stream-json`	NDJSON (default with `--json`)	line-delimited JSON via `--format json`	`stream-json` / partial output	`--stream=on\|off` (default on)	`--mode json` (streamed JSONL), or RPC mode
Session resume/fork	`-c`/`--continue`, `-r`/`--resume <id>`, `--fork-session` (all headless)	`codex exec resume --last` / `resume <id>`, `codex exec fork <id>`; bare `resume` and `fork` are interactive only	`-c`/`--continue`, `-s`/`--session <id>`, `--fork` (`undo`/`redo` are TUI-only)	`--resume` (CLI)	`--resume[=id]`, `--continue`	`pi -r`, `--session <id>`, `-c`
Remote / async execution	Agent SDK	`codex cloud exec`	Docker / self-hosted	Cloud Agents API (REST)	Cloud agent (background, GitHub-native)	-
First-party CI integration	Claude Code GitHub Action	GitHub Action	GitHub / GitLab integrations	Bugbot (PR reviewer)	GitHub Actions, cloud agent, PR review	`pi -p` scripted into any CI runner
Programmatic SDK	Claude Agent SDK	Codex SDK	OpenCode SDK	Cloud Agents REST API	GitHub REST/CLI surfaces; task dispatch depends on the documented Copilot surface	Pi SDK + RPC mode

Name collisions

“Headless” in Claude Code (claude -p) is the same idea as Codex’s exec, OpenCode’s run, Cursor’s cursor-agent -p, and Copilot CLI’s --prompt - but each tool’s SDK or background-agent surface is the more powerful path for non-trivial automation.
Codex Cloud is not the same as “remote MCP” - Cloud runs the whole CLI remotely; remote MCP just connects a local CLI to a remote tool server.
Copilot cloud agent (background async PR work, formerly called Coding Agent) is a different surface from Copilot CLI headless (copilot --prompt). The older gh copilot GitHub-CLI extension was retired in October 2025 - don’t confuse it with either of the two live surfaces.
Cursor Cloud Agents (REST API, GitHub-native) ≠ cursor-agent headless (local CLI) ≠ Bugbot (PR reviewer service).

Start smaller than a GitHub Action. Take one task you already run by hand, invoke it once with your tool’s headless flag and JSON output, and read what lands on stdout - that tells you whether the automation wants a shell script, a scheduled job, or the SDK. Tighten permissions before you put it on a trigger: an unattended run has nobody left to say no.