Headless Agents: Claude Code on Autopilot
Run Claude Code unattended for background tasks — scheduled maintenance, nightly builds, automated refactoring, and monitoring.
What headless mode enables
Headless mode runs Claude Code without a human in the loop. You give it a prompt, set permissions, and let it work. This is useful for tasks that are well-defined, low-risk, and benefit from running on a schedule: nightly dependency updates, automated test generation for new code, codebase-wide linting fixes, documentation updates, and performance audits. The key: headless mode requires more upfront configuration to be safe. In interactive mode, you approve each action. In headless mode, you pre-approve actions via settings.json. This means your permission configuration must be tight — allowlist only the tools and paths the agent needs. Ask Claude Code: "Set up a headless agent configuration for nightly maintenance. It should be allowed to read all files, write to src/ and tests/ only, run npm commands, and run git commands. It should not be allowed to delete files or modify configuration files."
Scheduled agents with cron
A headless agent running on a schedule is a cron job. Set up a script that runs Claude Code with a specific prompt: claude -p "Run the nightly maintenance checklist: 1. Check for outdated dependencies and update patch versions. 2. Run the test suite and fix any failing tests. 3. Check for unused imports and remove them. 4. Update the CHANGELOG with today's changes. Commit all changes to a maintenance/nightly branch and create a PR." Schedule this with cron (Linux/macOS) or Task Scheduler (Windows) to run at 2am daily. The PR creation means a human still reviews the changes — the agent does the tedious work, you approve the result.
Safety guardrails for unattended operation
Never run a headless agent with full permissions. The guardrails: restrict file write access to specific directories. Disable destructive commands (rm, git push --force, drop table). Set a timeout — if the agent runs for more than 15 minutes, kill it. Send all output to a log file for review. Require PR creation instead of direct commits to main. Add a PreToolUse hook that blocks any command containing dangerous patterns. Test your guardrails by asking the agent to do something it should not — verify it gets blocked. Run in dry-run mode first (claude -p "Show me what you would do for the nightly maintenance, but do not make any changes") to verify the plan before enabling writes.
Monitoring and alerting for agents
A headless agent needs monitoring like any production service. Add: a Notification hook that sends a Slack message when the agent starts, finishes, or encounters an error. A log file that captures all agent output with timestamps. A health check that verifies the agent ran successfully (check for the expected PR, commit, or output file). An alert if the agent fails three times in a row. Ask Claude Code: "Create a monitoring wrapper script for headless agents. It should: log all output with timestamps, send a Slack webhook notification on success and failure, track run duration and token usage, and maintain a history of the last 30 runs in a JSON file for debugging."
Autonomous AI Systems
This guide is hands-on and practical. The full curriculum covers the conceptual foundations in depth with structured lessons and quizzes.
Go to lesson