dots/common/.config/opencode/README.md

opencode config

Config tree for opencode (2.x), tuned for small local models behind a llama.cpp router. Stowed into ~/.config/opencode/ as per-file symlinks; editing here edits the live config (restart opencode, or opencode service restart, to pick changes up — the 2.x background service caches config).

Layout

Path	What
opencode.json	Providers, permissions, primary agents, defaults. Written in the v1 schema, which 2.x still accepts.
openai-gpt.jsonc	Optional GPT/Codex OAuth overlay (OpenAI provider + opencode-openai-codex-auth plugin). Not loaded by itself — see GPT overlay.
AGENTS.md	Global rules prepended to every session. Same text as the pi config's AGENTS.md: terse, verify-before-asserting, small-model friendly.
agents/*.md	Four subagents with real prompts and scoped permissions: code-reviewer, test-runner (hidden), doc-writer (edits docs only), security-auditor (hidden).
commands/*.md	/commit (Conventional Commits message, never commits) and /review (read-only diff review), both on the plan agent.
plugins/verbose/	2.x TUI plugin: <leader>v, /verbose, or the palette entry toggles the verbose view — thinking blocks expanded and tool calls ungrouped — reading the live state from the built-in toggles so a mixed state converges. server.ts is a no-op half required by the loader.
themes/catppuccin-mocha.json	Catppuccin Mocha (dark) / Latte (light) theme following the pi theme's semantic mapping. Built-in catppuccin exists too; this one matches pi.
tui.json	TUI settings in the v1 schema (2.x compat): theme, leader timeout, stacked diffs, block cursor, attention notifications, a few extra keybinds.

The sandbox wrapper lives in ../fish/functions/opencodes.fish: opencodes runs opencode under bwrap with the stowed config dirs, ~/.cache/opencode, state and data bound, and only the needed environment passed through. Extra arguments go to opencode.

Providers and models

Two OpenAI-compatible providers point at the same llama.cpp router: llama.cpp on the LAN and duskadiy through the public hostname (apiKey from $DUSKADIY_API_KEY). Model ids are the preset section names in fl/.config/llamacpp/config.ini; keep the lists in sync with it and with the pi and aichat configs. Both providers use a one-hour request timeout — the default five minutes cut off long local replies.

Decisions that look odd but are deliberate:

• No small_model. The router runs --models-max 1; any second model id evicts the resident one. With small_model unset, title generation falls back to the session's model. Subagents carry no pinned model for the same reason — the task tool uses the caller's model.
• No temperature / top_p from opencode. Verified by capturing request bodies: only max_tokens is sent, so the router presets own sampling.
• reasoning: true only on the presets that actually think (no reasoning-budget = 0); GLM also replays reasoning_content in history because its preset sets reasoning-preserve.
• snapshot: false — file-change undo is not used. tool_output capped at 200 lines / 16 KiB for 24k-context models. compaction.reserved/prune are inert at this context size.
• question: allow everywhere so agents ask instead of guessing.

Agents

auto is the default agent and cycles with build and plan on Tab. It runs without prompts except for the serious set — git history rewriting and pushing, rm, killing processes, systemctl, network transfers, package installs — which ask, and sudo/dd/mkfs/secret-file reads, which are denied. Colors: build primary, plan info, auto yellow. All three cap agentic iterations at 30.

Permission rules resolve global first, agent rules appended, last match wins, so an agent that wants a blanket rule must restate its own denies after it (the auto block does).

GPT overlay

openai-gpt.jsonc is a template. opencode 2.x ignores OPENCODE_CONFIG, but it merges a second global file named opencode.jsonc. fish/config.fish links opencode.jsonc → openai-gpt.jsonc only on a host whose ~/.local/share/opencode/auth.json holds an OpenAI credential (from opencode auth login), and removes the link again when the login is gone.

Host overlays

lw/.config/opencode/opencode.json is a fork of the common file that adds the laptop's local CPU llama.cpp provider (lwcpp). Mirror every edit between the two.

Lifting pieces into a stock opencode

Everything is plain files: copy agents/, commands/, plugins/verbose/ or the theme into your own ~/.config/opencode/. The plugin needs 2.x (it uses the keymap.layer / dispatch API and is discovered as a directory under plugins/). The permission blocks in opencode.json are independent of the providers and can be pasted as-is.