Unlimited OpenCode with the Claude API

OpenCode is a terminal-based AI coding assistant that uses a provider plugin system for maximum flexibility. It supports custom providers through npm packages, runs parallel subagents for investigation and implementation, and maintains continuous terminal sessions that accumulate context over time. Its architecture of parallel agents doing continuous work makes it a heavy API consumer that benefits significantly from flat-rate unlimited access.

OpenCode's Parallel Agent Architecture

OpenCode operates with a primary agent (Build or Plan) and can spawn subagents (explore, scout) that work in parallel on related tasks. The Build agent handles direct code changes while Plan agent reasons about approach before delegating. Subagents run their own conversations with independent context, investigating codebases, reading documentation, or testing hypotheses while the primary agent continues its work.

This parallelism means multiple Claude conversations run simultaneously against your API key. A single complex task might have the Build agent editing files while an explore subagent reads related code and a scout subagent checks documentation. Each agent accumulates its own context independently — three agents running for ten turns each means thirty API calls, each carrying growing conversation histories.

Additionally, OpenCode supports custom agents that you define for project-specific workflows. Each custom agent is another parallel consumer of API tokens. On per-token billing, users carefully limit subagent usage to control costs. On unlimited, let OpenCode spawn as many subagents as the task benefits from — the flat rate covers all parallel work.

Configuring Custom Providers in opencode.json

OpenCode's provider system uses npm packages for API communication. For Claude through the unlimited gateway, you have two options: @ai-sdk/anthropic for the native Anthropic path, or @ai-sdk/openai-compatible for the OpenAI-compatible path. Configure these in your opencode.json file, which lives in your project root or ~/.config/opencode/.

For the OpenAI-compatible path, add a provider entry with package @ai-sdk/openai-compatible, set baseURL to https://unlimited.aiprimetech.io/v1 (with /v1), and configure your API key. Then reference this provider in your model definitions. For the native Anthropic path, use @ai-sdk/anthropic with baseURL set to https://unlimited.aiprimetech.io (root host, no /v1).

The opencode.json structure separates providers (how to connect) from models (what to use). Define your provider once, then create multiple model entries pointing to it with different model IDs. This cleanly separates connection configuration from model selection and lets you switch models without touching provider settings.

Model Configuration for Agents and Subagents

OpenCode lets you assign different models to different roles. The primary model handles your main interactions. The small_model handles trivial tasks like generating summaries or formatting output. Subagents can inherit the primary model or use their own assignment. Configure each in the models section of opencode.json.

For the primary model on unlimited, use claude-sonnet-4-5 for balanced performance or claude-opus-4-6 for maximum reasoning quality. Set small_model to claude-haiku-4-5 for fast, lightweight operations. The small_model handles tasks where latency matters more than depth — generating file summaries, formatting outputs, and quick lookups.

Custom agents defined in opencode.json can each specify their own model. A research agent might use Opus for deep analysis while an implementation agent uses Sonnet for fast code generation. On unlimited, assign models based purely on quality requirements — use the strongest model available for each role without cost considerations.

MCP Integration and Tool Expansion

OpenCode supports MCP (Model Context Protocol) servers that extend agent capabilities with custom tools. Configure MCP servers in opencode.json under the mcp section, specifying the server command, arguments, and environment. Tools from MCP servers become available to all agents, expanding what OpenCode can do without code changes.

Each MCP tool adds its schema to the system prompt sent with every request, increasing baseline token consumption. When an agent invokes an MCP tool, the tool call and result add further tokens to the conversation. With multiple MCP servers providing many tools, the per-request overhead can be substantial — 5,000-10,000 tokens just for tool definitions before any actual work begins.

On unlimited, you can connect as many MCP servers as genuinely useful: database clients, documentation servers, deployment tools, monitoring interfaces. The token overhead of rich tool sets is covered by the flat rate. This lets OpenCode function as a comprehensive development environment with access to every system it might need during a task.

Continuous Terminal Sessions and Context Growth

OpenCode maintains persistent terminal sessions where agents execute commands and observe output. Unlike tools that fire-and-forget terminal commands, OpenCode's agents can watch long-running processes, read streaming output, and react to changes in real time. Each terminal interaction adds to the conversation context — command output, error messages, log lines all become part of the growing history.

