Run opencode run non-interactively for a second opinion, review, or a
delegated edit worker. Model default: -m zai-coding-plan/glm-5.2 (verify the
slug with opencode models | grep glm; don't hard-code temperature).
Happy path
- Isolate and install agents. Copy the bundled agents (they are
mode: all, required for direct--agentlaunches) into.opencode/agents/of the checkout the run will use — opencode resolves--agentagainst--dir, so the agent must live there. Read-only review runs in the current checkout:
slug="opencode-$(date +%Y%m%d-%H%M%S)"
skill_dir="<directory containing this SKILL.md>"
run_dir="/tmp/opencode-$slug"
mkdir -p "$run_dir" .opencode/agents
cp "$skill_dir/assets/reviewer.md" .opencode/agents/
Edit work gets its own worktree instead (opencode never creates one):
slug="opencode-$(date +%Y%m%d-%H%M%S)"
skill_dir="<directory containing this SKILL.md>"
worktree="../$(basename "$PWD")-$slug"
git worktree add -b "agent/opencode/$slug" "$worktree" HEAD
run_dir="$worktree/.agent-runs/$slug"
mkdir -p "$run_dir" "$worktree/.opencode/agents"
cp "$skill_dir/assets/editor.md" "$worktree/.opencode/agents/"
-
Write the brief to
$run_dir/prompt.md: context, exact task, constraints, acceptance criteria, verification commands, required final output. It reaches opencode inline as the positional message —"$(cat prompt.md)".--filecannot carry the prompt (see Gotchas). -
Launch. Three wrappers are mandatory:
< /dev/null(stdin wedge),timeout(no stream timeout), and the output-cap env var (32k clamp):OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX=131072 \ timeout --signal=TERM 2700 opencode run \ --dir "$worktree" \ --agent editor \ -m zai-coding-plan/glm-5.2 \ --format json \ --title "$slug" \ --auto \ "$(cat "$run_dir/prompt.md")" \ < /dev/null \ > "$run_dir/events.jsonl"Reviewer: same command with
--agent reviewerand--dir "$PWD". Stagger concurrent runs past two per machine (see Gotchas). -
Harvest. Parse the final text event and
sessionIDfromevents.jsonl. Exit 0 does not mean an answer — always check the finish reason:jq -r 'select(.type=="step_finish") | .part.reason' "$run_dir/events.jsonl" \ | grep -qx length && echo "TRUNCATED - raise OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX or shorten the brief"stopis healthy. Hung-run check:events.jsonlstill 0 bytes after ~5 min, or mtime stale >10 min → kill and relaunch. Resume withopencode run --continue "..." < /dev/nulloropencode run --session <id> "..." < /dev/null; add--forkto branch without mutating the original.
Gotchas
- Missing
< /dev/nullwedges the run atinit— under a harness, stdin is a pipe that never closes and opencode parks on it before creating a session. Symptom: 0-byteevents.jsonlfrom the start, log ends atinitwith nocreated id=ses_.... Check this before anything else. - Silent provider stalls hang forever (no stream timeout; only explicit
provider errors retry). The
timeoutwrapper is what turns a zombie into a clean failure. - A third concurrent instance has hung at startup (zero log entries,
blocked on the shared SQLite/WAL db under
~/.local/share/opencode/) — observed once on 1.17.13, so treat "stagger past two" as a conservative heuristic, not a documented limit. - Output is clamped to 32k tokens including reasoning — a thinking-heavy
brief can burn it all and emit nothing, with exit 0 and
reason: "length". SetOPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAXto the model's reallimit.output(models.dev/api.json); it can only raise toward the ceiling. On models withoutlimit.input(glm-5.2 included) it shrinks usable context one-for-one — match the value to the model, don't set one number globally. --filenever carries the prompt — it only attaches files, a positional message is still required, and the flag greedily swallows positionals that follow it (--file prompt.md "do X"dies withFile not found: do X). Put the message BEFORE the flag, or inline with"$(cat prompt.md)".mode: subagentagents can't be launched with--agent— opencode silently falls back to the default agent, dropping your permission setup. Usemode: allorprimary; verify withopencode agent list.--autoauto-approves but explicitdenyrules still hold —edit: denystays safe for reviewers.- A dead mid-run worker loses the conversation, not the code — its edits
are on disk in the worktree. Recover with a continue-brief to a fresh run:
read the original prompt +
git diff, judge the partial work critically, finish, verify. - The shared log is
~/.local/share/opencode/log/opencode.log(UTC); greprun=/agent=to tell "never initialized" from "stalled mid-stream". - Worktrees omit ignored files; copy only explicit prerequisites. If the worker
needs uncommitted local changes, apply an explicit patch in the worktree —
never checkpoint unrelated user WIP with
git add -A.
Not possible
- No native worktree creation — manage git worktrees yourself.
- No stream/idle timeout — external
timeoutis the only guard. - No
opencode.jsonkey for the output cap — env var only. - No
--format jsononopencode agent list(text output). - No prompt via
--filealone — a positional message is always required. --dirwith--attachis a path on the remote server, not local.
Inline config alternative
Instead of the markdown assets, declare the agents in opencode.json
("$schema": "https://opencode.ai/config.json"): mirror each asset's
frontmatter — description, mode, model, permission — as
agent.reviewer / agent.editor objects under the top-level agent key.
Evidence, exact failure modes, and the output-cap analysis: reference/gotchas.md.