Vibe Coding with OpenCode

Vibe coding is the art of working with AI in a natural, intuitive flow. Instead of rigid prompts and formal processes, you describe what you want in your own words and let the AI handle the details. OpenCode makes this possible by being a fully capable coding partner.

What is Vibe Coding?

Vibe coding is about entering a creative flow state with AI assistance. You focus on the "what" and "why" - the AI handles the "how."

Key Principles

• Describe intent, not implementation - Say "add user authentication" not "create a JWT middleware with bcrypt"
• Trust the flow - Let the AI explore, iterate, and self-correct
• Stay in the driver's seat - You set direction, AI executes
• Embrace experimentation - Quick iterations over perfect planning
• Leverage skills - Superpowers handle methodology so you can focus on creativity

Why OpenCode for Vibe Coding?

Unlike chat-based AI tools, OpenCode operates directly on your codebase:

• Reads and writes files autonomously
• Runs tests and commands
• Navigates code with LSP intelligence
• Manages git operations
• Coordinates multiple specialized agents

This means you stay in creative mode while OpenCode handles the mechanical work.

Vibe Coding in Practice

Example 1: Starting Fresh

Instead of:

"Create a REST API with Express, add JWT authentication, connect to PostgreSQL with a users table..."

Vibe coding:

"I want to build a simple API for tracking my reading list. Books have titles, authors, and status. Make it work locally first."

OpenCode figures out the stack, sets up the project, and iterates with you.

Example 2: Debugging Flow

Instead of:

"Add console.log statements to the login function and check the token validation logic..."

Vibe coding:

"The login is broken, users can't get in. Figure it out."

OpenCode reads the code, runs tests, checks logs, identifies the issue, and fixes it.

Example 3: Refactoring Vibes

Instead of:

"Extract the validation logic into separate functions following the single responsibility principle and add unit tests..."

Vibe coding:

"This validation code is messy. Clean it up and make sure nothing breaks."

OpenCode refactors, adds tests, verifies behavior, all while you review the changes.

Example 4: Multi-Agent Flow

When things get complex, OpenCode spawns specialized agents:

"I need a full user management system with auth, profiles, and permissions."

OpenCode might:

1. Spawn a planner agent to design the architecture
2. Dispatch parallel agents for auth, profiles, permissions
3. Run verification agents to test integration
4. Handle git commits with proper messages

You just describe the destination, OpenCode navigates.

Installation and Setup

Prerequisites

Before installing OpenCode, ensure you have:

• Node.js 18 or higher
• A supported LLM API key (OpenAI, Anthropic, or compatible)
• Git installed and configured
• A terminal environment (bash, zsh, or PowerShell)

Installation Steps

Install OpenCode globally via npm:

npm install -g opencode

Or use the recommended approach with oh-my-opencode:

# Clone the configuration framework
git clone https://github.com/oh-my-opencode/oh-my-opencode.git ~/.oh-my-opencode

# Run the setup script
cd ~/.oh-my-opencode && ./install.sh

Initial Configuration

Create your configuration file at ~/.opencode/config.json:

{
  "provider": "anthropic",
  "model": "claude-3-opus",
  "apiKey": "${ANTHROPIC_API_KEY}",
  "maxTokens": 4096,
  "temperature": 0.7
}

Set your API key as an environment variable:

export ANTHROPIC_API_KEY="your-key-here"

Verify the installation:

opencode --version
opencode "What files are in this directory?"

oh-my-opencode Configuration

What is oh-my-opencode

oh-my-opencode is a configuration framework that extends OpenCode with project-specific settings, custom prompts, and skill definitions. It follows the philosophy that each codebase deserves its own AI configuration.

Configuration File Structure

The .opencode/ directory in your project root contains all customizations:

The AGENTS.md file sits at the repository root and describes your codebase conventions:

# AGENTS.md

## Project Overview
- Framework: Next.js 14 with App Router
- Styling: Tailwind CSS
- Testing: Vitest

## Build Commands
- `npm run build` - Production build
- `npm run test` - Run test suite
- `npm run lint` - Lint code

