OpenCode 2: follow a small repair from failing test to changed file

A test is failing in a service you inherited. In a separate chat, every step involves carrying something: a file into the conversation, a suggestion back to the editor, an error back to the conversation. OpenCode puts the discussion beside the files and tools, so you can follow the repair where it will run.

Meet the assistant working beside your files

OpenCode is an open-source coding assistant that works inside a software project. Describe a job in everyday language, and it can inspect files, explain behavior, edit code and run commands such as tests. Bug fixes, features and unfamiliar code become things to investigate in place. OpenCode tools

Choosing and using those tools is what “agent” means here. With the relevant permissions, it can make the edit and run the check, rather than leave you with code to copy.

Begin with a question about the code

A first request might be:

“Find the code that decides which failed requests we retry. Explain the current behavior and identify the tests that cover it. Don’t change anything yet.”

Once that explanation makes sense, narrow the change:

“Fix the retry rule so it handles the cases in these tests. Change only the helper, leave the tests alone, then run them and show me the changed lines.”

A tiny Python project below follows that sequence: original problem, proposed repair and a result you can inspect. It is an example task, not a report of an OpenCode session performed for this article.

Writing code is not the only useful starting point. You could ask it to:

• Explain an unfamiliar project’s authentication flow.
• Find where a configuration value originates.
• Locate a feature’s existing tests before editing it.
• Read a deployment script and identify assumptions to check.

Each question helps you understand the project before deciding how much the assistant should change.

Choose the interface and the model separately

OpenCode 2 has terminal, desktop and web interfaces. A terminal fits an existing command-line workflow; the desktop application offers a graphical entry point. This guide uses the terminal. OpenCode V2 introduction

The model and OpenCode have different jobs. Connect a supported provider and choose a model available to the project. The model interprets the request and proposes a solution; OpenCode supplies the working process and tools. Available models depend on the provider connection and configuration. Model selection

Start with work you can evaluate

Developers can bring feature work or bugs. SREs and platform engineers can bring scripts, tests, configuration or maintenance code. The project can be small. What matters is having a way to judge its result.

Start somewhere you can afford mistakes, and configure approvals before allowing edits or commands. OpenCode’s defaults are permissive. An approved shell command uses your operating-system account’s authority; the conversational interface does not protect a production credential left within reach. V2 permissions

The 2.0 changes make more sense against that small repair: they affect how work is coordinated, tools run and changes become visible while you remain involved.

Version scope: updated October 20, 2026. The first v2.0.0 tag appeared September 11; the official changelog lists 2.0.27 on October 12. This guide covers the 2.x generation and installs 2.1.0, released October 20. 2.0 tag · Changelog

The 2.0 changes behind a repair

While a test runs, a review need not stop. OpenCode 2.0 supports background shell commands and subagents, allowing separate parts of a larger repair to continue while a build finishes.

Code Mode reduces another kind of waiting: moving results between tools. The agent can compose connected tools in JavaScript, take a returned list, select relevant entries and pass them to another call. Instead of asking for every file separately, it can first identify the files that matter. That can help across repositories and work trackers; the small repair here needs none of those integrations. Official 2.0 release article

The visible interface is not the whole running application. Version 2.x automatically starts a shared background service, and local clients connect to it. That service manages sessions, configuration, permissions and tool execution. Restarting the terminal interface can therefore leave the same background problem untouched. Separate diagnostic commands inspect the service. CLI architecture

Existing users need to review the migration, too. V2 changes plugin and server/client contracts and moves terminal settings into one global cli.json file. Supported project configuration can still be read without rewriting everything. Old plugins require actual porting; a new entry name will not make old code compatible. V1 migration guide

Release notes also describe changes to reviewing work. Version 2.0.30 introduced docked terminal diffs and optional per-turn changed-file views in the desktop app. On October 20, 2.1.0 added persistent Windows terminals and fixed a five-minute connection deadline for long-running terminal requests. It changes public SDK, HTTP and plugin fields as well, so integration authors need its migration details before updating. These are reported release changes, not independent performance measurements. Release notes

