Skip to content
Showcase Ecosystem Docs

Advanced Configuration

Advanced Configuration

This document introduces advanced configuration options for Oh My OpenCode, helping you customize it for specific needs.

Configuration File Locations and Priority

Configuration File Locations

Oh My OpenCode searches for configuration files in the following order:

1. .opencode/oh-my-opencode.json (project-level, highest priority)
2. ~/.config/opencode/oh-my-opencode.json (user-level, macOS/Linux)
3. %APPDATA%\opencode\oh-my-opencode.json (user-level, Windows)

Configuration Merge Rules

Multiple configuration files are merged by priority:

Project-level Configuration (.opencode/oh-my-opencode.json):

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2
  }
}

User-level Configuration (~/.config/opencode/oh-my-opencode.json):

{
  "sisyphus": {
    "max_concurrent_tasks": 3  // Overrides project-level setting
  },
  "agents": {
    "oracle": { "enabled": true }
  }
}

Final Effective Configuration:

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3  // From user-level
  },
  "agents": {
    "oracle": { "enabled": true }  // From user-level
  }
}

JSONC Support

Oh My OpenCode supports JSON with Comments (JSONC) format:

{
  // This is a comment
  "sisyphus": {
    "enabled": true,
    /* 
     * Multi-line comment
     * Adjust based on subscription plan
     */
    "max_concurrent_tasks": 3
  },
  
  // Agent configuration
  "agents": {
    "oracle": {
      "enabled": true,
      // "temperature": 0.7,  // Can comment out unused configs
    }
  }
}

Subscription Plan Configuration

Claude Max20 Complete Configuration

The most powerful configuration, suitable for intensive development work:

{
  "subscription": "claude-max20",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3,
    "task_timeout": 300,
    "auto_delegate": true,
    "delegation_strategy": "optimal"
  },
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.7,
      "max_tokens": 4096
    },
    "librarian": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.5
    },
    "frontend-engineer": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.6
    },
    "backend-engineer": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.6
    },
    "explore": {
      "enabled": true,
      "model": "claude-sonnet-3.5",
      "temperature": 0.3
    }
  },
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "javascript", "python", "go", "rust"]
  },
  "background_task": {
    "defaultConcurrency": 3,
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5
    }
  }
}

ChatGPT Plus/Pro Configuration

Balanced performance and cost:

{
  "subscription": "chatgpt-plus",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2,
    "delegation_strategy": "balanced"
  },
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "gpt-4-turbo"
    },
    "librarian": {
      "enabled": true,
      "model": "gpt-4-turbo"
    },
    "frontend-engineer": {
      "enabled": true,
      "model": "gpt-4"
    },
    "backend-engineer": {
      "enabled": false  // Save quota
    },
    "explore": {
      "enabled": true,
      "model": "gpt-4"
    }
  },
  "background_task": {
    "defaultConcurrency": 2,
    "providerConcurrency": {
      "openai": 2
    }
  }
}

Gemini Advanced Configuration

High value for money:

{
  "subscription": "gemini-advanced",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2
  },
  "agents": {
    "oracle": {
      "enabled": false  // Gemini slightly weaker at architecture design
    },
    "librarian": {
      "enabled": true,
      "model": "gemini-pro-1.5"
    },
    "frontend-engineer": {
      "enabled": true,
      "model": "gemini-pro-1.5"
    },
    "explore": {
      "enabled": true,
      "model": "gemini-pro-1.5"
    }
  }
}

Agent Customization

Complete Agent Configuration Options

{
  "agents": {
    "oracle": {
      // Basic configuration
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.7,
      "max_tokens": 4096,
      "top_p": 0.9,
      
      // Prompt customization
      "prompt_append": "Please provide detailed technical decision rationale and trade-off analysis",
      "system_prompt_override": "You are a senior architect...",
      
      // Behavior control
      "auto_retry": true,
      "max_retries": 3,
      "retry_delay": 2,
      
      // Tool permissions
      "tools": {
        "lsp": true,
        "ast_grep": true,
        "file_operations": true,
        "shell_commands": false  // Security consideration
      },
      
      // Resource limits
      "rate_limit": {
        "requests_per_minute": 20,
        "tokens_per_minute": 50000
      }
    }
  }
}

Custom Agent Prompts

Customize agent behavior for specific projects:

