OpenCode — Deep-Dive Delegation Reference

Comprehensive reference for spawning and managing the OpenCode CLI (opencode) as a delegated coding agent under ethos process control. OpenCode is provider-agnostic — it connects to any LLM backend (Ollama, AWS Bedrock, Google Vertex, Azure OpenAI, OpenRouter, and more).

When to use

• Provider-agnostic delegation — the user wants a specific model that neither Claude Code nor Codex exposes (local Ollama, a Bedrock-hosted model, an enterprise Azure deployment, a Google Vertex model).
• Cost-controlled environments — where the choice of provider matters for billing, data residency, or compliance reasons.
• Local models — when the user wants to run a local LLM (via Ollama) for privacy or offline work.
• Multi-provider comparison — delegate the same task to multiple providers via OpenCode and compare results.

Do not use when Claude Code or Codex would suffice. Those CLIs have tighter integration with their respective APIs and less surface area for configuration errors. OpenCode's strength is flexibility, not depth — use it when flexibility is what you need.

Binary resolution and PATH caveat

OpenCode may not be in $PATH depending on how it was installed. Always verify before delegating:

which opencode || command -v opencode

If the command is not found, check common installation locations:

# npm global install
ls ~/.local/bin/opencode 2>/dev/null

# npm local install (project-local)
ls ./node_modules/.bin/opencode 2>/dev/null

# Go install
ls ~/go/bin/opencode 2>/dev/null

# Homebrew
ls /opt/homebrew/bin/opencode 2>/dev/null

If none of these resolve, the CLI is not installed. Print the install instructions:

OpenCode is not installed. Install with npm i -g opencode-ai (or see https://opencode.ai for alternative install methods) and authenticate with opencode login.

Version check

After resolving the binary, verify the version:

opencode --version

Some features (like --format json) are version-dependent. Document the minimum version you tested against when adding new invocation patterns.

One-shot invocation — the core pattern

opencode run "<task description>"

run mode executes the task and exits. This is the canonical pattern for delegation from process_start. Do not use interactive mode — it opens a TUI that cannot be driven programmatically.

Minimal delegation

process_start({
  command: 'opencode run "Add error handling to the database connection pool in src/db/pool.ts"',
  name: 'delegated-opencode-db-error-handling',
  cwd: '/path/to/project'
})

With provider and model

process_start({
  command: 'opencode run "Refactor the auth middleware to support JWT rotation" --model ollama/llama3',
  name: 'delegated-opencode-auth-refactor',
  cwd: '/path/to/project'
})

Provider and model selection

OpenCode's key differentiator is provider flexibility. The --model flag uses a provider/model syntax:

Provider examples

Provider selection guidelines

• Local/private: Ollama — no data leaves the machine. Best for sensitive codebases or offline work.
• Enterprise AWS: Bedrock — uses existing AWS IAM roles. Best for teams already on AWS.
• Enterprise GCP: Vertex — uses existing GCP service accounts. Best for teams already on GCP.
• Enterprise Azure: Azure OpenAI — uses existing Azure AD. Best for teams on Azure.
• Cost optimization: OpenRouter or Together — access many models with a single API key, often at lower cost.

Authentication per provider

Each provider has its own auth flow. Run opencode login and follow the interactive setup, or set the provider-specific environment variable before spawning:

# Ollama — no auth needed (local)
# Bedrock — standard AWS credential chain (AWS_PROFILE, AWS_ACCESS_KEY_ID, etc.)
# Vertex — standard GCP credential chain (GOOGLE_APPLICATION_CREDENTIALS, gcloud auth)
# Azure — standard Azure credential chain (AZURE_OPENAI_API_KEY, az login)
# OpenRouter — OPENROUTER_API_KEY

The /exit trap

In interactive mode (the TUI), /exit is the only way to quit cleanly. Ctrl+C may leave the process dangling with orphaned child processes.

This does not apply to run mode — one-shot invocations exit cleanly on their own. But if someone accidentally spawns OpenCode in interactive mode (by omitting run), the only reliable cleanup is:

1. Send /exit via the PTY.
2. If that fails, process_stop (SIGTERM).
3. If that fails, SIGKILL.

Always use run mode for delegation to avoid this entirely.

Smoke test

Before delegating real work, verify the CLI and provider are functional:

opencode run "echo hello"

This should produce a response within a few seconds. If it hangs, errors, or produces no output:

1. Check that the provider is reachable (network, auth).
2. Check that the model exists on the provider.
3. Check opencode --version for a supported version.

Run the smoke test once per session, not per delegation.

Structured output with --format json

When available (version-dependent), use --format json for structured output:

opencode run "<task>" --format json

Expected JSON shape (when supported):

{
  "result": "The response text — what was done.",
  "model": "ollama/llama3",
  "duration_ms": 12400
}

Fallback for plain text

Not all OpenCode versions support --format json. The fallback parsing strategy:

1. Check if --format json is supported: opencode run "test" --format json 2>&1
2. If it errors with "unknown flag", fall back to plain text mode.
3. In plain text mode, capture raw stdout as the result.
4. Use the exit code as the success/failure indicator.

Always attempt JSON first and fall back gracefully. Do not hard-fail on a missing --format flag.

Working directory

Set the project root explicitly with --cwd:

opencode run "<task>" --cwd /absolute/path/to/project

If --cwd is not supported by the installed version, set the working directory via process_start's cwd parameter instead. Both achieve the same result — process_start.cwd is the more reliable option since it works regardless of OpenCode version.

Session continuation

Resume the last session for the current directory:

opencode run "<follow-up task>" --continue

--continue carries over the conversation history from the previous invocation in the same directory. Use it for multi-step delegations where context should accumulate (e.g., "now add tests for what you just changed").

Caveat: session continuation is directory-scoped. If you use worktrees, each worktree has its own session history. This is usually the desired behavior — parallel delegations in different worktrees should not share context.

Error recovery

Common failures

Recovery pattern

1. Capture exit code and stderr from process_logs.
2. Match stderr against known failure patterns.
3. For transient errors (timeout, rate limit): retry up to 2 times with a 30-second backoff.
4. For permanent errors (auth, model not found): surface to the user with specific remediation.
5. For local model issues (Ollama): check RAM, model compatibility, and suggest alternatives.

Delegation checklist

Before spawning an OpenCode delegation, verify:

1. which opencode succeeds — the CLI is installed.
2. Smoke test passes — opencode run "echo hello" produces output.
3. The target provider is reachable and authenticated.
4. The target model exists on the provider.
5. --cwd or process_start.cwd points to the correct project root.
6. A process_start name is chosen (descriptive slug).
7. The user has authorized the delegation.

Comparison with other CLIs

Use this table to choose the right CLI for the task. OpenCode is the fallback when the other two do not support the required provider or model.

Hard rules

• Always use run mode. Interactive TUI mode cannot be driven from process_start.
• Always smoke-test first. Provider misconfigurations fail silently or with opaque errors.
• Always verify the binary is in PATH. OpenCode installs vary — do not assume it is available.
• Never delegate without the process tool. Without process_start, the orchestrator blocks for the full duration and the user cannot kill the delegation.
• Fall back gracefully on --format json. Not all versions support it — parse plain text as a fallback.

Adapted from NousResearch/hermes-agent (MIT)