opencode-starter

A launcher toolkit for AI coding tools powered by OpenCode backends.

opencode-starter is an interactive CLI wizard that configures and launches AI coding tools — starting with Claude Code — using OpenCode Zen or Go as the API backend. Built to be extensible: future tools (Codex, Aider, and others) will be added over time.

Features

• Backend selector — choose OpenCode Zen (free tier + subscription) or OpenCode Go (subscription)
• Subscription-aware — tells the wizard what you have access to (free / Zen / Go / both), filters models accordingly
• Free models highlighted — green (free) label makes it easy to spot zero-cost options
• Built-in translation proxy — models using OpenAI format are automatically routed through a local translation proxy so Claude Code talks to them in Anthropic format; labeled (via proxy) in the list
• Clean environment isolation — removes conflicting env vars (Vertex AI, Bedrock, AWS, Foundry) before launch; never modifies ~/.claude/settings.json
• Secure key storage — stores your API key in the OS credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service) or your shell profile — your choice
• Cross-platform — macOS, Windows, and Linux (Ubuntu, Fedora, and other distros with GNOME Keyring or KWallet)
• Dry run mode — preview exactly what would be run without launching anything
• Preference memory — remembers your last backend and model, pre-selects them next time

Supported tools

| Tool | Command | Status | |------|---------|--------| | Claude Code | opencode-starter claude | ✅ Supported | | API server | opencode-starter server | ✅ Supported | | Codex | opencode-starter codex | 🔜 Planned |

Prerequisites

• Node.js 18+
• One of the supported AI coding tools installed (e.g. Claude Code)
• An OpenCode API key

Installation

# Install globally
npm install -g opencode-starter

# Upgrade to the latest version
npm update -g opencode-starter

Setup

Get your API key at opencode.ai/settings/keys.

On first run, opencode-starter will prompt you for the key and ask where to save it. Options vary by OS:

| Platform | Secure storage | Plaintext fallback | |----------|---------------|-------------------| | macOS | Keychain (optional: + ~/.zshrc auto-load) | Shell profile | | Windows | Credential Manager | setx user env var | | Linux (desktop) | Secret Service (GNOME Keyring / KWallet) | Shell profile | | Linux (headless) | — | Shell profile |

The key is always active immediately in the current session regardless of which option you choose. No need to restart your terminal.

Usage

opencode-starter claude

On first run, the wizard asks about your OpenCode subscription so it can show the right models. This is saved and skipped on subsequent runs.

Bare opencode-starter now prints help and migration guidance. It no longer launches Claude Code. Use opencode-starter claude for the Claude Code wizard and launcher.

Flags

| Flag | Description | |------|-------------| | --dry-run | Run the full wizard but preview the launch command instead of executing | | --setup | Re-configure your subscription tier | | --trace | Write Claude Code debug logs to /tmp/opencode-starter-debug.log and show errors on exit | | --help | Show usage | | --version | Show version |

Starter flags go after the claude command:

opencode-starter claude --dry-run
opencode-starter claude --setup
opencode-starter claude --trace

Claude Code flags and session IDs pass through unchanged:

opencode-starter claude -c
opencode-starter claude --resume abc-123
opencode-starter claude abc-123

Use -- when you want every following token passed directly to Claude Code:

opencode-starter claude -- --print "hello"
opencode-starter claude -- --dangerously-skip-permissions
opencode-starter claude --dry-run -- --print "test"

Server mode

Run OpenCode Starter as a foreground API gateway:

opencode-starter server

The server asks whether to listen locally or on the network.

Local mode binds to 127.0.0.1:

export ANTHROPIC_BASE_URL="http://127.0.0.1:17645/anthropic"
export ANTHROPIC_API_KEY="anything"

Network mode binds to 0.0.0.0 and asks for a server password:

export ANTHROPIC_BASE_URL="http://<server-ip>:17645/anthropic"
export ANTHROPIC_API_KEY="<server-password>"

By default, the server password is kept in memory only. If you choose to save it, OpenCode Starter stores it in ~/.opencode-starter/config.json.

The server also exposes OpenAI-compatible endpoints for OpenAI-format models:

export OPENAI_BASE_URL="http://127.0.0.1:17645/openai/v1"
export OPENAI_API_KEY="anything"

How it works

Subscription tiers

On first run, opencode-starter asks what you have access to:

| Tier | Backends available | Models shown | |------|--------------------|--------------| | Free only | Zen | Free Zen models only | | Zen subscription | Zen | All Zen models (paid + free) | | Go subscription | Zen + Go | All Go models + Zen free models | | Both | Zen + Go | All models on both backends |

Run opencode-starter claude --setup at any time to change your tier.

Environment isolation

When launched, opencode-starter builds a clean child environment:

1. Removes 17 conflicting env vars from the child process (Vertex AI, Bedrock, AWS, Foundry, stale Anthropic config)
2. Sets ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, and ANTHROPIC_MODEL for the session
3. Passes --model <selected> to the tool as a belt-and-suspenders override

When the tool exits — for any reason (normal exit, Ctrl+C, terminal close) — everything returns to your normal environment. No cleanup step, no restore needed.

Model compatibility

OpenCode exposes models through different API formats. opencode-starter handles all of them transparently:

| Model format | Examples | How it works | Label | |---|---|---|---| | Anthropic native | Claude, Qwen, MiniMax (Go) | Direct connection to OpenCode | (none) | | OpenAI compatible | DeepSeek, Kimi, MiMo, GLM, Nemotron, Grok | Local translation proxy (Anthropic↔OpenAI) | via proxy | | Not yet supported | GPT, Gemini | Needs format support not yet implemented | not yet supported |

The translation proxy starts automatically on a random local port when you select an OpenAI-compatible model, and stops when Claude Code exits. No configuration needed.

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 is automatically set for all sessions to prevent beta header issues with the OpenCode proxy layer.

API key storage

opencode-starter uses @napi-rs/keyring to interface with the OS credential store. On subsequent runs it checks the credential store silently — if a key is found, the wizard skips the key prompt entirely.

| Platform | Credential store | Notes | |----------|-----------------|-------| | macOS | macOS Keychain | Optional ~/.zshrc auto-load line makes the key available system-wide | | Windows | Windows Credential Manager | setx available as a plaintext alternative | | Linux (desktop) | Secret Service API (GNOME Keyring, KWallet) | Requires a running keyring daemon | | Linux (headless) | Not available | Falls back to shell profile or session-only |

If the native module fails to load on an unsupported platform, the credential store options are silently skipped and only shell profile / session-only storage is offered.

Preference persistence

Your last backend, model selection, subscription tier, model cache, and optional saved server password are saved to:

~/.opencode-starter/config.json

The OpenCode API key is handled separately by the key storage option you choose during setup.

Contributing

This project is in private beta. Contributions and feedback welcome — open an issue or PR on GitHub.

License

MIT