This lesson is being recorded
Every video of this course is being uploaded to my YouTube channel. Subscribe so you do not miss it.
Bruno Ashford @brunoashfordSubscribeModule 10 · Lesson 10.2 · 12 min
Hands-Off Runs, Safely
Understand headless mode (claude -p), its limits, and how to give an unattended run only the permissions it needs.
Use ← → to move. The marker highlights text and the pencil draws on the slide; navigation locks while you annotate. Undo removes the last mark, Esc exits.
1Run your first headless command
From your business folder, run a read-only question with -p. Claude reads what it needs, prints the answer and exits. This is exactly what a scheduler will run for you later.
claude -p 'Read finance/open-invoices.csv and list the five largest overdue invoices with client, amount and days late.'2Send the output to a file
Headless output is plain text, so you can redirect it into a dated report. This means the agent only needs permission to read, not to write, which is a much safer starting point.
claude -p "$(cat prompts/weekly-ops-check.md)" > "ops/reports/ops-check-$(date +%F).md"3Lock it down with a permission mode and an allowlist
Add --permission-mode dontAsk and --allowedTools. In dontAsk mode, anything that would normally ask for your approval is denied, and only the tools you list (plus ordinary file reads in your folder) are allowed. For a report routine, Read is often all it needs.
claude -p "$(cat prompts/weekly-ops-check.md)" --permission-mode dontAsk --allowedTools "Read" > "ops/reports/ops-check-$(date +%F).md"4Get structured output when a script needs it
If another tool will read the result, ask for JSON with --output-format json. The response includes the text result, a session ID and an estimated cost, which you can record in your run log.
claude -p 'Summarise this week in three bullet points from ops/reports' --permission-mode dontAsk --allowedTools "Read" --output-format json5Know the limits
A headless run cannot ask you a clarifying question, so vague prompts produce vague work. It loads your CLAUDE.md, skills, hooks and MCP servers from the folder it runs in, so run it in the right folder. And never use the setting that skips all permission checks on your own computer; it is meant only for isolated containers.
When you work with Claude Code interactively, you are the safety net. It asks before running a command, and you can say no. At 7am on a Monday, nobody is there to say no. That changes the question from what can the agent do to what should it be allowed to do when nobody is watching.
Headless mode is simply Claude Code without the conversation: you run claude -p with a prompt, it does the work and prints the result. The skill is in the flags. You decide which tools it may use, and anything outside that list is refused instead of waiting for an approval that never comes.
Key points
- claude -p runs Claude Code without the conversation.
- Unattended means nobody can approve, so decide permissions in advance.
- dontAsk plus a short allowlist is the safe default for routines.
- Redirect output to a file so the agent only needs to read.
Avoid
- Giving a scheduled run broad permissions because it worked interactively.
- Using the skip-all-permissions option outside an isolated container.
- Running the command from the wrong folder, so it misses your CLAUDE.md.
- Writing a prompt that assumes it can ask you questions.
A US outdoor gear store ran its first headless stock report with no restrictions, and the agent helpfully decided to also tidy up the exports folder by renaming files. Nothing was lost, but the next day's import failed. The owner rebuilt the routine with dontAsk mode, Read only, and output redirected to a dated file. It has run every morning for four months without touching a single source file.