afk.sh

About the Project

Working with a coding agent quickly hits the same wall: you have to sit in front of it. afk.sh is the missing loop around it. You hand it a list of issues, it opens one session per issue, lets it work, verifies the result, pushes the branch and labels the issue. Between launching it and reading the results, you sleep.

Hence the name: away from keyboard.

No model inside the orchestrator. It does not think, it orders, launches, verifies, pushes and labels. All the reasoning stays in the sessions it drives, which keeps it readable and predictable.

The principle

one issue  =  one fresh session  =  one worktree  =  one verified PR

Every issue starts from a blank context, in its own git worktree, so one session cannot pollute the next and everything can run in parallel.

What it does

• Scheduling: reads the dependencies between issues ("blocked by") and derives the executable waves; -n prints the plan without running anything
• Parallelism: several simultaneous sessions wherever the graph allows it
• Verification gate: an issue is only "done" if the repository's verification command passes, declared in an .afk.env versioned next to the code
• Retry: a failed issue is replayed once, in a fresh session rather than trying to rescue the previous one
• CI wait after the PR is opened, then labelling based on the outcome
• Integration pass at the end of a run: green branches are combined and verified together

The false-green trap

The most useful lesson of the project did not come from the code but from a real run. A build cache can hollow out a verification gate: if the cache key only accounts for git-tracked files, a worktree that never produced a generated file has the same fingerprint as one that did. The cache answers, logs are replayed, nothing actually runs, and the gate reports success without compiling a single line.

Eight issues went green on a defect that only the integration pass caught: it presented a combination of contents never seen before, therefore a real computation. Hence the split between the per-issue gate and the integration gate, and a simple rule: the number of cached entries is a safety line, not a performance statistic.

Tested without spending a single call

The script ships with two harnesses: one tests the parsers (issues, labels, dependencies), the other the full orchestrator with the agent and the GitHub API stubbed out. Behaviour can be checked in a few seconds, offline, without spending a token.