A typical development session involves repeated build-test-fix cycles. Each cycle adds terminal output to context: compiler errors, test results, application logs. Over an hour of active development, the terminal context alone can grow to tens of thousands of tokens. Combined with file contents and conversation history, sessions regularly approach context limits.

On unlimited, this continuous workflow runs without token anxiety. Let OpenCode watch your test suite run, observe build output, monitor server logs — each observation costs nothing extra and gives the agent better awareness of your system's state. The flat rate covers hours of continuous terminal interaction at the same price as a single request.

Build Agent vs Plan Agent Workflows

The Build agent directly implements changes — it reads files, writes code, runs commands, and verifies results. Use it for well-defined tasks where you know what needs to happen: fix a specific bug, add a function with clear requirements, refactor a known pattern. Build is action-oriented and efficient for straightforward work.

The Plan agent reasons about approach before acting. It analyzes requirements, considers alternatives, and produces a structured plan before delegating implementation steps. Use it for ambiguous tasks, architectural decisions, or multi-step changes where the right approach is not obvious. Plan produces better results for complex work but uses more API calls due to the additional reasoning phase.

On unlimited, default to Plan agent for anything non-trivial. The extra API calls for planning and reasoning cost nothing and consistently produce better outcomes for complex tasks. Reserve Build agent for simple, mechanical changes where planning would be overhead without benefit — formatting fixes, simple renames, obvious bug fixes.

Troubleshooting OpenCode Provider Configuration

If OpenCode fails to load your provider, check that the npm package is installed. Run npm install @ai-sdk/openai-compatible or npm install @ai-sdk/anthropic in your project directory. OpenCode resolves provider packages from your project's node_modules — if the package is not installed, the provider configuration is silently ignored.

For connection errors, verify the baseURL format matches your provider package. The @ai-sdk/openai-compatible package expects a URL with /v1 suffix. The @ai-sdk/anthropic package expects the root host without /v1. Mixing these up causes 404 errors that may surface as cryptic 'model not available' messages rather than clear HTTP errors.

If subagents fail while the primary agent works, check that your model configuration is complete. Subagents may use different model assignments — if a subagent's configured model does not exist on the gateway, it fails silently. Ensure all model entries in opencode.json reference valid model IDs that your gateway supports.

// opencode.json - OpenAI-compatible path
{
  "providers": {
    "unlimited": {
      "package": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://aiprimetech.io/v1",
        "apiKey": "<your AI Prime Tech Unlimited key>"
      }
    }
  },
  "models": {
    "sonnet": { "provider": "unlimited", "model": "claude-sonnet-4-5" },
    "opus":   { "provider": "unlimited", "model": "claude-opus-4-6" },
    "haiku":  { "provider": "unlimited", "model": "claude-haiku-4-5" }
  },
  "agent": { "model": "sonnet", "small_model": "haiku" }
}

Frequently asked questions

Which npm package should I use for Claude in OpenCode?
Use @ai-sdk/openai-compatible with baseURL set to https://unlimited.aiprimetech.io/v1, or @ai-sdk/anthropic with baseURL set to https://unlimited.aiprimetech.io (no /v1). Both work; the OpenAI-compatible path is more common in OpenCode configurations.

How do subagents affect API usage in OpenCode?
Each subagent (explore, scout, custom) runs its own independent conversation with growing context. Three parallel subagents running ten turns each means thirty separate API calls. On unlimited, this parallelism is fully covered by the flat rate.

What is small_model and when is it used?
small_model handles trivial tasks like generating summaries, formatting output, and quick lookups where speed matters more than depth. Set it to claude-haiku-4-5 for fastest response times on lightweight operations.

Can I define custom agents in OpenCode?
Yes. Add agent definitions in opencode.json with custom system prompts, tool access, and model assignments. On unlimited, create as many specialized agents as your workflow needs — research, implementation, review, documentation — without per-agent cost concerns.

Why does OpenCode's context grow so large during terminal sessions?
OpenCode maintains persistent terminal sessions where all command output (build logs, test results, error messages) accumulates in the conversation context. An hour of active development can add tens of thousands of tokens from terminal output alone. On unlimited, this growth costs nothing extra.

AI Prime Tech is an independent API gateway. It is not affiliated with, endorsed by, or a reseller of Anthropic. Claude and related model names are trademarks of their respective owners.