Skip to content

Glossary

Headless mode

Last updated

Definition

Headless mode, also called non-interactive mode, is running an AI coding agent from a single command or script, so it works through a prompt and prints the result without an interactive interface.

Also called: non-interactive mode, print mode, claude -p, codex exec.

Claude CodeCodex
Commandclaude -p "Summarise this repo" (--print)codex exec "Summarise this repo" (alias codex e)
Machine-readable output--output-format json or stream-json--json (one JSON event per line); -o saves the last message
Continue a conversation--continue, or --resume <session-id>codex exec resume --last
Permissions--permission-mode, --allowedTools--sandbox (-s)

Headless runs are how agents get into scripts, CI jobs and scheduled tasks, for example piping git diff into claude -p to review a change. They use the same login and plan as interactive use. The catch is that nobody is there to approve anything: a claude -p run starts in the default permission mode, so actions that would prompt are denied unless you pre-approve tools or choose another mode, and Codex runs are bounded by their sandbox. Sessions started with claude -p don't appear in claude --resume's picker, but you can resume them by ID.

In Pairbar

Pairbar uses headless runs of your own claude and codex: a Claude chat with custom settings runs its first turn with claude -p and then opens in Claude, interactive Codex new chats open as native drafts for you to review and Send, and every workflow step and check-in runs this way. Send message… continues a Claude chat with claude -p --resume, and helper chats agents ask for (once you approve) run headless too. Because headless runs can't ask, pick Can run commands or Can edit files for steps that need them. See How chats start and What happens when it runs.

Frequently asked questions

What does `claude -p` do?
It runs Claude Code non-interactively: it takes the prompt, does the work and prints the result, optionally as JSON, then exits.
Is `codex exec` the Codex equivalent of `claude -p`?
Yes. codex exec runs Codex without an interactive interface, and --json prints its events as newline-delimited JSON.
Why does a headless run fail at a permission prompt?
Nobody can answer it, so the action is denied. Pre-approve the tools it needs, or choose a permission mode or sandbox that allows them.

Related