Headless agents in scripts and CI

Most coding agents have a non-interactive mode: you pass a prompt, it works, it exits with a result. No chat, no one watching.

That turns an agent into a building block. You can call it from a script, a scheduled job or a CI pipeline, for the chores nobody wants to do by hand.

What changes when nobody is watching

In a chat, you catch a bad direction after two messages. Headless, the agent runs to the end on its own. Everything you used to fix live has to be decided up front: the brief, the allowed actions, the checks and the output format.

1. ⏰TriggerSchedule, label on an issue, failed build
2. ↓→
3. 📄Fixed briefVersioned prompt file plus inputs
4. ↓→
5. 🤖Agent runIsolated runner, limited permissions
6. ↓→
7. ✅ChecksThe same checks as a human PR
8. ↓→
9. 👀Draft PRA human reviews and merges

Good first jobs

Start with work that is repetitive, well specified and easy to verify. The best candidates already have a clear pass or fail.

• Dependency bumps that also fix what the bump broke, until the tests pass.
• Failing lint or type errors after a rule gets stricter, in batches.
• Triage notes on a new issue: likely files, a reproduction attempt, a suggested plan.
• Doc drift: compare the API docs to the code and propose fixes.

Save “implement this feature from the ticket” for later. That job needs the human steering you learned in Module 3.

The brief is now a file

A headless prompt should live in the repo, reviewed like code. It needs even more structure than an interactive brief, because the agent can’t ask you anything.

Task: Upgrade the dependency named in DEP_NAME to the version in DEP_VERSION.

Do:
- Update the manifest and lockfile.
- Run the check command. Fix breakages caused by the upgrade only.
- Keep changes minimal. No refactors, no unrelated cleanups.

Stop and report instead of guessing if:
- A fix requires changing a public API.
- More than 10 files need edits.
- A test fails for a reason unrelated to the upgrade.

Output: a pull request description with what changed, what broke,
how you fixed it, and anything a reviewer should double-check.

Make it observable

A headless run that fails silently is worse than no automation. Keep the agent’s full transcript as a build artifact, cap its time and cost per run, and post a short summary where your team already looks.

Check yourself

🧠 Headless agents

Score: 0 / 4

1. 1. Which task is the best first headless job?

   Implement a new onboarding flow from a ticketFix type errors after enabling a stricter compiler settingRedesign the database schemaDecide which features to build next

   Repetitive, well specified and with a clear pass/fail from the type checker. The others need human judgment along the way.

2. 2. Why do headless briefs need explicit stop conditions?

   To save tokensBecause the agent can't ask you a question mid-run, so it needs to know when to stop and report instead of guessingBecause CI systems require themThey don't, a good model figures it out

   Without a way out, an agent in doubt keeps going and makes a choice you'd have vetoed.

3. 3. Where should a headless job's output go?

   Straight to main if all checks passA draft pull request that runs the normal CI and waits for a humanA comment in the chat tool, no codeNowhere, just the logs

   A draft PR reuses your whole review and CI process. The agent proposes, a human merges.

4. 4. A nightly agent job has been 'green' for weeks but nothing ever changes. What's missing?

   A bigger modelObservability: kept transcripts and a summary of what it actually didMore parallel runsA longer prompt

   Green can mean 'did nothing' or 'silently gave up'. Keep the transcript and report outcomes, not just exit codes.

↺ Try again

Before you move on

✅ Key takeaways

0 / 4 completed

• Headless briefs live in the repo and include explicit stop conditions.
• My first headless jobs are repetitive chores with a clear pass or fail.
• Headless jobs open draft pull requests. A human always merges.
• Every run keeps its transcript and has a cap on time and cost.

↺ Reset