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 [email protected] "RobertTLange/headless-cli/skills/headless-swarm#$HEADLESS_REF" ~/.codex/skills/headless-swarm

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

# 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 --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

# 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

# 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, cursor. ACP-compatible agents are explicit-only: use headless acp --acp-agent ... or headless acp --acp-command ....

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, --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 | | --- | --- | --- | | 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.
• 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.