A version-controlled OpenCode configuration. The opencode/ directory in this repo mirrors OpenCode's global config directory one-to-one:

opencode/
├── opencode.json     # providers, model, permissions
├── tui.json          # theme (tokyonight)
├── AGENTS.md         # global rules applied to every session
├── agents/           # read-only subagents: investigator, architect, boundaries
└── tools/            # custom tools (list.ts)

"Using" this repo means making OpenCode load the contents of opencode/ as its global config. There are three ways to do that, below.

• Install OpenCode (the opencode CLI).
• A reachable model provider. For the DGX Spark that backs this config, spark_model_installation_instructions.md is the server-side manual: Docker image, downloading model weights from Hugging Face, model-choice rules of thumb, the vLLM launch commands for both models, and making them survive reboots.
• This repo cloned somewhere stable, e.g. ~/Projects/opencodeconfig.

You can override this location with the OPENCODE_CONFIG_DIR environment variable (method B).

If a config dir already exists at the default location, back it up first so you don't lose it:

• macOS: mv ~/.config/opencode ~/.config/opencode.bak
• Windows (PowerShell): Rename-Item "$env:USERPROFILE\.config\opencode" opencode.bak

A plain copy into the default config location. Simplest and most portable — no symlinks or environment variables. The trade-off: you must re-run the copy after every git pull.

macOS / Linux:

mkdir -p ~/.config/opencode
cp -R opencode/. ~/.config/opencode/

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode" | Out-Null
Copy-Item -Recurse -Force opencode\* "$env:USERPROFILE\.config\opencode\"

No copying or symlinking. OpenCode reads config straight from your clone, so git pull is the only update step. Set the variable to the repo's opencode/ subdirectory (not the repo root).

macOS / Linux (zsh) — add to ~/.zshrc, then restart the shell:

export OPENCODE_CONFIG_DIR="$HOME/Projects/opencodeconfig/opencode"

Windows (PowerShell) — persist for the current user:

setx OPENCODE_CONFIG_DIR "C:\Users\<you>\Projects\opencodeconfig\opencode"

Open a new terminal (so the variable is picked up) and run opencode.

Edits in the repo take effect immediately; git pull updates the live config.

macOS / Linux:

mkdir -p ~/.config
ln -s "$HOME/Projects/opencodeconfig/opencode" ~/.config/opencode

Windows — symlinks require an admin terminal or Developer Mode enabled.

PowerShell:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config" | Out-Null
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode" -Target "C:\Users\<you>\Projects\opencodeconfig\opencode"

cmd:

mklink /D "%USERPROFILE%\.config\opencode" "C:\Users\<you>\Projects\opencodeconfig\opencode"

Launch opencode and confirm:

• The tokyonight theme is applied.
• The local model is selected (or change it with /models).
• The subagents @investigator, @architect, and @boundaries are available.
• The custom list tool works (it satisfies ls-style tool calls).

Restart OpenCode after any change to opencode.json, tui.json, AGENTS.md, or any file under agents/ or tools/ — config and tools are loaded at startup.

opencode.json defines one provider per model, but both point at the same endpoint — the Spark serves one model at a time on port 8000, and which one is a server-side choice (switching, image, model downloads, reboot persistence: spark_model_installation_instructions.md):

To use the 27B:

• Switch the Spark to it first — docker stop vllm-qw36-35b && docker start vllm-qw36-27b (see the install doc). Requests for a model the server isn't running fail with model-not-found.
• In the TUI: type /models and pick Qwen3.6-27B-NVFP4 under "Local LLM 27B". OpenCode remembers the last-used model across sessions.
• One-off, non-interactive: opencode run -m localllm27b/nvidia/Qwen3.6-27B-NVFP4 "your prompt"
• As the default: set model (and small_model) in opencode.json to localllm27b/nvidia/Qwen3.6-27B-NVFP4 and restart OpenCode.

The subagents (agents/*.md) pin their own model in frontmatter — currently the 35B — so they only work while the Spark serves the 35B; switch back (or repoint them) before using them.

git pull

With Method B or C, that's all. With Method A (copy), re-run the copy step.

This config is built around one bet: with a small, local, sequential model, the context window is the only lever on output quality — and a cheap one to waste. So the architecture (aggressive delegation to read-only subagents, edit-over-write rules, a research→plan→implement→validate command set) borrows directly from HumanLayer's Advanced Context Engineering for Coding Agents: keep the main context small and high-signal, push exploration into disposable subagents, and write research and plans to disk so every step starts from a clean, curated context.

Diagram from Advanced Context Engineering for Coding Agents by Dex Horthy / HumanLayer.

A bad line of code costs a few lines; a bad plan costs hundreds; bad research costs thousands. The commands below front-load research and planning — the highest-leverage steps — so that's where your review effort goes.

Type these as slash commands in OpenCode (e.g. /create_plan add rate limiting). They chain into a research → plan → implement → validate loop, each writing to disk so the working context stays lean:

Typical loop: /research_codebase → /create_plan → (review the plan) → /implement_plan → /validate_plan → /commit.