opencode

---
name: "opencode"
description: "The opencode worker exposes the OpenCode API as iii functions. One opencode::run call executes one headless OpenCode turn — the same agent the user runs in their terminal, with the same tools — in a chosen working directory, and returns the final result, token usage, and cost. Every JSON event…"
license: "Apache-2.0"
---

# opencode

The opencode worker exposes the OpenCode API as iii functions. One
`opencode::run` call executes one headless OpenCode turn — the same agent the
user runs in their terminal, with the same tools — in a chosen working
directory, and returns the final result, token usage, and cost. Every JSON
event OpenCode emits (`step_start`, `text`, `tool_use`, `step_finish`) mirrors
verbatim onto `opencode::events`; a translated AgentEvent view lands on
`agent::events`, which the iii console and the acp worker render.

Requires the `opencode` CLI on the host and an API key for the LLM provider you
use (e.g. `ANTHROPIC_API_KEY`, or `opencode auth`). When a turn needs a
capability beyond OpenCode itself, add another iii worker to the bus instead of
bolting anything onto this one.

## When to Use

- Delegate a whole coding task ("add an endpoint and run the tests") in one
  call: `opencode::run` with `prompt` and `cwd`.
- Continue a conversation across calls: pass the same `session_id` again and
  the worker resumes the underlying OpenCode session (`--session`).
- Run long jobs without holding the call open: `opencode::start` returns
  `{session_id, started}` immediately; follow `agent::events` (group_id =
  session_id) for the rendered view or `opencode::events` for raw JSON;
  interrupt with `opencode::stop`.
- Act on the whole backend: turns carry the iii runtime context by default, so
  the agent discovers and calls any registered function through the iii CLI
  (engine::functions::list, `iii trigger <fn> --help`); disable per turn with
  `iii_context: false`.
- Pick a model or agent per turn: `model` as `provider/model`, `agent` as an
  OpenCode agent name.

## Boundaries

- Spawns the host `opencode` CLI per turn — needs OpenCode installed and a
  provider key; not available in a bare container without it.
- `opencode::run` / `opencode::start` are not agent-callable without human
  approval (they spawn a full agent with the host's shell + filesystem);
  read-only introspection is allowed (see iii-permissions.yaml).
- One turn per session at a time: check `opencode::status` (`live: true`) before
  another `opencode::run` for the same `session_id`.

## Functions

- `opencode::run` — run one turn, wait; accepts `prompt` (or a `messages`
  array), plus `model`, `cwd`, `agent`, `iii_context`; returns `{session_id,
  opencode_session_id, result, stop_reason, usage, total_cost_usd}`.
- `opencode::start` — same payload, returns `{session_id, started}` immediately.
- `opencode::stop` — interrupt the live run for a session.
- `opencode::status` — point-in-time session view: live flag, status, turns,
  usage, cost.
- `opencode::sessions::list` — every session this worker has run.
- `run::start_and_wait` — alias for `opencode::run` under the entrypoint the
  console and acp worker drive.