# opencode config

Config tree for [opencode](https://opencode.ai) (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.