Skip to content

opencode.md

Latest commit

 

History

History
158 lines (115 loc) · 5.18 KB

opencode.md

File metadata and controls

158 lines (115 loc) · 5.18 KB

OpenCode Go tracking and delegation

Setup

OpenCode Go's official usage API was still unavailable when last reviewed on 2026-05-07, so tokenmaxxer scrapes the dashboard with your browser auth cookie. The easiest path is to run /tokenmaxxer:setup inside Claude Code — when a cookie is needed, the setup output prints the absolute path to the helper for your install, so you can run it without guessing the plugin path.

To run the helper directly from a local terminal, point it at your tokenmaxxer install (plugin installs land at ~/.claude/plugins/cache/tokenmaxxer/tokenmaxxer/<version-or-sha>/):

bash /path/to/tokenmaxxer/scripts/configure-opencode-cookie.sh

Tracking credentials and delegation credentials are separate; the canonical credential-role table is in facts.md.

The helper walks the user through a manual DevTools-based copy of the auth cookie:

  1. Prints a 3-step playbook (sign in to OpenCode, copy the workspace URL from the address bar, copy the auth cookie value via DevTools).
  2. Opens the OpenCode console (https://opencode.ai/auth) in the user's default browser.
  3. Prompts for the workspace URL or ID, then for the cookie value (input hidden).

The helper writes ~/.claude/.tokenmaxxer-opencode-go.json with 0600 permissions:

{
  "workspaceId": "your-workspace-id",
  "authCookie": "your-browser-auth-cookie"
}

The workspace ID comes from the dashboard URL:

https://opencode.ai/workspace/<workspaceId>/go

The auth cookie is the value of the browser cookie named auth for opencode.ai.

Alternative: env vars

You can skip the config file entirely:

export OPENCODE_GO_WORKSPACE_ID=your-workspace-id
export OPENCODE_GO_AUTH_COOKIE=your-browser-auth-cookie

Environment variables take precedence over the config file when both are set.

Permissions

If you use a compatibility config path under ~/.config/opencode or ~/.opencode, keep that file private — tokenmaxxer rejects cookie config files that are readable or writable by group/others.

What renders

tokenmaxxer surfaces the windows documented in facts.md. The monthly row appears only when opencode quota data is present; when it renders, it stays aligned under the opencode go column above it.

Where the data lives

File Purpose
~/.claude/.tokenmaxxer-opencode-go.json Cookie config (mode 0600)
~/.claude/.tokenmaxxer-opencode.json Sidecar tokenmaxxer reads from
~/.claude/.tokenmaxxer-opencode.debug.log Last scrape attempt detail

Empty / failure states

Quota scrape states come from the dashboard-cookie path:

Cell text Meaning Fix
opencode go (cookie needed) No cookie config and no env vars Run the cookie helper above
opencode go (config insecure) Cookie config is group/others-readable chmod 0600 the config file
opencode go (scrape failed) Cookie expired or dashboard markup changed Rerun the cookie helper for a fresh cookie
opencode go (config incomplete) Cookie config is missing workspaceId or authCookie Re-run the cookie helper or fix the file

Official usage probes may also report this state while tokenmaxxer is checking for a future OpenCode Go usage API:

Cell text Meaning Fix
opencode go (auth failed) API key in ~/.local/share/opencode/auth.json rejected Re-run opencode auth

Delegation

The plugin ships an opencode-run subagent for delegating work to OpenCode Go when capability fit favors it. The default model is documented in facts.md.

Claude can invoke opencode-run during routing decisions. The subagent routes through the /tokenmaxxer:opencode slash command (which only pre-approves the opencode harness invocation, not arbitrary bash). You can also call the same harness directly:

/tokenmaxxer:opencode "say hello in 3 words"

Add Model: or Variant: directives at the top of the task to tune cost and effort:

/tokenmaxxer:opencode "Model: opencode-go/deepseek-v4-flash
Variant: minimal
write a jq command that extracts .items[].id"

Warm-session fork pattern

The harness uses OpenCode's warm-session-plus-fork pattern. On the first invocation in a project, it captures the OpenCode session ID and stores it in:

~/.claude/.tokenmaxxer-opencode-warm.json

Later invocations fork from that warm session with --session <id> --fork, so the warm anchor stays small while delegated tasks inherit the cached prefix. Delete the warm file (or remove a project entry from it) to force fresh sessions.

In local empirical testing, OpenCode Go reported 12K+ cache-read tokens on a brand-new session, confirming transparent provider-side prefix caching. Warm-session fork layers on top: prefix caching is a multiplier on whichever backend and variant the orchestrator chooses.

Kill switch

To opt out of OpenCode delegation entirely without uninstalling the plugin:

export TOKENMAXXER_OPENCODE_DISABLED=1

References