oh-my-opencode-configuration

name: oh-my-opencode-configuration description: Comprehensive configuration guide for oh-my-opencode including agent settings, MCP servers, hooks, categories, and advanced options domain: integrations tags:

• ai-agent
• api
• configuration
• integrations
• opencode
• third-party

Oh My OpenCode Configuration

Overview

This skill provides detailed guidance on configuring oh-my-opencode, covering all configuration options for agents, MCP servers, hooks, categories, and advanced settings.

When to Use

• Configure new projects – Set up project-level configuration in .opencode/oh-my-opencode.jsonc
• Configure user-wide settings – Set up user-level configuration in ~/.config/opencode/oh-my-opencode.jsonc ( lower priority)
• Customize agents – Override default models, temperatures, and permissions for Sisyphus, Hephaestus, Oracle, Librarian, Explore
• Add MCP servers – Configure external tools like websearch, context7, grep_app, playwright, git-master
• Set up hooks – Configure workflow triggers (PreToolUse, PostToolUse, UserPromptSubmit, Stop)
• Customize categories – Create domain-specific task categories (visual, business-logic, etc.)
• Fine-tune performance – Adjust concurrency limits, agent timeouts, verification settings
• Apply themes and keybinds – Customize UI appearance and keyboard shortcuts

Configuration Structure

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Config File Locations

Config Format

oh-my-opencode uses JSONC (JSON with Comments):

{
  // This is a comment
  "agents": { ... },
  "features": { ... },
  "mcp": { ... }
}

Agent Configuration

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Sisyphus Configuration

{
  "agents": {
    "sisyphus": {
      "model": "openai/gpt-4o",
      "temperature": 0.7,
      "maxTokens": 8192,
      "enabled": true,
      "prompt": "You are Sisyphus, an autonomous agent...",
      "permissions": {
        "fileSystem": "restricted",
        "network": true,
        "shell": true
      }
    }
  }
}

Hephaestus Configuration

{
  "agents": {
    "hephaestus": {
      "model": "openai/gpt-4o",
      "temperature": 0.3,
      "maxTokens": 8192,
      "enabled": true,
      "exploreBeforeActing": {
        "parallelAgents": 3,
        "timeout": 60000
      },
      "verification": {
        "lsp": true,
        "tests": true,
        "build": true
      }
    }
  }
}

Oracle Configuration

{
  "agents": {
    "oracle": {
      "model": "anthropic/claude-3-5-sonnet-20241022",
      "temperature": 0.1,
      "maxTokens": 4096,
      "enabled": true,
      "consultationLimit": 3
    }
  }
}

Librarian Configuration

{
  "agents": {
    "librarian": {
      "model": "glm-4",
      "temperature": 0.5,
      "maxTokens": 4096,
      "enabled": true,
      "sources": [
        "official-docs",
        "github",
        "stackoverflow"
      ],
      "search": {
        "maxResults": 5,
        "timeout": 30000
      }
    }
  }
}

Explore Configuration

{
  "agents": {
    "explore": {
      "model": "grok-code-fast",
      "temperature": 0.3,
      "maxTokens": 2048,
      "enabled": true,
      "search": {
        "maxFiles": 20,
        "timeout": 10000
      }
    }
  }
}

Feature Configuration

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Parallel Agents

{
  "features": {
    "parallelAgents": {
      "enabled": true,
      "maxConcurrent": 5,
      "timeout": 120000,
      "failStrategy": "continue"
    }
  }
}

Background Tasks

{
  "features": {
    "backgroundTasks": {
      "enabled": true,
      "maxConcurrent": 3,
      "timeout": 600000,
      "persistence": true
    }
  }
}

Todo Enforcement

{
  "features": {
    "todoEnforcement": {
      "enabled": true,
      "strict": true,
      "autoContinue": true,
      "reminderInterval": 300000
    }
  }
}

Hash-Anchored Editing

{
  "features": {
    "hashAnchoredEdit": {
      "enabled": true,
      "validation": true,
      "autoCorrect": false
    }
  }
}

Comment Checker

{
  "features": {
    "commentChecker": {
      "enabled": true,
      "strictness": "moderate",
      "allowedPatterns": [
        "TODO",
        "FIXME",
        "HACK",
        "NOTE"
      ]
    }
  }
}

MCP Server Configuration

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Built-in MCPs

{
  "mcp": {
    "servers": {
      "websearch": {
        "enabled": true,
        "provider": "exa",
        "apiKey": "${EXA_API_KEY}"
      },
      "context7": {
        "enabled": true,
        "cacheSize": 1000,
        "ttl": 3600
      },
      "grep_app": {
        "enabled": true,
        "timeout": 30000
      }
    }
  }
}

