docs: reorganize configuration.md for better readability
- Add Table of Contents with clear navigation structure - Reorganize sections into logical groups: - Getting Started (File Locations, Quick Start Example) - Core Concepts (Agents, Categories, Model Resolution) - Task System (Background Tasks, Sisyphus Agent, Sisyphus Tasks) - Features (Skills, Hooks, Commands, Integrations) - Advanced (Runtime Fallback, Hashline Edit, Experimental) - Reference (Environment Variables, Provider-Specific) - Improve section headers and descriptions - Add cross-references within document - Maintain all original content without omissions - Add clarifying comments to Quick Start Example
This commit is contained in:
YeonGyu-Kim
parent
5a3fddf03b
commit
0b4ebc3538
@ -1,6 +1,46 @@
|
||||
# Configuration Reference
|
||||
|
||||
## File Locations
|
||||
Complete reference for `oh-my-opencode.jsonc` configuration. This document covers every available option with examples.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Getting Started](#getting-started)
|
||||
- [File Locations](#file-locations)
|
||||
- [Quick Start Example](#quick-start-example)
|
||||
- [Core Concepts](#core-concepts)
|
||||
- [Agents](#agents)
|
||||
- [Categories](#categories)
|
||||
- [Model Resolution](#model-resolution)
|
||||
- [Task System](#task-system)
|
||||
- [Background Tasks](#background-tasks)
|
||||
- [Sisyphus Agent](#sisyphus-agent)
|
||||
- [Sisyphus Tasks](#sisyphus-tasks)
|
||||
- [Features](#features)
|
||||
- [Skills](#skills)
|
||||
- [Hooks](#hooks)
|
||||
- [Commands](#commands)
|
||||
- [Browser Automation](#browser-automation)
|
||||
- [Tmux Integration](#tmux-integration)
|
||||
- [Git Master](#git-master)
|
||||
- [Comment Checker](#comment-checker)
|
||||
- [Notification](#notification)
|
||||
- [MCPs](#mcps)
|
||||
- [LSP](#lsp)
|
||||
- [Advanced](#advanced)
|
||||
- [Runtime Fallback](#runtime-fallback)
|
||||
- [Hashline Edit](#hashline-edit)
|
||||
- [Experimental](#experimental)
|
||||
- [Reference](#reference)
|
||||
- [Environment Variables](#environment-variables)
|
||||
- [Provider-Specific](#provider-specific)
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### File Locations
|
||||
|
||||
Priority order (project overrides user):
|
||||
|
||||
@ -14,79 +54,64 @@ Priority order (project overrides user):
|
||||
|
||||
JSONC supports `// line comments`, `/* block comments */`, and trailing commas.
|
||||
|
||||
Schema autocomplete:
|
||||
Enable schema autocomplete:
|
||||
```json
|
||||
{ "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json" }
|
||||
```
|
||||
|
||||
Run `bunx oh-my-opencode install` for guided setup. Run `opencode models` to list available models.
|
||||
|
||||
## My Setup
|
||||
### Quick Start Example
|
||||
|
||||
Here's my personal `~/.config/opencode/oh-my-opencode.jsonc`. Adapt to your providers.
|
||||
Here's a practical starting configuration:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
|
||||
|
||||
"agents": {
|
||||
/*
|
||||
* Sisyphus: Main orchestrator.
|
||||
* Kimi K2.5 for daily driving; ultrawork escalates to Claude Opus.
|
||||
* Alternatives: anthropic/claude-opus-4-6, zai-coding-plan/glm-5
|
||||
*/
|
||||
// Main orchestrator: Claude Opus or Kimi K2.5 work best
|
||||
"sisyphus": {
|
||||
"model": "kimi-for-coding/k2p5",
|
||||
"ultrawork": { "model": "anthropic/claude-opus-4-6", "variant": "max" }
|
||||
},
|
||||
|
||||
/*
|
||||
* Librarian + Explore: parallel research/grep. Cheap models are fine.
|
||||
* Alternatives: opencode/gpt-5-nano, github-copilot/gpt-5, anthropic/claude-haiku-4-5
|
||||
*/
|
||||
// Research agents: cheaper models are fine
|
||||
"librarian": { "model": "zai-coding-plan/glm-4.7" },
|
||||
"explore": { "model": "github-copilot/grok-code-fast-1" },
|
||||
|
||||
/*
|
||||
* Oracle: architecture consultation + hard debugging.
|
||||
* Alternatives: anthropic/claude-opus-4-6, google/gemini-3-pro
|
||||
*/
|
||||
// Architecture consultation: GPT or Claude Opus
|
||||
"oracle": { "model": "openai/gpt-5.2", "variant": "high" },
|
||||
|
||||
// Prometheus inherits sisyphus model; just add prompt guidance.
|
||||
// Prometheus inherits sisyphus model; just add prompt guidance
|
||||
"prometheus": { "prompt_append": "Leverage deep & quick agents heavily, always in parallel." }
|
||||
},
|
||||
|
||||
"categories": {
|
||||
// quick — trivial tasks. Alternatives: anthropic/claude-haiku-4-5, google/gemini-3-flash
|
||||
// quick — trivial tasks
|
||||
"quick": { "model": "opencode/gpt-5-nano" },
|
||||
|
||||
// unspecified-low — moderate tasks. Alternatives: anthropic/claude-sonnet-4-6, openai/gpt-5
|
||||
// unspecified-low — moderate tasks
|
||||
"unspecified-low": { "model": "kimi-for-coding/k2p5" },
|
||||
|
||||
// unspecified-high — complex work. Alternatives: anthropic/claude-opus-4-6 (max), openai/gpt-5.3-codex
|
||||
// unspecified-high — complex work
|
||||
"unspecified-high": { "model": "anthropic/claude-sonnet-4-6", "variant": "max" },
|
||||
|
||||
// writing — docs/prose. Alternatives: anthropic/claude-sonnet-4-6, openai/gpt-5.2
|
||||
// writing — docs/prose
|
||||
"writing": { "model": "kimi-for-coding/k2p5" },
|
||||
|
||||
// git — custom category for git ops
|
||||
// visual-engineering — Gemini dominates visual tasks
|
||||
"visual-engineering": { "model": "google/gemini-3-pro", "variant": "high" },
|
||||
|
||||
// Custom category for git operations
|
||||
"git": {
|
||||
"model": "opencode/gpt-5-nano",
|
||||
"description": "All git operations",
|
||||
"prompt_append": "Focus on atomic commits, clear messages, and safe operations."
|
||||
},
|
||||
|
||||
// batch — custom category for spamming parallel low-stakes tasks
|
||||
"batch": {
|
||||
"model": "opencode/gpt-5-nano",
|
||||
"description": "Parallel batch processing. Needs very explicit prompts.",
|
||||
"prompt_append": "RESPOND CONCISELY. FOLLOW INSTRUCTIONS EXACTLY.",
|
||||
"is_unstable_agent": true
|
||||
}
|
||||
},
|
||||
|
||||
// Limit expensive providers; let cheap ones run freely.
|
||||
// Limit expensive providers; let cheap ones run freely
|
||||
"background_task": {
|
||||
"providerConcurrency": { "anthropic": 3, "openai": 3, "opencode": 10, "zai-coding-plan": 10 },
|
||||
"modelConcurrency": { "anthropic/claude-opus-4-6": 2, "opencode/gpt-5-nano": 20 }
|
||||
@ -97,9 +122,13 @@ Here's my personal `~/.config/opencode/oh-my-opencode.jsonc`. Adapt to your prov
|
||||
}
|
||||
```
|
||||
|
||||
## Agents
|
||||
---
|
||||
|
||||
Override built-in agent settings in `agents`:
|
||||
## Core Concepts
|
||||
|
||||
### Agents
|
||||
|
||||
Override built-in agent settings. Available agents: `sisyphus`, `hephaestus`, `prometheus`, `oracle`, `librarian`, `explore`, `multimodal-looker`, `metis`, `momus`, `atlas`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -110,14 +139,12 @@ Override built-in agent settings in `agents`:
|
||||
}
|
||||
```
|
||||
|
||||
Available agents: `sisyphus`, `hephaestus`, `prometheus`, `oracle`, `librarian`, `explore`, `multimodal-looker`, `metis`, `momus`, `atlas`
|
||||
Disable agents entirely: `{ "disabled_agents": ["oracle", "multimodal-looker"] }`
|
||||
|
||||
Disable via `disabled_agents`: `{ "disabled_agents": ["oracle", "multimodal-looker"] }`
|
||||
|
||||
### Agent Options
|
||||
#### Agent Options
|
||||
|
||||
| Option | Type | Description |
|
||||
| --- | --- | --- |
|
||||
|--------|------|-------------|
|
||||
| `model` | string | Model override (`provider/model`) |
|
||||
| `fallback_models` | string\|array | Fallback models on API errors |
|
||||
| `temperature` | number | Sampling temperature |
|
||||
@ -132,12 +159,12 @@ Disable via `disabled_agents`: `{ "disabled_agents": ["oracle", "multimodal-look
|
||||
| `category` | string | Inherit model from category |
|
||||
| `variant` | string | Model variant: `max`, `high`, `medium`, `low`, `xhigh` |
|
||||
| `maxTokens` | number | Max response tokens |
|
||||
| `thinking` | object | Anthropic extended thinking (see below) |
|
||||
| `thinking` | object | Anthropic extended thinking |
|
||||
| `reasoningEffort` | string | OpenAI reasoning: `low`, `medium`, `high`, `xhigh` |
|
||||
| `textVerbosity` | string | Text verbosity: `low`, `medium`, `high` |
|
||||
| `providerOptions` | object | Provider-specific options |
|
||||
|
||||
### Thinking (Anthropic)
|
||||
#### Anthropic Extended Thinking
|
||||
|
||||
```json
|
||||
{
|
||||
@ -147,7 +174,9 @@ Disable via `disabled_agents`: `{ "disabled_agents": ["oracle", "multimodal-look
|
||||
}
|
||||
```
|
||||
|
||||
### Permissions
|
||||
#### Agent Permissions
|
||||
|
||||
Control what tools an agent can use:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -164,21 +193,21 @@ Disable via `disabled_agents`: `{ "disabled_agents": ["oracle", "multimodal-look
|
||||
```
|
||||
|
||||
| Permission | Values |
|
||||
| --- | --- |
|
||||
|------------|--------|
|
||||
| `edit` | `ask` / `allow` / `deny` |
|
||||
| `bash` | `ask` / `allow` / `deny` or per-command: `{ "git": "allow", "rm": "deny" }` |
|
||||
| `webfetch` | `ask` / `allow` / `deny` |
|
||||
| `doom_loop` | `ask` / `allow` / `deny` |
|
||||
| `external_directory` | `ask` / `allow` / `deny` |
|
||||
|
||||
## Categories
|
||||
### Categories
|
||||
|
||||
Domain-specific model delegation used by the `task()` tool.
|
||||
Domain-specific model delegation used by the `task()` tool. When Sisyphus delegates work, it picks a category, not a model name.
|
||||
|
||||
### Built-in Categories
|
||||
#### Built-in Categories
|
||||
|
||||
| Category | Default Model | Description |
|
||||
| --- | --- | --- |
|
||||
|----------|---------------|-------------|
|
||||
| `visual-engineering` | `google/gemini-3-pro` (high) | Frontend, UI/UX, design, animation |
|
||||
| `ultrabrain` | `openai/gpt-5.3-codex` (xhigh) | Deep logical reasoning, complex architecture |
|
||||
| `deep` | `openai/gpt-5.3-codex` (medium) | Autonomous problem-solving, thorough research |
|
||||
@ -190,10 +219,10 @@ Domain-specific model delegation used by the `task()` tool.
|
||||
|
||||
> **Note**: Built-in defaults only apply if the category is present in your config. Otherwise the system default model is used.
|
||||
|
||||
### Category Options
|
||||
#### Category Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
|--------|------|---------|-------------|
|
||||
| `model` | string | - | Model override |
|
||||
| `fallback_models` | string\|array | - | Fallback models on API errors |
|
||||
| `temperature` | number | - | Sampling temperature |
|
||||
@ -208,20 +237,20 @@ Domain-specific model delegation used by the `task()` tool.
|
||||
| `description` | string | - | Shown in `task()` tool prompt |
|
||||
| `is_unstable_agent` | boolean | `false` | Force background mode + monitoring. Auto-enabled for Gemini models. |
|
||||
|
||||
Disable via `disabled_categories`: `{ "disabled_categories": ["ultrabrain"] }`
|
||||
Disable categories: `{ "disabled_categories": ["ultrabrain"] }`
|
||||
|
||||
## Model Resolution
|
||||
### Model Resolution
|
||||
|
||||
3-step priority at runtime:
|
||||
|
||||
1. **User override** — model set in `oh-my-opencode.json` → used exactly as-is
|
||||
2. **Provider fallback chain** — tries each provider in priority order until one is available
|
||||
1. **User override** — model set in config → used exactly as-is
|
||||
2. **Provider fallback chain** — tries each provider in priority order until available
|
||||
3. **System default** — falls back to OpenCode's configured default model
|
||||
|
||||
### Agent Provider Chains
|
||||
#### Agent Provider Chains
|
||||
|
||||
| Agent | Default Model | Provider Priority |
|
||||
| --- | --- | --- |
|
||||
|-------|---------------|-------------------|
|
||||
| **Sisyphus** | `claude-opus-4-6` | anthropic → github-copilot → opencode → kimi-for-coding → zai-coding-plan |
|
||||
| **Hephaestus** | `gpt-5.3-codex` | openai → github-copilot → opencode |
|
||||
| **oracle** | `gpt-5.2` | openai → google → anthropic (via github-copilot/opencode) |
|
||||
@ -233,10 +262,10 @@ Disable via `disabled_categories`: `{ "disabled_categories": ["ultrabrain"] }`
|
||||
| **Momus** | `gpt-5.2` | openai → anthropic → google (via github-copilot/opencode) |
|
||||
| **Atlas** | `k2p5` | kimi-for-coding → opencode → anthropic → openai → google |
|
||||
|
||||
### Category Provider Chains
|
||||
#### Category Provider Chains
|
||||
|
||||
| Category | Default Model | Provider Priority |
|
||||
| --- | --- | --- |
|
||||
|----------|---------------|-------------------|
|
||||
| **visual-engineering** | `gemini-3-pro` | google → zai-coding-plan → anthropic → kimi-for-coding |
|
||||
| **ultrabrain** | `gpt-5.3-codex` | openai → google → anthropic (via github-copilot/opencode) |
|
||||
| **deep** | `gpt-5.3-codex` | openai → anthropic → google (via github-copilot/opencode) |
|
||||
@ -248,13 +277,93 @@ Disable via `disabled_categories`: `{ "disabled_categories": ["ultrabrain"] }`
|
||||
|
||||
Run `bunx oh-my-opencode doctor --verbose` to see effective model resolution for your config.
|
||||
|
||||
## Skills
|
||||
---
|
||||
|
||||
## Task System
|
||||
|
||||
### Background Tasks
|
||||
|
||||
Control parallel agent execution and concurrency limits.
|
||||
|
||||
```json
|
||||
{
|
||||
"background_task": {
|
||||
"defaultConcurrency": 5,
|
||||
"staleTimeoutMs": 180000,
|
||||
"providerConcurrency": { "anthropic": 3, "openai": 5, "google": 10 },
|
||||
"modelConcurrency": { "anthropic/claude-opus-4-6": 2 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `defaultConcurrency` | - | Max concurrent tasks (all providers) |
|
||||
| `staleTimeoutMs` | `180000` | Interrupt tasks with no activity (min: 60000) |
|
||||
| `providerConcurrency` | - | Per-provider limits (key = provider name) |
|
||||
| `modelConcurrency` | - | Per-model limits (key = `provider/model`). Overrides provider limits. |
|
||||
|
||||
Priority: `modelConcurrency` > `providerConcurrency` > `defaultConcurrency`
|
||||
|
||||
### Sisyphus Agent
|
||||
|
||||
Configure the main orchestration system.
|
||||
|
||||
```json
|
||||
{
|
||||
"sisyphus_agent": {
|
||||
"disabled": false,
|
||||
"default_builder_enabled": false,
|
||||
"planner_enabled": true,
|
||||
"replace_plan": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `disabled` | `false` | Disable all Sisyphus orchestration, restore original build/plan |
|
||||
| `default_builder_enabled` | `false` | Enable OpenCode-Builder agent (off by default) |
|
||||
| `planner_enabled` | `true` | Enable Prometheus (Planner) agent |
|
||||
| `replace_plan` | `true` | Demote default plan agent to subagent mode |
|
||||
|
||||
Sisyphus agents can also be customized under `agents` using their names: `Sisyphus`, `OpenCode-Builder`, `Prometheus (Planner)`, `Metis (Plan Consultant)`.
|
||||
|
||||
### Sisyphus Tasks
|
||||
|
||||
Enable the Sisyphus Tasks system for cross-session task tracking.
|
||||
|
||||
```json
|
||||
{
|
||||
"sisyphus": {
|
||||
"tasks": {
|
||||
"enabled": false,
|
||||
"storage_path": ".sisyphus/tasks",
|
||||
"claude_code_compat": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `enabled` | `false` | Enable Sisyphus Tasks system |
|
||||
| `storage_path` | `.sisyphus/tasks` | Storage path (relative to project root) |
|
||||
| `claude_code_compat` | `false` | Enable Claude Code path compatibility mode |
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### Skills
|
||||
|
||||
Skills bring domain-specific expertise and embedded MCPs.
|
||||
|
||||
Built-in skills: `playwright` (default), `agent-browser`, `git-master`
|
||||
|
||||
Disable built-in skills via `disabled_skills`: `{ "disabled_skills": ["playwright"] }`
|
||||
Disable built-in skills: `{ "disabled_skills": ["playwright"] }`
|
||||
|
||||
### Skills Config
|
||||
#### Skills Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
@ -283,56 +392,140 @@ Disable built-in skills via `disabled_skills`: `{ "disabled_skills": ["playwrigh
|
||||
```
|
||||
|
||||
| `sources` option | Default | Description |
|
||||
| --- | --- | --- |
|
||||
|------------------|---------|-------------|
|
||||
| `path` | - | Local path or remote URL |
|
||||
| `recursive` | `false` | Recurse into subdirectories |
|
||||
| `glob` | - | Glob pattern for file selection |
|
||||
|
||||
## Sisyphus Agent
|
||||
### Hooks
|
||||
|
||||
| Option | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `disabled` | `false` | Disable all Sisyphus orchestration, restore original build/plan |
|
||||
| `default_builder_enabled` | `false` | Enable OpenCode-Builder agent (off by default) |
|
||||
| `planner_enabled` | `true` | Enable Prometheus (Planner) agent |
|
||||
| `replace_plan` | `true` | Demote default plan agent to subagent mode |
|
||||
Disable built-in hooks via `disabled_hooks`:
|
||||
|
||||
```json
|
||||
{
|
||||
"sisyphus_agent": {
|
||||
"disabled": false,
|
||||
"default_builder_enabled": false,
|
||||
"planner_enabled": true,
|
||||
"replace_plan": true
|
||||
}
|
||||
}
|
||||
{ "disabled_hooks": ["comment-checker", "agent-usage-reminder"] }
|
||||
```
|
||||
|
||||
Sisyphus agents can also be customized under `agents` using their names: `Sisyphus`, `OpenCode-Builder`, `Prometheus (Planner)`, `Metis (Plan Consultant)`.
|
||||
Available hooks: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`, `auto-slash-command`, `sisyphus-junior-notepad`, `no-sisyphus-gpt`, `start-work`, `runtime-fallback`
|
||||
|
||||
## Background Tasks
|
||||
**Notes:**
|
||||
- `directory-agents-injector` — auto-disabled on OpenCode 1.1.37+ (native AGENTS.md support)
|
||||
- `no-sisyphus-gpt` — **do not disable**. Sisyphus is not optimized for GPT; this hook switches to Hephaestus automatically.
|
||||
- `startup-toast` is a sub-feature of `auto-update-checker`. Disable just the toast by adding `startup-toast` to `disabled_hooks`.
|
||||
|
||||
### Commands
|
||||
|
||||
Disable built-in commands via `disabled_commands`:
|
||||
|
||||
```json
|
||||
{ "disabled_commands": ["init-deep", "start-work"] }
|
||||
```
|
||||
|
||||
Available commands: `init-deep`, `start-work`
|
||||
|
||||
### Browser Automation
|
||||
|
||||
| Provider | Interface | Installation |
|
||||
|----------|-----------|--------------|
|
||||
| `playwright` (default) | MCP tools | Auto-installed via npx |
|
||||
| `agent-browser` | Bash CLI | `bun add -g agent-browser && agent-browser install` |
|
||||
|
||||
Switch provider:
|
||||
|
||||
```json
|
||||
{ "browser_automation_engine": { "provider": "agent-browser" } }
|
||||
```
|
||||
|
||||
### Tmux Integration
|
||||
|
||||
Run background subagents in separate tmux panes. Requires running inside tmux with `opencode --port <port>`.
|
||||
|
||||
```json
|
||||
{
|
||||
"background_task": {
|
||||
"defaultConcurrency": 5,
|
||||
"staleTimeoutMs": 180000,
|
||||
"providerConcurrency": { "anthropic": 3, "openai": 5, "google": 10 },
|
||||
"modelConcurrency": { "anthropic/claude-opus-4-6": 2 }
|
||||
"tmux": {
|
||||
"enabled": true,
|
||||
"layout": "main-vertical",
|
||||
"main_pane_size": 60,
|
||||
"main_pane_min_width": 120,
|
||||
"agent_pane_min_width": 40
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `defaultConcurrency` | - | Max concurrent tasks (all providers) |
|
||||
| `staleTimeoutMs` | `180000` | Interrupt tasks with no activity (min: 60000) |
|
||||
| `providerConcurrency` | - | Per-provider limits (key = provider name) |
|
||||
| `modelConcurrency` | - | Per-model limits (key = `provider/model`). Overrides provider limits. |
|
||||
|--------|---------|-------------|
|
||||
| `enabled` | `false` | Enable tmux pane spawning |
|
||||
| `layout` | `main-vertical` | `main-vertical` / `main-horizontal` / `tiled` / `even-horizontal` / `even-vertical` |
|
||||
| `main_pane_size` | `60` | Main pane % (20–80) |
|
||||
| `main_pane_min_width` | `120` | Min main pane columns |
|
||||
| `agent_pane_min_width` | `40` | Min agent pane columns |
|
||||
|
||||
Priority: `modelConcurrency` > `providerConcurrency` > `defaultConcurrency`
|
||||
### Git Master
|
||||
|
||||
## Runtime Fallback
|
||||
Configure git commit behavior:
|
||||
|
||||
```json
|
||||
{ "git_master": { "commit_footer": true, "include_co_authored_by": true } }
|
||||
```
|
||||
|
||||
### Comment Checker
|
||||
|
||||
Customize the comment quality checker:
|
||||
|
||||
```json
|
||||
{ "comment_checker": { "custom_prompt": "Your message. Use {{comments}} placeholder." } }
|
||||
```
|
||||
|
||||
### Notification
|
||||
|
||||
Force-enable session notifications:
|
||||
|
||||
```json
|
||||
{ "notification": { "force_enable": true } }
|
||||
```
|
||||
|
||||
`force_enable` (`false`) — force session-notification even if external notification plugins are detected.
|
||||
|
||||
### MCPs
|
||||
|
||||
Built-in MCPs (enabled by default): `websearch` (Exa AI), `context7` (library docs), `grep_app` (GitHub code search).
|
||||
|
||||
```json
|
||||
{ "disabled_mcps": ["websearch", "context7", "grep_app"] }
|
||||
```
|
||||
|
||||
### LSP
|
||||
|
||||
Configure Language Server Protocol integration:
|
||||
|
||||
```json
|
||||
{
|
||||
"lsp": {
|
||||
"typescript-language-server": {
|
||||
"command": ["typescript-language-server", "--stdio"],
|
||||
"extensions": [".ts", ".tsx"],
|
||||
"priority": 10,
|
||||
"env": { "NODE_OPTIONS": "--max-old-space-size=4096" },
|
||||
"initialization": { "preferences": { "includeInlayParameterNameHints": "all" } }
|
||||
},
|
||||
"pylsp": { "disabled": true }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Option | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `command` | array | Command to start LSP server |
|
||||
| `extensions` | array | File extensions (e.g. `[".ts"]`) |
|
||||
| `priority` | number | Priority when multiple servers match |
|
||||
| `env` | object | Environment variables |
|
||||
| `initialization` | object | Init options passed to server |
|
||||
| `disabled` | boolean | Disable this server |
|
||||
|
||||
---
|
||||
|
||||
## Advanced
|
||||
|
||||
### Runtime Fallback
|
||||
|
||||
Auto-switches to backup models on API errors.
|
||||
|
||||
@ -350,7 +543,7 @@ Auto-switches to backup models on API errors.
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
| --- | --- | --- |
|
||||
|--------|---------|-------------|
|
||||
| `enabled` | `true` | Enable runtime fallback |
|
||||
| `retry_on_errors` | `[400,429,503,529]` | HTTP codes that trigger fallback. Also handles classified provider key errors. |
|
||||
| `max_fallback_attempts` | `3` | Max fallback attempts per session (1–20) |
|
||||
@ -371,22 +564,7 @@ Define `fallback_models` per agent or category:
|
||||
}
|
||||
```
|
||||
|
||||
## Hooks
|
||||
|
||||
Disable built-in hooks via `disabled_hooks`:
|
||||
|
||||
```json
|
||||
{ "disabled_hooks": ["comment-checker", "agent-usage-reminder"] }
|
||||
```
|
||||
|
||||
Available hooks: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `tool-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `anthropic-context-window-limit-recovery`, `rules-injector`, `background-notification`, `auto-update-checker`, `startup-toast`, `keyword-detector`, `agent-usage-reminder`, `non-interactive-env`, `interactive-bash-session`, `compaction-context-injector`, `thinking-block-validator`, `claude-code-hooks`, `ralph-loop`, `preemptive-compaction`, `auto-slash-command`, `sisyphus-junior-notepad`, `no-sisyphus-gpt`, `start-work`, `runtime-fallback`
|
||||
|
||||
**Notes:**
|
||||
- `directory-agents-injector` — auto-disabled on OpenCode 1.1.37+ (native AGENTS.md support)
|
||||
- `no-sisyphus-gpt` — **do not disable**. Sisyphus is not optimized for GPT; this hook switches to Hephaestus automatically.
|
||||
- `startup-toast` is a sub-feature of `auto-update-checker`. Disable just the toast by adding `startup-toast` to `disabled_hooks`.
|
||||
|
||||
## Hashline Edit
|
||||
### Hashline Edit
|
||||
|
||||
Replaces the built-in `Edit` tool with a hash-anchored version using `LINE#ID` references to prevent stale-line edits. Enabled by default.
|
||||
|
||||
@ -396,110 +574,7 @@ Replaces the built-in `Edit` tool with a hash-anchored version using `LINE#ID` r
|
||||
|
||||
When enabled, two companion hooks are active: `hashline-read-enhancer` (annotates Read output) and `hashline-edit-diff-enhancer` (shows diffs). Disable them individually via `disabled_hooks`.
|
||||
|
||||
## Commands
|
||||
|
||||
Disable built-in commands via `disabled_commands`:
|
||||
|
||||
```json
|
||||
{ "disabled_commands": ["init-deep", "start-work"] }
|
||||
```
|
||||
|
||||
Available commands: `init-deep`, `start-work`
|
||||
|
||||
## Tools & Integrations
|
||||
|
||||
### Browser Automation
|
||||
|
||||
| Provider | Interface | Installation |
|
||||
| --- | --- | --- |
|
||||
| `playwright` (default) | MCP tools | Auto-installed via npx |
|
||||
| `agent-browser` | Bash CLI | `bun add -g agent-browser && agent-browser install` |
|
||||
|
||||
Switch provider:
|
||||
|
||||
```json
|
||||
{ "browser_automation_engine": { "provider": "agent-browser" } }
|
||||
```
|
||||
|
||||
### Tmux
|
||||
|
||||
Run background subagents in separate tmux panes. Requires running inside tmux with `opencode --port <port>`.
|
||||
|
||||
```json
|
||||
{
|
||||
"tmux": {
|
||||
"enabled": true,
|
||||
"layout": "main-vertical",
|
||||
"main_pane_size": 60,
|
||||
"main_pane_min_width": 120,
|
||||
"agent_pane_min_width": 40
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `enabled` | `false` | Enable tmux pane spawning |
|
||||
| `layout` | `main-vertical` | `main-vertical` / `main-horizontal` / `tiled` / `even-horizontal` / `even-vertical` |
|
||||
| `main_pane_size` | `60` | Main pane % (20–80) |
|
||||
| `main_pane_min_width` | `120` | Min main pane columns |
|
||||
| `agent_pane_min_width` | `40` | Min agent pane columns |
|
||||
|
||||
### Git Master
|
||||
|
||||
```json
|
||||
{ "git_master": { "commit_footer": true, "include_co_authored_by": true } }
|
||||
```
|
||||
|
||||
### Comment Checker
|
||||
|
||||
```json
|
||||
{ "comment_checker": { "custom_prompt": "Your message. Use {{comments}} placeholder." } }
|
||||
```
|
||||
|
||||
### Notification
|
||||
|
||||
```json
|
||||
{ "notification": { "force_enable": true } }
|
||||
```
|
||||
|
||||
`force_enable` (`false`) — force session-notification even if external notification plugins are detected.
|
||||
|
||||
### MCPs
|
||||
|
||||
Built-in MCPs (enabled by default): `websearch` (Exa AI), `context7` (library docs), `grep_app` (GitHub code search).
|
||||
|
||||
```json
|
||||
{ "disabled_mcps": ["websearch", "context7", "grep_app"] }
|
||||
```
|
||||
|
||||
### LSP
|
||||
|
||||
```json
|
||||
{
|
||||
"lsp": {
|
||||
"typescript-language-server": {
|
||||
"command": ["typescript-language-server", "--stdio"],
|
||||
"extensions": [".ts", ".tsx"],
|
||||
"priority": 10,
|
||||
"env": { "NODE_OPTIONS": "--max-old-space-size=4096" },
|
||||
"initialization": { "preferences": { "includeInlayParameterNameHints": "all" } }
|
||||
},
|
||||
"pylsp": { "disabled": true }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Option | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `command` | array | Command to start LSP server |
|
||||
| `extensions` | array | File extensions (e.g. `[".ts"]`) |
|
||||
| `priority` | number | Priority when multiple servers match |
|
||||
| `env` | object | Environment variables |
|
||||
| `initialization` | object | Init options passed to server |
|
||||
| `disabled` | boolean | Disable this server |
|
||||
|
||||
## Experimental
|
||||
### Experimental
|
||||
|
||||
```json
|
||||
{
|
||||
@ -525,7 +600,7 @@ Built-in MCPs (enabled by default): `websearch` (Exa AI), `context7` (library do
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
| --- | --- | --- |
|
||||
|--------|---------|-------------|
|
||||
| `truncate_all_tool_outputs` | `false` | Truncate all tool outputs (not just whitelisted) |
|
||||
| `aggressive_truncation` | `false` | Aggressively truncate when token limit exceeded |
|
||||
| `auto_resume` | `false` | Auto-resume after thinking block recovery |
|
||||
@ -539,19 +614,23 @@ Built-in MCPs (enabled by default): `websearch` (Exa AI), `context7` (library do
|
||||
| `strategies.supersede_writes.aggressive` | `false` | Prune any write if ANY subsequent read exists |
|
||||
| `strategies.purge_errors.turns` | `5` | Turns before pruning errored tool inputs |
|
||||
|
||||
## Environment Variables
|
||||
---
|
||||
|
||||
## Reference
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
| --- | --- |
|
||||
|----------|-------------|
|
||||
| `OPENCODE_CONFIG_DIR` | Override OpenCode config directory (useful for profile isolation) |
|
||||
|
||||
## Provider-Specific
|
||||
### Provider-Specific
|
||||
|
||||
### Google Auth
|
||||
#### Google Auth
|
||||
|
||||
Install [`opencode-antigravity-auth`](https://github.com/NoeFabris/opencode-antigravity-auth) for Google Gemini. Provides multi-account load balancing, dual quota, and variant-based thinking.
|
||||
|
||||
### Ollama
|
||||
#### Ollama
|
||||
|
||||
**Must** disable streaming to avoid JSON parse errors:
|
||||
|
||||
@ -566,23 +645,3 @@ Install [`opencode-antigravity-auth`](https://github.com/NoeFabris/opencode-anti
|
||||
Common models: `ollama/qwen3-coder`, `ollama/ministral-3:14b`, `ollama/lfm2.5-thinking`
|
||||
|
||||
See [Ollama Troubleshooting](../troubleshooting/ollama.md) for `JSON Parse error: Unexpected EOF` issues.
|
||||
|
||||
### Sisyphus Tasks
|
||||
|
||||
```json
|
||||
{
|
||||
"sisyphus": {
|
||||
"tasks": {
|
||||
"enabled": false,
|
||||
"storage_path": ".sisyphus/tasks",
|
||||
"claude_code_compat": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `enabled` | `false` | Enable Sisyphus Tasks system |
|
||||
| `storage_path` | `.sisyphus/tasks` | Storage path (relative to project root) |
|
||||
| `claude_code_compat` | `false` | Enable Claude Code path compatibility mode |
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user