How to Use OpenCode

Start with one bug you understand and a model account you already have. You can decide whether another coding subscription earns its place after you have reviewed a real patch and its cost.

What OpenCode Does

OpenCode reads a project, edits files and runs commands through a terminal interface. The terminal is the workbench; the model is the engine you connect to it. Changing the engine changes its reasoning, speed and price. Your repository remains the job being worked on. OpenCode overview, Ollama integration

A provider is the service supplying the model. An API key is a credential that lets a program use that service and charge its billing account. A local model runs through an inference server on your own machine. These are separate decisions from choosing the agent interface.

Provider compatibility also needs a practical test. Tool calling means requesting an action such as reading a file or running a command. OpenCode points out that relatively few models handle both tool calling and code generation well. Choose the model on a small task before trusting it with a broad refactor. Model guidance

Install OpenCode and Open Your Project

Install from the official documentation, then launch it inside the repository you want it to work on. For a developer with Node.js and npm installed, the documented package route is:

npm install -g opencode-ai
cd /path/to/project
opencode

Replace the project path with yours. OpenCode's docs also offer curl -fsSL https://opencode.ai/install | bash, and the recommended Homebrew tap is brew install anomalyco/tap/opencode. Choose one installation method. On Windows, the docs recommend WSL, the Windows environment for running Linux tools, and also list npm, Chocolatey and Scoop options. Official installation and first run

OpenCode opens a TUI, a text user interface inside your terminal. Commands beginning with /, including /connect, belong inside that interface. Commands beginning with opencode, such as opencode stats, run in your shell.

Use a Git repository and start on a fresh branch. Git records your changes so you can inspect the diff, the exact lines added and removed, before committing anything.

Connect the Model Access You Already Pay For

Run /connect, select the provider, complete its documented authentication route, then run /models and pick a model. Popular providers are already configured; custom endpoints and local servers can need additional configuration. Model selection

These are routes described on OpenCode's public provider page, rather than claims about what a particular paid account will expose. Provider connection instructions

A chat subscription is not automatically an API allowance. Anthropic says Claude Pro excludes Claude Console API usage. OpenCode's Anthropic section also warns against Claude Pro/Max authentication plugins. Use an Anthropic API key for that route, or use Claude Code with the subscription. OpenAI likewise distinguishes API token prices from subscription usage. Claude Pro billing, OpenCode's Anthropic warning, OpenAI subscription and API pricing

For Ollama, start with ollama launch opencode after installing Ollama and OpenCode, and select a local model. Ollama also offers ollama launch opencode --config to configure without opening a session. Its launcher offers local and cloud models, so choose deliberately. Ollama's OpenCode setup

For manual local setup, OpenCode's provider example uses @ai-sdk/openai-compatible, the local address http://localhost:11434/v1, and a model ID matching the model you serve. LM Studio has its own provider example. An unlisted OpenAI-compatible service uses /connect → Other, plus a matching provider ID, address and model configuration in opencode.json. Local and custom providers

Run a First Real Task

Choose a bug whose correct behavior you can state before the agent starts. A signup form accepting an empty email address is a better first task than a request to redesign the entire application.

First, initialize the project. Run /init. It creates or updates AGENTS.md, a Markdown file containing instructions for future agent sessions. Read the result and correct its commands and assumptions before continuing. Project initialization

Next, ask for a plan. Press Tab until Plan is selected. Use @ to reference the actual implementation and test files in your repository. For the empty-email bug, you could ask:

This is an example task brief, not a report of a completed test. Substitute a real bug and real files from your project. Plan restricts edits and shell commands through permissions; it is not an isolated execution environment. Agents and Plan behavior, File references

Then implement the agreed scope. Switch to Build with Tab and ask it to add a regression test, the test that demonstrates the bug, and make the smallest fix. Have it show that the test fails for the original behavior and passes after the change, then run the relevant existing checks. Build is the default agent with tools enabled. Build agent

Finally, review the result yourself. Read the diff, check the test assertion against the behavior you intended, and inspect unrelated changes. A passing test that asserts the wrong behavior proves little. Ask the agent to report commands actually run and failures it could not resolve.

