Skip to content

opencode2-setup.md

Latest commit

 

History

History
143 lines (105 loc) · 4.06 KB

opencode2-setup.md

File metadata and controls

143 lines (105 loc) · 4.06 KB
Raw

OpenCode 2 setup

This fork is for the OpenCode 2 beta CLI (opencode2) only. It uses two plugin entrypoints because OpenCode 2 separates server plugins from terminal UI plugins.

Requirements

  • OpenCode 2 with the opencode2 command available
  • Node.js 22 or newer
  • pnpm 11 through Corepack or a direct installation

1. Clone and build

git clone https://github.com/sr4dev/opencode-quota-v2.git
cd opencode-quota-v2
corepack pnpm install --frozen-lockfile
corepack pnpm build

The build must create both of these files:

dist/opencode2-server.js
dist/index.js

2. Register the server plugin

Add the repository's OpenCode 2 server plugin directory to ~/.config/opencode/opencode.json. Preserve all existing settings and plugin entries.

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    "file:///D:/Workspace/opencode-quota-v2/opencode2"
  ]
}

Use an absolute file:/// URL. On Windows, use forward slashes and include the drive letter as shown above.

The path must name the opencode2 directory, not dist/opencode2-server.js. Current OpenCode 2 releases reject configured server plugin paths that are files. The directory entrypoint forwards to the built adapter.

The plural plugins field is intentional. The upstream OpenCode V1 examples use a singular plugin field and do not register this OpenCode 2 adapter.

3. Register the terminal plugin

Add the built TUI plugin to ~/.config/opencode/cli.json. Preserve existing CLI settings.

{
  "$schema": "https://opencode.ai/v2/cli.json",
  "plugins": [
    "file:///D:/Workspace/opencode-quota-v2/dist/index.js"
  ],
  "session": {
    "sidebar": "auto"
  }
}

Do not put this entry in the V1 tui.json. OpenCode 2 terminal plugins are loaded from cli.json.

4. Configure the quota sidebar

Create ~/.config/opencode/opencode-quota/quota-toast.json:

{
  "enableToast": false,
  "showSessionTokens": true,
  "enabledProviders": [
    "anthropic",
    "copilot",
    "openai"
  ],
  "minIntervalMs": 300000,
  "formatStyle": "allWindows",
  "percentDisplayMode": "remaining",
  "tuiSidebarPanel": {
    "enabled": true
  },
  "tuiCompactStatus": {
    "enabled": true,
    "homeBottom": true,
    "sessionPrompt": false
  }
}

If claude is not on PATH, add an absolute path for the local Claude executable:

{
  "anthropicBinaryPath": "C:\\Users\\you\\.local\\bin\\claude.exe"
}

Merge that field into the complete configuration rather than replacing the file with the one-field example.

5. Restart and verify

opencode2 service restart
opencode2 service status
opencode2 api get /api/health

Then start opencode2, open a session, and inspect the sidebar. A Quota panel should appear. Run /quota_status to verify provider detection and the effective quota configuration.

If the sidebar is hidden at the current terminal width, widen the terminal or open it through the command palette. The session.sidebar value above allows OpenCode 2 to manage its normal responsive behavior.

Updating

Close running OpenCode 2 terminal clients, then update the checkout and rebuild:

git pull --ff-only
corepack pnpm install --frozen-lockfile
corepack pnpm build
opencode2 service restart

The configuration points at the checkout's dist files, so no path changes are needed after an in-place update.

Common failures

Sidebar does not appear

  • Confirm cli.json uses plugins, not plugin.
  • Confirm it references dist/index.js, not dist/opencode2-server.js.
  • Confirm the path is an absolute file:/// URL with forward slashes.
  • Run corepack pnpm build again after every pull.

/quota_status is missing

  • Confirm opencode.json references the repository's opencode2 directory.
  • Restart the shared service with opencode2 service restart.
  • Check health with opencode2 api get /api/health.

V1 instructions conflict with this guide

The inherited upstream documentation describes the npm-published OpenCode V1 package in several places. For this fork, this guide and the root README take precedence.