An older tutorial can explain an apparently inexplicable command. Check its address: /docs/ belongs to the older line, while this generation uses /v2/docs/.

Prepare the machine and the provider connection

This walkthrough uses the macOS or Linux terminal version. Prepare:

• A current Node.js installation with npm, used here to install the native OpenCode binary.
• Git and Python 3 for the small, dependency-free exercise below.
• A model connection you are allowed to use with the files you will supply. Use a synthetic project first if your employer has not approved sharing source code with that provider.
• A clean working folder without production credentials or private customer data.

Windows users can choose the standalone CLI from the V2 download page. The exercise is otherwise portable; use python instead of python3 if that names Python 3 on your machine. The desktop app is an alternative if a full-screen terminal is not your preferred starting point.

For an existing V1 setup, close its clients, stop its running service and back up configuration and data before switching. V1 and V2 share the opencode command. Remove a package-managed V1 installation through its original package manager before installing V2, and check essential integrations and plugins first. Migration guidance

Choose one installation method

Install the version used by this guide:

npm install -g @opencode/cli@2.1.0
opencode --version

The version response should be 2.1.0. The V2 package is @opencode/cli; opencode-ai belongs to the older line. There is also an official V2 installer. Choose one method instead of accumulating competing binaries. V2 installation

The software download and model usage are separate costs. Direct provider connections are available; OpenCode Console is optional pay-as-you-go access, and OpenCode Go is a separate subscription. Free-model availability and data-use conditions vary. A free application does not make every request free, nor does a chat subscription automatically grant API access. Check your account’s connection method and current terms. Before adding billing details for paid Console access, review automatic credit recharge and its available controls. The current documentation explains its trigger and amount settings; it does not show a disable control. Confirm how to stop automatic charges in your account before enabling them. Model access and pricing

Put a small repair inside explicit limits

Create an empty opencode-retry-demo folder, open a terminal inside it and initialize Git:

git init

Before launching OpenCode, put this configuration in opencode.jsonc in that folder:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "ask" },
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ]
}

These rules ask before shell execution, edits and outside-project access. V2 defaults are more permissive, including outside-directory access. Later matching rules win, and existing global or agent-specific settings can affect the result. Leave auto-accept off and inspect each proposed action. Permissions

An approval gives you a chance to inspect a command, not a smaller operating-system account. Once approved, it can reach files, services or state outside Git. Use a disposable environment without valuable credentials for unfamiliar code. The Plan agent does not make shell execution read-only.

Approval and execution limits are separate: one decides whether a tool call proceeds; the other limits what the running process can reach. This is a conceptual illustration, not a screenshot.

Make the retry mistake visible

Save this deliberately flawed teaching helper as retry_policy.py:

def should_retry(status_code):
    return status_code != 200

Every status except 200 triggers another attempt. That includes 201, a successful creation, and 401, where repeating the same unauthorized request will not repair the credentials. One request already worked; the other needs different credentials. Both acquire unnecessary traffic.

The exercise requires retries for 429 and 5xx responses only, not the other cases below. Save these checks as test_retry_policy.py:

import unittest
from retry_policy import should_retry

class RetryPolicyTests(unittest.TestCase):
    def test_status_policy(self):
        cases = [
            (200, False), (201, False), (400, False),
            (401, False), (429, True), (499, False),
            (500, True), (503, True), (599, True), (600, False),
        ]
        for status, expected in cases:
            with self.subTest(status=status):
                self.assertEqual(should_retry(status), expected)

if __name__ == "__main__":
    unittest.main()

Run the unchanged starting version before requesting a repair:

python3 -m unittest -v

Five cases should fail: 201, 400, 401, 499 and 600. The tests turn “fix retries” into a concrete description of the behavior this limited exercise requires.

