An overnight workflow for coding agents

Write tasks the way you would for a new contractor

An overnight task has no one to ask. It has to carry its own context. Each task should fit in a paragraph and answer three questions. What is wrong or missing. What done looks like. How to prove it.

## Task: paginate the /orders endpoint
Problem: GET /orders returns every order. Large accounts time out.
Done: accepts ?cursor and ?limit (max 100), returns next_cursor.
Proof: new tests in tests/orders_pagination.test.ts pass; existing tests pass.
Do not: change the response shape of existing fields.

Keep tasks small. Two to four hours of human work is the sweet spot. Bigger than that, split it. A task the agent finishes in twenty minutes is fine too. Put them in a file in the repository or in issues the agent can read. A file is simplest.

One task, one branch, one worktree

Tasks must not share a working tree. Two tasks editing the same checkout produce a diff nobody can untangle. Git worktrees give each task its own folder on the same repository.

git worktree add ../work/orders-pagination -b agent/orders-pagination
git worktree add ../work/retry-webhooks -b agent/retry-webhooks

Each branch gets its own agent run and its own pull request. In the morning you review them one at a time. If one is bad, you close it and the others are untouched.

Decide what the agent does alone

Set the permission mode and the deny list before the first run, not after. The guide to running Claude Code unattended has the exact settings. The short version for overnight work is this. Edit files freely. Run the test suite freely. Commit and push the task branch freely. Open a pull request. Nothing else without asking, and nothing that reaches outside the repository.

The run loop

A small script starts one headless run per task, in its worktree, with a turn ceiling and a log file. This is the whole thing.

#!/bin/sh
# run-overnight.sh: one agent run per task file in tasks/
for task in tasks/*.md; do
  name=$(basename "$task" .md)
  dir="../work/$name"
  git worktree add "$dir" -b "agent/$name" 2>/dev/null
  (
    cd "$dir" || exit 1
    claude -p "Complete the task in $task. Commit on this branch, push it, and open a pull request with gh pr create. Stop when the tests pass or when you are blocked, and say which." \
      --permission-mode acceptEdits \
      --max-turns 80 \
      > "../logs/$name.log" 2>&1
  )
done

Run it inside tmux so the SSH connection does not matter. Tasks run one after another. Parallel runs are possible but they compete for CPU and for your rate limit, and they make the logs harder to read. Start sequential.

Let the tests be the judge

The prompt tells the agent to stop when the tests pass. Your CI then runs the same tests on the pull request. If the agent claimed green and CI says red, you know before you read a line of the diff. Protect main so nothing merges without that check. This is the single most valuable guardrail in the workflow and it costs nothing.

The morning review, ten minutes

• Open the pull request list. Count them against the task list. Missing ones are in the logs.
• Read the log of anything that stopped as blocked. Usually it is a missing credential or an ambiguous task. Fix the task text, not the agent.
• Review green pull requests smallest first. Merge the ones that are right. Close the ones that are wrong with one line saying why, and copy that line into tomorrow's task file.
• Delete merged worktrees and branches so tonight starts clean.

git worktree remove ../work/orders-pagination
git branch -d agent/orders-pagination

What to hand over first

Some work suits the night better than other work. Start with these and expand as trust builds.

• Failing or flaky tests with a clear expected behavior.
• Dependency upgrades where the test suite is the judge.
• Mechanical refactors across many files.
• Missing tests for code that already works.
• Type errors, lint errors, and deprecation warnings.

Keep design decisions, anything touching billing or auth, and anything the tests cannot verify for daytime, when you can answer questions.

The machine underneath

All of this assumes a machine that is still running at 4 a.m. A laptop that sleeps is the most common reason an overnight run produces nothing. The sleep guide fixes that on a Mac you own, and a hosted agent Mac has it fixed already.