OpenCode Template Installer

Automatically configure OpenCode with the opencode-template for Linux, Windows, and macOS.

Built with @clack/prompts for a beautiful, interactive CLI experience.

Installation

Simply run:

npx octicoc

What it does

1. Backups existing configuration (if any)
2. Downloads and installs opencode-template from GitHub
3. Merges configs: Template (opencode.jsonc) + Your existing config (opencode.json)
4. Detects system username (automatically, with option to change)
5. Updates opencode.json with your username
6. Creates .env file from .env.example
7. Prompts for API keys (optional - can skip and configure later)
8. Everything is installed to: ~/.config/opencode (same for all platforms)

Cross-Platform Support

✅ Windows - Uses node-tar package for reliable extraction
✅ macOS - Works with native tar support
✅ Linux - Works with native tar support

The installer uses the tar npm package to ensure consistent extraction across all platforms, avoiding issues with Windows path limitations and tar command compatibility.

Interactive CLI Features

The installer provides a modern, user-friendly experience:

• 🎨 Beautiful UI - Clean, colorful interface with clear visual hierarchy
• ⏳ Progress Indicators - Spinners show real-time progress during downloads and extraction
• ✅ Input Validation - Prevents common mistakes with built-in validation
• 🎯 Smart Defaults - Auto-detects your username and suggests sensible defaults
• ❌ Cancellation Support - Press Ctrl+C anytime to gracefully exit
• 💬 Clear Messages - Success, warning, and error messages are easy to understand
• 📝 Helpful Prompts - Placeholders and hints guide you through configuration

Merge Behavior

The installer intelligently merges the template with your existing config:

• opencode.jsonc: Contains the template definition (skills, agents, commands, etc.)
• opencode.json: Your personalized config with custom settings
• Automatic backup: Your existing config is backed up before merging
• Smart merge: Preserves your custom agents, skills, and environment variables

If you run the installer again, it will:

1. Backup your current config
2. Update the template with new features
3. Preserve all your customizations

Environment Variables

After installation, you'll need to configure your API keys:

| Variable | Description | | ----------------------- | -------------------------- | | CONTEXT7_API_KEY | Context7 MCP API key | | REF_API_KEY | Ref documentation API key | | EXA_API_KEY | Exa AI search API key | | SUPABASE_PROJECT_REF | Supabase project reference | | SUPABASE_ACCESS_TOKEN | Supabase access token | | CLIPROXY_API_KEY | Cliproxy provider API key |

Configuration Steps

The installer will automatically:

1. Backup your existing OpenCode config
2. Download and extract the template (with progress spinner)
3. Merge configs: Keeps your custom settings while adding new features
4. Detect your system username and prompt for confirmation/change
5. Update opencode.json with your username
6. Copy .env.example to .env for you
7. Prompt you to enter API keys (you can skip this step and configure later)
8. Show you the config location: ~/.config/opencode/.env

Manual Configuration (Optional)

If you skipped the API key configuration during installation, you can edit them later:

nano ~/.config/opencode/.env
# or
vim ~/.config/opencode/.env

Restart OpenCode to apply the configuration.

Features Included

• Multi-Agent System: Specialized agents for backend, frontend, security, database, and TypeScript development
• Custom Commands: Brainstorm, debug, enhance, SEO, mobile-responsiveness, and more
• Skill Framework: Code review, refactoring, frontend design, UI animation, and 15+ other skills
• MCP Integrations: Next.js DevTools, Exa AI, Ref documentation, Supabase, Context7
• Superpowers: Advanced planning, subagent orchestration, and systematic debugging

License

MIT