## Code Style
- Use TypeScript strict mode
- Prefer named exports
- Component files: PascalCase

Environment Variables

OpenCode respects several environment variables:

# API Configuration
OPENCODE_API_KEY          # Default API key
OPENCODE_PROVIDER         # Default provider (openai, anthropic)
OPENCODE_MODEL            # Default model

# Behavior
OPENCODE_MAX_TOKENS       # Maximum response tokens
OPENCODE_TEMPERATURE      # Response randomness (0-1)
OPENCODE_LOG_LEVEL        # Logging verbosity

# Project
OPENCODE_PROJECT_ROOT     # Override project detection

Custom Prompts and Templates

Create reusable prompt templates in .opencode/prompts/:

<!-- .opencode/prompts/review.md -->
Review the following code changes for:

1. **Correctness**: Does the code do what it claims?
2. **Security**: Are there any vulnerabilities?
3. **Performance**: Any obvious bottlenecks?
4. **Style**: Does it match project conventions?

Focus on actionable feedback with specific line references.

Invoke custom prompts:

opencode --prompt review --input changes.diff

MCP Server Integration

Model Context Protocol (MCP) servers extend OpenCode with external capabilities. Configure MCP servers in your config:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem",
      "args": ["/path/to/project"]
    },
    "github": {
      "command": "mcp-github",
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Superpowers Skills System

What are Superpowers Skills

Superpowers skills are pre-built workflows that guide OpenCode through complex, multi-step processes. Each skill encapsulates best practices and ensures consistent, high-quality outcomes.

Skills work by injecting detailed instructions into the agent context before it begins work. This gives the agent a roadmap to follow rather than improvising.

Built-in Skills Overview

superpowers/using-superpowers

The meta-skill that teaches how to discover and invoke other skills. Load this first when exploring available capabilities.

When to use: Starting any new conversation or when you need to understand what skills exist.

# The agent loads this automatically at conversation start
opencode "Help me understand what skills are available"

superpowers/writing-plans

Guides creation of detailed implementation plans before writing code. Plans break work into atomic steps with clear acceptance criteria.

When to use: Any feature request or bug fix that requires multiple steps.

Workflow:

1. Gather requirements and context
2. Identify affected files and components
3. Break into atomic, sequential steps
4. Define verification criteria for each step
5. Review plan with user before execution

superpowers/test-driven-development

Enforces strict TDD discipline: write tests first, then implement.

When to use: Implementing new features or fixing bugs where tests add value.

Workflow:

1. Write a failing test that describes desired behavior
2. Run test to confirm it fails for the right reason
3. Write minimal code to make test pass
4. Refactor while keeping tests green
5. Repeat for next requirement

opencode "Add a user registration feature using TDD"

superpowers/systematic-debugging

Provides structured approach to finding and fixing bugs without guessing.

When to use: Any unexpected behavior, test failure, or error condition.

Workflow:

1. Reproduce the issue reliably
2. Gather diagnostic information (logs, stack traces)
3. Form a hypothesis about root cause
4. Design a test to validate hypothesis
5. Implement fix
6. Verify fix resolves original issue
7. Check for similar issues elsewhere

superpowers/verification-before-completion

Ensures work is actually complete before claiming success.

When to use: Before marking any task as done, before commits, before PRs.

Checks:

1. All modified files pass linting
2. All tests pass
3. No TypeScript errors
4. Build succeeds
5. Manual verification of changed behavior

superpowers/writing-skills

Guides creation of new custom skills for your project.

When to use: You find yourself repeating a workflow that could be standardized.

Structure of a skill:

# Skill Name

## When to Use
[Trigger conditions]

## Prerequisites
[Required setup or state]

## Steps
1. [First step with specifics]
2. [Second step with specifics]
...

## Verification
[How to confirm success]

## Rollback
[How to undo if needed]

superpowers/using-git-worktrees

Creates isolated git worktrees for parallel development without context switching.

When to use: Starting feature work that needs isolation from your current branch.

Workflow:

1. Create worktree in isolated directory
2. Checkout target branch in worktree
3. Perform work in isolation
4. Complete and push from worktree
5. Remove worktree when done

opencode "Create a worktree for the auth feature"

superpowers/subagent-driven-development

Coordinates multiple parallel tasks using background agents.

When to use: Large features that can be decomposed into independent parts.

Workflow:

1. Decompose work into independent tasks
2. Spawn background agents for each task
3. Monitor progress and gather results
4. Integrate completed work
5. Verify integration

How to Invoke Skills

Skills load automatically based on trigger keywords, or you can explicitly request them:

# Implicit invocation via trigger words
opencode "Debug the login issue"  # triggers systematic-debugging

# Explicit invocation
opencode "Use the TDD skill to add password reset"

Creating Custom Skills

Place custom skills in .opencode/skills/:

<!-- .opencode/skills/deploy.md -->
# Deploy to Production

## When to Use
Deploying code to production environment.

## Prerequisites
- All tests passing
- Code reviewed and approved
- CHANGELOG updated

## Steps
1. Run full test suite
2. Build production bundle
3. Create git tag with version
4. Push tag to remote
5. Trigger CI/CD pipeline
6. Monitor deployment health
7. Verify in production

## Verification
- Application loads at production URL
- Health check endpoint returns 200
- No errors in production logs

Agent Categories

OpenCode routes requests to specialized agents based on task characteristics.

visual-engineering

Frontend-focused work including UI components, styling, layouts, and visual polish.

Best for:

• React/Vue/Svelte component development
• CSS and styling tasks
• Layout fixes and responsive design
• Accessibility improvements
• Animation and interaction design

opencode "Fix the header alignment on mobile" --category visual-engineering

ultrabrain

Logic-heavy tasks requiring deep reasoning and algorithmic thinking.

Best for:

• Complex algorithm implementation
• Architecture decisions
• Performance optimization
• Security-critical code
• Concurrency and parallelism

opencode "Optimize the database query that's causing timeouts" --category ultrabrain

deep

Goal-oriented autonomous problem-solving. The agent works independently toward a defined goal.

Best for:

• Large refactoring projects
• Migration tasks
• Multi-file feature implementation
• Research and exploration

opencode "Migrate the authentication system from JWT to OAuth" --category deep

artistry

Creative problem-solving with emphasis on elegant solutions and code aesthetics.

Best for:

• API design
• Code architecture
• Developer experience improvements
• Library and framework code

opencode "Design a clean API for the plugin system" --category artistry

quick

Trivial tasks and single-file changes that need no planning.

Best for:

• Typo fixes
• Single function changes
• Configuration updates
• Quick documentation updates

opencode "Fix the typo in the README" --category quick

unspecified-low

Lower effort tasks that don't fit other categories.

Best for:

• Minor bug fixes
• Small feature additions
• Code cleanup

unspecified-high

Higher effort tasks requiring substantial work but without special focus.

Best for:

• Medium-sized features
• Moderate refactoring
• Multi-step changes

writing

Documentation, prose, and content creation.

Best for:

• README files
• API documentation
• Blog posts
• Code comments and JSDoc
• Changelog entries

opencode "Write documentation for the webhook API" --category writing

Available Tools Reference

OpenCode agents access your system through a comprehensive toolset.

File Operations

Read - Read file or directory contents

Parameters: filePath (absolute path), offset, limit
Returns: File contents with line numbers

Write - Create or overwrite files

Parameters: filePath, content
Note: Overwrites existing files completely

Edit - Make precise string replacements

Parameters: filePath, oldString, newString, replaceAll
Note: Requires exact match, fails on ambiguity

Glob - Find files by pattern

Parameters: pattern (glob syntax), path
Returns: Matching file paths sorted by modification time

Grep - Search file contents

Parameters: pattern (regex), include (file filter), path
Returns: Matching files with context

Code Analysis (LSP Tools)

lsp_goto_definition - Jump to symbol definition

Parameters: filePath, line, character
Returns: Location where symbol is defined

lsp_find_references - Find all usages

Parameters: filePath, line, character, includeDeclaration
Returns: All locations where symbol is used

lsp_symbols - Get document or workspace symbols

Parameters: filePath, scope (document/workspace), query
Returns: Symbol outline or search results

lsp_diagnostics - Get errors and warnings

Parameters: filePath, severity (error/warning/hint/all)
Returns: Diagnostic items with positions

lsp_rename - Rename symbol across workspace

Parameters: filePath, line, character, newName
Note: Use lsp_prepare_rename first to validate

AST Operations

ast_grep_search - AST-aware code pattern matching

Parameters: pattern, lang, paths, globs
Supports meta-variables: $VAR (single node), $$$ (multiple)

ast_grep_replace - AST-aware code transformation

Parameters: pattern, rewrite, lang, dryRun

Shell Operations

Bash - Execute shell commands

Parameters: command, workdir, timeout, description
Note: Commands run in persistent shell session

interactive_bash - Interactive TUI applications

Parameters: tmux_command
Note: Uses tmux for interactive programs

Web Tools

webfetch - Fetch and parse web content

Parameters: url, format (markdown/text/html), timeout

google_search - Search the web with citations

Parameters: query, urls (optional), thinking

websearch_web_search_exa - High-quality web search

Parameters: query, numResults, contextMaxCharacters

Git Operations

All git tools mirror git CLI commands:

• git_git_status - Working tree status
• git_git_diff_unstaged - Unstaged changes
• git_git_diff_staged - Staged changes
• git_git_diff - Branch/commit differences
• git_git_commit - Create commit
• git_git_add - Stage files
• git_git_reset - Unstage all
• git_git_log - Commit history
• git_git_create_branch - Create branch
• git_git_checkout - Switch branches
• git_git_show - Show commit contents
• git_git_branch - List branches

Session Management

session_list - List all sessions

Parameters: limit, from_date, to_date

session_read - Read session messages

Parameters: session_id, limit, include_todos

session_search - Search session content

Parameters: query, session_id, limit

session_info - Get session metadata

Parameters: session_id

Background Tasks

call_omo_agent - Spawn background agent

Parameters: subagent_type, prompt, description, run_in_background
Types: explore, librarian, oracle, hephaestus, metis, momus

background_output - Get task output

Parameters: task_id, block, full_session

background_cancel - Cancel running task

Parameters: taskId, all

MCP Integrations

skill_mcp - Invoke MCP server operations

Parameters: mcp_name, tool_name, resource_name, arguments

Ableton MCP - Music production automation

Tools: ableton-mcp-server_* for session control, tracks, clips, devices

Blender MCP - 3D creation automation

Tools: blender_* for scene manipulation, rendering, asset import

Chrome DevTools MCP - Browser automation

Tools: chrome-devtools_* for navigation, screenshots, console

Slash Commands

Built-in commands provide shortcuts for common workflows.

/init-deep

Initializes a hierarchical AGENTS.md knowledge base for your project.

opencode /init-deep

This analyzes your codebase structure and generates a comprehensive AGENTS.md with:

• Project architecture overview
• Build and test commands
• Code style conventions
• File organization patterns

/ralph-loop

Starts a self-referential development loop that continues until completion.

opencode /ralph-loop "Implement user authentication"

The loop:

1. Creates a plan
2. Executes first step
3. Evaluates progress
4. Adjusts plan if needed
5. Continues until done

/ulw-loop

Ultrawork loop mode for maximum productivity on well-defined tasks.

opencode /ulw-loop "Refactor the API handlers"

Emphasizes speed and throughput for routine work.

/cancel-ralph

Cancels an active Ralph Loop.

opencode /cancel-ralph

Use when a loop has gone off track or you need to regain control.

/refactor

Intelligent refactoring with LSP analysis, AST transformations, and verification.

opencode /refactor "Extract the validation logic into separate module"

Workflow:

1. Analyzes current code structure
2. Identifies dependencies via LSP
3. Creates refactoring plan
4. Applies AST transformations
5. Runs tests to verify
6. Fixes any issues

/start-work

Starts a work session from an existing Prometheus plan.

opencode /start-work --plan feature-auth.md

Loads the plan and begins systematic execution.

/stop-continuation

Stops all continuation mechanisms (ralph loop, todo continuation, boulder) for the current session.

opencode /stop-continuation

Use when you need to pause and reassess.

/handoff

Creates a detailed context summary for continuing work in a new session.

opencode /handoff > handoff.md

The handoff includes:

• Current task state
• Completed steps
• Remaining work
• Important context and decisions
• File references

Workflow Examples

Starting a New Project

# Initialize OpenCode configuration
opencode /init-deep

# Create initial structure
opencode "Set up a Next.js project with TypeScript, Tailwind, and Vitest"

# Add first feature with TDD
opencode "Add a homepage with a hero section using TDD" --load-skills test-driven-development

# Verify everything works
opencode /refactor "Ensure all imports are consistent"

TDD Workflow with OpenCode

# 1. Start with the TDD skill loaded
opencode "Add user login functionality" --category visual-engineering --load-skills test-driven-development

# The agent will:
# - Write a failing test for login form
# - Implement the form component
# - Write a failing test for form submission
# - Implement submission logic
# - Continue until feature complete

Debugging a Complex Issue

# Load the debugging skill
opencode "The checkout process fails intermittently" --load-skills systematic-debugging

# The agent will:
# - Reproduce the issue
# - Check logs and error traces
# - Form hypotheses
# - Test each hypothesis
# - Implement and verify fix

Code Review and Refactoring

# Get a comprehensive review
opencode "Review the payment processing module for security and performance"

# Apply refactoring
opencode /refactor "Simplify the error handling in payment processing"

# Verify with tests
opencode "Run all tests related to payments and ensure they pass"

Multi-Agent Parallel Development

# Decompose a large feature
opencode "We need to add a dashboard with charts, data tables, and filters"

# Agent might spawn background tasks:
# - Task 1: Build chart components
# - Task 2: Build data table with sorting
# - Task 3: Implement filter logic

# Then integrate all pieces

Best Practices

Prompt Engineering for OpenCode

Be specific about scope:

Good: "Add a validation function for email addresses in utils/validation.ts"
Bad: "Add email validation"

Provide context:

Good: "In the context of the user registration flow, add password strength validation"
Bad: "Validate passwords"

Specify constraints:

Good: "Add the feature without adding new dependencies"
Bad: "Add the feature"

Request verification:

Good: "Add the feature and run the related tests to verify"
Bad: "Add the feature"

Effective Skill Usage

• Load relevant skills at the start of complex tasks
• Let skills guide the workflow rather than micromanaging
• Trust the skill's process even when it seems verbose
• Use verification-before-completion before claiming done

Session Management Tips

• Keep related work in the same session for context
• Use session search to find past solutions
• Create handoffs when switching between major tasks
• Review session history to understand what was tried

Context Window Optimization

• Close irrelevant files before starting
• Use specific file paths rather than broad searches
• Let OpenCode manage which files it needs to read
• Break large tasks into smaller, focused sessions

Troubleshooting

Common Issues and Solutions

Agent loses context mid-task:

• Break the task into smaller pieces
• Use handoffs to preserve state
• Restart with a fresh session and handoff file

Skills not loading:

• Check .opencode/skills/ directory exists
• Verify skill files have correct format
• Look for syntax errors in skill markdown

Tools failing with permission errors:

• Check file permissions
• Verify working directory is correct
• Ensure API keys are set

Unexpected behavior:

• Check AGENTS.md for conflicting conventions
• Review session history for context
• Use /stop-continuation to reset state

Debugging OpenCode Behavior

Enable verbose logging:

OPENCODE_LOG_LEVEL=debug opencode "your prompt"

Check tool invocations in the session output to see exactly what OpenCode is doing.

Reset and Recovery

Reset a session:

opencode "Reset the current task and start fresh"

Recover from bad state:

opencode /stop-continuation
opencode "Undo the last change and explain what went wrong"

Full reset:

rm -rf ~/.opencode/sessions/*
opencode "Start fresh"

---

OpenCode transforms development from a manual process into a collaborative partnership with AI. By understanding its tools, skills, and best practices, you can leverage its full potential while maintaining control over your codebase.