Turn vanilla OpenCode into a god-tier AI coding assistant.
A drop-in configuration that gives you specialized agents, battle-tested skills, powerful custom commands, and a gorgeous Gruvbox theme — all designed to outperform Claude Code, Cursor, and every other AI coding tool.
Tired of constantly discovering new AI coding tricks, prompt patterns, and agent enhancements?
Every week there's a new "best way" to use Claude Code, a new skill pattern, a new agent workflow.
OpenCode MAX does the research so you don't have to — we track every meaningful advancement in AI-assisted development
and bake it into this configuration, so you can stay focused on writing great code
instead of endlessly tuning your tools.
Installation • What's Included • Agents • Commands • Skills • Customize
Most people use OpenCode with default settings. That's like driving a Ferrari in first gear.
OpenCode MAX gives you:
| Feature | Vanilla OpenCode | OpenCode MAX |
|---|---|---|
| Agents | 2 (Build + Plan) | 12 specialized agents |
| Commands | 5 built-in | 14+ custom commands |
| Skills | None | 6 reusable workflows |
| Theme | Default | Custom Gruvbox with full syntax highlighting |
| Permissions | Wide open | Granular security with safe defaults |
| Prompts | Generic | Expert-crafted system prompts per agent |
| Debugging | Manual | Hypothesis-driven debug loop |
| Code Review | Manual | One-command /review with severity ratings |
| Git | Manual | Auto-generated conventional commits |
| Security | None | Built-in security audit command |
curl -sSL https://raw.githubusercontent.com/ab1nv/opencode-max/master/install.sh | bashgit clone https://github.com/ab1nv/opencode-max.git
cd opencode-max
./install.shThe installer will ask you:
- Current project — Copies configs to your working directory
- Global — Installs to
~/.config/opencode/(applies everywhere) - Both — Global + current project
- Update — Safe update mode (does not overwrite modified files)
# Clone the repo
git clone https://github.com/ab1nv/opencode-max.git
# Copy to your project
cp opencode-max/opencode.json ./
cp opencode-max/tui.json ./
cp opencode-max/AGENTS.md ./
cp -r opencode-max/.opencode/ ./.opencode/
cp -r opencode-max/prompts/ ./prompts/
# Or copy globally
cp opencode-max/opencode.json ~/.config/opencode/
cp opencode-max/tui.json ~/.config/opencode/
cp opencode-max/AGENTS.md ~/.config/opencode/
cp -r opencode-max/.opencode/themes/ ~/.config/opencode/themes/
cp -r opencode-max/.opencode/agents/ ~/.config/opencode/agents/
cp -r opencode-max/.opencode/commands/ ~/.config/opencode/commands/
cp -r opencode-max/.opencode/skills/ ~/.config/opencode/skills/Only want the theme? Copy .opencode/themes/gruvbox-max.json.
Only want agents? Copy .opencode/agents/ and opencode.json.
Mix and match whatever works for you.
opencode-max/
├── opencode.json # Main config — agents, permissions, commands, MCP
├── tui.json # TUI theme & keybindings
├── AGENTS.md # Global rules & coding standards
├── install.sh # Interactive installer
│
├── prompts/ # Agent system prompts
│ ├── build.md # Build agent prompt
│ ├── plan.md # Plan agent prompt
│ ├── architect.md # Architect agent prompt
│ └── debugger.md # Debugger agent prompt
│
└── .opencode/
├── themes/
│ └── gruvbox-max.json # Custom Gruvbox theme
│
├── agents/ # Markdown-based subagents
│ ├── grill-me.md # Design decision challenger
│ ├── perf-profiler.md # Performance analyzer
│ └── changelog.md # Changelog generator
│
├── commands/ # Custom slash commands
│ ├── pre-commit.md # Pre-commit review
│ ├── overview.md # Project overview
│ ├── diff-summary.md # Change summary
│ └── explain.md # Code explainer
│
├── tools/ # Custom callable tools
│ ├── handoff.ts # Save/load session handoff notes
│ └── run-checks.ts # Run ordered verification commands
│
└── skills/ # Reusable workflow skills
├── plan-first/ # Plan-before-code workflow
├── tdd/ # Test-driven development
├── code-review/ # Review checklist
├── git-commit/ # Conventional commits
├── debug-loop/ # Hypothesis-driven debugging
└── to-prd/ # Idea → PRD converter
OpenCode MAX ships with 12 specialized agents: 3 primary agents you can switch between with Tab, and 9 subagents invokable with @.
| Agent | Color | Purpose |
|---|---|---|
| Build | Orange | Full-power implementation: all tools enabled |
| Plan | Blue | Read-only analysis and planning: never modifies files |
| Architect | Purple | System design and architecture decisions |
| Agent | Invoke | Purpose |
|---|---|---|
| Code Reviewer | @code-reviewer |
Deep review with security, correctness, and performance checks |
| Debugger | @debugger |
Systematic hypothesis-driven bug investigation |
| Docs Writer | @docs-writer |
Technical documentation and README generation |
| Security Auditor | @security-auditor |
OWASP-based security vulnerability scanning |
| Refactor | @refactor |
Code quality improvement without behavior change |
| Explorer | @explorer |
Fast read-only codebase navigation (10 step limit) |
| Grill Me | @grill-me |
Socratic challenger: pressure-tests your design decisions |
| Perf Profiler | @perf-profiler |
Finds bottlenecks, N+1 queries, and complexity issues |
| Changelog | @changelog |
Generates changelogs from git history |
┌─────────────────────────────────────────────┐
│ Primary Agents │
│ ┌─────────┐ ┌──────┐ ┌───────────┐ │
│ │ Build │──│ Plan │──│ Architect │ Tab │
│ └────┬────┘ └──────┘ └───────────┘ │
│ │ │
│ ▼ Delegates to subagents │
│ ┌──────────────────────────────────┐ │
│ │ @code-reviewer @debugger │ │
│ │ @docs-writer @security │ │
│ │ @refactor @explorer │ │
│ │ @grill-me @perf-profiler │ │
│ │ @changelog │ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────────┘
Type / in OpenCode to see all commands. OpenCode MAX adds 14 custom commands:
| Command | Description |
|---|---|
/test |
Run tests, analyze failures, suggest fixes |
/tdd <feature> |
Test-driven development workflow |
/debug <issue> |
Systematic hypothesis-driven debugging |
/refactor <target> |
Refactor code while preserving behavior |
| Command | Description |
|---|---|
/review |
Full code review on staged changes |
/pre-commit |
Pre-commit quality check with go/no-go verdict |
/security |
OWASP-based security audit |
/perf <target> |
Performance analysis and optimization suggestions |
| Command | Description |
|---|---|
/plan <task> |
Create a detailed implementation plan |
/doc <target> |
Generate documentation for a file or module |
/explain <target> |
Plain-English code explanation |
/overview |
Quick project overview and tech stack scan |
| Command | Description |
|---|---|
/commit |
Generate conventional commit message from staged changes |
/diff-summary |
Summarize all uncommitted changes |
# Review your staged changes before committing
/review
# Plan a new feature
/plan Add user authentication with JWT
# Debug a specific issue
/debug Users can't login after password reset
# Generate a commit message
/commit
# Explain unfamiliar code
/explain src/auth/middleware.ts
# Run TDD for a new feature
/tdd Add email validation to signup formSkills are reusable workflow instructions that agents load on-demand. They teach the AI HOW to approach specific types of tasks.
| Skill | Trigger | What It Does |
|---|---|---|
| plan-first | Complex tasks (3+ files) | Enforces requirements → discovery → plan → approval → execution |
| tdd | /tdd or test-related tasks |
Red → Green → Refactor cycles |
| code-review | /review or review tasks |
Structured checklist: security, correctness, perf, design |
| git-commit | /commit |
Conventional commit message generation |
| debug-loop | /debug or bug reports |
Hypothesis-driven: gather → hypothesize → test → fix → prevent |
| to-prd | New features / ideas | Converts rough ideas into structured PRDs |
OpenCode MAX includes lightweight custom tools in .opencode/tools/:
| Tool | Purpose |
|---|---|
handoff_save / handoff_load |
Persist and restore structured handoff notes across sessions |
run-checks |
Run tests/lint/typecheck commands in sequence with a compact report |
A carefully crafted Gruvbox dark theme with:
- Warm orange primary accents (
#fe8019) - Tinted diff backgrounds — green-tinted for additions, red-tinted for removals
- Full syntax highlighting — 9 distinct token colors
- High contrast — dark background (
#1d2021) with light text (#ebdbb2) - Active borders — orange glow on focused elements
| Role | Color | Hex |
|---|---|---|
| Primary | Orange | #fe8019 |
| Secondary | Blue | #83a598 |
| Accent | Aqua | #8ec07c |
| Success | Green | #b8bb26 |
| Warning | Yellow | #fabd2f |
| Error | Red | #fb4934 |
| Info | Blue | #83a598 |
| Background | Dark | #1d2021 |
| Text | Light | #ebdbb2 |
OpenCode MAX uses a secure-by-default permission model:
- Reading files (except
.env) - Git read operations (
status,diff,log,branch,show) - Search tools (
grep,rg,find,ls,cat) - Test runners (
npm test,jest,vitest,pytest,cargo test) - Linters and type checkers (
tsc,eslint,prettier,clippy) - Build commands (
npm run build,cargo build,go build) - Web fetch and search
- Git write operations (
commit,push,merge,rebase,checkout) - Docker commands
- Make commands
- External directory access
- Doom loop detection (same tool called 3x with same input)
- Destructive commands (
rm,rm -rf) - System commands (
sudo,chmod,chown) - Reading
.envfiles
Each agent has tailored permissions:
- Build: Full power, blocks destructive commands
- Plan: Read-only — cannot edit files or run most commands
- Code Reviewer: Read-only + git diff/log
- Debugger: Can edit + run tests, needs approval for other commands
| Action | Shortcut |
|---|---|
| Switch agent | Tab / Shift+Tab |
| Leader key | Ctrl+X |
| New session | <Leader> + N |
| Session list | <Leader> + L |
| Compact session | <Leader> + C |
| Model list | <Leader> + M |
| Agent list | <Leader> + A |
| Command list | Ctrl+P |
| Copy messages | <Leader> + Y |
| Undo | <Leader> + U |
| Toggle sidebar | <Leader> + B |
| Toggle tips | <Leader> + H |
| Exit | Ctrl+C / Ctrl+D |
Edit opencode.json and update the model field for any agent:
Create a markdown file in .opencode/agents/:
---
description: My custom agent
mode: subagent
temperature: 0.3
permission:
edit: allow
bash:
"*": ask
---
You are a custom agent. Do amazing things.Create a markdown file in .opencode/commands/:
---
description: My custom command
agent: build
---
Do something cool with: $ARGUMENTSCreate .opencode/skills/my-skill/SKILL.md:
---
name: my-skill
description: What this skill does
---
## Instructions for the agent...Edit opencode.json:
{
"mcp": {
"my-server": {
"type": "local",
"command": ["npx", "-y", "my-mcp-server"],
"enabled": true
}
}
}Either use a built-in theme in tui.json:
{ "theme": "tokyonight" }Or modify .opencode/themes/gruvbox-max.json to your liking.
Don't use Build for planning. Don't use Plan for coding. Hit Tab to switch.
Before touching code, run /plan <description>. This creates a structured plan that the Build agent can follow.
One command catches bugs, security issues, and style problems. Much cheaper than production bugs.
Type @debugger investigate the login timeout to delegate to a specialist without leaving your main conversation.
The plan-first skill ensures agents don't jump into code without a plan. The tdd skill enforces Red-Green-Refactor.
/plan Add pagination to /api/users
# Review the plan, approve it
# Switch to Build agent (Tab)
# Implement the plan
/test
/review
/commit
It gives a clear safe/fix/do-not-commit verdict before you commit.
Before finalizing architecture, invoke @grill-me to find blind spots.
This configuration is inspired by and built upon:
- OpenCode Documentation — Official docs
- Graphify — Knowledge graph skill patterns
- Claude Code Templates — Agent configuration patterns
- Matt Pocock's Skills — Workflow skill design
- Oh My Codex (OmX) — Agent orchestration patterns
- Andrej Karpathy's LLM Skills - Base of entire design
{ "agent": { "build": { "model": "openai/gpt-5.1-codex" // or any provider/model } } }