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.5" },
      "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"`)

Runtime Preset Switching

Presets can also be switched at runtime without restarting using the /preset command. See Preset Switching for details.

`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
`autoUpdate`	boolean	`true`	Automatically install plugin updates in the background; set to `false` for notification-only mode
`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`
`sessionManager.maxSessionsPerAgent`	integer	`2`	Maximum remembered resumable child sessions per specialist type in the current orchestrator session (1–10). See Session Management
`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`	Treat silent empty provider responses (0 tokens) as failures and retry. Set `false` to accept empty responses
`council.presets`	object	—	Required if using council. Named councillor presets
`council.presets.<name>.<councillor>.model`	string	—	Councillor model
`council.presets.<name>.<councillor>.variant`	string	—	Councillor variant
`council.presets.<name>.<councillor>.prompt`	string	—	Optional role guidance for the councillor
`council.default_preset`	string	`"default"`	Default preset when none is specified
`council.timeout`	number	`180000`	Per-councillor timeout (ms)
`council.councillor_execution_mode`	string	`"parallel"`	Run councillors in `parallel` or `serial`; use `serial` for single-model setups
`council.councillor_retries`	number	`3`	Max retries per councillor on empty provider response (0–5)
`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

Council configuration note

The Council agent model is configured like any other agent, for example in presets.<name>.council.model.
The councillor models are configured separately under council.presets.<name>.<councillor>.model.
Deprecated council.master* fields should not be used in new configs.

Startup Toast

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

{
  "showStartupToast": false
}

Manual Update Mode

Set autoUpdate to false if you want update notifications without automatic bun install runs.

{
  "autoUpdate": false
}

With autoUpdate set to false, this becomes notification-only mode: you'll see that a new version is available, but the plugin won't install it automatically.

Pinned plugin entries in opencode.json (for example "oh-my-opencode-slim@1.0.1") are the true version lock. Those stay pinned regardless of autoUpdate.

Session Management

Session management is enabled by default and does not need to be present in the starter config. Add sessionManager only if you want to tune how many resumable child-agent sessions are remembered. See Session Management for the concept, defaults, and examples.

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.5",
      "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"
    }
  }
}