Headless Claude Code on a timer: a minimal scheduled runner
A scheduled agent is a normal Claude Code session started by a timer instead of by you. The model part is the easy half. The hard half is everything around it: making sure two runs do not overlap, noticing when a run died, and keeping the bill under control. This page gives a minimal runner and the five failure modes we hit.
Check Anthropic's Claude Code documentation (headless or print mode) for the current flags before relying on the command below; options change between versions.
A minimal runner
#!/bin/sh
# scripts/operate.sh: run one cycle if no other is running
LOCK=/tmp/company-operate.lock
[ -e "$LOCK" ] && exit 0
trap 'rm -f "$LOCK"' EXIT
touch "$LOCK"
cd "$(dirname "$0")/.." || exit 1
echo "start $(date -u +%FT%TZ)" >> ops/run.log
claude -p "Run the operate skill for one cycle. Today is $(date +%A)." >> ops/run.log 2>&1
echo "end $(date -u +%FT%TZ) rc=$?" >> ops/run.log
The prompt names a skill (a procedure kept in .claude/skills/) rather than spelling out the cycle, so you can improve the procedure without touching the runner. Run the script from launchd on macOS or cron on Linux. A 30-minute heartbeat is a reasonable start: builders finish in minutes, the market takes days, so faster only costs more.
What a cycle should do
- Read the tail of the run log (did the last run end?), then the one-page state file, then the constitution.
- Check the backlog and launch builders up to the number in flight you set.
- Collect reports, add their follow-ups to the backlog, write one log line per report.
- Rewrite the state page so the next cycle starts from the truth.
What breaks
- Overlap. Two cycles at once corrupt the state file. The lock above prevents it. After a crash, remove a stale lock.
- Editing the runner while it runs. A shell reads a script incrementally, so a mid-run edit can give a syntax error in the live run. Edit only when the last log line is an
endline. - Silent death. A cycle that dies at the start logs only
end rc=1. Make the first step of every cycle read the log tail and report a non-zero exit. - Cost. A cycle that launches six builders every 30 minutes is a large bill. Set a usage budget in
CLAUDE.md: builders in flight, model tier, heartbeat. Change it deliberately. - Headless permission refusals. Some actions are refused when nobody is there to approve them. Do not let a sub-agent spend the run finding out. Record the action under a "Handoffs" heading in the state page for your next interactive session, and put the commands you do trust in the allowlist (see below).
Permissions for unattended runs
Claude Code's settings file lets you allow specific tools and commands ahead of time. Start with read-only commands and the exact scripts your cycle runs; add an entry only when you see the same prompt twice. Keep secrets in a secrets manager or an untracked env file, never in the settings file, and never in the repo. Review the allowlist when you review the rest of your rules.
Keep a person in the loop for the things that matter
Let the agent act inside limits you wrote down (spend, messages to real people, anything legal), and give it one channel to reach you for the rest. A message that says exactly what to do and what it unlocks gets answered; a status update does not.
Related
The files that make a cycle useful (the operate skill, the state page, the backlog) are described in the parallel sub-agents workflow. The Agent-Run Company Kit includes an operate skill template, a scheduling guide with this runner and a starter permissions file: see what is in it.
More from this set
- A CLAUDE.md template for a company run by Claude Code (free walkthrough)
- Run Claude Code sub-agents in parallel: a desk-and-builders workflow
- 14 lessons from running a company on AI agents (free excerpt)
- Agent-Run Company Kit for Claude Code (US$19)
Related guides
- A CLAUDE.md template for a company run by Claude Code (free walkthrough)
- Run Claude Code sub-agents in parallel: a desk-and-builders workflow
- 14 lessons from running a company on AI agents (free excerpt)
- Agent-Run Company Kit for Claude Code (US$19)
- SPF, DKIM and DMARC checker: free, runs in your browser
- Email header analyzer: free, runs in your browser