Headless Mode: Running Agents Without Interaction

In headless or non-interactive mode, an AI agent runs without a chat window — great for scripts and CI, but it can't ask you anything.

What headless means

Normally you chat live with an agent: it asks a question, you answer, it continues. In headless or non-interactive mode, that dialogue disappears. You provide a prompt as an argument or via a pipe, the agent works through it, and returns a single answer at the end — no follow-up questions, no chat window.

What this looks like in Claude Code

The command claude -p "Find and fix the bug in auth.py" starts Claude Code non-interactively. You can also pipe data in: cat error.log | claude -p "Explain the root cause". The output can be retrieved as plain text or as structured JSON (--output-format json), which fits nicely into scripts.

What it's used for

Batch processing: automatically working through many files or tickets
CI/CD: e.g. automatically checking every pull request for typos or security issues
Cron jobs and scheduled automation without human involvement

The risk: no follow-up questions

The biggest difference from interactive mode: the agent cannot ask you for permission or clarification. If it runs into a situation where it would normally ask, it has to decide on its own or abort. That's why choosing the right permission mode (see its own entry) matters so much in headless operation: without clear rules, an agent can either do too little (constantly aborting) or too much (taking risky actions without asking).

EXAMPLE

# CI script: typo check for every PR diff git diff main | claude -p "Find typos in this diff. For each one, output 'file:line' and the issue, nothing else." --output-format json

🛠️ EXERCISE — TRY IT YOURSELF

Build a simple headless call that summarizes a file, and observe how it behaves without being able to ask questions.

Run in a terminal: claude -p "Summarize this file in 3 sentences" --allowedTools "Read" with a real file from your project.
Repeat the call, but point it at a file that doesn't exist — observe how the agent reacts without asking (an error instead of a question).
Try --output-format json and look at the resulting JSON: which fields besides the actual text does it contain?

✅ SELF-CHECK

☐ Could you explain why the agent didn't simply ask when the file was missing?
☐ Did you understand what --allowedTools is good for in this context?
☐ Do you know the two scenarios (batch, CI) from the entry where headless operation makes the most sense?

QUICK QUIZ

What is the biggest risk when running an agent in headless / non-interactive mode?