Headless & CI
What headless mode is
Section titled “What headless mode is”Every CLI in scope has a way to run non-interactively: you pass a prompt, the agent runs its loop to completion, prints a result, and exits. No TUI, no live editing, no approvals — just call it from a script, get an answer back.
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 in scope go further than a local headless command. Copilot’s canonical headless surfaces are Coding Agent (background, async, GitHub-native) and the copilot CLI — both non-IDE. Cursor ships cursor-agent plus Cloud Agents (REST API) and Bugbot (PR reviewer).
Why you’d want one
Section titled “Why you’d want one”You’ve got a thing 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.
Then you try to wire it up and the TUI gets 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.
That’s the gap headless mode closes. 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.
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
CHANGELOGentry. 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: verifymarkers 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 Coding 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.
Why this and not…
Section titled “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, Claude Agent SDK, 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 | codex resume (Codex), 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 Coding 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
Section titled “How it works in each tool”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.
CI integration: the Claude Agent SDK is the recommended path for richer automation than -p allows — for example, in GitHub Actions, you’d typically wrap an SDK call rather than shell out to the CLI.
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-codein early 2026) - PyPI:
claude-agent-sdk
Command: codex exec "<prompt>" (alias codex e).
Session resume / fork: codex resume re-enters the last session; codex fork branches a session. Useful for CI flows where one run produces context another consumes.
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. Known bug: --json + --output-schema is silently ignored when MCP servers are active (issue #15451).
Command: opencode run "<prompt>".
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, cursor-agent (often shown as 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 lets the agent write files without confirmation.
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 cursor-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). 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. 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 Coding Agent is the canonical async / background surface. Triggers:
- Assigning a GitHub Issue to Copilot
@copilotmention in a PR comment- REST API:
POST /repos/{owner}/{repo}/issues/{issue_number}/assigneeswith Copilot as assignee, or the dedicated Copilot agent endpoints (Unverified as of 2026-05-21 on stable API path) - “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. Still ships, still useful for one-liner command help, but is not an agent — no file edits, no tool calls, no MCP.
Copilot in PR review. Assign Copilot as a PR reviewer; it posts inline review comments. Configurable per-repo and via org policy. Combine with Coding Agent: review → suggest changes → delegate fixes to @copilot.
GitHub Actions — copilot-setup-steps.yml is itself a workflow. Community patterns also trigger Coding Agent from custom Actions via the REST API. Microsoft’s Agentic Workflows (markdown-defined Actions, in awesome-copilot) describes another pattern — Unverified as of 2026-05-21 whether GA-grade or community.
Webhooks — standard GitHub webhook events fire for Coding Agent PRs (pull_request, check_run). No Copilot-specific webhook namespace as of 2026-05-21.
Comparison
Section titled “Comparison”| Aspect | Claude Code | Codex | opencode | Cursor | Copilot |
|---|---|---|---|---|---|
| Headless command | claude -p | codex exec | opencode run | cursor-agent -p | copilot --prompt |
| Structured output | --output-format json | --json / --experimental-json + optional --output-schema | --format json | json, stream-json, --stream-partial-output | — |
| Streaming output | stream-json | NDJSON (default with --json) | line-delimited JSON via --format json | stream-json / partial output | — |
| Session resume/fork | /resume (TUI) | codex resume, codex fork | Sessions w/ undo-redo | /resume (CLI) | — |
| Remote / async execution | Agent SDK | codex cloud exec | Docker / self-hosted | Cloud Agents API (REST) | Coding Agent (background, GitHub-native) |
| First-party CI integration | Claude Agent SDK | GitHub Action | GitHub / GitLab integrations | Bugbot (PR reviewer) | GitHub Actions, Coding Agent, PR review |
| Programmatic SDK | Claude Agent SDK | Codex SDK | opencode SDK | Cloud Agents REST API | REST API (Unverified on stable path) |
Name collisions
Section titled “Name collisions”- “Headless” in Claude Code (
claude -p) is the same idea as Codex’sexec, opencode’srun, Cursor’scursor-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 Coding Agent (background async PR work) is a different surface from Copilot CLI headless (
copilot --prompt) and fromgh copilot(the legacy GitHub-CLI extension, not an agent). - Cursor Cloud Agents (REST API, GitHub-native) ≠
cursor-agentheadless (local CLI) ≠ Bugbot (PR reviewer service).