{
  "agents": {
    "frontend-engineer": {
      "enabled": true,
      "prompt_append": "You are our team's frontend engineer. Please follow these standards:\n\n1. Technology Stack:\n   - React 18+ with TypeScript\n   - Tailwind CSS for styling\n   - React Query for data fetching\n\n2. Code Style:\n   - Use function components and Hooks\n   - Props must define TypeScript interfaces\n   - Prefer composition over inheritance\n\n3. Accessibility:\n   - All interactive elements must be keyboard accessible\n   - Use semantic HTML\n   - Provide appropriate ARIA labels\n\n4. Performance:\n   - Use React.memo to optimize rendering\n   - Images must use lazy loading\n   - Avoid creating objects in render functions"
    }
  }
}

Permission Control Configuration

File Operation Permissions

{
  "permissions": {
    "file_operations": {
      "read": {
        "allow": ["src/**", "docs/**", "*.md"],
        "deny": [".env*", "*.key", "secrets/**"]
      },
      "write": {
        "allow": ["src/**", "docs/**"],
        "deny": ["package.json", "tsconfig.json"]  // Critical files require manual confirmation
      },
      "delete": {
        "require_confirmation": true,
        "allow": ["temp/**"],
        "deny": ["**"]  // Deny deletion by default
      }
    }
  }
}

Shell Command Permissions

{
  "permissions": {
    "shell_commands": {
      "enabled": true,
      "whitelist": [
        "npm test",
        "npm run lint",
        "git status",
        "git diff"
      ],
      "blacklist": [
        "rm -rf",
        "sudo",
        "curl *",  // Prevent data leaks
        "wget *"
      ],
      "require_confirmation_for": [
        "git push",
        "npm publish",
        "docker"
      ]
    }
  }
}

API Call Permissions

{
  "permissions": {
    "api_calls": {
      "allowed_domains": [
        "api.github.com",
        "registry.npmjs.org"
      ],
      "rate_limit": {
        "requests_per_minute": 60
      },
      "require_user_secrets": true  // API keys must be provided by user
    }
  }
}

Background Task Concurrency Control

Concurrency Strategy Configuration

{
  "background_task": {
    "defaultConcurrency": 5,
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5
    },
    
    // Priority configuration
    "priority_levels": {
      "high": {
        "max_concurrent": 2,
        "timeout": 600
      },
      "normal": {
        "max_concurrent": 2,
        "timeout": 300
      },
      "low": {
        "max_concurrent": 1,
        "timeout": 120
      }
    },
    
    // Resource allocation strategy
    "scheduling": {
      "strategy": "fair",  // fair, priority, round-robin
      "preemption": false,  // Allow high-priority tasks to preempt
      "queue_size": 10
    },
    
    // Failure handling
    "error_handling": {
      "retry_failed": true,
      "max_retries": 2,
      "fallback_to_sync": true  // Execute synchronously after failure
    }
  }
}

Task Type Configuration

{
  "task_types": {
    "analysis": {
      "can_run_in_background": true,
      "priority": "low",
      "timeout": 120
    },
    "code_generation": {
      "can_run_in_background": false,  // Code generation requires user confirmation
      "priority": "high"
    },
    "documentation": {
      "can_run_in_background": true,
      "priority": "low"
    },
    "testing": {
      "can_run_in_background": true,
      "priority": "normal"
    }
  }
}

Sisyphus Agent Configuration Options

Complete Sisyphus Configuration

{
  "sisyphus": {
    // Basic configuration
    "enabled": true,
    "max_concurrent_tasks": 3,
    "task_timeout": 300,
    
    // Delegation strategy
    "auto_delegate": true,
    "delegation_strategy": "optimal",  // optimal, balanced, sequential, parallel
    
    // Task decomposition
    "task_decomposition": {
      "enabled": true,
      "max_subtasks": 10,
      "min_subtask_complexity": 2
    },
    
    // Agent selection
    "agent_selection": {
      "strategy": "capability_match",  // capability_match, load_balance, random
      "consider_workload": true,
      "prefer_specialists": true
    },
    
    // Result aggregation
    "result_aggregation": {
      "strategy": "merge",  // merge, vote, best
      "conflict_resolution": "oracle_decides"
    },
    
    // Context management
    "context_sharing": {
      "enabled": true,
      "share_between_agents": true,
      "max_context_size": 8192
    }
  }
}

