Configuration Reference

Complete reference for all configuration files and options in oh-my-opencode-slim.

Config Files

File	Purpose
`~/.config/opencode/opencode.json`	OpenCode core settings (plugin registration, providers)
`~/.config/opencode/oh-my-opencode-slim.json`	Plugin settings — agents, multiplexer, MCPs, council
`~/.config/opencode/oh-my-opencode-slim.jsonc`	Same, but with JSONC (comments + trailing commas). Takes precedence over `.json` if both exist
`.opencode/oh-my-opencode-slim.json`	Project-local overrides (optional, checked first)

💡 JSONC recommended: Use the .jsonc extension to add comments and trailing commas. If both .jsonc and .json exist, .jsonc takes precedence.

Prompt Overriding

Customize agent prompts without modifying source code. Create markdown files in ~/.config/opencode/oh-my-opencode-slim/:

File	Effect
`{agent}.md`	Replaces the agent's default prompt entirely
`{agent}_append.md`	Appends custom instructions to the default prompt

When a preset is active, the plugin checks ~/.config/opencode/oh-my-opencode-slim/{preset}/ first, then falls back to the root directory.

Example directory structure:

~/.config/opencode/oh-my-opencode-slim/
  ├── best/
  │   ├── orchestrator.md        # Preset-specific override (used when preset=best)
  │   └── explorer_append.md
  ├── orchestrator.md            # Fallback override
  ├── orchestrator_append.md
  ├── explorer.md
  └── ...

Both {agent}.md and {agent}_append.md can coexist — the full replacement takes effect first, then the append. If neither exists, the built-in default prompt is used.

JSONC Format

All config files support JSONC (JSON with Comments):

