opencode#

Unreleased: after 0.11.0. This page is on Hekma's main branch and ships in the next release; Hekma 0.11.0 does not have it.

opencode (anomalyco) ships a native ACP server since v2 (its acp subcommand), so it runs under Hekma's built-in acp kind with no adapter work of its own. No login is needed for the default free models; a paid model requires opencode auth login first — a logged-out agent refuses at the handshake with a JSON-RPC error code the engine surfaces.

Register#

hekma agent config set my-opencode acp.command "opencode"
hekma agent config set my-opencode acp.args "acp"
hekma agent register my-opencode --kind acp
hekma agent start my-opencode

Honesty table#

The pause and interaction levels are the acp kind's own capability declaration — identical for every ACP agent and proven by the conformance kit against a scripted stand-in; they are not per-agent promises. The metering rows are what the pinned real-agent run demonstrated.

Surface	Value	Evidence class
`pause`	`guaranteed` (Linux), `guaranteed` (macOS), `best-effort` (Windows)	`contract-validated`
`interaction`	`guaranteed` (all OSes)	`contract-validated`
Metering source	`self-reported`	`contract-validated`
Billing-grade tokens	`—` — no billing-grade usage in the ledger — tiers attempted: observed: not-configured; sentinel: no-lines-seen; context usage reported (ACP usage_update is context-grain, never billed). opencode reports per-turn token counts inside its `session/prompt` RESULT as well as a context-grain `usage_update` — both outside the v1 billing tiers, so they surface honestly and bill nothing	`run-verified`
Context usage	the agent's `usage_update` surfaces under `acp_context_usage` — context-grain, never billed	`run-verified`

Validation status. Upstream: stable. Evidence: run-verified — registered, started (handshake against its rich initialize/session/new shapes), one full prompt turn completed with the reply retained, context-grain metering surfaced, stopped clean. Its dialect extras (authMethods, configOptions, available_commands_update) are pinned against the contract twin, so tolerance does not depend on having the binary. Validated against v2.0.28 (2026-10-16); the pin is also recorded in Supported agents.

Isolation#

Under the acp kind, opencode's data and config roots follow its XDG levers. Set XDG_DATA_HOME and XDG_CONFIG_HOME in the instance's env config for per-instance isolation — isolated roots inside each Agent Home are the recommended posture in the adapter contract. Recipes are in Run an ACP agent.

PATH requirement#

The launch command is the bare word opencode, resolved through the PATH of the environment hekma runs in. Hekma does not bundle, install or pin the opencode binary — install it yourself, keep it on the PATH, or give an absolute path. A start whose opencode cannot resolve fails with the engine's launch-failure diagnostic naming the executable.

Re-validation duty#

opencode ships several releases a week; the pin above is a snapshot by design. Re-validate against the version you install before relying on agent-specific behaviour, and move the pin forward with fresh evidence — Re-validation states the full duty, including the contract duties that no automated kit can prove.