Hooks Integration Configuration

Lifecycle Hooks

{
  "hooks": {
    "pre_task": {
      "enabled": true,
      "script": ".opencode/hooks/pre-task.sh",
      "timeout": 30
    },
    "post_task": {
      "enabled": true,
      "script": ".opencode/hooks/post-task.sh"
    },
    "on_error": {
      "enabled": true,
      "script": ".opencode/hooks/error-handler.sh",
      "notify_user": true
    },
    "on_agent_switch": {
      "enabled": true,
      "script": ".opencode/hooks/agent-switch.sh"
    }
  }
}

Hook Script Example

#!/bin/bash
# .opencode/hooks/pre-task.sh

# Execute before task starts
echo "Starting task: $TASK_ID"

# Check code quality
npm run lint || {
  echo "Lint failed. Please fix before continuing."
  exit 1
}

# Pull latest code
git pull origin main

exit 0

MCP Server Configuration

Model Context Protocol Integration

{
  "mcp": {
    "enabled": true,
    "servers": [
      {
        "name": "github",
        "command": "mcp-server-github",
        "args": ["--token", "${GITHUB_TOKEN}"],
        "env": {
          "GITHUB_API_URL": "https://api.github.com"
        }
      },
      {
        "name": "database",
        "command": "mcp-server-postgres",
        "args": ["--connection", "${DATABASE_URL}"]
      },
      {
        "name": "slack",
        "command": "mcp-server-slack",
        "args": ["--token", "${SLACK_TOKEN}"]
      }
    ],
    
    // Server resource limits
    "resource_limits": {
      "max_connections": 5,
      "timeout": 30,
      "retry_attempts": 3
    }
  }
}

Complete Configuration Example

Enterprise-Grade Configuration Template

{
  "version": "1.0",
  "subscription": "claude-max20",
  
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3,
    "delegation_strategy": "optimal"
  },
  
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.7,
      "prompt_append": "Follow company technology stack and architecture principles"
    },
    "librarian": {
      "enabled": true,
      "model": "claude-sonnet-4"
    },
    "frontend-engineer": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "prompt_append": "Use React + TypeScript + Tailwind"
    },
    "backend-engineer": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "prompt_append": "Use Node.js + Express + PostgreSQL"
    },
    "explore": {
      "enabled": true,
      "model": "claude-sonnet-3.5"
    }
  },
  
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "python", "go"]
  },
  
  "background_task": {
    "defaultConcurrency": 5,
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5
    }
  },
  
  "permissions": {
    "file_operations": {
      "read": {
        "allow": ["src/**", "docs/**"],
        "deny": [".env*", "secrets/**"]
      },
      "write": {
        "allow": ["src/**", "docs/**"],
        "deny": ["package.json"]
      }
    },
    "shell_commands": {
      "whitelist": ["npm test", "npm run lint", "git status"]
    }
  },
  
  "hooks": {
    "pre_task": {
      "enabled": true,
      "script": ".opencode/hooks/pre-task.sh"
    },
    "post_task": {
      "enabled": true,
      "script": ".opencode/hooks/post-task.sh"
    }
  },
  
  "context_injection": {
    "enabled": true,
    "files": [".opencode/CONTEXT.md", "AGENTS.md"]
  }
}

Configuration Validation

Validate Configuration File

# Validate configuration syntax
opencode "Validate configuration file"

# Test configuration
opencode "Perform test task using current configuration"

# View effective configuration
opencode "Show current complete configuration"

Common Configuration Errors

// ❌ Error: Concurrency exceeds subscription limit
{
  "sisyphus": {
    "max_concurrent_tasks": 10  // Claude Max20 max is 3
  }
}

// ✅ Correct
{
  "sisyphus": {
    "max_concurrent_tasks": 3
  }
}

// ❌ Error: Disabled agent
{
  "sisyphus": {
    "auto_delegate": true
  },
  "agents": {
    "oracle": { "enabled": false }  // But Sisyphus may try to delegate
  }
}

// ✅ Correct
{
  "agents": {
    "oracle": { "enabled": true }
  }
}

Next Steps

After configuration is complete, we recommend:

  1. 💡 Check Use Cases to learn how to apply configuration
  2. 📖 Review Best Practices to optimize workflow
  3. 🧪 Test and adjust configuration in real projects