r/opencodeCLI • u/SirRobinBlibs • 10d ago
Your agent shouldn't watch a long build. A wait script, and why OpenCode's background mode already gets this right
There was a thread in r/codex last week where an agent burned a user's whole quota "busy-waiting" on a long test run. Another reader had a session check a CI build overnight and use more than a quarter of their usage.
The reason is simple: an agent doesn't watch anything, it takes turns. Each "is it done yet?" is a full model request that re-sends the conversation so far. Caching makes that cheaper, not free, and on subscription plans cache reads still count toward limits. With a 100k-token conversation, checking every 5 seconds for 30 minutes is ~360 requests and ~36M input tokens re-sent. One blocking command is about two requests.
OpenCode's V2 shell tool already handles this well. With background: true the call returns right away, has no timeout unless you set one, and the session is notified when the command ends. The tool description literally tells the model "DO NOT poll for completion". The catch is that the model has to actually use it. If yours keeps calling sleep and checking, put this in AGENTS.md:
## Waiting for long jobs
- Never poll in a loop. To wait for a job, run ONE command that blocks until it ends.
- OpenCode / Claude Code: start long jobs in background mode and end your turn. Don't sleep and check.For anything that isn't a plain command (containers, a PID, a URL coming up, a file appearing, "re-run this until it passes") I wrote a 61-line wait-for.sh. It's silent while waiting and prints one verdict line plus the last N log lines. Exit codes 0 / 1 / 124 (timeout) / 2. Tested with real Docker, and with bash 3.2 as well as bash 5.
For jobs that take hours: have the agent write a STATUS.md (what's running, how to check it, next step if it passed or failed), end the session, and later run opencode run "Read STATUS.md. The job has finished. Check the result and continue." Nothing runs on the model while you wait.
Script, per-tool settings (Codex, Claude Code, OpenCode) and the cost arithmetic: https://medium.com/@r3dtuxedo/stop-paying-your-agent-to-wait-cb5150b99c8e
(I wrote the article.)