If the patch goes off course, /undo can revert the last message and its changes; /redo restores an undone message. Both rely on Git. Undo and redo

Make AGENTS.md and Rules Useful

Write the instructions a capable developer would need to work in this repository. Keep them specific enough to verify:

• The actual install, build, lint and test commands, including the order when it matters.
• Where application code, shared packages and generated files live.
• Which conventions to follow and which existing modules demonstrate them.
• What counts as completion, including the relevant checks and a summary of changed behavior.

Commit the project file so the team shares it. Personal rules belong in ~/.config/opencode/AGENTS.md. OpenCode can use CLAUDE.md as a fallback when the corresponding OpenCode rules file is absent. Rules and file locations

opencode.json is the configuration file. Its instructions array can load existing guidance, so you do not need to copy a contribution guide into AGENTS.md. The following example also asks before edits and shell commands:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md"],
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Use an instruction filename that exists in your project, and merge these settings into an existing config. A bare reference to another file inside AGENTS.md is not automatically expanded. Use instructions when you want that file loaded. Custom instructions

Rules describe the behavior you want. Permissions control whether a tool action proceeds. Most permissions start at allow, so choose permission settings deliberately when you want prompts. Permission configuration

Add Plugins When You Have a Specific Need

A plugin is JavaScript or TypeScript code that extends OpenCode through events, such as a tool running or a session becoming idle. You could use that mechanism for a local completion notification or a repository-specific workflow. Plugin hooks and examples

Put a local plugin in .opencode/plugins/ for one project, or ~/.config/opencode/plugins/ for all projects. OpenCode loads those files at startup. For a published npm package, add it to the plugin array in opencode.json; the docs show names such as opencode-wakatime. Packages and dependencies install automatically with Bun at startup. Review a plugin's source and maintenance before adding executable code to your development environment. Loading plugins

Start with the built-in workflow. Add a plugin when you can name the repeated job it will remove. A larger plugin collection can add configuration and debugging work before you have earned any benefit.

What OpenCode and Zen Cost

Separate the agent workflow from the model bill. With an existing supported subscription, you use that account's access. With an API key, usage is metered by the provider. With local inference, your machine capacity and running costs matter. Zen is a separate, optional way to buy model access. Provider choices

OpenCode Zen is a pay-as-you-go model service. Its public page advertises a $20 balance plus a $1.23 card processing fee, so that advertised purchase is $21.23, with $20 available for usage. It says requests have zero markup, monthly spend limits are available, and a $20 automatic top-up happens when the balance reaches $5. Those are balance and payment terms, not a monthly subscription price. Check the current terms before funding it. Zen's public pricing page

To connect it, run /connect, choose OpenCode Zen, follow the account and billing setup to obtain an API key, paste it into OpenCode, and use /models. It is optional when another provider already meets your needs. Zen connection

A Worked Session Estimate From Anthropic

An illustrative session using Claude Sonnet 4.6 through Anthropic's direct API can be priced from its published standard rates: $3 per million input tokens and $15 per million output tokens. A token is a small unit of text the model processes or produces. Assume the whole session, across all requests, totals 200,000 uncached input tokens and 20,000 output tokens. Anthropic's model and tool pricing

This is arithmetic, not a measured OpenCode session or a promised bug-fix price. It assumes standard direct API rates, no caching and no extra service charges. Count everything in the requests, including instructions, repeated conversation context and tool results. Cache reads and writes have different rates; other services and model choices change the bill. The estimate does not price Zen.

Twenty sessions at that assumed usage would total $18; thirty would total $27. For context, Claude Pro is publicly priced at $20 per month in the US and includes Claude Code with usage limits. This shows where a variable API budget can cross a fixed seat price; it does not establish equal output, equal allowance or which option is cheaper for your work. Claude Pro price and API distinction

Use opencode stats in your shell to see usage and cost statistics, or opencode stats --days 1 for the last day. For one session, opencode export lets you choose a session and export its data as JSON. Reconcile usage with the service billing you; a token-based estimate is not the price of an included subscription task. Usage commands

