Advanced Configuration

Runtime Fallback

Auto-switches to backup models when API errors occur.

Basic Configuration

Enable with defaults:

{
  "runtime_fallback": true
}

Disable:

{
  "runtime_fallback": false
}

Full control over fallback behavior:

{
  "runtime_fallback": {
    "enabled": true,
    "retry_on_errors": [400, 429, 503, 529],
    "max_fallback_attempts": 3,
    "cooldown_seconds": 60,
    "timeout_seconds": 30,
    "notify_on_fallback": true
  }
}

Configuration Options

runtime_fallback.enabled

boolean

default:false

Enable runtime fallback system.

runtime_fallback.retry_on_errors

number[]

default:"[400, 429, 503, 529]"

HTTP status codes that trigger fallback. Also handles classified provider key errors.Common codes:

400 — Bad request / invalid key
429 — Rate limit exceeded
503 — Service unavailable
529 — Overloaded

runtime_fallback.max_fallback_attempts

number

default:3

Maximum fallback attempts per session (1–20).

"max_fallback_attempts": 5

runtime_fallback.cooldown_seconds

number

default:60

Seconds before retrying a failed model.

"cooldown_seconds": 120  // Wait 2 minutes

runtime_fallback.timeout_seconds

number

default:30

Seconds before forcing next fallback when provider hangs.Set to 0 to disable timeout-based escalation:

"timeout_seconds": 0  // Only error-based fallback

runtime_fallback.notify_on_fallback

boolean

default:true

Show toast notification on model switch.

"notify_on_fallback": false  // Silent fallback

Per-Agent Fallback Models

Define fallback models for specific agents:

{
  "runtime_fallback": true,
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "fallback_models": ["openai/gpt-5.2", "google/gemini-3-pro"]
    },
    "hephaestus": {
      "model": "openai/gpt-5.3-codex",
      "fallback_models": "github-copilot/gpt-5.2"  // Single fallback
    }
  }
}

Per-Category Fallback Models

Define fallback models for categories:

{
  "runtime_fallback": true,
  "categories": {
    "ultrabrain": {
      "model": "openai/gpt-5.3-codex",
      "fallback_models": ["anthropic/claude-opus-4-6", "google/gemini-3-pro"]
    },
    "quick": {
      "model": "anthropic/claude-haiku-4-5",
      "fallback_models": ["opencode/gpt-5-nano"]
    }
  }
}

Complete Example

{
  "runtime_fallback": {
    "enabled": true,
    "retry_on_errors": [400, 429, 503, 529],
    "max_fallback_attempts": 5,
    "cooldown_seconds": 90,
    "timeout_seconds": 45,
    "notify_on_fallback": true
  },
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "fallback_models": [
        "kimi-for-coding/k2p5",
        "openai/gpt-5.2",
        "google/gemini-3-pro"
      ]
    }
  }
}

Hashline Edit

Replaces the built-in Edit tool with a hash-anchored version using LINE#ID references to prevent stale-line edits.

hashline_edit

boolean

default:true

Enable hashline edit tool.Enabled by default:

{
  // hashline_edit is enabled by default
}

Disable:

{
  "hashline_edit": false
}

How It Works

Read tool annotates output with hash anchors:

1#a3f2  import { z } from "zod"
2#9b1e  import { config } from "./config"
3#7c4d  
4#2e8f  export function load() {

Edit tool uses anchors instead of line numbers:

oldString: "2#9b1e  import { config } from \"./config\""
newString: "import { loadConfig } from \"./config\""

Protection: Edit fails if anchor doesn’t match (file changed)

Companion Hooks

When enabled, two hooks activate:

hashline-read-enhancer — Annotates Read output
hashline-edit-diff-enhancer — Shows diffs

Disable individual hooks:

{
  "hashline_edit": true,
  "disabled_hooks": [
    "hashline-read-enhancer"  // Keep edit, remove read annotations
  ]
}

Background Tasks

Control parallel agent execution and concurrency limits.

{
  "background_task": {
    "defaultConcurrency": 5,
    "staleTimeoutMs": 180000,
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5,
      "google": 10,
      "opencode": 20,
      "zai-coding-plan": 10
    },
    "modelConcurrency": {
      "anthropic/claude-opus-4-6": 2,
      "opencode/gpt-5-nano": 50
    }
  }
}

Configuration Options

background_task.defaultConcurrency

number

Maximum concurrent tasks across all providers.

"defaultConcurrency": 10

background_task.staleTimeoutMs

number

default:180000

Interrupt tasks with no activity (minimum: 60000ms = 1 minute).

"staleTimeoutMs": 300000  // 5 minutes

background_task.providerConcurrency

object

Per-provider concurrency limits. Key = provider name.

"providerConcurrency": {
  "anthropic": 3,
  "openai": 5,
  "google": 10
}

background_task.modelConcurrency

object

Per-model concurrency limits. Key = provider/model. Overrides provider limits.

"modelConcurrency": {
  "anthropic/claude-opus-4-6": 2,
  "anthropic/claude-haiku-4-5": 10
}

Priority: modelConcurrency > providerConcurrency > defaultConcurrency

Experimental Features

Cutting-edge features that may change or be removed.

{
  "experimental": {
    "aggressive_truncation": false,
    "truncate_all_tool_outputs": false,
    "auto_resume": false,
    "disable_omo_env": false,
    "task_system": false,
    "hashline_edit": false,
    "model_fallback_title": false,
    "plugin_load_timeout_ms": 10000,
    "safe_hook_creation": true,
    "dynamic_context_pruning": {
      "enabled": false,
      "notification": "detailed",
      "turn_protection": { "enabled": true, "turns": 3 },
      "protected_tools": ["task", "todowrite", "todoread"],
      "strategies": {
        "deduplication": { "enabled": true },
        "supersede_writes": { "enabled": true, "aggressive": false },
        "purge_errors": { "enabled": true, "turns": 5 }
      }
    }
  }
}

