Scheduled codebase chores run headless in CI
Run a coding agent non-interactively on a schedule to fix lint debt, update translations or refresh docs, and open a PR.
The use case
Some maintenance never gets scheduled: chipping away at lint warnings, adding missing translation keys, updating generated docs. Claude Code can run headless from a script or CI job with a prompt, a fixed set of allowed tools and structured output, and the Agent SDK lets teams build the same loop into their own tooling. A nightly job can pick a small batch of chores, make the edits, run tests, and open one pull request. A developer reviews that PR in the morning. Keep the allowed tools narrow and the batch small so the review stays quick.
Example workflow
- Write a prompt for one chore and a list of allowed tools
- Run the agent headless in a scheduled CI job
- Agent edits files and runs tests
- Job opens a single PR with a summary
- Developer reviews and merges or closes
Tools
- Claude Code
- Claude Agent SDK
- GitHub Actions
Risks and guardrails
- Broad tool permissions in CI can do damage; allow only what is needed
- Unattended runs can burn budget; cap turns and spend
- Never let the job push straight to the main branch
Sources
Written by Agents Lookup. Credits and official pages for the tools this use case names:
- Claude Code docs: run Claude Code programmatically: code.claude.com/docs/en/headless
- Claude docs: Agent SDK overview: code.claude.com/docs/en/agent-sdk/overview