Coding Backend Opencode

You are preparing a coding agent run for OpenCode, a provider-agnostic, open-source AI coding agent with a TUI and CLI. Use it as an autonomous coding worker orchestrated via terminal/process tools.

When to Use

• The user explicitly asks to use OpenCode.
• You want an external coding agent to implement, refactor, or review code.
• You need long-running coding sessions with progress checks.
• You want parallel task execution in isolated workdirs/worktrees.

Prerequisites

• OpenCode installed: npm i -g opencode-ai@latest or brew install anomalyco/tap/opencode.
• Auth configured: opencode auth login or provider env vars (e.g. OPENROUTER_API_KEY).
• Verify readiness: opencode auth list should show at least one provider.
• A git repository for code tasks (recommended).
• pty=true for interactive TUI sessions.

Binary Resolution

Shell environments may resolve different OpenCode binaries. If behavior differs between your terminal and the agent, check:

which -a opencode
opencode --version

If needed, pin an explicit binary path, e.g. $HOME/.opencode/bin/opencode run '...'.

One-Shot Tasks

Prefer opencode run for bounded, non-interactive tasks (no pty needed):

opencode run 'Add retry logic to API calls and update tests'

Attach context files with -f:

opencode run 'Review this config for security issues' -f config.yaml -f .env.example

Show model thinking with --thinking, or force a specific model with --model provider/model.

Interactive Sessions (Background)

For iterative work requiring multiple exchanges, start the TUI in the background:

opencode   # with background=true, pty=true — returns a session id

Then send prompts and monitor progress via process actions (submit, poll, log). Send follow-up input with submit, and exit cleanly with Ctrl+C (\x03) or kill the process.

Important: Do NOT use /exit — it is not a valid OpenCode command and opens an agent selector dialog instead. Use Ctrl+C or kill to exit.

TUI Keybindings

| Key | Action | |-----|--------| | Enter | Submit message (press twice if needed) | | Tab | Switch between agents (build/plan) | | Ctrl+P | Open command palette | | Ctrl+X L | Switch session | | Ctrl+X M | Switch model | | Ctrl+X N | New session | | Ctrl+X E | Open editor | | Ctrl+C | Exit OpenCode |

Resuming Sessions

After exiting, OpenCode prints a session ID. Resume with opencode -c (continue last) or opencode -s ses_abc123 (specific session).

Common Flags

| Flag | Use | |------|-----| | run 'prompt' | One-shot execution and exit | | --continue / -c | Continue the last OpenCode session | | --session / -s | Continue a specific session | | --agent | Choose OpenCode agent (build or plan) | | --model provider/model | Force specific model | | --format json | Machine-readable output/events | | --file / -f | Attach file(s) to the message | | --thinking | Show model thinking blocks | | --variant | Reasoning effort (high, max, minimal) | | --title | Name the session |

Procedure

1. Verify tool readiness: opencode --version and opencode auth list.
2. For bounded tasks, use opencode run '...' (no pty needed).
3. For iterative tasks, start opencode with background=true, pty=true.
4. Monitor long tasks with poll / log.
5. If OpenCode asks for input, respond via submit.
6. Exit with Ctrl+C (\x03) or kill — never /exit.
7. Summarize file changes, test results, and next steps back to the user.

PR Review Workflow

OpenCode has a built-in PR command:

opencode pr 42

Or review in a temporary clone for isolation: clone the repo, then opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' with the changed files attached via -f.

Parallel Work Pattern

Use separate workdirs/worktrees to avoid collisions — one OpenCode session per workdir, run in the background.

Session & Cost Management

List past sessions with opencode session list. Check token usage and opencode stats (optionally --days 7 --models anthropic/claude-sonnet-4).

Pitfalls

• Interactive opencode (TUI) sessions require pty=true. opencode run does NOT need pty.
• /exit is NOT a valid command — it opens an agent selector. Use Ctrl+C to exit the TUI.
• PATH mismatch can select the wrong OpenCode binary/model config.
• If OpenCode appears stuck, inspect logs before killing.
• Avoid sharing one working directory across parallel OpenCode sessions.
• Enter may need to be pressed twice to submit in the TUI.

Verification

Smoke test:

opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'

Success criteria: output includes OPENCODE_SMOKE_OK, command exits without provider/model errors, and for code tasks the expected files change and tests pass.

Rules

1. Prefer opencode run for one-shot automation — simpler, no pty.
2. Use interactive background mode only when iteration is needed.
3. Always scope OpenCode sessions to a single repo/workdir.
4. For long tasks, provide progress updates from process logs.
5. Report concrete outcomes (files changed, tests, remaining risks).
6. Exit interactive sessions with Ctrl+C or kill, never /exit.

Prompt Preparation Checklist

When preparing the coding agent instruction for OpenCode:

• State the desired code outcome clearly and concretely.
• Tell OpenCode to inspect the repository context before editing files.
• Include any file, behavior, or test hints that reduce ambiguity.
• Prefer precise change requests over broad open-ended prompts.
• Ask for a compact final report: changes made, validation run, remaining concerns.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ahmadrosid
• Source: ahmadrosid/nakama
• License: MIT
• Homepage: https://ahmadrosid.github.io/nakama

Install and usage instructions live in the source repository linked above.