Feature Flags

experimental.aggressive_truncation

boolean

default:false

Aggressively truncate when token limit exceeded.

experimental.truncate_all_tool_outputs

boolean

default:false

Truncate all tool outputs, not just whitelisted tools.

Tool output truncator is enabled by default. Disable via disabled_hooks.

experimental.auto_resume

boolean

default:false

Auto-resume after thinking block recovery.

experimental.disable_omo_env

boolean

default:false

Disable auto-injected <omo-env> block (date/time/locale). Improves cache hit rate.

experimental.task_system

boolean

default:false

Enable Sisyphus task system for cross-session tracking.

experimental.model_fallback_title

boolean

default:false

Append fallback model info to session title when runtime fallback occurs.

experimental.plugin_load_timeout_ms

number

default:10000

Timeout in ms for loadAllPluginComponents during config handler init (minimum: 1000).

"plugin_load_timeout_ms": 15000  // 15 seconds

experimental.safe_hook_creation

boolean

default:true

Wrap hook creation in try/catch to prevent plugin crashes.Disable for debugging:

"safe_hook_creation": false

Dynamic Context Pruning

Auto-prune old tool outputs to manage context window.

experimental.dynamic_context_pruning.enabled

boolean

default:false

Enable dynamic context pruning.

experimental.dynamic_context_pruning.notification

enum

default:"detailed"

Pruning notifications: off, minimal, detailed

experimental.dynamic_context_pruning.turn_protection

object

Protect recent turns from pruning.

"turn_protection": {
  "enabled": true,
  "turns": 3  // Protect last 3 turns (1-10)
}

experimental.dynamic_context_pruning.protected_tools

string[]

Tools whose outputs are never pruned.

"protected_tools": [
  "task",
  "todowrite",
  "todoread",
  "lsp_rename",
  "session_read",
  "session_write",
  "session_search"
]

experimental.dynamic_context_pruning.strategies

object

Pruning strategies.Deduplication:

"deduplication": { "enabled": true }

Supersede writes:

"supersede_writes": {
  "enabled": true,
  "aggressive": false  // Prune ANY write if subsequent read exists
}

Purge errors:

"purge_errors": {
  "enabled": true,
  "turns": 5  // Prune errored inputs after 5 turns
}

Sisyphus Task System

Enable cross-session task tracking:

{
  "sisyphus": {
    "tasks": {
      "enabled": false,
      "storage_path": ".sisyphus/tasks",
      "claude_code_compat": false
    }
  }
}

sisyphus.tasks.enabled

boolean

default:false

Enable Sisyphus Tasks system.

sisyphus.tasks.storage_path

string

default:".sisyphus/tasks"

Storage path relative to project root.

sisyphus.tasks.claude_code_compat

boolean

default:false

Enable Claude Code path compatibility mode.

Notification Settings

Force-enable session notifications:

{
  "notification": {
    "force_enable": true
  }
}

notification.force_enable

boolean

default:false

Force session-notification even if external notification plugins are detected.

Tmux Integration

Run background subagents in separate tmux panes.

Requires running inside tmux with opencode --port <port>.

{
  "tmux": {
    "enabled": true,
    "layout": "main-vertical",
    "main_pane_size": 60,
    "main_pane_min_width": 120,
    "agent_pane_min_width": 40
  }
}

tmux.enabled

boolean

default:false

Enable tmux pane spawning.

tmux.layout

enum

default:"main-vertical"

Tmux layout: main-vertical, main-horizontal, tiled, even-horizontal, even-vertical

tmux.main_pane_size

number

default:60

Main pane percentage (20–80).

tmux.main_pane_min_width

number

default:120

Minimum main pane columns.

tmux.agent_pane_min_width

number

default:40

Minimum agent pane columns.

Complete Advanced Example

{
  // Runtime fallback with aggressive settings
  "runtime_fallback": {
    "enabled": true,
    "retry_on_errors": [400, 429, 503, 529],
    "max_fallback_attempts": 5,
    "cooldown_seconds": 120,
    "timeout_seconds": 60,
    "notify_on_fallback": true
  },

  // Hashline edit enabled
  "hashline_edit": true,

  // Background task limits
  "background_task": {
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5,
      "opencode": 20
    },
    "modelConcurrency": {
      "anthropic/claude-opus-4-6": 2,
      "opencode/gpt-5-nano": 50
    }
  },

  // Experimental features
  "experimental": {
    "aggressive_truncation": true,
    "task_system": true,
    "disable_omo_env": false,
    "dynamic_context_pruning": {
      "enabled": true,
      "notification": "minimal",
      "turn_protection": { "enabled": true, "turns": 5 },
      "strategies": {
        "deduplication": { "enabled": true },
        "supersede_writes": { "enabled": true, "aggressive": false },
        "purge_errors": { "enabled": true, "turns": 3 }
      }
    }
  },

  // Sisyphus task tracking
  "sisyphus": {
    "tasks": {
      "enabled": true,
      "storage_path": ".sisyphus/tasks"
    }
  },

  // Tmux integration
  "tmux": {
    "enabled": false  // Requires tmux
  }
}

Get Started

Core Concepts

Guides

Configuration

Advanced Configuration

Runtime Fallback

Basic Configuration