Six Tasks Worth Trying, Ranked by Practical Payoff

Start with repeated work whose output you can judge. These are proposed workflows, not claims of observed time savings.

OpenCode's noninteractive opencode run command can take a prompt for scripted work once your provider and workflow are configured. Use repeatable automation after a task has a reliable verification method. CLI run command

When to Choose OpenCode, Claude Code or Pi

Choose OpenCode when model choice is central to your workflow and you want built-in Plan and Build agents alongside project rules and plugin support. Its provider menu gives you a common working interface for multiple services and local setups. This is a workflow recommendation, not a claim that it produces better code. OpenCode models, Agents

Choose Claude Code when you already work mainly with Claude and want to use the Claude Pro or Max subscription through its documented terminal or IDE integration. Claude and Claude Code share the plan's usage limits. Compare your billing options in Claude Code Pricing in 2026. Claude's subscription integration

Choose Pi when you want a smaller core that you shape through extensions, prompt templates, skills and themes. Pi also supports multiple providers, so model flexibility alone is not a reason to choose OpenCode over Pi. Pi's public overview says a plan mode can be added through extensions rather than shipped in the core. My recommendation is OpenCode for its supplied workflow and Pi for a developer who wants to design more of that workflow. Pi's public overview

For the wider terminal-agent decision, read Gemini CLI vs Claude Code. Keep model access, your preferred workflow and payment route as separate comparison questions.

Two Things You Could Build Around It

Strongest: a Repository-Specific Review Workflow

A small engineering team could pay for a review workflow that checks its recurring mistakes and returns concerns with reproducible evidence. The demand signal is about 1,300 monthly US searches for “ai code review”, from DataForSEO's keyword estimate checked on October 4, 2026. CodeRabbit's public Essentials price is $24 per developer per month billed annually, or $30 monthly, a concrete paid category anchor. DataForSEO keyword data, CodeRabbit pricing

The smallest sellable version would load a team's review checklist and project instructions, examine a supplied diff, and return a short report with file locations, verification steps and recorded model usage. Begin as a repeatable local command, then add plugin hooks only where they reduce manual work.

The catch is competition and trust. A generic review wrapper offers little advantage over existing tools. A promising niche needs recurring domain rules and evidence that its suggestions reduce reviewer effort. The search number indicates category interest, not demand for an OpenCode product. This is the strongest opportunity here because review repeats and its usefulness can be judged against actual diffs.

A Tested OpenCode Onboarding Kit for Agencies

An agency could buy a setup service that delivers a working provider connection, accurate AGENTS.md, a minimal config and a reviewed first task for each client repository. About 1,600 monthly US searches for “open source ai coding assistant” indicate interest in this category, based on the same DataForSEO check. DataForSEO keyword data

The MVP would be a setup checklist plus repository-specific configuration, with a successful verification command and a clear billing route as the deliverables. Avoid making another broad coding-agent interface. The catch is that free documentation already covers installation, and search interest does not establish willingness to pay. Charge for the client-specific setup and maintained handoff only if agencies value that work.

What It Still Leaves to You

OpenCode does not settle whether the model understood your business requirements. Tests, code review and deployment judgment remain yours. A provider change also needs a fresh check of output quality and actual cost.

Local inference trades a hosted model bill for hardware capacity and setup work. A local agent interface connected to a cloud provider still sends model requests to that provider. Decide where inference runs separately from where you type the prompt.

For a tiny edit you already know how to make, the setup and review cycle may cost more attention than the change. For an ambiguous project, define the acceptance criteria before asking an agent to implement it. The valuable unit is a correct, reviewed change.

Your Monday move: pick one reproducible bug, open a fresh branch, connect one provider and finish the read, plan, edit, test and review cycle. Record which model you used, what checks passed and how the session was billed. That gives you evidence for the next tooling decision.

If you want a repository-specific coding or review workflow built for your team, AI agent development is the relevant next step.