5745
Sc
sacenox.github.io / files
sacenox.github.io / _posts / 2026-02-03-opencode-setup-guide.md
6.6 KB
1--- 2layout: post 3title: building-a-production-ready-opencode-configuration-from-scratch 4description: A deep dive into cost optimization, workflows, and skills for OpenCode. 5--- 6 7# Building a Production-Ready OpenCode Configuration from Scratch 8 9Setting up an AI coding assistant isn't just about picking a model and starting to code. After spending time configuring OpenCode from the ground up, I learned that a thoughtful setup can save you money, improve code quality, and create a more disciplined development workflow. 10 11Here's how I built a comprehensive OpenCode configuration that balances cost efficiency with powerful capabilities. 12 13## The Foundation: Global Rules and Workflow 14 15The first step was creating a global `AGENTS.md` file at `~/.config/opencode/AGENTS.md`. This isn't just documentation—it's the behavioral contract for all AI interactions. 16 17### Core Principles 18 19I established several non-negotiable rules: 20- Professional tone (no "You're absolutely right!" responses) 21- No emojis or AI-speak 22- Documentation-first approach 23- No auto-commits without explicit approval 24- Always work within the current repo's root 25 26### The Six-Phase Workflow 27 28The real breakthrough was implementing a structured development workflow: 29 301. **Plan** - Use Plan mode for gathering information and creating detailed plans 312. **Validate** - Verify assumptions before building 323. **Build** - Implement with discipline to return to Plan if issues arise 334. **Review** - Use the built-in `/review` command (a hidden gem I discovered) 345. **Document** - Update AGENTS.md, README.md, and inline docs 356. **Complete** - Provide verification evidence before claiming "done" 36 37This workflow prevents the common AI pitfall of pushing through problems blindly. 38 39## Configuration: opencode.json Optimization 40 41The `opencode.json` file is where the magic happens. Here's what I learned about model selection and cost optimization. 42 43### Model Selection Strategy 44 45I started with Claude Sonnet 4.5 at $3.00/$15.00 per 1M tokens, but the costs were adding up fast. After analyzing usage patterns, I discovered that cache reads were dominating my bill—534M cache reads in typical usage. 46 47The breakthrough came with Gemini 3 Flash at $0.50/$3.00 per 1M tokens. This represented an 80% cost reduction while maintaining quality for most coding tasks. 48 49### Smart Configuration Choices 50 51```json 52{ 53 "provider": "opencode-zen", 54 "default_model": "opencode/gemini-3-flash", 55 "small_model": "opencode/gpt-5-nano", 56 "instructions": [ 57 "CONTRIBUTING.md", 58 "docs/guidelines.md", 59 ".cursor/rules/*.md" 60 ], 61 "agent_temperatures": { 62 "plan": 0.1, 63 "build": 0.3 64 } 65} 66``` 67 68Key insights: 69- Use a free model (GPT 5 Nano) for simple tasks like title generation 70- Auto-load project documentation with the `instructions` array 71- Different temperatures for different modes (lower for planning, higher for creative building) 72- Git permission rules requiring approval for destructive operations 73 74## Skills: The Secret Weapon 75 76The skills ecosystem through `skills.sh` was a game-changer. I installed seven carefully chosen skills: 77 78### Core Skills Installed 79 80- **systematic-debugging** - Methodical approach to problem-solving 81- **verification-before-completion** - QA discipline before claiming "done" 82- **writing-plans** - Structured planning methodology 83- **commit-work** - Git commit discipline and best practices 84- **crafting-effective-readmes** - Documentation standards 85- **mermaid-diagrams** - Visual documentation tools 86- **writing-clearly-and-concisely** - Communication improvement 87 88### Installation Strategy 89 90I used the `npx skills -g` command to install skills globally, then copied them as actual files (not symlinks) for portability across machines. This ensures the configuration works identically on any development environment. 91 92## Hidden Features and Discoveries 93 94### The /review Command 95 96OpenCode has a built-in `/review` command that I wish I'd discovered earlier. It can review changes at different scopes: 97- `review changes` - Uncommitted changes (default) 98- `review changes commit` - Last commit 99- `review changes branch` - Current branch vs main 100- `review changes pr` - Pull request changes 101 102This eliminates the need for manual code review workflows. 103 104### Model Naming Convention 105 106OpenCode Zen uses a specific naming convention with the "opencode/" prefix. This caught me off guard initially—make sure to use names like `opencode/gemini-3-flash`, not just `gemini-3-flash`. 107 108## Cost Analysis and Optimization 109 110The numbers tell the story. My original configuration would have cost roughly $50-80 per month for heavy usage. The optimized setup reduced this to $10-15 per month—a 75-80% savings. 111 112### Cost Factors to Consider 113 114- **Input tokens** - Your code and prompts 115- **Output tokens** - AI responses 116- **Cache reads** - Often the biggest cost factor 117- **Model capabilities** - Balance cost vs. quality needs 118 119The key insight: cache reads can dominate your bill. Choose models with favorable cache pricing, and Gemini 3 Flash excels here. 120 121## Final Directory Structure 122 123``` 124~/.config/opencode/ 125├── AGENTS.md # Global rules and workflow (63 lines) 126├── opencode.json # Optimized configuration 127├── agents/ 128│ └── writer.md # Specialized subagents 129└── skills/ # Portable skill library 130 ├── commit-work/ 131 ├── crafting-effective-readmes/ 132 ├── mermaid-diagrams/ 133 ├── systematic-debugging/ 134 ├── verification-before-completion/ 135 ├── writing-clearly-and-concisely/ 136 └── writing-plans/ 137``` 138 139## Lessons Learned 140 1411. **Start with discipline** - Rules and workflow matter more than model choice 1422. **Monitor costs actively** - Usage patterns reveal optimization opportunities 1433. **Skills are force multipliers** - The ecosystem provides battle-tested methodologies 1444. **Documentation is configuration** - AGENTS.md shapes AI behavior as much as JSON settings 1455. **Hidden features exist** - Explore built-in commands like `/review` 146 147## Next Steps 148 149This configuration provides a solid foundation, but it's designed to evolve. As new models become available and costs change, the structure supports easy updates. The workflow ensures quality remains high regardless of the underlying technology. 150 151The investment in setup pays dividends in every subsequent coding session. Professional AI assistance isn't just about having access to models—it's about creating systems that amplify your capabilities while maintaining discipline and cost control. 152 153## Sources 154 155- OpenCode documentation and configuration reference 156- skills.sh ecosystem and skill library 157- OpenCode Zen pricing analysis and model comparisons 158- Personal configuration testing and cost optimization experiments