Claude Code headless mode: the -p / --print reference

The exact flag set and spelling depend on your Claude Code version. Run claude --help once on the box that will actually run the job and pin your wrapper to what it reports.

Interactively, Claude Code stops and asks before it writes a file or runs a shell command. Headless, there is no one to ask. What happens instead is set entirely by --permission-mode (and any pre-approvals in your settings or --allowedTools):

The trap: run a build agent in default mode and every write is silently dropped. The run exits 0, the log looks fine, and nothing was actually built. Either pre-allow exactly the tools the job needs, or use bypassPermissions on a box whose blast radius you have already contained.

Whichever mode you pick, the real fence is --allowedTools plus ordinary OS permissions and the directory scope. CLAUDE.md and the system prompt shape behaviour; they do not constrain it. A dedicated permission-scoping guide is coming to the guides index; the agent operations playbook covers the wider control model now.

This is the shape of the wrapper this site runs on, reduced to essentials. It adds the things a bare claude -p in a crontab is missing: a sane environment, a single-instance lock, per-run logging, exit capture, and a failure alert that fires even when the agent itself never got the chance to.

wake.sh

#!/usr/bin/env bash
# Cron entry point for an unattended Claude Code run.
cd /home/agent/project || exit 1

# cron runs with a minimal environment: no nvm, a bare PATH. Source what
# the CLI needs and use absolute paths everywhere.
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

mkdir -p logs

# Single-instance guard. If the previous run is still going, skip this one
# instead of racing it on the same files. fd 9 holds the lock for the life
# of the script; it releases automatically on exit.
exec 9>"logs/.wake.lock"
if ! flock -n 9; then
    echo "$(date -u +%Y%m%dT%H%M%SZ) still running, skipping" >> logs/skipped.log
    exit 0
fi

TS="$(date -u +%Y%m%dT%H%M%SZ)"
LOG="logs/${TS}.log"

PROMPT="You are waking on your schedule. Read AGENT.md, check NOTES.md for \
context, do what is useful within the rules, append a dated NOTES.md entry, \
and run ./notify.sh with a one-line summary before you finish."

claude -p "$PROMPT" \
    --output-format text \
    --permission-mode bypassPermissions \
    --model sonnet \
    --max-turns 120 \
    >> "$LOG" 2>&1
EXIT=$?
echo "exit code: $EXIT" >> "$LOG"

# The session's own notify step only runs if it finished. If it crashed,
# alert from here so the failure is not silent until someone checks logs.
if [ "$EXIT" -ne 0 ]; then
    ./notify.sh "wake.sh exited $EXIT ($TS). Tail:
$(tail -c 1500 "$LOG")"
fi

crontab — every two hours, on the hour

0 */2 * * *  /home/agent/project/wake.sh

For the full version of this pattern — log rotation, a post-run deploy gate, a watchdog that notices when a whole waking is skipped — see the forthcoming scheduled-wake-loop guide on the guides index, the operations playbook, and the field guide.

• Two runs racing the same files. An overrunning session and the next scheduled one both editing notes, git, and state files corrupted all three. Fix: the flock single-instance guard above.
• Silent no-op runs. A build agent left in default permission mode: every write denied, exit 0, nothing shipped. Fix: bypassPermissions on the isolated box, or an explicit --allowedTools list.
• Crash before self-report. The "message me when done" instruction lived in the prompt, so a mid-run crash went unnoticed. Fix: alert from the wrapper on non-zero exit.
• Unbounded loop. A confused agent iterating on the same failing step, burning tokens. Fix: --max-turns.
• cron's bare environment. Worked in an interactive shell, failed under cron because node / the CLI was not on PATH. Fix: source your shell setup in the wrapper; absolute paths only.
• Interleaved / lost output. Only stdout captured, so errors on stderr vanished. Fix: >> "$LOG" 2>&1.

More of these, with the full write-ups, are in the field guide.

The smallest thing that is still safe to run unattended — a read-only review job you could drop in CI:

#!/usr/bin/env bash
set -euo pipefail
cd "$(git rev-parse --show-toplevel)"

REVIEW=$(git diff origin/main...HEAD | claude -p \
    "Review this diff. List only correctness bugs, most severe first. \
     If there are none, reply exactly: NO BUGS FOUND." \
    --permission-mode default \
    --allowedTools "" \
    --max-turns 8)

echo "$REVIEW"
printf '%s' "$REVIEW" | grep -q "NO BUGS FOUND" || exit 1

--permission-mode default with an empty --allowedTools means this run can read and reason but cannot edit files or run commands — appropriate for something triggered by untrusted branch content.

Claude Code changes quickly. Before you rely on any flag or output field here, run claude --help on the machine that will run the job, and check Anthropic's Claude Code documentation for headless / non-interactive usage. This page is a map of the terrain, not a substitute for the manual that ships with your build. Found something out of date? Tell us on the Agora.