Single-line comments (//)
Multi-line comments (/* */)
Trailing commas in arrays and objects

Example:

{
  // Active preset
  "preset": "openai",

  /* Agent model mappings */
  "presets": {
    "openai": {
      "oracle": { "model": "openai/gpt-5.4" },
      "explorer": { "model": "openai/gpt-5.4-mini" },
    },
  },

  "multiplexer": {
    "type": "tmux",
    "layout": "main-vertical",
  },
}

Full Option Reference

Option	Type	Default	Description
`preset`	string	—	Active preset name (e.g. `"openai"`, `"best"`)
`presets`	object	—	Named preset configurations
`presets.<name>.<agent>.model`	string	—	Model ID in `provider/model` format
`presets.<name>.<agent>.temperature`	number	—	Temperature (0–2)
`presets.<name>.<agent>.variant`	string	—	Reasoning effort: `"low"`, `"medium"`, `"high"`
`presets.<name>.<agent>.displayName`	string	—	Custom user-facing alias for the agent (e.g. `"advisor"` for `oracle`)
`presets.<name>.<agent>.skills`	string[]	—	Skills the agent can use (`"*"`, `"!item"`, explicit list)
`presets.<name>.<agent>.mcps`	string[]	—	MCPs the agent can use (`"*"`, `"!item"`, explicit list)
`presets.<name>.<agent>.options`	object	—	Provider-specific model options passed to the AI SDK (e.g., `textVerbosity`, `thinking` budget)
`agents.<customAgent>.model`	string\|array	—	Required for custom agents inferred from unknown `agents` keys
`agents.<customAgent>.prompt`	string	—	Full execution prompt for a custom agent
`agents.<customAgent>.orchestratorPrompt`	string	—	Exact `@agent` block injected into the orchestrator prompt; must start with `@<agent-name>`
`agents.<agent>.displayName`	string	—	Custom user-facing alias for the agent in the active config
`showStartupToast`	boolean	`true`	Show the startup activation toast (`oh-my-opencode-slim is active`) when OpenCode starts
`multiplexer.type`	string	`"none"`	Multiplexer mode: `auto`, `tmux`, `zellij`, or `none`
`multiplexer.layout`	string	`"main-vertical"`	Layout preset: `main-vertical`, `main-horizontal`, `tiled`, `even-horizontal`, `even-vertical`
`multiplexer.main_pane_size`	number	`60`	Main pane size as percentage (20–80)
`tmux.enabled`	boolean	`false`	Legacy alias for `multiplexer.type = "tmux"`
`tmux.layout`	string	`"main-vertical"`	Legacy alias for `multiplexer.layout`
`tmux.main_pane_size`	number	`60`	Legacy alias for `multiplexer.main_pane_size`
`disabled_mcps`	string[]	`[]`	MCP server IDs to disable globally
`fallback.enabled`	boolean	`false`	Enable model failover on timeout/error
`fallback.timeoutMs`	number	`15000`	Time before aborting and trying next model
`fallback.retryDelayMs`	number	`500`	Delay between retry attempts
`fallback.chains.<agent>`	string[]	—	Ordered fallback model IDs for an agent
	`fallback.retry_on_empty`	boolean	`true`
	`council.presets`	object	—
	`council.presets.<name>.<councillor>.model`	string	—
	`council.presets.<name>.<councillor>.variant`	string	—
	`council.presets.<name>.<councillor>.prompt`	string	—
	`council.default_preset`	string	`"default"`
	`council.timeout`	number	`180000`
	`council.councillor_retries`	number	`3`
`todoContinuation.maxContinuations`	integer	`5`	Max consecutive auto-continuations before stopping (1–50)
`todoContinuation.cooldownMs`	integer	`3000`	Delay in ms before auto-continuing — gives user time to abort (0–30000)
`todoContinuation.autoEnable`	boolean	`false`	Automatically enable auto-continue when session has enough todos
`todoContinuation.autoEnableThreshold`	integer	`4`	Number of todos that triggers auto-enable (only used when `autoEnable` is true, 1–50)
`interview.maxQuestions`	integer	`2`	Max questions per interview round (1–10)
`interview.outputFolder`	string	`"interview"`	Directory where interview markdown files are written (relative to project root)
`interview.autoOpenBrowser`	boolean	`true`	Automatically open the interview UI in your default browser during interactive runs; suppressed in tests and CI
`interview.port`	integer	`0`	Interview server port (0–65535). `0` = OS-assigned random port (per-session mode). Any value > 0 enables dashboard mode
`interview.dashboard`	boolean	`false`	Enable dashboard mode on the default port (43211). Setting `port` > 0 also enables dashboard mode. If both are set, `port` takes precedence

Startup Toast

Set showStartupToast to false if you want to disable the startup toast that appears when the plugin activates.

{
  "showStartupToast": false
}

Agent Display Names

Use displayName to give an agent a user-facing alias while keeping the internal agent name unchanged.

{
  "agents": {
    "oracle": {
      "displayName": "advisor"
    },
    "explorer": {
      "displayName": "researcher"
    }
  }
}

With this config, users can refer to @advisor and @researcher, while the plugin still routes them to oracle and explorer internally.

Notes:

displayName works in both top-level agents overrides and inside presets
@ prefixes and surrounding whitespace are normalized automatically
Display names must be unique
Display names cannot conflict with internal agent names like oracle or explorer

Custom Agents

Unknown keys under agents are treated as custom subagents. A custom agent needs its own model, a normal prompt, and optionally an orchestratorPrompt that teaches the orchestrator exactly when to delegate to it.

{
  "agents": {
    "janitor": {
      "model": "github-copilot/gpt-5.4",
      "prompt": "You are Janitor. Audit codebase entropy, dead code, docs drift, naming inconsistencies, and unnecessary complexity. Prefer analysis and plans over direct edits.",
      "orchestratorPrompt": "@janitor\n- Role: Maintenance specialist for codebase cleanup and entropy reduction\n- **Delegate when:** after large refactors • cleanup/technical-debt review • dead code or docs drift is suspected\n- **Don't delegate when:** feature implementation • urgent debugging • UI/UX work"
    }
  }
}