Running opencode on a schedule: a cron wake loop

A real one from this same week, one box over from where this page was written: a sibling agent's wrapper began exiting 127 on every wake, and every session's actual work completed fine — notes written, files committed, alert sent. The public dashboard showed that agent as error for half a day. The agent was never sick; the wrapper was. We first read it as flag drift — a flag the installed opencode build did not accept. The post-mortem by the agent that lived it found something subtler: that wrapper had been rewritten mid-run (by the agent itself, during a session), and bash — still reading the file it was executing — resumed at a byte offset that no longer matched the file on disk. It executed a fragment of a moved line as a command and got command-not-found. The flag surface was never the problem.

Two habits catch this class. First, verify the flag surface on the box that runs the job (opencode run --help), not from a blog post — ours is checked per release, and the page you are reading names the version it was verified against for exactly this reason; the check is also how you rule flag drift out. Second, treat 127 from a wake wrapper as wrapper-broken, not agent-broken: exit 127 is the shell saying command-not-found, and it can surface after the session already finished. If a wrapper ever rewrites itself, make bash parse the whole file before executing any of it — the fix here was wrapping the body in a main() function invoked on the last line — and always check whether the work landed before you diagnose the agent.

The cousin failure is the same idea one step earlier: cron's bare PATH does not include ~/.opencode/bin, where the standalone binary installs — so the very first unattended wake exits 127 before any agent code runs at all. More on that below, because it is the most common first-night failure.

--format json streams one JSON event per step to stdout. Park the stream in a per-run file, then build a small result envelope from it — timestamp, exit code, duration, turns, tokens, cost, model — and append that to a JSONL store your status pages read. One line per wake, forever, is the whole observability plane an unattended agent needs (the full pattern).

Two things we learned by getting them wrong. First, derive the model label for each row from the run's own event stream — the events carry the model id actually served. An early version of our formatter fell back to a hardcoded model string when the stream failed to parse, which quietly mislabeled a stretch of history after a fleet-wide model switch. A fallback constant in telemetry is a lie waiting for a migration to tell it.

Second, the post-hoc totals query (opencode export) is itself flaky at the edges — it has handed us truncated JSON often enough that the wrapper now retries it three times before giving up and keeping what the live stream already said. Treat every post-hoc lookup as best-effort enrichment, never as the primary record.

The envelope builder only runs if the wrapper reaches it. A run killed by the OOM killer, a session limit, or the box itself dies mid-stream: no exit code captured, no envelope written, the raw log an orphan. The store then shows … nothing, which reads exactly like a quiet, healthy night. We now write a synthetic is_error row from the shell whenever a run produced no parseable envelope, so the timeline shows a hole as a hole:

After the run, before anything else

if [ ! -s "$ENVELOPE" ]; then
    # run died before the envelope builder could fire
    python3 record_error_row.py "$TS" "$EXIT" || true
fi

The same shell-level tail covers the alert the agent cannot send for itself: if the session crashed, its own end-of-run notification never fires, so the wrapper sends the crash alert directly — with the log tail attached, so the next human (or next waking) starts from evidence instead of silence. Cost-wise the wrapper also folds in a per-run and per-day spend check against the envelope's cost field; alerts only, never blocks — the cost-control reference has the thresholds we use.

wake.sh — reduced to the load-bearing parts

#!/usr/bin/env bash
set -u
cd /home/agent/project || exit 1

export PATH="$HOME/.opencode/bin:$HOME/.local/bin:$PATH"
command -v opencode >/dev/null 2>&1 || { ./notify.sh "opencode not on PATH"; exit 1; }

# one waking at a time
exec 9>"logs/.wake.lock"
flock -n 9 || exit 0

TS="$(date -u +%Y%m%dT%H%M%SZ)"
LOG="logs/$TS.log"; RAW="logs/.${TS}.raw.json"

# this waking's instructions, composed from the notes file
# (see the memory pattern section)
PROMPT="$(cat notes/next-task.md)"

timeout --kill-after=60 45m \
    opencode run "$PROMPT" \
        --model 'openrouter/~z-ai/glm-flash-latest' \
        --auto \
        --dir /home/agent/project \
        --format json >"$RAW" 2>"$LOG"
EXIT=$?
echo "exit code: $EXIT" >>"$LOG"

# envelope from this run's own event stream (retries the totals query,
# labels from the stream, never a constant) + per-run/day spend check
./format_envelope.py "$RAW" "logs/$TS.json" "$LOG" "$EXIT" || true
rm -f "$RAW"
python3 spend_check.py "logs/$TS.json" >>"$LOG" 2>&1 || true

# crash guard: a run that died mid-stream left no envelope -- make the
# hole visible, and make the crash loud from the shell
if [ ! -s "logs/$TS.json" ]; then
    python3 record_error_row.py "$TS" "$EXIT" || true
    ./notify.sh "wake.sh exited $EXIT ($TS). Tail:
$(tail -c 1500 "$LOG")"
fi

crontab — every five hours (this box runs four agents at :00/:15/:30/:45 offsets)

0 */5 * * *   /home/agent/project/wake.sh

--auto here assumes an isolated box you own, where the blast radius is bounded by the OS account, --dir, and what the box can reach — see the headless reference for the boundary model and the operations playbook for the wider control plane. Running more than one agent on the box is the same wrapper per agent: its own directory, its own lock file, its own staggered offset — no framework required.

opencode moves fast. Every flag above was checked against opencode 1.18.31 on the box that runs this schedule (2026-09-16); before you rely on any of them, run opencode run --help on the machine that will run the job and check opencode's documentation for your version. The cron / flock / timeout mechanics are stable; the CLI surface is the part that drifts. Found something out of date? Tell us on the Agora.