OpenCode Config

Lean OpenCode setup for day-to-day coding: a locally built opencode binary, a tmux-aware launcher, repo-specific agents, and a small skill set for planning, implementation, review, backlog work, and worktree hygiene.

What This Repo Configures

• opencode.jsonc is the active config: plugins, MCP servers, permissions, agent defaults, and LSPs.
• opencode.example.jsonc is the template if you want to fork or trim the stack.
• opc.sh is the preferred launcher.
• opc-up.sh rebuilds and refreshes the local toolchain.
• agents/ defines the repo's primary agents and subagents.
• skills/ holds reusable workflows the agents can load on demand.

Current Stack

Core

• OpenCode CLI built locally to ~/.local/bin/opencode
• tmux for session and window management
• Worktrunk (wt) for branch and worktree flow
• backlog.md MCP for task tracking

Plugins

• @tarquinen/opencode-dcp@latest
• opentmux

Enabled MCP Servers

• context7 - library docs lookup
• tauri - Tauri app automation
• websearch - Exa-backed web and code search
• eslint - ESLint MCP
• backlog - Backlog.md MCP
• playwright - headless Chromium browser automation

LSPs

• typescript-language-server
• pyright-langserver
• oxlint
• docker-langserver
• remark-language-server
• biome lsp-proxy

Prerequisites

Install the tools this config expects:

These examples are Linux-first. If you are on macOS, use Homebrew equivalents where appropriate.

# Bun
curl -fsSL https://bun.sh/install | bash

# tmux
sudo apt install tmux

# backlog.md
bun add -g backlog.md

# opentmux
npm install -g opentmux

# Worktrunk
brew tap bkrausz/tap && brew install worktrunk

Install the OpenCode CLI from source:

git clone -b beta https://github.com/anomalyco/opencode.git ~/opencode
cd ~/opencode
bun install
bun packages/opencode/script/build.ts --single
install -m 755 ~/opencode/packages/opencode/dist/opencode-*/bin/opencode ~/.local/bin/opencode

Optional but expected by the active config:

• Chromium at /usr/bin/chromium for Playwright MCP

Setup

1. Clone This Repo

git clone <repo-url> ~/.config/opencode
cd ~/.config/opencode

Reuse is under the MIT License. If you plan to contribute, keep it lean and follow CONTRIBUTING.md.

2. Create the Active Config

opencode.jsonc is the active config and is meant to be created locally from the template:

cp opencode.example.jsonc opencode.jsonc

3. Create Secrets

Create ~/.config/opencode/.mcp-secrets.env for MCP servers that source env vars:

CONTEXT7_API_KEY=your_key_here
EXA_API_KEY=your_key_here

4. Add Shell Aliases

alias opc='~/.config/opencode/opc.sh'
alias opc-up='~/.config/opencode/opc-up.sh'

Reload your shell:

source ~/.bashrc
# or
source ~/.zshrc

Everyday Use

Launch With opc

opc

What it does:

• disables OpenCode autoupdate for the session
• launches ~/.local/bin/opencode
• finds the next free port starting at 4096
• uses tmux sessions named from OPC_SESSION_PREFIX (default: opencode)
• stores the original working directory as tmux option @opc_context_root
• opens a new tmux window if already inside a live tmux client
• otherwise creates and attaches a new tmux session, then falls back to direct launch if tmux fails

From an interactive shell on the default branch, opc checks Worktrunk state and prompts you to:

• work on the default branch
• switch to an existing trunk/* branch
• create a new trunk worktree (recommended)

Useful variants:

OPC_DEBUG=1 opc
OPC_SESSION_PREFIX=myproj opc
opc -- <extra opencode args>

Update With opc-up

opc-up

What it does:

• updates the source repo at ${OPC_UP_REPO:-~/opencode}
• hard-resets that repo to its configured upstream branch when one exists (otherwise falls back to the remote default branch) and removes untracked files there
• runs bun install
• provisions a cached helper Python with setuptools for node-gyp if the system Python lacks distutils
• rebuilds the single-file OpenCode binary
• installs the result to ~/.local/bin/opencode
• updates backlog.md
• updates opentmux if it is installed globally
• upgrades Worktrunk if it is installed via Homebrew
• refreshes wt config shell install

Important: opc-up is intentionally destructive inside ${OPC_UP_REPO}. It discards local changes in the OpenCode source checkout it manages.

Agents

Built-in build and plan agents are disabled in this config; Brokkr and Mimir cover those roles.

Primary Agents

Agent	Role
Brokkr - Orchestrator	Default agent; orchestrates implementation by specialty, runs independent lanes in parallel when safe, verifies diff plus tests or build before done, commits only when asked
Mimir - Planner	Research, architecture, and parallel-aware task creation only; absolutely no code implementation
compaction	Context compression and preservation

Subagents

Agent	Role
backend	Server-side logic and data layer
blogger	Docs, guides, tutorials, README rewrites, and editorial cleanup
explore	Read-only codebase exploration
frontend	UI logic, state, and accessibility
general	General-purpose multi-step work
reviewer-a	Structured reviewer A
reviewer-b	Structured reviewer B
small	Small edits and git ops
webui	Browser UI and Rust/Tauri frontend visual work

Skills

Skill	Purpose
frontend-design	High-quality production frontend design
interface-design	Deliberate dashboard, SaaS, and tool interface design
peer-review	Parallel review orchestration across reviewer-a and reviewer-b
prune-worktrees	Safe Worktrunk cleanup and pruning
report-loc	SCC-only codebase LoC and language breakdown
save-work	End-of-session commit, push, PR, and merge workflow
tasks-create	Create backlog tasks against the canonical default-branch backlog
tasks-do	Execute an existing backlog task end-to-end

Usage Rules

General

• Launch normal sessions with opc, not raw opencode, so tmux and worktree behavior stay consistent.
• When starting from the default branch, prefer switching to or creating a trunk/* worktree unless you intentionally want base-branch work.
• Treat opencode.jsonc as the active source of truth; opencode.example.jsonc is only a template.
• Brokkr should usually delegate through task, break implementation into lanes, launch independent subagents in parallel when safe, route docs writing and rewrites to blogger, and verify the diff plus tests or build before calling work done.
• Mimir is for research, architecture, and /tasks-create planning only; it must not implement code, and it should create task graphs that preserve safe parallel execution with real dependencies only.

How to Prompt tasks-do

• Single task: name one task and tasks-do should do only that task.
• Task range: name the range and tasks-do should do only that range.
• Keyword task set: name the keyword(s) and tasks-do should do only the related matching tasks.
• Pause or stop: say so explicitly and tasks-do should pause and update the backlog task.

Examples:

do task-333
do task-333 through task-340
work the auth tasks
pause task-333
stop after task-333 and update the backlog

Backlog Rules

• Shared backlog writes must resolve to the canonical default-branch backlog; branch-local backlog drift is unsupported.
• tasks-create only writes to the canonical default-branch backlog on main or master; if the write target is branch-local, it should refuse.
• tasks-create should model multi-task work as a DAG, identify parallel lanes and the critical path, and add dependencies only when a real blocker or prerequisite exists.
• tasks-do must read the task first, work only the named scope, move active work to In Progress, automatically continue task-to-task in continuous mode without asking for approval between ready tasks, run ready independent work in parallel when safe, pause on blockers or explicit stop requests, and always update the backlog task after done or pause.
• tasks-do acts as the foreman: subagents may implement lanes, but Brokkr keeps ownership of coordination, verification, synthesis, and backlog updates.
• Never invent task IDs or dependency IDs.
• Use real dependencies to encode execution order for multi-task plans.

Repo-Specific Backlog Statuses

This repo uses exactly:

• Backlog
• To Do
• In Progress
• Done

Rules:

• do not invent Blocked or Cancelled
• keep blockers in task notes while leaving the real status intact
• archive invalid, duplicate, superseded, or abandoned tasks instead of marking them Done

Save and Cleanup Rules

• small is the subagent for small edits and git operations.
• Push only when explicitly requested unless you are intentionally running the save-work workflow.
• Use save-work for the end-of-session save, push, PR, and merge flow.
• Use prune-worktrees for safe cleanup, and run it from the main worktree context rather than a secondary worktree.
• Never force-push as part of the normal workflow.

Repo Layout

~/.config/opencode/
├── .mcp-secrets.env
├── agents/
├── biome.json
├── dcp.jsonc
├── opentmux.json
├── skills/
├── opencode.jsonc
├── opencode.example.jsonc
├── opc.sh
├── opc-up.sh
├── themes/
├── tui.json
└── README.md

Recommended Flow

1. Start in the repo you want to work in.
2. Run opc.
3. If you are on the default branch, create or switch to a trunk/* worktree when prompted.
4. Use Mimir or tasks-create for planning.
5. Use Brokkr for implementation orchestration.
6. Use tasks-do for an existing backlog item.
7. Use save-work to finish cleanly.
8. Use prune-worktrees later from the main worktree when merged branches are safe to remove.