Custom MCPs

{
  "mcp": {
    "servers": {
      "custom-server": {
        "command": "python",
        "args": ["-m", "custom_mcp"],
        "env": {
          "CUSTOM_VAR": "value"
        },
        "enabled": true
      }
    }
  }
}

MCP Groups

{
  "mcp": {
    "groups": {
      "development": ["websearch", "context7", "grep_app"],
      "research": ["websearch", "context7"],
      "minimal": []
    }
  }
}

Category Configuration

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Built-in Categories

{
  "categories": {
    "visual-engineering": {
      "model": "openai/gpt-4o",
      "temperature": 0.7,
      "defaultSkills": ["frontend-ui-ux"]
    },
    "ultrabrain": {
      "model": "anthropic/claude-3-5-sonnet-20241022",
      "temperature": 0.1,
      "defaultSkills": []
    },
    "deep": {
      "model": "openai/gpt-4o",
      "temperature": 0.3,
      "defaultSkills": []
    }
  }
}

Custom Categories

{
  "categories": {
    "backend-api": {
      "model": "openai/gpt-4o",
      "temperature": 0.3,
      "defaultSkills": ["git-master", "playwright"],
      "agents": ["hephaestus"]
    },
    "data-processing": {
      "model": "anthropic/claude-3-5-sonnet-20241022",
      "temperature": 0.2,
      "defaultSkills": [],
      "agents": ["oracle"]
    }
  }
}

Hook Configuration

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Available Hooks

{
  "hooks": {
    "PreToolUse": {
      "enabled": true,
      "handlers": ["logging", "validation"]
    },
    "PostToolUse": {
      "enabled": true,
      "handlers": ["logging", "verification"]
    },
    "UserPromptSubmit": {
      "enabled": true,
      "handlers": ["context-injection"]
    },
    "Stop": {
      "enabled": true,
      "handlers": ["cleanup"]
    }
  }
}

Custom Hooks

{
  "hooks": {
    "PreToolUse": {
      "enabled": true,
      "custom": {
        "my-hook": {
          "script": "./hooks/pre-tool-use.js",
          "timeout": 5000
        }
      }
    }
  }
}

Disabled Hooks

{
  "hooks": {
    "disabled_hooks": [
      "comment-checker",
      "verbose-logging"
    ]
  }
}

LSP Configuration

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Built-in LSP Tools

{
  "lsp": {
    "enabled": true,
    "tools": {
      "diagnostics": true,
      "definition": true,
      "references": true,
      "rename": true,
      "symbols": true
    }
  }
}

Custom LSP Servers

{
  "lsp": {
    "servers": {
      "typescript": {
        "command": "typescript-language-server",
        "args": ["--stdio"],
        "enabled": true
      },
      "python": {
        "command": "pylsp",
        "args": ["--sp-settings", "{\"pylsp\":{\"plugins\":{\"pycodestyle\":{\"enabled\":false}}}"],
        "enabled": true
      }
    }
  }
}

Permission Configuration

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Agent Permissions

{
  "permissions": {
    "agents": {
      "sisyphus": {
        "fileSystem": {
          "allowed": ["src/**/*", "tests/**/*"],
          "denied": [".env", "secrets/**/*"]
        },
        "network": {
          "allowed": true,
          "domains": ["api.github.com"]
        },
        "shell": {
          "allowed": true,
          "commands": ["git", "npm", "docker"]
        }
      }
    }
  }
}

Global Permissions

{
  "permissions": {
    "global": {
      "fileSystem": {
        "default": "read-only",
        "projectRoot": "read-write"
      },
      "network": {
        "default": false,
        "apiKeysRequired": true
      }
    }
  }
}

Theme and UI Configuration

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Theme

{
  "theme": {
    "name": "dark",
    "custom": {
      "primary": "#007AFF",
      "background": "#1E1E1E",
      "foreground": "#FFFFFF"
    }
  }
}

Keybinds

{
  "keybinds": {
    "ctrl+x": "quick-command",
    "ctrl+p": "command-palette",
    "ctrl+f": "find",
    "ctrl+r": "redo",
    "ctrl+z": "undo",
    "tab": "toggle-mode"
  }
}

Environment Configuration

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Environment Variables

