Headless CLI

One CLI entrypoint for running Antigravity, Claude, Codex, Cursor, Gemini, Pi, OpenCode, and ACP-compatible agents in headless mode.

Headless normalizes the small differences between coding-agent CLIs: prompts, models, reasoning effort, working directories, output modes, sessions, and environment checks use one interface while each backend keeps its native execution flags.

Install

Run once with npx:

npx -y @roberttlange/headless codex --prompt "Hello world"

Or install globally:

npm install -g @roberttlange/headless
headless codex --prompt "Hello world"

Requires Node.js 22+.

To install the bundled Codex skill for visual Headless swarms, use npx to copy it into Codex's skill directory:

mkdir -p ~/.codex/skills
HEADLESS_REF=main
npx -y degit@2.8.4 "RobertTLange/headless-cli/skills/headless-swarm#$HEADLESS_REF" ~/.codex/skills/headless-swarm

Python SDK

Install the typed Python wrapper after installing the Headless CLI:

pip install headless-cli

from headless_cli import Headless

headless = Headless()
result = headless.run("codex", prompt="Review this repository")
print(result.final_message)

Sync and async clients cover runs, native and tmux sessions, coordinated runs, cron jobs, Docker helpers, structured streaming, and a raw CLI escape hatch. See the Python SDK guide for the complete interface.

Core Usage

# Use the first installed supported agent.
headless --prompt "Inspect this repository"

# Choose an agent, model, and normalized reasoning effort.
headless codex --prompt "Run the tests and fix failures" --model gpt-5 --reasoning-effort high

# Opt into provider Fast mode for a Codex or Claude run. It is off by default.
headless codex --fast --prompt "Run the focused test suite"
headless claude --fast --prompt "Review this pull request"

# Read a prompt from a file and run from another repository.
headless claude --prompt-file prompt.md --work-dir /path/to/project

# Pipe a prompt over stdin.
printf "Review this diff" | headless pi --model claude-opus

# Preview the native backend command.
headless gemini --prompt "Summarize the codebase" --print-command
headless antigravity --prompt "Inspect the current worktree" --print-command
headless --prompt "identity" --print-command --json

# Run an ACP-compatible agent from the registry or a custom ACP server command.
headless acp --acp-agent auggie --prompt "Inspect this repository"
headless acp --acp-command "atlas alta agent run" --prompt "Fix the failing tests"

# Stream native JSON, debug traces, or append normalized usage.
headless pi --prompt "Summarize this repo" --json
headless codex --prompt "Fix the failing tests" --debug
headless codex --prompt "Summarize this repo" --usage
headless codex --prompt "Summarize this repo" --json --usage
headless antigravity --prompt "Summarize this repo" --usage

# Use read-only mode for review/planning work.
headless codex --allow read-only --prompt "Review this repo"

# Start or resume native sessions.
headless codex --prompt "Continue the fix" --session bughunt
headless codex --docker --session bughunt --prompt "Continue the fix in a durable Docker home"

# Launch an interactive tmux session.
headless codex --prompt "Fix the failing tests" --tmux
headless codex --prompt "Fix the failing tests" --tmux --wait --delete
headless attach --all

# Validate local setup.
headless --check

When no agent is specified, Headless selects the first installed agent in this order: codex, claude, pi, opencode, gemini, antigravity, cursor. ACP-compatible agents are explicit-only: use headless acp --acp-agent ... or headless acp --acp-command ....

Native TUI Completion

Use --tmux --wait --delete when you want Headless to launch the agent in its native TUI, wait for the final native transcript message, print that message, and then terminate the tmux session after the prompt completes.

headless codex --prompt "Fix the failing tests" --tmux --wait --delete
headless codex --prompt "\goal ship the review fixes" --tmux --wait --delete

This setup circumvents the built-in headless execution mode of each agent harness. Because the agent runs inside its own interactive TUI, native TUI features remain available, including prompts that use commands such as \goal.

Scheduled Jobs

Headless can run detached one-shot agent invocations on a schedule with a per-user daemon and local state under ~/.headless/cron.

headless cron add codex --name inbox-triage --every 1h --prompt "Triage inbox"
headless cron add codex --schedule "0 */6 * * *" --prompt-file ./triage.md --work-dir /path/to/project
headless cron list
headless cron view inbox-triage
headless cron pause inbox-triage
headless cron resume inbox-triage
headless cron kill inbox-triage
headless cron rm inbox-triage --force

Cron jobs accept detached-safe one-shot options such as --model, --fast (Codex and Claude only), --reasoning-effort, --allow, --work-dir, --docker, --modal, --timeout, --json, --debug, and --usage. Interactive tmux/session/run-management flags are intentionally rejected for scheduled jobs.

Multi-Agent Orchestration

Headless can track a local multi-agent run with named roles, team declarations, per-node logs, status updates, and routed follow-up messages. Use an orchestrator node to plan work, declare teammates with repeatable --team specs, then inspect and message the run with headless run.

headless codex --role orchestrator --run auth --node orchestrator --team explorer --team worker=2 --prompt "Build auth"
headless run view auth
headless run message auth worker-1 --prompt "Implement token refresh" --async
headless run wait auth

Roles include orchestrator, explorer, worker, and reviewer. Team specs accept forms like explorer, worker=2, claude/reviewer, and codex/worker=3. See docs/orchestration.md for coordination modes, run state, and message routing.

Supported Agents

Agent	Install	Binary used by Headless
Antigravity CLI	Follow Google's CLI install docs; the upstream installer runs a shell script from antigravity.google	agy, or set ANTIGRAVITY_CLI_BIN / AGY_CLI_BIN
Codex	npm install -g @openai/codex	codex
Claude Code	npm install -g @anthropic-ai/claude-code	claude
Cursor	curl https://cursor.com/install -fsS | bash	agent, or set CURSOR_CLI_BIN=cursor-agent
Gemini CLI	npm install -g @google/gemini-cli	gemini
OpenCode	curl -fsSL https://opencode.ai/install | bash or npm install -g opencode-ai	opencode
Pi	npm install -g @mariozechner/pi-coding-agent	pi, or set PI_CODING_AGENT_BIN
ACP	Use --acp-agent <id> to resolve from the ACP registry, or --acp-command <cmd> for a custom ACP server	headless acp-client ... adapter

Install the agent CLIs you want Headless to drive.

More Docs

• Usage guide: agents, output modes, sessions, cron jobs, Docker, Modal, config defaults, CLI flags, and environment variables.
• Python SDK: typed sync/async clients, structured streaming, namespaces, and raw invocation.
• Multi-agent workflows: roles, coordinated runs, teams, run state, messaging, and headless run commands.
• Development: local setup, test commands, pre-push integration coverage, project layout, and agent install references.

Development

npm install
npm run build
npm test
npm run check

See docs/development.md for integration tests, hooks, and repository layout.

Related Inspirations

Projects that shaped parts of Headless' CLI and session-management ergonomics:

• mngr: a tmux-based manager for running and monitoring multiple coding-agent sessions.
• llm: Simon Willison's CLI and Python library for running prompts, models, plugins, and local/remote LLM workflows.

License

Apache-2.0. See LICENSE.