Headless AI Coding Agents in CI: Claude Code, Codex CLI, Gemini CLI, and opencode Compared

Running an AI coding agent interactively in a terminal is one thing. Running it unattended inside a CI job, where nobody is there to click "allow" on a tool call, is a different problem: you need a non-interactive invocation mode, a way to constrain what the agent can touch, a machine-readable output format, and a sane way to hand it credentials without leaking them into logs.

Four tools currently ship first-class headless modes worth comparing for real pipelines: Claude Code, OpenAI's Codex CLI, Google's Gemini CLI, and the open-source opencode. This is not a benchmark of which one writes better code. It's a comparison of the plumbing: how each one is actually invoked in CI, what its sandbox and permission model does when there's no human to ask, and what the output looks like when you need to parse it.

Non-interactive invocation#

Claude Code runs headless with the -p/--print flag, which prints a single response and exits instead of opening the REPL. Combine it with --output-format json or --output-format stream-json for machine-readable output, and --permission-mode to control tool approval without a human present. Official docs: Claude Code SDK / headless mode.

Codex CLI has a dedicated non-interactive subcommand, codex exec (aliased codex e), built specifically for scripts and CI rather than being a flag bolted onto the interactive command. It takes a --sandbox/-s policy (see below) and a --json flag for newline-delimited JSON events, which can be paired with --output-last-message <path> to also capture a plain-text final summary. Note that the older --full-auto flag is deprecated in favor of --sandbox workspace-write and will print a warning if used - update any scripts still relying on it. Reference: OpenAI Codex CLI docs and the Codex CLI GitHub repo.

Gemini CLI runs non-interactively when you pipe a prompt to stdin or pass -p, and supports --output-format json. Google documents this in the Gemini CLI headless/scripting docs and the Gemini CLI GitHub Actions guide.

opencode exposes opencode run "<prompt>" as its headless entry point, with -m to pin a model and -c/-s for session continuation, which matters for multi-step CI workflows that need to resume a prior run. Docs: opencode documentation.

Sandboxing and permissions with no human in the loop#

This is the part that actually matters for CI safety, because the default assumption of an interactive agent (a person will approve risky actions) is false in a pipeline.

• Claude Code's --permission-mode and settings-based tool allowlists let you pre-approve exactly which tools (bash, file edit, etc.) run without a prompt; anything outside that list should fail closed rather than block on an approval that will never come. See the Claude Code settings and permissions reference.
• Codex CLI's sandbox modes (read-only, workspace-write, danger-full-access) are documented in the Codex CLI config reference; workspace-write is the sane default for a CI job that needs to edit files but not touch the rest of the filesystem or network.
• Gemini CLI supports a --sandbox flag backed by Docker/Podman or macOS Seatbelt profiles, described in the Gemini CLI sandboxing docs.
• opencode's permission model is configured per-agent in opencode.jsonc (the permission block on each agent), so a CI-specific agent definition can be scoped tighter than your interactive build agent.

None of these are a substitute for running the whole job inside an already-sandboxed CI runner or container. Treat the tool's own sandbox flag as a second layer, not the only layer.

Auth and secrets in CI#

All four expect an API key or OAuth token via environment variable rather than an interactive login, which is the right shape for CI secrets managers:

• Claude Code: ANTHROPIC_API_KEY, documented in the Claude Code CI/CD guide.
• Codex CLI: OPENAI_API_KEY, or GitHub App auth via the Codex GitHub Action.
• Gemini CLI: GEMINI_API_KEY or Google Cloud Application Default Credentials, per the Gemini CLI authentication docs.
• opencode: provider-specific keys resolved through opencode auth login or environment variables per provider, per the opencode providers docs.

Whichever you use, scope the key to the minimum project/model access your CI job needs and rotate it separately from any key you use interactively, since a leaked CI secret has a much bigger blast radius than a local session.

Output formats for parsing in a pipeline#

A CI job needs a deterministic way to tell "the agent succeeded and did X" from "the agent failed, timed out, or refused." Structured output matters more here than in a terminal session:

• Claude Code's stream-json output gives you an event stream you can tee into a log processor and still get a final result block for pass/fail logic.
• Codex CLI's codex exec --json emits newline-delimited JSON events plus a proper process exit code, which is the simplest thing to gate a pipeline step on.
• Gemini CLI's --output-format json gives a single JSON object per invocation.
• opencode's run command output is primarily plain text by design; if you need structured events, opencode serve (the headless server mode) is the better fit for programmatic polling than parsing run output.

Practical decision guide#

• Already standardized on Anthropic for interactive development? Claude Code's headless mode reuses the same config, skills, and MCP servers as your interactive setup, so CI behavior matches local behavior. Check the GitHub Actions integration first.
• Need the tightest sandbox-mode granularity and already use OpenAI models? Codex CLI's codex exec was purpose-built for this and has the most explicit sandbox levels of the four. Start with the Codex CLI GitHub repo.
• On Google Cloud infrastructure already, or want Docker/Podman-backed sandboxing out of the box? Gemini CLI's sandbox flag is the most container-native of the group. See the Gemini CLI Action.
• Running multiple model providers from one CI pipeline, or need per-agent config (different model for lint-fix vs. test-fix jobs)? opencode's per-agent opencode.jsonc config is the most flexible for mixed-provider pipelines. See opencode's agent docs.

Whatever you pick, start every CI integration in the most restrictive sandbox mode available, run it against a throwaway branch or fork first, and only loosen permissions once you've watched it operate on real diffs.

FAQ#

Can I run Claude Code, Codex CLI, Gemini CLI, or opencode without any human approval in CI?#

Yes, all four have a documented non-interactive/headless mode built for exactly this: claude -p, codex exec, gemini -p (or piped stdin), and opencode run. Each still requires you to pre-configure permissions, since there's no one to approve individual tool calls mid-run.

Which tool has the best sandboxing for untrusted CI jobs?#

Codex CLI and Gemini CLI both expose explicit sandbox levels (read-only, workspace-write, full-access for Codex; Docker/Podman/Seatbelt profiles for Gemini CLI). Claude Code and opencode rely more on allowlist-style permission configuration. In all cases, running the whole CI job inside an already-isolated container or ephemeral runner is still the baseline you should not skip.

Do these tools support GitHub Actions directly?#

Yes. Anthropic publishes a Claude Code GitHub Action, OpenAI publishes a Codex Action, and Google publishes a Gemini CLI Action. opencode does not ship an official first-party GitHub Action as of this writing, so a headless opencode run step inside a standard actions/checkout + install job is the common pattern.

What is the difference between running these headless versus their normal interactive mode?#

Headless mode swaps the REPL for a single prompt-in, response-out invocation (or a resumable session), disables interactive approval prompts in favor of pre-set permission configuration, and typically adds a structured output format so a pipeline can parse success/failure without parsing raw terminal text.

Can I mix models within one CI pipeline using these tools?#

opencode is built for this directly, letting you define separate agents pinned to different models in one config file. The others are generally single-provider per invocation, though you can still run separate CI steps with different tools or different -m flags to approximate the same effect.

Official Sources#

Continue Reading#

• Claude Code vs Codex vs Cursor vs opencode (2026) - feature comparison across four coding agents
• AI Coding Tools Pricing 2026 - cost comparison across all major tools
• Claude Code Dynamic Workflows Guide - building agentic CI pipelines with Claude
• Cursor Automations Developer Guide - automated coding workflows in Cursor