AI That Works While You Sleep

!!! warning “Prerequisites” This page assumes you’re comfortable with the terminal and basic shell scripting. If commands like export and cron are unfamiliar, spend 30 minutes on a shell scripting basics tutorial first. The Claude Code section is a gentler starting point.

What is headless mode?

When you run Claude Code normally, there’s a conversation interface — you type, Claude responds, you type again. Headless mode strips that away. You pass Claude a prompt and some flags, it runs the task, and exits. No back-and-forth. No waiting for you.

This is the foundation of automation. A headless Claude command can be called from a script, triggered by a cron job, or wired into any system that can run a shell command.

The basic pattern

The key flag is -p (for “prompt”). It switches Claude from interactive to one-shot mode:

claude -p "Summarize the last 24 hours of errors in /var/log/app.log"

That’s it. Claude reads the log, produces a summary, prints it to stdout, and exits.

A few other flags that matter:

Flag	What it does
`-p "prompt"`	Run non-interactively with this prompt
`--output-format json`	Output machine-readable JSON instead of plain text
`--max-turns 10`	Stop after this many agent steps (safety limit)
`--allowedTools "Read,Bash"`	Restrict which tools Claude can use

Piping and chaining

Claude can work inside shell pipelines like any Unix tool:

# Pipe content into Claude
cat weekly-report.txt | claude -p "Pull out the three most important action items"

# Use Claude's output in another command
claude -p "List all TODO comments in src/" | grep "URGENT"

# Write output to a file
claude -p "Generate a weekly status report" > status-$(date +%Y-%m-%d).md

This makes Claude composable with existing scripts and workflows. You don’t need to rebuild anything — just drop Claude into the pipeline where it adds value.

Practical examples

Daily email summary

Get a briefing every morning without opening your inbox.

The script (~/scripts/morning-briefing.sh):

#!/bin/bash
set -euo pipefail

source ~/.env  # Load ANTHROPIC_API_KEY

claude -p "
  Check my Gmail inbox for the last 24 hours.
  Give me:
  1. A count of unread messages
  2. Anything that looks urgent or time-sensitive
  3. Any emails that need a reply today

  Keep it brief — this is a morning briefing, not a full report.
" \
  --max-turns 5 \
  >> ~/briefings/$(date +%Y-%m-%d).md

Schedule it (runs at 7am every day):

0 7 * * * /home/yourname/scripts/morning-briefing.sh

File organization: weekly downloads cleanup

Your downloads folder gets messy. Claude can sort it.

The script (~/scripts/cleanup-downloads.sh):

#!/bin/bash
set -euo pipefail

source ~/.env

claude -p "
  Look at the files in ~/Downloads that are more than 7 days old.
  For each file, either:
  - Move it to the appropriate folder (Documents, Pictures, etc.)
  - Or tell me what it is and ask if I want to keep it

  Don't delete anything without asking first.
" \
  --max-turns 20 \
  --allowedTools "Read,Write,Bash,ListFiles"

Schedule it (runs every Sunday at 10am):

0 10 * * 0 /home/yourname/scripts/cleanup-downloads.sh

Code review on every pull request

Have Claude review every PR before a human looks at it.

The script (scripts/pr-review.sh):

#!/bin/bash
set -euo pipefail

PR_DIFF=$(git diff main...HEAD)

claude -p "
  Review this pull request diff and provide:
  1. A brief summary of what changed
  2. Any bugs or logic errors you spot
  3. Security concerns, if any
  4. Code quality notes (keep it constructive)

  Diff:
  $PR_DIFF
" \
  --output-format json \
  | jq -r '.result' > pr-review.md

echo "Review written to pr-review.md"

Wire this into your CI pipeline or git hooks.

Weekly report from multiple sources

Compile a summary that would take you an hour to write manually.

The script (~/scripts/weekly-report.sh):

#!/bin/bash
set -euo pipefail

source ~/.env

WEEK=$(date +%Y-W%V)

claude -p "
  Compile a weekly report for the week of $WEEK. Pull from:
  - Gmail: any project updates, decisions, or action items from emails
  - My calendar: what meetings happened, any follow-ups mentioned

  Format as:
  ## What happened this week
  ## Decisions made
  ## Action items for next week

  Keep it to one page.
" \
  --max-turns 15 \
  > ~/reports/weekly-$WEEK.md

echo "Weekly report saved to ~/reports/weekly-$WEEK.md"

Schedule it (runs every Friday at 5pm):

0 17 * * 5 /home/yourname/scripts/weekly-report.sh

Cron basics

If you haven’t used cron before, here’s what you need to know.

Cron is a Unix job scheduler. You define a schedule and a command in a “crontab” file, and cron runs the command at those times automatically.

Open your crontab:

crontab -e

The schedule format:

minute  hour  day-of-month  month  day-of-week  command

*       *     *             *      *            # every minute
0       7     *             *      *            # 7:00 AM every day
0       9     *             *      1            # 9:00 AM every Monday
0       8     1             *      *            # 8:00 AM on the 1st of every month

A complete crontab example:

# Morning briefing — every day at 7am
0 7 * * * /home/yourname/scripts/morning-briefing.sh >> /var/log/briefing.log 2>&1

# Downloads cleanup — every Sunday at 10am
0 10 * * 0 /home/yourname/scripts/cleanup-downloads.sh

# Weekly report — every Friday at 5pm
0 17 * * 5 /home/yourname/scripts/weekly-report.sh

The >> /var/log/briefing.log 2>&1 at the end of the first line captures both stdout and stderr to a log file. Do this for any cron job you want to be able to debug later.

!!! tip “Use full paths in cron” Cron runs in a minimal environment without your normal PATH. Use full paths to scripts and commands: /home/yourname/scripts/my-script.sh not ~/scripts/my-script.sh. Same goes for any commands inside the script — use /usr/bin/claude not just claude.

Safety for unattended AI

Running Claude without a human in the loop means it can make mistakes without anyone catching them immediately. A few habits that help:

!!! warning “Always set —max-turns” Without a turn limit, an agentic loop can run indefinitely — burning through API credits and potentially doing more than intended. Set --max-turns to a reasonable ceiling for the task. For a simple summary job, 5 turns is plenty. For something that needs to read and write files, 20 might be appropriate.

Log everything:

claude -p "your task" >> /var/log/claude-jobs.log 2>&1

Keep logs for at least a week so you can debug anything that goes wrong.

Restrict tools with --allowedTools:

If a job only needs to read files, don’t give it write access:

claude -p "summarize these logs" \
  --allowedTools "Read,Bash" \
  --max-turns 5

Test interactively first:

Before scheduling anything, run the exact same prompt in an interactive Claude session and verify it does what you expect. Automate only what you’ve already validated manually.

Don’t automate destructive actions without a review step:

A Claude job that deletes files, sends emails, or posts to external services should write its proposed actions to a file first. You review, then run a second script that executes the approved actions. The extra step is worth it.