opencode · diff

v1.0.0 to v1.0.0

2 added, 0 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: opencode
description: Deep-dive reference for delegating implementation work to the OpenCode CLI. Provider-agnostic — pick it when the user wants a specific non-Anthropic, non-OpenAI model (local Ollama, Bedrock, Vertex, Azure). Covers binary resolution, one-shot mode, provider selection, and common pitfalls.
version: 1.0.0
author: ethosagent
tags: [delegation, opencode, coding-agent]
required_tools: [terminal, process_start, process_logs, process_stop]
ethos:
+ external_cli_alternatives:
+ - opencode
category: delegation-and-orchestration
default_personalities: [engineer, coordinator]
prerequisites:
external_cli: [opencode]
auth: ["opencode login (per-provider auth)"]
env_vars: []
optional_tools: [memory_write]
integrates_with:
- skill: coding-agent
role: coding-agent routes here when opencode is the chosen CLI
surface_metadata:
invocation_trigger: "coding-agent selected opencode as the delegation target; user says 'use OpenCode for this' or wants a specific non-Anthropic/non-OpenAI model"
estimated_turns: "2-5"
---
# 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:
```bash
which opencode || command -v opencode
```
If the command is not found, check common installation locations:
```bash
# 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:
```bash
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
```bash
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
```bash
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
```bash
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 | Syntax | Auth required |
|---|---|---|
| Ollama (local) | `--model ollama/llama3` | None (local) |
| AWS Bedrock | `--model bedrock/anthropic.claude-v2` | AWS credentials |
| Google Vertex | `--model vertex/gemini-pro` | GCP credentials |
| Azure OpenAI | `--model azure/gpt-4` | Azure credentials |
| OpenRouter | `--model openrouter/anthropic/claude-3.5-sonnet` | OPENROUTER_API_KEY |
| Together | `--model together/meta-llama/Llama-3-70b` | TOGETHER_API_KEY |
### 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:
```bash
# 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:
```bash
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:
```bash
opencode run "<task>" --format json
```
Expected JSON shape (when supported):
```json
{
"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`:
```bash
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:
```bash
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
| Symptom | Cause | Recovery |
|---|---|---|
| "command not found" | Binary not in PATH | Check install locations (see Binary Resolution above) |
| Connection refused (Ollama) | Ollama server not running | Start it: `ollama serve` |
| Auth error (cloud providers) | Credentials expired or missing | Re-authenticate: `opencode login` or set the provider env var |
| Model not found | Model name typo or model not pulled | For Ollama: `ollama pull <model>`. For cloud: verify model ID in provider docs |
| Timeout | Model too slow or network issue | Retry; for Ollama, check that the model fits in available RAM |
| Garbled output | Encoding issue with local model | Try a different model; some local models produce malformed output |
### 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
| Dimension | Claude Code | Codex | OpenCode |
|---|---|---|---|
| Provider | Anthropic only | OpenAI only | Any |
| Structured output | `--output-format json` (rich) | None (plain text) | `--format json` (if supported) |
| Tool scoping | `--allowedTools` | None | None |
| Git requirement | No | Yes | No |
| PTY requirement | No | Yes | No |
| Best for | Deep reasoning, large refactors | Fast iteration, batch ops | Provider flexibility, local models |
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)