{
  "environment": {
    "variables": {
      "OPENAI_API_KEY": "${OPENAI_API_KEY}",
      "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    },
    "passThrough": [
      "PATH",
      "HOME",
      "USER"
    ]
  }
}

Secrets Management

{
  "secrets": {
    "provider": "env-file",
    "files": [
      ".env",
      ".secrets"
    ],
    "required": [
      "OPENAI_API_KEY"
    ]
  }
}

Advanced Configuration

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Truncation

{
  "truncation": {
    "aggressive": {
      "enabled": false,
      "threshold": 0.8,
      "preserve": ["function-signatures", "class-definitions"]
    }
  }
}

Session Persistence

{
  "session": {
    "persistence": {
      "enabled": true,
      "storage": "file",
      "location": "~/.config/opencode/sessions",
      "maxSessions": 50
    },
    "continuity": {
      "enabled": true,
      "maxContextTokens": 100000
    }
  }
}

Experimental Features

{
  "experimental": {
    "autoResume": {
      "enabled": true,
      "maxRetries": 3
    },
    "agentMemory": {
      "enabled": false,
      "storage": "~/.config/opencode/memory"
    }
  }
}

Configuration Profiles

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Profile Structure

{
  "profiles": {
    "development": { ... },
    "production": { ... },
    "research": { ... }
  }
}

Profile Switching

# Via command
/profile development

# Via environment
export OMO_PROFILE=development

# Via CLI flag
opencode --profile development

Validation and Testing

This section covers validation and testing for the oh-my-opencode-configuration skill. Key operations include input validation, core processing, and output verification. Refer to the skill overview for detailed usage instructions.

Config Validation

# Validate config file
opencode config validate

# Check specific section
opencode config validate --section agents

# Lint config
opencode config lint

Test Configuration

# Test agent configuration
opencode config test-agents

# Test MCP servers
opencode config test-mcp

# Test hooks
opencode config test-hooks

Troubleshooting Configuration

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Common Issues

Config Not Loading

# Check file location
ls -la ~/.config/opencode/oh-my-opencode.jsonc

# Validate syntax
cat ~/.config/opencode/oh-my-opencode.jsonc | python3 -m json.tool

# Check permissions
chmod 600 ~/.config/opencode/oh-my-opencode.jsonc

Agent Not Responding

# Check agent configuration
opencode config show --section agents

# Verify model settings
opencode config test-model <model-name>

MCP Server Failing

# Test MCP connection
opencode mcp test <server-name>

# Check MCP logs
opencode logs --mcp

Quick Reference

The Process

1. Verify config location – Identify whether project-level (.opencode/) or user-level (~/.config/opencode/) config takes precedence
2. Read current config – Use opencode config get or read JSONC file directly
3. Make changes – Edit agent settings, MCP servers, hooks, or categories as needed
4. Validate syntax – JSONC must have valid comments and structure (no trailing commas)
5. Restart session – Reload OpenCode to apply config changes
6. Verify activation – Check config is loaded via opencode config get commands
7. Test agent behavior – Each configured agent should respond according to settings

When NOT to Use

• Task is outside your authorization scope
• You need to implement controls (use implementing-* skills)
• Task is about analysis, not action (use analyzing-* skills)
• You don't have access to target systems
• Task requires compliance expertise (consult professionals)
• Task is about defense, not offense (use defensive skills)

Red Flags

• Edit conflicts – Modifying config while OpenCode session is running (changes may not apply until restart)
• Invalid JSONC syntax – Trailing commas, unclosed strings, or malformed comments breaking config loading
• Overly broad permissions – Enabling full fileSystem/network/shell permissions when not needed
• Model mismatch – Assigning agent to model it's not designed for (e.g., oracle on gpt-4o instead of claude-3-5-sonnet)
• Hook duplication – Same hook firing multiple actions causing infinite loops
• Ignoring config hierarchy – Not understanding project-level overrides user-level settings
• Missing validation – Not verifying config with opencode config get after making changes

Verification

• Config loads: opencode config get returns values without errors
• Agent settings applied: Configured agents show correct models, temperatures, and permissions
• MCP servers active: Configured servers respond to commands and resource requests
• Hooks firing: Hook actions execute at expected times (PreToolUse, PostToolUse, etc.)
• Categories working: Domain-specific categories route tasks to correct agents
• No syntax errors: No JSONC parse errors in OpenCode logs
• Persistence verified: Config survives OpenCode restarts

References

• Configuration Docs: https://github.com/code-yeongyu/oh-my-opencode/blob/master/docs/configurations.md
• OpenCode Config: https://opencode.ai/docs/config/
• Agent-Model Matching: https://github.com/code-yeongyu/oh-my-opencode/blob/master/docs/guide/agent-model-matching.md

Related Skills

• oh-my-opencode: Overall integration
• oh-my-opencode-installation: Setup guide
• oh-my-opencode-agents: Agent usage
• oh-my-opencode-usage: Daily usage
• oh-my-opencode-features: Complete features list

Process

1. Analyze the task requirements
2. Apply domain expertise
3. Verify output quality