This classifies statuses; it is not a complete production retry policy. Real retries depend on whether repetition is safe, waiting time, server guidance and total attempt or time limits. Passing a 503 test does not establish that repeating a payment is safe. HTTP retry semantics

Explain the failure before changing the helper

Launch the agent:

opencode

Use /connect inside the interface and choose an authentication method offered by your provider. Enter API keys only in the provider credential prompt, never in conversation or committed files. Use /models to choose an available model. Supported authentication choices come from the connected provider. Provider setup

Ask for an explanation before an edit:

Read retry_policy.py and test_retry_policy.py. Explain which cases fail and why. Do not edit files yet. If you want to run a command, show me the command first.

The answer should link the failing assertions to the overly broad condition. If the agent asks to install a package, ask why: this two-file example uses only the standard library.

The important detail is easy to picture: creation succeeded with 201, yet the helper asks to try again. Once the agent explains that mismatch, the edit has a purpose. A plausible Python expression without that connection could solve a different problem.

Once the explanation is sound, give the bounded change:

Change only retry_policy.py so that 429 and statuses from 500 through 599 return True. All other integer status codes should return False. Keep the tests unchanged. Run python3 -m unittest -v and report the result and the changed lines.

Inspect the proposed code and commands. Checking for 429 or the inclusive 500–599 range implements the stated rule directly. Keep expected test results unchanged; editing them could merely make the tests agree with the bug.

Review /diff, but also open the files and run git status --short. These files begin untracked, so an empty ordinary git diff does not prove nothing changed. Run the tests yourself afterward. The summary helps orient you; the files and test output establish the result.

/undo and /redo cover recent conversation and eligible file changes. Snapshot capture is best effort, and restoring files requires a Git worktree. They do not reverse database writes, processes or other external effects. Important work still needs ordinary commits and backups. Snapshot behavior

Find the part that is refusing to cooperate

A wrong version may mean the shell found another installation. On macOS or Linux, command -v opencode shows its executable path. Remove an obsolete installation with its original package manager, not by deleting arbitrary files.

If the interface cannot connect, inspect the background service before reinstalling:

opencode service status
opencode api get /api/info

For an unhealthy service, the documented next step is opencode service restart. It affects the shared service, so finish or stop other active work first. Logs normally reside at ~/.local/share/opencode/log/opencode.log. Remove secrets and private project content before sharing diagnostics. Troubleshooting

Authentication and a failing project test belong to different parts of the system. In /connect, check the account, chosen method and provider entitlement. The background server makes the request. A variable added to a new terminal need not reach an already-running server, which is why reopening the interface may leave the problem unchanged.

Missing editor diagnostics after an upgrade may be a documented difference. V2 currently accepts LSP configuration but does not run those language servers or produce their diagnostics. Use the project’s real lint, compiler or type-check command. Old session-sharing instructions also no longer apply: the sharing backend and /share were removed. Migration details · Release notes

Keep the repair understandable as the work grows

The repaired helper is small enough to understand from beginning to end. A successful creation no longer provokes another attempt, and an unchanged test catches that difference. Increase the task’s size when you can still follow the path from failure through edit to result.

Model choice and working interfaces can make that loop convenient. The result worth keeping is a patch another person can understand and accept. The Pi guide explores a different approach to adaptable coding tools. Before connecting an agent to live operational tools, the production-agent guide explains the separate authorization and verification work those changes require.

Verification scope: the October 20, 2026 review records checks of official release notes and V2 documentation, plus local runs of the Python fixture’s failing baseline and reference correction. The raw output from those original runs is not retained in this revision’s evidence. On November 2, 2026, a fresh local check of the same ten-case fixture observed the five expected baseline failures and a passing reference correction. Installation, an interactive OpenCode session and provider authentication were documentation-checked, not exercised as a hands-on product test. No product benchmark or production result is claimed.