Add comprehensive .gitignore and reorganize README with Installation before Zen

This commit is contained in:
Wesam Abousaid
2026-02-26 22:10:44 +01:00
19 changed files with 8628 additions and 1 deletions
+148
View File
@@ -0,0 +1,148 @@
# OpenCode Everything You Need to Know - .gitignore
# This file specifies intentionally untracked files that Git should ignore
# ==================== SYSTEM FILES ====================
# macOS system files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
.AppleDouble
.LSOverride
# Windows system files
Thumbs.db
ehthumbs.db
Desktop.ini
$RECYCLE.BIN/
# Linux temporary files
*~
*.swp
*.swo
# ==================== EDITOR/IDE FILES ====================
# Visual Studio Code
.vscode/
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
*.code-workspace
# IntelliJ IDEA
.idea/
*.iml
*.iws
*.ipr
# Other editors
.project
.classpath
.settings/
# ==================== OPENCODE RUNTIME FILES ====================
# OpenCode configuration and runtime files (user-specific)
.opencode/node_modules/
.opencode/package.json
.opencode/bun.lock
.opencode/.gitignore
.opencode/cache/
.opencode/logs/
.opencode/sessions/
.opencode/config.local.json
.opencode/state.json
.opencode/agents/
.opencode/commands/
.opencode/skills/
# ==================== DEPENDENCIES ====================
# Node.js dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
package-lock.json
yarn.lock
bun.lock
# ==================== BUILD OUTPUTS ====================
# Documentation build outputs
docs/_build/
docs/_site/
docs/_out/
# General build outputs
dist/
build/
.out/
.next/
.nuxt/
# ==================== ENVIRONMENT FILES ====================
# Environment variables (never commit secrets!)
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
.env.*.local
# ==================== TEMPORARY FILES ====================
# Temporary files
tmp/
temp/
*.tmp
*.temp
*.bak
*.backup
*.old
# ==================== LOGS ====================
# Log files
*.log
logs/
.opencode/logs/
# ==================== COVERAGE REPORTS ====================
# Test coverage
coverage/
.nyc_output
*.lcov
# ==================== OS-SPECIFIC IGNORES ====================
# Network files
Network Trash Folder
Temporary Items
.apdisk
# ==================== PROJECT-SPECIFIC ====================
# Example projects dependencies
examples/*/node_modules
examples/*/package-lock.json
examples/*/yarn.lock
examples/*/bun.lock
# Plugin development
plugins/*/node_modules
plugins/*/dist
plugins/*/build
# MCP server development
mcp-servers/*/node_modules
mcp-servers/*/dist
mcp-servers/*/build
# Image processing cache
Images/.DS_Store
Images/thumbnails/
# TypeScript cache
*.tsbuildinfo
# ==================== PERSONAL WORKSPACE ====================
# Personal workspace files (optional - comment out if you want to track these)
# .workspace/
# personal-notes.md
# todo.md
+53
View File
@@ -0,0 +1,53 @@
name: Code Reviewer
description: Specialized agent for thorough code reviews
model: claude-sonnet-4.6
temperature: 0.1
verbosity: high
## Instructions
You are a senior code reviewer. Your job is to:
1. Review code for bugs, security issues, and performance problems
2. Suggest improvements following best practices
3. Focus on readability, maintainability, and scalability
4. Provide specific, actionable feedback
## Tools
- read: true
- ask: true
- write: false # Reviewer doesn't make changes
- edit: false
- bash: false
## Examples
When reviewing authentication code, check for:
- Input validation
- Password hashing
- Session management
- Error handling
When reviewing API code, check for:
- Proper HTTP status codes
- Request/response validation
- Error handling and logging
- Rate limiting considerations
When reviewing database code, check for:
- SQL injection prevention
- Proper indexing
- Transaction management
- Connection pooling
## Review Process
1. **Security First**: Identify security vulnerabilities
2. **Performance**: Check for bottlenecks and inefficiencies
3. **Maintainability**: Assess code organization and clarity
4. **Testing**: Verify adequate test coverage
5. **Documentation**: Check for proper comments and docs
## Output Format
For each issue found:
- **Severity**: Critical/High/Medium/Low
- **Location**: File and line number
- **Issue**: Description of the problem
- **Suggestion**: Specific fix with code example
- **Rationale**: Why this change improves the code
+43
View File
@@ -0,0 +1,43 @@
---
name: "Create Pull Request"
description: "Automated PR creation with branch management and commit splitting"
version: "1.0.0"
tools: ["read", "write", "edit", "bash"]
permissions: ["project"]
---
# Create Pull Request
Automatically creates a pull request from current changes with proper commit hygiene.
## Behavior
1. Check for uncommitted changes
2. Create feature branch based on current changes
3. Format code using project formatter (Biome/Prettier/ESLint)
4. Analyze changes and split into logical commits
5. Create descriptive commit messages
6. Push branch to remote
7. Create pull request with summary and test plan
## Guidelines for Commit Splitting
- Split by feature, component, or concern
- Keep related changes together
- Separate refactoring from feature work
- Ensure each commit stands alone
- Follow conventional commit format
## Examples
### Basic PR creation
```bash
/pr
```
### PR with specific branch name
```bash
/pr feature/user-authentication
```
### PR with custom description
```bash
/pr --description "Add user authentication with JWT"
```
+41
View File
@@ -0,0 +1,41 @@
---
name: "Code Review"
description: "Comprehensive code review with security, performance, and style checks"
version: "1.0.0"
tools: ["read", "ask"]
permissions: ["project"]
---
# Code Review
Perform thorough code review focusing on security, performance, and maintainability.
## Behavior
1. Analyze the specified file or directory
2. Check for security vulnerabilities (OWASP Top 10)
3. Review performance implications and bottlenecks
4. Assess code style and consistency
5. Suggest specific improvements with examples
6. Provide actionable recommendations
## Guidelines
- Focus on critical issues first
- Provide code examples for fixes
- Consider project-specific conventions
- Balance perfection with practicality
## Examples
### Review a specific file
```bash
/review @src/auth/index.ts
```
### Review changed files
```bash
/review changed
```
### Review with specific focus
```bash
/review @src/ --focus security
```
+172
View File
@@ -0,0 +1,172 @@
# OpenCode Agent Guidelines
This document helps OpenCode understand your project's structure, conventions, and requirements.
## Project Overview
**Project Type**: [Describe your project type, e.g., React/TypeScript web application]
**Purpose**: [Brief description of what the project does]
**Key Technologies**: [List main technologies and frameworks]
## Code Conventions
### File Structure
```
src/
├── components/ # React components
├── pages/ # Page components
├── utils/ # Utility functions
├── hooks/ # Custom React hooks
├── types/ # TypeScript type definitions
└── styles/ # CSS/SCSS files
```
### Naming Conventions
- **Files**: kebab-case (e.g., `user-profile.tsx`)
- **Components**: PascalCase (e.g., `UserProfile`)
- **Functions**: camelCase (e.g., `formatUserName`)
- **Constants**: UPPER_SNAKE_CASE (e.g., `MAX_RETRY_COUNT`)
- **Types**: PascalCase with `Type` suffix (e.g., `UserProfileType`)
### Code Style
- **Indentation**: 2 spaces
- **Semicolons**: Yes
- **Quotes**: Single quotes for strings
- **Line length**: 100 characters max
- **Trailing commas**: Yes in objects and arrays
## Development Guidelines
### Testing
- Write unit tests for all utility functions
- Use Jest and React Testing Library
- Test files should be next to source files (e.g., `component.tsx` and `component.test.tsx`)
- Aim for 80%+ test coverage
### Error Handling
- Use try/catch for async operations
- Log errors to console in development
- Show user-friendly error messages in production
- Validate all external inputs
### Security
- Never commit secrets or API keys
- Validate and sanitize all user inputs
- Use environment variables for configuration
- Implement proper authentication and authorization
### Performance
- Use React.memo() for expensive components
- Implement code splitting for large bundles
- Optimize images and assets
- Monitor bundle size
## Project-Specific Rules
### Do's
- Use TypeScript strict mode
- Follow the existing component patterns
- Add comments for complex logic
- Update documentation when changing APIs
- Run tests before committing
### Don'ts
- Don't use `any` type in TypeScript
- Don't commit console.log statements
- Don't modify multiple concerns in one commit
- Don't ignore TypeScript/ESLint warnings
- Don't add dependencies without team approval
## Common Patterns
### API Calls
```typescript
// Use this pattern for API calls
async function fetchUser(id: string): Promise<User> {
try {
const response = await api.get(`/users/${id}`);
return response.data;
} catch (error) {
console.error('Failed to fetch user:', error);
throw new Error('User not found');
}
}
```
### Component Structure
```typescript
// Use this component structure
interface UserProfileProps {
userId: string;
onUpdate?: () => void;
}
export function UserProfile({ userId, onUpdate }: UserProfileProps) {
const [user, setUser] = useState<User | null>(null);
useEffect(() => {
loadUser();
}, [userId]);
async function loadUser() {
const data = await fetchUser(userId);
setUser(data);
}
if (!user) return <LoadingSpinner />;
return (
<div className="user-profile">
<h2>{user.name}</h2>
{/* ... */}
</div>
);
}
```
## Tool Configuration
### Formatters
- **Prettier**: Use project prettier config
- **ESLint**: Follow Airbnb style guide with custom rules
- **TypeScript**: Strict mode enabled
### Build Tools
- **Bundler**: Vite
- **Package Manager**: npm
- **CI/CD**: GitHub Actions
## Getting Started
1. **Install dependencies**: `npm install`
2. **Start development server**: `npm run dev`
3. **Run tests**: `npm test`
4. **Build for production**: `npm run build`
5. **Check code quality**: `npm run lint`
## Helpful Commands
```bash
# Format code
npm run format
# Type check
npm run type-check
# Run all checks
npm run check
# Update dependencies
npm run update-deps
```
## Contact & Support
- **Team**: [Your team name]
- **Repository**: [GitHub repo URL]
- **Documentation**: [Docs URL]
- **Slack**: [Slack channel]
---
*This document is automatically generated and should be updated as the project evolves.*
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 195 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 205 KiB

+1 -1
View File
@@ -1,6 +1,6 @@
MIT License
Copyright (c) 2026 Wesam Abousaid
Copyright (c) 2026 OpenCode Everything You Need to Know
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
+3968
View File
File diff suppressed because it is too large Load Diff
+532
View File
@@ -0,0 +1,532 @@
# AI Agents Guide
## 🎯 Understanding OpenCode Agents
**What are Agents?**
Agents in OpenCode are specialized AI personas with specific:
- **Prompts**: Custom instructions and behavior guidelines
- **Tools**: Permission sets for file access, shell commands, etc.
- **Models**: Dedicated or shared AI models
- **Temperature**: Creativity vs determinism settings
- **Verbosity**: Detail level in responses
**Agent Types:**
1. **Primary Agents**: Main conversation agents (cycle with Tab)
2. **Subagents**: Specialized agents invoked via `@mention`
3. **System Agents**: Hidden agents for compaction, titling, etc.
## 🤖 Built-in Agents
### Build Agent (`primary`):
- **Default mode**: Full tool access (write, edit, bash)
- **Purpose**: Implementation and code changes
- **Tools**: All enabled (configurable)
- **Temperature**: 0.1 (deterministic)
### Plan Agent (`primary`):
- **Activation**: Press `Tab` to switch
- **Purpose**: Analysis, planning, brainstorming
- **Tools**: Limited (typically `ask` only by default)
- **Temperature**: 0.3 (slightly creative)
### General Subagent (`subagent`):
- **Invocation**: Automatically for multi-step tasks
- **Purpose**: Complex task execution
- **Tools**: Full access (like Build)
- **Use Case**: "Research and implement X"
### Explore Subagent (`subagent`):
- **Invocation**: For codebase exploration
- **Purpose**: Read-only analysis
- **Tools**: Read-only file access
- **Use Case**: "Explain this codebase"
## 🔄 Agent Workflow Patterns
### Pattern 1: Plan → Build Cycle
```bash
# 1. Start in Plan mode (default or Tab)
[Plan] How would you implement user authentication?
# 2. Review and refine plan
Add JWT token refresh mechanism
# 3. Switch to Build mode (Tab)
[Build] Implement the authentication system as planned
```
### Pattern 2: Multi-Agent Collaboration
```bash
# Use @mentions to invoke specific agents
@explore Analyze the security vulnerabilities in @src/auth/
@general Based on the analysis, create a security fix plan
[Build] Implement the security fixes
```
### Pattern 3: Specialized Task Delegation
```bash
# Create custom agents for specific tasks
@code-reviewer Review @src/components/Button.tsx
@test-writer Write unit tests for @src/utils/validation.ts
@documentation Generate API docs for @src/api/
```
## 🛠️ Creating Custom Agents
### Method 1: Markdown Configuration (Recommended)
```markdown
# ~/.config/opencode/agents/code-reviewer.md
name: Code Reviewer
description: Specialized agent for thorough code reviews
model: claude-sonnet-4.6
temperature: 0.2
verbosity: high
## Instructions
You are a senior code reviewer. Your job is to:
1. Review code for bugs, security issues, and performance problems
2. Suggest improvements following best practices
3. Focus on readability, maintainability, and scalability
4. Provide specific, actionable feedback
## Tools
- read: true
- ask: true
- write: false # Reviewer doesn't make changes
- edit: false
- bash: false
## Examples
When reviewing authentication code, check for:
- Input validation
- Password hashing
- Session management
- Error handling
```
### Method 2: JSON Configuration
```json
// ~/.config/opencode/agents/code-reviewer.json
{
"name": "Code Reviewer",
"description": "Specialized agent for thorough code reviews",
"prompt": "You are a senior code reviewer...",
"model": "claude-sonnet-4.6",
"temperature": 0.2,
"verbosity": "high",
"tools": {
"read": true,
"ask": true,
"write": false,
"edit": false,
"bash": false
}
}
```
### Method 3: Project-Specific Agents
```bash
# Create in project root
mkdir -p .opencode/agents
touch .opencode/agents/project-specific.md
# Project agents override global agents
```
## ⚙️ Agent Configuration Options
### Tool Permissions:
```yaml
tools:
read: true # Read files
ask: true # Ask clarifying questions
write: true # Create new files
edit: true # Edit existing files
bash: true # Execute shell commands
skill: ["git", "test"] # Specific skills only
```
### Model Settings:
```yaml
model: gpt-5.2-codex # Specific model
# or
model_config:
provider: opencode
family: claude
version: sonnet-4.6
```
### Behavior Settings:
```yaml
temperature: 0.1 # 0.0-1.0 (lower = more deterministic)
verbosity: medium # low, medium, high, verbose
max_tokens: 4000 # Response length limit
thinking: enabled # Show thinking steps
```
## 🔗 Advanced Agent Patterns
### 1. Chain of Agents:
```bash
# Sequential agent workflow
@explore Analyze the codebase structure
@architect Design the new feature architecture
@implementer Write the implementation code
@tester Create test cases
@reviewer Review the complete implementation
```
### 2. Parallel Agent Teams:
```bash
# Multiple agents working on different aspects
@frontend Implement React components for the UI
@backend Create API endpoints and database models
@devops Set up deployment configuration
@documentation Write user and developer docs
```
### 3. Conditional Agent Routing:
```bash
# Based on task type, route to appropriate agent
If it's a bug fix: @debugger
If it's a new feature: @implementer
If it's documentation: @technical-writer
If it's refactoring: @refactor-specialist
```
## 📋 Agent Management Commands
### List Available Agents:
```bash
/agents
# Shows: Build, Plan, code-reviewer, test-writer, etc.
```
### Switch Agents:
```bash
# Tab cycles between primary agents
Tab
# Direct selection
/agents select code-reviewer
```
### Create New Agent:
```bash
# Interactive creation
/agents create
# Follow prompts for name, description, tools, etc.
```
### Edit Existing Agent:
```bash
# Edit configuration
/agents edit code-reviewer
# Opens in $EDITOR
```
### Delete Agent:
```bash
/agents delete old-agent-name
```
## 📝 Pre-built Agent Examples
### Code Reviewer Agent:
```markdown
# .opencode/agents/code-reviewer.md
name: Code Reviewer
model: claude-sonnet-4.6
temperature: 0.1
## Instructions
You are a meticulous code reviewer. For each file:
1. Check for security vulnerabilities (OWASP Top 10)
2. Verify error handling and edge cases
3. Assess performance implications
4. Review code style and consistency
5. Suggest improvements with examples
Focus on:
- Input validation and sanitization
- Authentication and authorization
- Data privacy and encryption
- Resource management
- Logging and monitoring
```
### Test Writer Agent:
```markdown
# .opencode/agents/test-writer.md
name: Test Writer
model: gpt-5.2-codex
temperature: 0.3
## Instructions
You are a test-driven development expert. Create:
1. Unit tests for individual functions
2. Integration tests for component interactions
3. End-to-end tests for user workflows
4. Performance and load tests
5. Security and penetration tests
Principles:
- Test behavior, not implementation
- Use realistic test data
- Mock external dependencies
- Achieve high coverage
- Follow AAA pattern (Arrange, Act, Assert)
```
### Documentation Agent:
```markdown
# .opencode/agents/documentation.md
name: Documentation Specialist
model: gemini-2.5-pro
temperature: 0.4
## Instructions
You create comprehensive, user-friendly documentation:
1. API documentation with examples
2. User guides with step-by-step instructions
3. Architecture diagrams and explanations
4. Troubleshooting guides
5. Changelogs and release notes
Style:
- Clear, concise language
- Practical examples
- Visual aids when helpful
- Multiple formats (markdown, HTML, PDF-ready)
```
## ⚡ Agent Performance Optimization
### 1. Model Selection:
```yaml
# Match agent to appropriate model
code-reviewer: claude-sonnet-4.6 # Good for analysis
test-writer: gpt-5.2-codex # Good for code generation
documentation: gemini-2.5-pro # Good for creative writing
```
### 2. Temperature Tuning:
```yaml
# Lower for deterministic tasks
code-reviewer: 0.1
refactoring: 0.2
# Higher for creative tasks
brainstorming: 0.7
naming: 0.5
```
### 3. Tool Restriction:
```yaml
# Limit tools to prevent accidents
reviewer: [read, ask] # Read-only review
implementer: [read, write, edit] # Can modify code
admin: [read, write, edit, bash] # Full access
```
### 4. Verbosity Control:
```yaml
# Adjust detail level
debugging: verbose # Show all reasoning steps
production: medium # Balanced detail
automation: low # Minimal output
```
## 🎯 Agent Best Practices
### 1. Start Simple:
- Begin with basic agents (reviewer, implementer)
- Add complexity gradually
- Test each agent thoroughly
### 2. Clear Prompts:
- Be specific about agent's role
- Include examples of good output
- Define boundaries and limitations
### 3. Security First:
- Restrict bash access for sensitive agents
- Use project-specific agents for client work
- Review agent permissions regularly
### 4. Performance Monitoring:
- Track token usage per agent
- Monitor response times
- Adjust models based on performance
### 5. Iterative Improvement:
- Collect feedback from agent usage
- Refine prompts based on results
- Share successful agents with team
## 🔧 Common Agent Use Cases
### Code Review Workflow:
```bash
# 1. Create PR with changes
!git checkout -b feature/new-auth
# ... make changes ...
# 2. Run code review
@code-reviewer Review all changed files
# 3. Address feedback
[Build] Fix the security issues identified
# 4. Run tests
@test-writer Add tests for the new authentication
# 5. Final review
@code-reviewer Verify all issues are resolved
```
### Feature Development Workflow:
```bash
# 1. Planning phase
@explore Analyze current codebase structure
@architect Design new feature architecture
# 2. Implementation phase
@frontend Implement UI components
@backend Create API endpoints
@database Design database schema
# 3. Testing phase
@test-writer Create comprehensive test suite
@security-reviewer Check for vulnerabilities
# 4. Documentation phase
@documentation Write user and developer docs
```
### Bug Fix Workflow:
```bash
# 1. Diagnosis
@debugger Analyze the bug report and logs
@explore Find related code and dependencies
# 2. Solution design
@architect Design the fix with minimal impact
@reviewer Review the proposed solution
# 3. Implementation
[Build] Implement the fix
# 4. Verification
@test-writer Create regression tests
@reviewer Verify the fix doesn't break anything
```
## 🐛 Troubleshooting Agents
### Common Issues:
**1. Agent not responding**
```bash
# Check agent configuration
/agents list
# Verify model availability
/models
```
**2. Incorrect tool permissions**
```bash
# Check agent tools
/agents show agent-name
# Edit permissions
/agents edit agent-name
```
**3. Poor quality responses**
```bash
# Adjust temperature
/agents edit agent-name
# Set temperature: 0.1-0.3 for code, 0.4-0.7 for creative
# Try different model
/agents edit agent-name
# Change model to better fit task
```
**4. Agent using wrong context**
```bash
# Be specific in invocation
@agent-name Please review @specific-file.ts
# Provide clear boundaries
Focus only on security aspects, not code style
```
### Debug Commands:
```bash
# See agent thinking process
/thinking on
# Check agent configuration
!cat ~/.config/opencode/agents/agent-name.md
# Test agent with simple task
@agent-name What's 2+2?
```
> **💡 Pro Tip**: Create a "debug" agent with verbose output and thinking enabled to understand how other agents are working. This is invaluable for troubleshooting complex agent interactions.
## 📚 Agent Templates Repository
Consider creating a repository of agent templates for common tasks:
```
agents-templates/
├── code-review/
│ ├── security-reviewer.md
│ ├── performance-reviewer.md
│ └── style-reviewer.md
├── development/
│ ├── frontend-developer.md
│ ├── backend-developer.md
│ └── fullstack-developer.md
├── testing/
│ ├── unit-test-writer.md
│ ├── integration-test-writer.md
│ └── e2e-test-writer.md
└── documentation/
├── api-docs-writer.md
├── user-guide-writer.md
└── architecture-docs-writer.md
```
Share these with your team for consistent AI-assisted development across projects.
---
## 📚 What's Next?
- [Skills Guide](SKILLS-GUIDE.md) - Create reusable workflows
- [Workflows Guide](WORKFLOWS.md) - Design development workflows
- [MCP Guide](MCP-GUIDE.md) - Extend OpenCode with servers
- [Back to Main Guide](../README.md)
---
*Last updated: February 2026*
+625
View File
@@ -0,0 +1,625 @@
# Commands Reference Guide
## 🎯 Overview
OpenCode's command system provides powerful control over your AI-assisted development workflow. This guide covers all built-in and custom commands.
## 📋 Built-in Slash Commands
### Essential Commands:
| Command | Purpose | Example |
|---------|---------|---------|
| `/help` | Show help and available commands | `/help` |
| `/connect` | Add or configure LLM providers | `/connect` |
| `/init` | Initialize project with AGENTS.md | `/init` |
| `/undo` | Undo last change (Git-based) | `/undo` |
| `/redo` | Redo last undone change | `/redo` |
| `/share` | Create shareable conversation link | `/share` |
| `/export` | Export conversation to markdown | `/export` |
| `/compact` | Summarize long conversation | `/compact` |
| `/editor` | Open external editor for message | `/editor` |
### Provider & Model Commands:
| Command | Purpose | Example |
|---------|---------|---------|
| `/models` | List available models | `/models` |
| `/sessions` | Manage conversation sessions | `/sessions` |
| `/thinking` | Toggle thinking steps display | `/thinking off` |
| `/themes` | Change TUI theme | `/themes` |
| `/config` | View/edit configuration | `/config` |
### Agent Commands:
| Command | Purpose | Example |
|---------|---------|---------|
| `/agents` | List available agents | `/agents` |
| `/agents select` | Switch to specific agent | `/agents select code-reviewer` |
| `/agents create` | Create new agent | `/agents create` |
| `/agents edit` | Edit agent configuration | `/agents edit reviewer` |
| `/agents delete` | Remove agent | `/agents delete old-agent` |
### Skill Commands:
| Command | Purpose | Example |
|---------|---------|---------|
| `/skills` | List available skills | `/skills` |
| `/skills install` | Install new skill | `/skills install url` |
| `/skills update` | Update skills | `/skills update` |
| `/skills test` | Test skill execution | `/skills test review` |
## 💻 CLI Commands
### Basic CLI Usage:
```bash
# Start interactive TUI
opencode
# Run single command non-interactively
opencode run "Fix the bug in @src/utils/validation.ts"
# Start in specific directory
opencode /path/to/project
# Use specific model
opencode --model gpt-5.2-codex
```
### Advanced CLI Commands:
| Command | Purpose | Example |
|---------|---------|---------|
| `opencode serve` | Start headless HTTP server | `opencode serve --port 8080` |
| `opencode web` | Start web interface | `opencode web` |
| `opencode stats` | Show usage statistics | `opencode stats` |
| `opencode github` | GitHub integration | `opencode github install` |
| `opencode agent` | Agent management | `opencode agent create` |
| `opencode models` | Model management | `opencode models list` |
### Server Mode:
```bash
# Start headless server
opencode serve --port 3000 --host 0.0.0.0
# API endpoints:
# POST /v1/chat - Send message
# GET /v1/status - Server status
# GET /v1/models - Available models
# Example curl request:
curl -X POST http://localhost:3000/v1/chat \
-H "Content-Type: application/json" \
-d '{"message": "Hello OpenCode", "model": "gpt-5.2-codex"}'
```
### Web Interface:
```bash
# Start web server
opencode web
# Open in browser: http://localhost:3000
# Provides web-based TUI interface
```
## 🛠️ Creating Custom Commands
### Method 1: Markdown Commands
```markdown
# .opencode/commands/analyze.md
# Code Analysis Command
Analyze code for performance issues and suggest optimizations.
## Usage
```bash
/analyze [file]
```
## Behavior
1. Analyze specified file for performance bottlenecks
2. Identify memory leaks and CPU-intensive operations
3. Suggest optimizations with code examples
4. Provide benchmarking recommendations
## Examples
```bash
/analyze @src/utils/processing.ts
/analyze @src/ --focus memory
```
```
### Method 2: JSON Configuration
```json
// .opencode/commands/optimize.json
{
"name": "optimize",
"description": "Optimize code performance",
"command": "analyze the code in $1 for optimization opportunities",
"tools": ["read", "ask"],
"agent": "performance-reviewer"
}
```
### Method 3: Shell Script Commands
```bash
# .opencode/commands/deploy.sh
#!/bin/bash
# Custom deploy command
echo "Starting deployment..."
!git push origin main
!npm run build
!docker build -t myapp .
echo "Deployment complete!"
```
### Command Arguments:
```markdown
# Command with arguments
## Behavior
- $ARGUMENTS: All arguments as string
- $1, $2, $3: Positional arguments
- $OPTIONS: Parsed options
## Examples
```bash
/command arg1 arg2 --option value
# $ARGUMENTS = "arg1 arg2 --option value"
# $1 = "arg1", $2 = "arg2"
```
```
## 🔗 Command Chaining & Pipelines
### Sequential Commands:
```bash
# Run commands in sequence
/init && /analyze @src/ && /review changed
```
### Conditional Execution:
```bash
# Run command only if previous succeeded
/test @src/ && /deploy
# Run alternative on failure
/test @src/ || /fix-tests
```
### Command Output Piping:
```bash
# Use output of one command as input to another
!git status | /analyze-changes
# Capture and reuse output
OUTPUT=$(/analyze @src/)
echo "Analysis complete: $OUTPUT"
```
## ⚡ Advanced Command Patterns
### 1. Interactive Commands:
```markdown
# .opencode/commands/setup.md
# Interactive Setup Command
## Behavior
1. Ask for project type (React, Node.js, Python, etc.)
2. Request framework preferences
3. Configure testing setup
4. Set up deployment configuration
5. Generate project structure
## Interactive Prompts
- "What type of project are you creating?"
- "Which testing framework would you like?"
- "Do you need Docker configuration?"
```
```bash
# Usage
/setup
# Follow interactive prompts
```
### 2. File Generation Commands:
```markdown
# .opencode/commands/generate.md
# File Generation Command
## Behavior
1. Create component/file based on template
2. Apply project-specific conventions
3. Generate tests for the component
4. Update index files/exports
5. Create documentation stub
## Templates
- component: React/Vue component
- api: API endpoint handler
- util: Utility function
- test: Test file
```
```bash
# Usage
/generate component Button
/generate api users --method GET
```
### 3. Workflow Automation Commands:
```markdown
# .opencode/commands/workflow.md
# Complete Development Workflow
## Behavior
1. Check current git status
2. Create feature branch
3. Implement feature using TDD
4. Run tests and fix issues
5. Create pull request
6. Request code review
## Steps
```bash
!git checkout -b feature/$1
/tdd "Implement $1"
/test
/pr
/review
```
```
```bash
# Usage
/workflow "user-authentication"
```
## 🔒 Command Security & Permissions
### Permission Levels:
```yaml
# Command permission configuration
permissions:
read: true # Can read files
write: true # Can write files
edit: true # Can edit files
bash: true # Can execute shell commands
network: false # Can make network requests
env: false # Can access environment variables
```
### Secure Command Design:
```markdown
# Security Guidelines
## Do:
- Validate all input arguments
- Sanitize file paths
- Use minimal required permissions
- Log command execution
## Don't:
- Execute arbitrary shell commands
- Access sensitive environment variables
- Make unauthorized network requests
- Modify system files outside project
```
### Command Auditing:
```bash
# Enable command audit logging
export OPENCODE_AUDIT_LOG=/var/log/opencode-commands.log
# View command history
!cat ~/.local/share/opencode/command-history.log
# Audit specific user/command
grep "user@example.com" /var/log/opencode-commands.log | grep "/deploy"
```
## ⚡ Command Performance Optimization
### Caching Commands:
```bash
# Cache expensive command results
if [ ! -f /tmp/analysis-cache.json ]; then
/analyze @src/ > /tmp/analysis-cache.json
fi
cat /tmp/analysis-cache.json
```
### Parallel Command Execution:
```bash
# Run commands in parallel
/analyze @src/components/ &
/analyze @src/utils/ &
/analyze @src/api/ &
wait
echo "All analyses complete"
```
### Incremental Commands:
```markdown
# Incremental Analysis Command
## Behavior
1. Check for previous analysis results
2. Only analyze changed files since last run
3. Merge new results with cached results
4. Update cache with latest analysis
## Cache Management
- Store results in .opencode/cache/
- Use file modification times
- Invalidate cache on dependency changes
```
## 🧪 Command Testing & Validation
### Unit Testing Commands:
```bash
# Test command with sample input
/commands test analyze --input @test-data.json
# Test command output validation
/commands test deploy --expected "Deployment successful"
# Test command error handling
/commands test analyze --error "File not found"
```
### Integration Testing:
```bash
# Test command in CI/CD pipeline
opencode run "/test @src/" > test-results.json
if [ $? -eq 0 ]; then
echo "Tests passed"
else
echo "Tests failed"
exit 1
fi
```
### Performance Testing:
```bash
# Benchmark command execution time
time opencode run "/analyze @src/"
# Profile command resource usage
/commands profile optimize --memory --cpu
```
## 📖 Command Documentation
### Command Help System:
```markdown
# .opencode/commands/analyze.md
# Code Analysis Command
## Description
Analyzes code for performance issues, security vulnerabilities, and optimization opportunities.
## Syntax
```bash
/analyze [options] <file|directory>
```
## Options
- `--focus <area>`: Focus on specific area (performance, security, style)
- `--output <format>`: Output format (markdown, json, html)
- `--verbose`: Enable detailed output
- `--fix`: Automatically fix issues where possible
## Examples
### Basic usage
```bash
/analyze @src/utils/validation.ts
```
### Focus on security
```bash
/analyze @src/ --focus security
```
### Output as JSON
```bash
/analyze @src/api/ --output json
```
## Exit Codes
- 0: Success
- 1: Analysis failed
- 2: Invalid arguments
- 3: File not found
## See Also
- [/review](#review): Code review command
- [/test](#test): Testing command
- [/audit](#audit): Security audit command
```
### Auto-generated Documentation:
```bash
# Generate command documentation
/commands docs --output docs/commands.md
# Update command help
/commands update-help
# Validate command documentation
/commands validate-docs
```
## 🌐 Command Ecosystem Management
### Command Registry:
```bash
# Register custom commands
/commands register ./custom-commands/
# List registered commands
/commands list --registered
# Search commands
/commands search "analysis"
# Command categories
/commands list --category development
/commands list --category testing
/commands list --category deployment
```
### Command Versioning:
```markdown
# Command version metadata
---
name: "analyze"
version: "2.1.0"
changelog: |
v2.1.0: Added security scanning
v2.0.0: Performance improvements
v1.0.0: Initial release
compatibility: "opencode>=1.5.0"
dependencies:
- "review>=1.2.0"
- "test>=1.1.0"
---
```
### Command Dependencies:
```yaml
# Command dependency management
dependencies:
required:
- git
- node
- npm
optional:
- docker
- aws-cli
conflicts:
- old-analyze-command
```
## 🐛 Troubleshooting Commands
### Common Issues:
**1. Command not found**
```bash
# Check command location
ls -la .opencode/commands/
# Reload commands
/commands reload
# Check command permissions
chmod +x .opencode/commands/command.sh
```
**2. Command execution failed**
```bash
# Enable debug mode
/commands run command-name --debug
# Check command logs
!cat ~/.local/share/opencode/command-debug.log
# Test command manually
!bash .opencode/commands/command.sh --test
```
**3. Permission errors**
```bash
# Check command permissions
/commands permissions command-name
# Run with elevated permissions (careful!)
/commands run command-name --sudo
```
**4. Command conflicts**
```bash
# List conflicting commands
/commands conflicts
# Disable conflicting command
/commands disable old-command
```
### Debug Commands:
```bash
# Dry run command
/commands run command-name --dry-run
# Step through command execution
/commands run command-name --step
# Profile command performance
/commands run command-name --profile
# Trace command execution
/commands run command-name --trace
```
### Command Recovery:
```bash
# Backup command configuration
/commands backup --output commands-backup.tar.gz
# Restore commands from backup
/commands restore commands-backup.tar.gz
# Reset commands to default
/commands reset --confirm
```
> **💡 Pro Tip**: Create a "command-tester" command that validates other commands. This helps maintain command quality and catch issues before they affect your workflow.
## 🎯 Best Practices for Command Design
### 1. Keep Commands Focused:
- One command, one responsibility
- Clear input/output expectations
- Minimal side effects
### 2. Design for Composability:
- Output that can be piped to other commands
- Standard exit codes and error messages
- Consistent argument parsing
### 3. Prioritize Security:
- Validate all inputs
- Use principle of least privilege
- Log command execution for audit
### 4. Ensure Reliability:
- Handle errors gracefully
- Provide clear error messages
- Include rollback mechanisms
### 5. Optimize Performance:
- Cache expensive operations
- Support incremental execution
- Provide progress feedback
### 6. Maintain Documentation:
- Clear usage examples
- Comprehensive help text
- Version compatibility notes
By following these best practices, you can create robust, reliable commands that enhance your OpenCode workflow without introducing complexity or security risks.
---
## 📚 What's Next?
- [MCP Guide](MCP-GUIDE.md) - Extend OpenCode with servers
- [Workflows Guide](WORKFLOWS.md) - Design development workflows
- [FAQ & Troubleshooting](FAQ-TROUBLESHOOTING.md) - Common issues and solutions
- [Back to Main Guide](../README.md)
---
*Last updated: February 2026*
+550
View File
@@ -0,0 +1,550 @@
# FAQ & Troubleshooting Guide
## ❓ General Questions
### Q: Is OpenCode really free and open source?
**A:** Yes! OpenCode is 100% open source under the MIT license. You can:
- View the source code: https://github.com/anomalyco/opencode
- Self-host the entire platform
- Modify and distribute your own version
- The only costs are for AI model usage (through Zen or other providers)
### Q: How does OpenCode compare to Claude Code?
**A:** OpenCode offers several advantages:
| Feature | OpenCode | Claude Code |
|---------|----------|-------------|
| **Model Support** | 75+ providers | Claude only |
| **Pricing** | Pay-as-you-go | Monthly subscription |
| **Open Source** | ✅ Yes | ❌ No |
| **Self-hosting** | ✅ Yes | ❌ No |
| **Customization** | Extensive | Limited |
| **MCP Support** | ✅ Yes | Limited |
| **Local Models** | ✅ Yes | ❌ No |
### Q: Can I use OpenCode without an internet connection?
**A:** Partially. You need internet for:
- AI model inference (unless using local models)
- Installing/updating OpenCode
- MCP server communication
You can use OpenCode offline with:
- Local models (Ollama, llama.cpp)
- Cached responses
- Pre-installed MCP servers
## 🛠️ Installation & Setup
### Q: OpenCode command not found after installation
**A:** Try these solutions:
```bash
# 1. Check installation
which opencode
# 2. Add to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 3. Reinstall
curl -fsSL https://opencode.ai/install | bash
# 4. Check permissions
ls -la $(which opencode)
chmod +x $(which opencode)
```
### Q: Zen API key not working
**A:** Common fixes:
1. **Regenerate key**: Visit opencode.ai/auth → API Keys → Regenerate
2. **Check billing**: Ensure payment method is added and active
3. **Verify format**: Key should be `zen_` followed by 64 characters
4. **Test connection**: `curl -H "Authorization: Bearer YOUR_KEY" https://api.opencode.ai/v1/models`
### Q: OpenCode crashes on startup
**A:** Debug steps:
```bash
# Run with debug mode
opencode --debug
# Check system requirements
node --version # Should be 18+
which git # Git should be installed
# Clear corrupted config
rm -rf ~/.config/opencode
rm -rf ~/.opencode
# Try different terminal
# WezTerm or Alacritty recommended
```
## 🚀 Usage & Features
### Q: File references (@filename) not working
**A:** Solutions:
```bash
# 1. Check current directory
!pwd
# 2. Use absolute path
@/full/path/to/file.ts
# 3. Check file exists
!ls -la @filename
# 4. Fuzzy search works best with unique names
# Instead of @config, use @config/database.ts
```
### Q: OpenCode making wrong changes
**A:** Recovery options:
```bash
# 1. Undo changes
/undo # Can run multiple times
# 2. Check git status
!git status
# 3. Restore from git
!git checkout -- .
# 4. Be more specific in prompts
# Instead of "fix the bug", use:
# "Fix the null pointer exception on line 45 in @src/utils/validation.ts"
```
### Q: Slow response times
**A:** Performance optimization:
```bash
# 1. Use lighter model
/models
# Select smaller/faster model
# 2. Disable thinking steps
/thinking off
# 3. Use simpler theme
/themes
# Select "minimal" or "simple"
# 4. Reduce context size
/compact
# 5. Check system resources
!top -o cpu
```
## 🤖 Agents & Skills
### Q: Custom agent not appearing in list
**A:** Fix agent configuration:
```bash
# 1. Check agent file location
ls -la ~/.config/opencode/agents/
ls -la .opencode/agents/
# 2. Verify file format
# Should be .md or .json
# Should have proper YAML frontmatter
# 3. Reload agents
/agents reload
# 4. Check permissions
chmod +r .opencode/agents/my-agent.md
```
### Q: Skill execution failing
**A:** Debug skills:
```bash
# 1. Check skill syntax
/skills validate skill-name
# 2. Test with dry run
/skills run skill-name --dry-run
# 3. Check skill permissions
/skills permissions skill-name
# 4. View skill logs
!cat ~/.local/share/opencode/skills.log
```
### Q: Agent using wrong tools
**A:** Configure tool permissions:
```markdown
# In agent configuration
## Tools
- read: true
- ask: true
- write: false # Disable file writing
- edit: false # Disable file editing
- bash: false # Disable shell commands
- skill: ["review", "test"] # Only specific skills
```
## 🧠 Models & Providers
### Q: Model not available in Zen
**A:** Options:
1. **Check Zen status**: Visit status.opencode.ai
2. **Use alternative provider**: `/connect` → Add OpenAI/Anthropic directly
3. **Request model**: Contact OpenCode team via Discord
4. **Use similar model**: Try GPT 5.2 Codex instead of Claude Opus
### Q: High token usage/costs
**A:** Cost optimization:
```bash
# 1. Monitor usage
!opencode stats
# 2. Use cheaper models
# Qwen 2.5 Coder instead of GPT 5.2 Codex
# MiniMax M2.5 Free for experimentation
# 3. Reduce context size
/compact "Keep only relevant parts"
# 4. Be concise in prompts
# Instead of long explanations, use:
# "Fix bug: @file.ts line 45"
```
### Q: Model giving poor quality responses
**A:** Improve responses:
```bash
# 1. Adjust temperature
# Lower (0.1) for code, higher (0.7) for creative
/models --temperature 0.1
# 2. Provide more context
# Include relevant files, examples, constraints
# 3. Use chain of thought
# Ask model to think step by step
# 4. Try different model
# Some models better for specific tasks
```
## ⚡ Advanced Issues
### Q: MCP server connection failed
**A:** Troubleshoot MCP:
```bash
# 1. Check server status
/mcp status
# 2. View server logs
/mcp logs server-name
# 3. Test server manually
!command-from-mcp-config --help
# 4. Reinstall server
/mcp reinstall server-name
```
### Q: OpenCode not recognizing project structure
**A:** Improve project understanding:
```bash
# 1. Run /init
/init
# 2. Check AGENTS.md
cat AGENTS.md
# 3. Provide context manually
# "This is a React/TypeScript project using Tailwind CSS"
# 4. Share project structure
!find . -name "*.ts" -o -name "*.tsx" | head -20
```
### Q: Session sharing not working
**A:** Fix sharing:
```bash
# 1. Check internet connection
!curl -I https://opencode.ai
# 2. Generate share link
/share
# 3. If private, check authentication
/connect status
# 4. Export manually
/export
# Then share the markdown file
```
## ⚡ Performance & Optimization
### Q: OpenCode using too much memory
**A:** Memory optimization:
```bash
# 1. Reduce context window
export OPENCODE_MAX_CONTEXT=8000
# 2. Disable unused features
export OPENCODE_DISABLE_MCP=1
export OPENCODE_DISABLE_SKILLS=1
# 3. Use lighter models
/models
# Select models with smaller context
# 4. Regular cleanup
rm -rf ~/.cache/opencode
rm -rf ~/.local/share/opencode/sessions/old-*
```
### Q: Slow file operations
**A:** File system optimization:
```bash
# 1. Exclude large directories
echo 'node_modules' > .opencodeignore
echo '.git' >> .opencodeignore
echo 'dist' >> .opencodeignore
# 2. Use SSD if possible
# OpenCode benefits from fast storage
# 3. Limit file scanning
export OPENCODE_FILE_SCAN_LIMIT=1000
# 4. Use specific file references
# Instead of @src/, use @src/utils/validation.ts
```
### Q: High CPU usage
**A:** CPU optimization:
```bash
# 1. Check for background processes
!ps aux | grep opencode
# 2. Limit concurrent operations
export OPENCODE_MAX_CONCURRENT=2
# 3. Use simpler parsing
export OPENCODE_SIMPLE_PARSER=1
# 4. Update to latest version
curl -fsSL https://opencode.ai/install | bash
```
## 🔒 Security & Privacy
### Q: Is my code sent to AI providers?
**A:** Yes, when using cloud-based models. For privacy:
1. **Use local models**: Ollama, llama.cpp
2. **Use enterprise providers**: Some offer data privacy guarantees
3. **Self-host OpenCode**: Complete control over data
4. **Review provider policies**: Check data handling terms
### Q: How to secure API keys?
**A:** Best practices:
```bash
# 1. Use environment variables
export OPENCODE_API_KEY=your_key
export ZEN_API_KEY=your_zen_key
# 2. Never commit keys to git
echo '.env' >> .gitignore
echo '*.key' >> .gitignore
# 3. Use key rotation
# Rotate keys every 90 days
# 4. Monitor usage
!opencode stats --alert high-usage
```
### Q: Can OpenCode access sensitive files?
**A:** Yes, by default. Restrict access:
```bash
# 1. Create .opencodeignore
echo '.env' > .opencodeignore
echo 'secrets/' >> .opencodeignore
echo '*.key' >> .opencodeignore
# 2. Use agent permissions
# Create "restricted" agent with limited tools
# 3. Run in isolated environment
docker run -it --rm -v $(pwd):/workspace ghcr.io/anomalyco/opencode
# 4. Audit file access
!find ~/.local/share/opencode -name "*.log" | xargs grep "access"
```
## 🤝 Community & Support
### Q: Where to get help?
**A:** Support channels:
1. **Discord**: https://opencode.ai/discord (recommended)
2. **GitHub Issues**: https://github.com/anomalyco/opencode/issues
3. **Documentation**: https://opencode.ai/docs/
4. **Community Forum**: GitHub Discussions
### Q: How to contribute to OpenCode?
**A:** Contribution options:
1. **Code**: Fork GitHub repo, submit PRs
2. **Documentation**: Improve docs, add examples
3. **Skills/Agents**: Share with community
4. **MCP Servers**: Create and publish servers
5. **Bug Reports**: Submit detailed issues
### Q: Where to find examples and templates?
**A:** Resources:
1. **This repository**: Examples in `examples/` directory
2. **Official examples**: https://github.com/anomalyco/opencode-examples
3. **Community templates**: GitHub topic `opencode-template`
4. **Skill registry**: Built-in `/skills list`
## 🔄 Updates & Migration
### Q: How to update OpenCode?
**A:** Update methods:
```bash
# Using install script (recommended)
curl -fsSL https://opencode.ai/install | bash
# Using package manager
npm update -g opencode-ai
# or
brew upgrade opencode
# Check version
opencode --version
# Latest: https://github.com/anomalyco/opencode/releases
```
### Q: Breaking changes in new version
**A:** Migration steps:
1. **Backup configuration**
```bash
tar -czf opencode-backup.tar.gz ~/.config/opencode ~/.opencode
```
2. **Check changelog**: https://github.com/anomalyco/opencode/releases
3. **Test in isolated environment**
4. **Gradual migration**: Update one project at a time
### Q: Compatibility with other tools
**A:** Integration status:
- **VS Code**: Extension available
- **JetBrains IDEs**: Plugin in development
- **Neovim**: Plugin available
- **Docker**: Official image available
- **CI/CD**: GitHub Actions available
Check https://opencode.ai/docs/ for latest integration status.
## 🚨 Common Error Messages
### Error: "No provider configured"
```bash
# Solution:
/connect
# Follow prompts to add provider
```
### Error: "Model not available"
```bash
# Solution:
/models
# Select available model
# or
/connect
# Add different provider
```
### Error: "Permission denied"
```bash
# Solution:
# Check file permissions
!ls -la file.ts
# or
# Run with appropriate permissions
sudo chmod +r file.ts
```
### Error: "Out of context window"
```bash
# Solution:
/compact
# or
# Be more concise
# or
# Use model with larger context
```
### Error: "Rate limited"
```bash
# Solution:
# Wait and try again
# or
# Upgrade plan (Zen)
# or
# Use different provider
```
## 💡 Pro Tips & Best Practices
### 1. Start Simple:
- Begin with basic commands
- Master Plan/Build mode switching
- Create simple agents before complex ones
### 2. Iterate Gradually:
- Small, testable changes
- Regular undo/redo
- Continuous refinement
### 3. Document Everything:
- Keep AGENTS.md updated
- Document custom skills/agents
- Share successful workflows
### 4. Security First:
- Regular key rotation
- Principle of least privilege
- Audit logs review
### 5. Community Engagement:
- Share learnings
- Contribute improvements
- Help others learn
### 6. Continuous Learning:
- Stay updated with new features
- Experiment with different models
- Adapt workflows as tools evolve
Remember: OpenCode is a powerful tool that gets better with practice. Start with simple tasks, build confidence, and gradually tackle more complex challenges. The community is here to help!
---
## 📚 Additional Resources
### Quick Reference:
- [Main Guide](../README.md) - Overview and quick start
- [Quick Start Guide](QUICKSTART.md) - Installation and setup
- [Zen Guide](ZEN-GUIDE.md) - Model router details
- [TUI Guide](TUI-MASTERY.md) - Terminal interface mastery
- [Agents Guide](AGENTS-GUIDE.md) - AI agents comprehensive guide
- [Skills Guide](SKILLS-GUIDE.md) - Skills system
- [Commands Reference](COMMANDS-REFERENCE.md) - Complete command list
- [MCP Guide](MCP-GUIDE.md) - MCP servers
- [Workflows Guide](WORKFLOWS.md) - Development workflows
### Official Links:
- **Website**: https://opencode.ai
- **Documentation**: https://opencode.ai/docs/
- **GitHub**: https://github.com/anomalyco/opencode
- **Discord**: https://opencode.ai/discord
- **Status**: https://status.opencode.ai
---
*Last updated: February 2026*
+530
View File
@@ -0,0 +1,530 @@
# MCP (Model Context Protocol) Servers Guide
## 🎯 What are MCP Servers?
**MCP** (Model Context Protocol) servers extend OpenCode's capabilities by providing external tools and data sources. Think of MCP servers as "plugins for AI" that give OpenCode access to databases, APIs, file systems, and other external resources.
### Key Concepts:
1. **Servers**: External processes that provide tools/resources
2. **Tools**: Functions that the AI can call (read file, query DB, call API)
3. **Resources**: Data sources the AI can access (files, databases, APIs)
4. **Protocol**: Standardized communication between AI and servers
### Benefits of MCP:
- **Extensibility**: Add new capabilities without modifying OpenCode
- **Security**: Isolate external access in separate processes
- **Standardization**: Consistent interface across different tools
- **Composability**: Combine multiple servers for complex workflows
## 🤖 Built-in MCP Servers
### File System Server:
- **Purpose**: Read/write access to local files
- **Tools**: `read_file`, `write_file`, `list_directory`
- **Use Case**: Basic file operations within project
### Git Server:
- **Purpose**: Version control operations
- **Tools**: `git_status`, `git_diff`, `git_commit`, `git_push`
- **Use Case**: Automated git workflows
### HTTP Server:
- **Purpose**: Make HTTP requests
- **Tools**: `http_get`, `http_post`, `http_put`, `http_delete`
- **Use Case**: API integration, web scraping
### SQL Server:
- **Purpose**: Database operations
- **Tools**: `sql_query`, `sql_execute`, `sql_schema`
- **Use Case**: Database management, data analysis
## 📦 Installing MCP Servers
### Method 1: OpenCode Registry
```bash
# List available MCP servers
/mcp list
# Install server from registry
/mcp install github
# Install specific version
/mcp install postgres --version 1.2.0
```
### Method 2: From URL
```bash
# Install from GitHub repository
/mcp install https://github.com/user/mcp-server-repo
# Install from npm package
/mcp install npm:package-name
# Install from local file
/mcp install ./custom-mcp-server/
```
### Method 3: Manual Installation
```bash
# Clone server repository
git clone https://github.com/modelcontextprotocol/servers.git
# Configure in OpenCode
echo '{
"mcpServers": {
"filesystem": {
"command": "node",
"args": ["servers/filesystem/dist/index.js"]
}
}
}' > ~/.config/opencode/opencode.json
```
## 📋 Popular MCP Servers
### Development Servers:
| Server | Purpose | Tools |
|--------|---------|-------|
| **GitHub** | GitHub API access | `list_repos`, `create_pr`, `read_issue` |
| **PostgreSQL** | PostgreSQL database | `query`, `execute`, `schema` |
| **Redis** | Redis cache | `get`, `set`, `keys`, `del` |
| **Docker** | Container management | `ps`, `run`, `build`, `logs` |
| **AWS** | AWS services | `s3_list`, `ec2_describe`, `lambda_invoke` |
### Productivity Servers:
| Server | Purpose | Tools |
|--------|---------|-------|
| **Google Calendar** | Calendar management | `list_events`, `create_event`, `update_event` |
| **Slack** | Slack integration | `send_message`, `read_channel`, `search_messages` |
| **Email** | Email management | `send_email`, `read_inbox`, `search_emails` |
| **Jira** | Issue tracking | `list_issues`, `create_issue`, `update_issue` |
### Data & Analysis Servers:
| Server | Purpose | Tools |
|--------|---------|-------|
| **CSV** | CSV file operations | `read_csv`, `write_csv`, `filter_csv` |
| **JSON** | JSON manipulation | `parse_json`, `stringify_json`, `query_json` |
| **Excel** | Excel file operations | `read_excel`, `write_excel`, `format_excel` |
| **PDF** | PDF processing | `extract_text`, `merge_pdfs`, `create_pdf` |
## 🚀 Using MCP Servers
### Basic Usage:
```bash
# OpenCode automatically uses available MCP servers
# When you ask about files, it uses filesystem server
List all TypeScript files in the project
# When you mention git, it uses git server
What files have been modified recently?
# When you ask about APIs, it uses HTTP server
Fetch data from https://api.example.com/users
```
### Explicit Server Invocation:
```bash
# Use specific server tools
Using the filesystem server, read @src/config.json
# Chain server operations
Using git server, check status, then using filesystem server, read changed files
# Combine multiple servers
Using github server, list issues, then using slack server, notify team
```
### Server Configuration:
```json
// ~/.config/opencode/opencode.json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "your-token-here"
}
},
"postgres": {
"command": "npx",
"args": ["@modelcontextprotocol/server-postgres"],
"env": {
"PGURI": "postgres://user:pass@localhost/db"
}
}
}
}
```
## 🛠️ Creating Custom MCP Servers
### Simple MCP Server Example (JavaScript):
```javascript
// custom-server.js
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const server = new Server(
{
name: 'custom-server',
version: '1.0.0',
},
{
capabilities: {
tools: {},
},
}
);
// Define a tool
server.setRequestHandler('tools/call', async (request) => {
if (request.params.name === 'echo') {
return {
content: [
{
type: 'text',
text: `Echo: ${request.params.arguments?.message || 'Hello!'}`,
},
],
};
}
throw new Error(`Unknown tool: ${request.params.name}`);
});
// Start server
const transport = new StdioServerTransport();
await server.connect(transport);
```
### Python MCP Server Example:
```python
# custom_server.py
from mcp import Client, StdioServerParameters
import asyncio
async def main():
# Create server
server = Client(
StdioServerParameters(
command="python",
args=["custom_server.py"],
)
)
# Define tools
@server.tool("echo")
async def echo(message: str) -> str:
return f"Echo: {message}"
# Start server
await server.initialize()
# Run forever
await asyncio.Future()
if __name__ == "__main__":
asyncio.run(main())
```
### MCP Server Structure:
```
mcp-server/
├── src/
│ ├── index.ts # Main server file
│ ├── tools/ # Tool definitions
│ └── resources/ # Resource definitions
├── package.json # Dependencies
├── tsconfig.json # TypeScript config
└── README.md # Documentation
```
## 🔗 Advanced MCP Patterns
### 1. Server Composition:
```bash
# Use multiple servers together
Using github server, get latest commit
Using filesystem server, read the changed files
Using http server, deploy to staging
Using slack server, notify deployment status
```
### 2. Server Orchestration:
```bash
# Conditional server usage
If there are database changes, use postgres server to run migrations
If there are API changes, use http server to test endpoints
If there are UI changes, use filesystem server to update snapshots
```
### 3. Server Caching:
```json
// Server with caching
{
"mcpServers": {
"github-cached": {
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"cache": {
"enabled": true,
"ttl": 300, // 5 minutes
"directory": "~/.cache/opencode/mcp"
}
}
}
}
```
### 4. Server Monitoring:
```bash
# Monitor server performance
/mcp stats
# Check server health
/mcp health
# View server logs
/mcp logs github
```
## 🔒 MCP Server Security
### Authentication & Authorization:
```json
// Secure server configuration
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${env:GITHUB_TOKEN}" // Use env variable
},
"permissions": {
"network": true,
"filesystem": false,
"process": false
}
}
}
}
```
### Server Sandboxing:
```bash
# Run server in Docker container
/mcp install github --sandbox docker
# Use bubblewrap for isolation
/mcp install postgres --sandbox bubblewrap
# Custom sandbox configuration
/mcp install custom-server --sandbox-config ./sandbox.json
```
### Access Control:
```yaml
# Server access control list
servers:
github:
allowed_tools:
- list_repos
- read_issues
- create_pr
denied_tools:
- delete_repo
- update_settings
allowed_users:
- developer@company.com
rate_limit: 100/hour
```
## 🏗️ MCP Server Development
### Development Workflow:
1. **Plan**: Define server purpose and tools
2. **Develop**: Implement server with TypeScript/Python
3. **Test**: Test server with OpenCode
4. **Package**: Create distribution package
5. **Publish**: Share with community
### Testing MCP Servers:
```bash
# Test server locally
/mcp test ./custom-server/
# Run server tests
cd mcp-server && npm test
# Integration test with OpenCode
opencode run "Test custom server: echo hello"
```
### Debugging MCP Servers:
```bash
# Enable debug logging
export MCP_DEBUG=1
# View server communication
/mcp debug github
# Trace server execution
/mcp trace custom-server --output trace.json
```
## 🌐 MCP Server Ecosystem
### Community Servers:
- **Official Registry**: https://github.com/modelcontextprotocol/servers
- **Community Contributions**: GitHub topics `mcp-server`
- **Enterprise Servers**: Internal company servers
### Server Standards:
- **Naming**: Use descriptive names (github, postgres, slack)
- **Versioning**: Semantic versioning (1.0.0, 1.1.0, 2.0.0)
- **Documentation**: Include README with examples
- **Testing**: Include comprehensive test suite
### Server Distribution:
```bash
# Publish to npm
npm publish --access public
# Publish to GitHub Packages
npm publish --registry=https://npm.pkg.github.com
# Create standalone binary
pkg dist/index.js --targets node18-linux-x64
```
## 🐛 Troubleshooting MCP Servers
### Common Issues:
**1. Server not starting**
```bash
# Check server command
/mcp status github
# View server logs
/mcp logs github --tail 100
# Test server manually
!npx @modelcontextprotocol/server-github --help
```
**2. Tool not found**
```bash
# List available tools
/mcp tools github
# Check tool permissions
/mcp permissions github list_repos
# Update server version
/mcp update github
```
**3. Authentication errors**
```bash
# Check environment variables
/mcp env github
# Re-authenticate
/mcp auth github --reset
# Use different auth method
/mcp auth github --method oauth
```
**4. Performance issues**
```bash
# Monitor server performance
/mcp stats github --interval 5
# Adjust server resources
/mcp config github --memory 512mb --cpu 1
# Enable caching
/mcp config github --cache enabled
```
### Debug Commands:
```bash
# Dry run server tool
/mcp tool github list_repos --dry-run
# Profile server performance
/mcp profile postgres query "SELECT * FROM users"
# Trace server communication
/mcp trace slack --output trace.json --verbose
```
### Server Recovery:
```bash
# Backup server configuration
/mcp backup --output mcp-backup.tar.gz
# Restore servers from backup
/mcp restore mcp-backup.tar.gz
# Reset server to defaults
/mcp reset github --confirm
```
## 🎯 Best Practices for MCP Servers
### 1. Design for Reliability:
- Handle errors gracefully
- Implement retry logic
- Provide clear error messages
- Include timeout handling
### 2. Prioritize Security:
- Validate all inputs
- Implement rate limiting
- Use secure authentication
- Log security events
### 3. Optimize Performance:
- Implement caching
- Use connection pooling
- Batch operations when possible
- Monitor resource usage
### 4. Ensure Compatibility:
- Follow MCP specification
- Test with multiple OpenCode versions
- Provide migration guides
- Maintain backward compatibility
### 5. Comprehensive Documentation:
- Clear installation instructions
- Detailed tool documentation
- Usage examples
- Troubleshooting guide
### 6. Community Engagement:
- Accept feedback and issues
- Consider feature requests
- Participate in MCP community
- Share learnings and improvements
By leveraging MCP servers, you can extend OpenCode's capabilities far beyond its built-in features, creating a truly customized AI development environment tailored to your specific needs and workflows.
---
## 📚 What's Next?
- [Workflows Guide](WORKFLOWS.md) - Design development workflows
- [FAQ & Troubleshooting](FAQ-TROUBLESHOOTING.md) - Common issues and solutions
- [Back to Main Guide](../README.md)
---
*Last updated: February 2026*
+242
View File
@@ -0,0 +1,242 @@
# OpenCode Quick Start Guide
## 📋 Overview
This guide helps you install OpenCode and get started in under 5 minutes.
## 🚀 Installation Methods
### Method 1: Install Script (Recommended)
```bash
curl -fsSL https://opencode.ai/install | bash
```
### Method 2: Package Managers
**Homebrew (macOS/Linux):**
```bash
brew install anomalyco/tap/opencode
```
**npm:**
```bash
npm install -g opencode-ai
```
**Bun:**
```bash
bun install -g opencode-ai
```
**pnpm:**
```bash
pnpm install -g opencode-ai
```
**Yarn:**
```bash
yarn global add opencode-ai
```
### Method 3: System Package Managers
**Arch Linux:**
```bash
sudo pacman -S opencode
```
**Arch Linux AUR (latest):**
```bash
paru -S opencode-bin
```
**Chocolatey (Windows):**
```bash
choco install opencode
```
**Scoop (Windows):**
```bash
scoop install opencode
```
### Method 4: Binary Download
1. Visit: https://github.com/anomalyco/opencode/releases
2. Download appropriate binary for your OS
3. Extract and add to PATH
## 🖥️ Windows Installation
### Recommended: Use WSL2 (Windows Subsystem for Linux)
```bash
# Enable WSL2
wsl --install
# Install Ubuntu or preferred distro
wsl --install -d Ubuntu
# Then use Linux installation methods above
```
### Native Windows Options:
```bash
# Using Chocolatey
choco install opencode
# Using Scoop
scoop install opencode
# Using npm
npm install -g opencode-ai
# Using Docker
docker run -it --rm ghcr.io/anomalyco/opencode
```
## ✅ Verification
After installation, verify OpenCode is working:
```bash
# Check version
opencode --version
# Start OpenCode TUI
opencode
# Or run a quick test
opencode run "Hello, what version of OpenCode am I running?"
```
## 🔧 Post-Installation Setup
### 1. First Run Configuration
```bash
# Start OpenCode
opencode
# You'll see the welcome screen
# Press Enter to continue
```
### 2. Configure Your First Provider
```bash
# In the TUI, run:
/connect
# Follow the prompts to add:
# 1. OpenCode Zen (recommended for beginners)
# 2. Or another provider (OpenAI, Anthropic, etc.)
```
### 3. Initialize a Project
```bash
# Navigate to your project
cd /path/to/your/project
# Start OpenCode in project context
opencode .
# Initialize project analysis
/init
```
## 🛠️ Troubleshooting Installation
### Common Issues:
**1. "Command not found: opencode"**
```bash
# Check installation path
which opencode
# Add to PATH if needed
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
**2. Permission Errors**
```bash
# Fix permissions for global install
sudo chown -R $(whoami) /usr/local/lib/node_modules
```
**3. Node.js Version Issues**
```bash
# Check Node.js version
node --version
# Update if needed (using nvm)
nvm install 18
nvm use 18
```
**4. Windows WSL Setup**
```bash
# Enable WSL2
wsl --install
# Install Ubuntu or preferred distro
wsl --install -d Ubuntu
# Then use Linux installation methods
```
## 🔄 Updating OpenCode
### Update Methods:
```bash
# Using install script (re-run)
curl -fsSL https://opencode.ai/install | bash
# Using npm
npm update -g opencode-ai
# Using Homebrew
brew update
brew upgrade opencode
# Check for updates
opencode --version
# Compare with latest: https://github.com/anomalyco/opencode/releases
```
## 🗑️ Uninstallation
### Remove OpenCode:
```bash
# npm
npm uninstall -g opencode-ai
# Homebrew
brew uninstall opencode
# Remove config files (optional)
rm -rf ~/.config/opencode
rm -rf ~/.opencode
```
> **💡 Pro Tip**: Keep your config files (`~/.config/opencode/`) if you plan to reinstall, as they contain your provider configurations and customizations.
## 🎯 Next Steps
After successful installation:
1. **Configure Zen** (recommended for beginners) or your preferred provider
2. **Initialize a test project** to explore features
3. **Try basic commands** like `/help` and `/models`
4. **Explore the TUI** with Tab key for agent switching
You're now ready to dive into OpenCode's powerful features!
---
## 📚 What's Next?
- [Core Concepts](../README.md#-core-concepts-30-minutes) - Learn Zen, TUI, and Agents
- [Zen Model Router Guide](ZEN-GUIDE.md) - Deep dive into Zen
- [TUI Mastery Guide](TUI-MASTERY.md) - Master the terminal interface
- [Agents Guide](AGENTS-GUIDE.md) - Work with AI agents
---
*Last updated: February 2026*
+592
View File
@@ -0,0 +1,592 @@
# Skills System Guide
## 🎯 What Are OpenCode Skills?
**Skills** are reusable behavior definitions that transform complex workflows into simple, repeatable commands. Think of them as "macros for AI" that encapsulate multi-step processes into single invocations.
### Key Characteristics:
1. **Reusable**: Define once, use everywhere
2. **Shareable**: Commit to version control, share with team
3. **Customizable**: Modify for specific projects or workflows
4. **Secure**: Permission-controlled execution
5. **Discoverable**: Auto-listed in OpenCode interface
## 📁 Skill File Structure
### Basic SKILL.md Template:
```markdown
---
name: "Skill Name"
description: "Brief description of what this skill does"
version: "1.0.0"
license: "MIT"
compatibility: "opencode>=1.5.0"
tools: ["read", "ask", "write", "edit", "bash"]
permissions: ["project", "global"]
---
# Skill Name
Detailed description of the skill's purpose and behavior.
## Behavior
- Step 1: What OpenCode should do first
- Step 2: Next action to take
- Step 3: Final steps and cleanup
## Guidelines
- Best practices to follow
- Constraints or requirements
- Error handling procedures
## Examples
### Example 1: Basic Usage
```bash
/skill-name argument1 argument2
```
### Example 2: Advanced Usage
```bash
/skill-name --option value @file.ts
```
## Notes
- Additional information
- Troubleshooting tips
- Related skills
```
## 🚀 Creating Your First Skill
### Step 1: Create Skill Directory
```bash
# Global skills (available in all projects)
mkdir -p ~/.config/opencode/skills
# Project-specific skills (recommended for teams)
mkdir -p .opencode/skills
```
### Step 2: Create Skill File
```bash
# Create a simple code review skill
cat > .opencode/skills/review.md << 'EOF'
---
name: "Code Review"
description: "Comprehensive code review with security, performance, and style checks"
version: "1.0.0"
tools: ["read", "ask"]
permissions: ["project"]
---
# Code Review
Perform thorough code review focusing on security, performance, and maintainability.
## Behavior
1. Analyze the specified file or directory
2. Check for security vulnerabilities (OWASP Top 10)
3. Review performance implications and bottlenecks
4. Assess code style and consistency
5. Suggest specific improvements with examples
6. Provide actionable recommendations
## Guidelines
- Focus on critical issues first
- Provide code examples for fixes
- Consider project-specific conventions
- Balance perfection with practicality
## Examples
### Review a specific file
```bash
/review @src/auth/index.ts
```
### Review changed files
```bash
/review changed
```
### Review with specific focus
```bash
/review @src/ --focus security
```
EOF
```
### Step 3: Test Your Skill
```bash
# Start OpenCode
opencode
# Use your new skill
/review @src/utils/validation.ts
```
## 📋 Available Skill Categories
### 🔹 Development Workflow
**`/pr` - Pull Request Creation**
- Creates feature branch from current changes
- Formats code using project formatters
- Splits changes into logical commits
- Generates descriptive commit messages
- Creates PR with summary and test plan
**`/tdd` - Test-Driven Development**
- Enforces Red-Green-Refactor cycle
- Creates failing tests first
- Implements minimal solution
- Refactors for quality
- Maintains feature notes
**`/refactor` - Code Refactoring**
- Analyzes code for improvement opportunities
- Suggests refactoring strategies
- Implements changes safely
- Preserves functionality
- Updates tests as needed
### 🔹 Quality Assurance
**`/review` - Code Review**
- Multi-perspective review (security, performance, style)
- Actionable recommendations
- Code examples for fixes
- Priority-based feedback
**`/test` - Test Generation**
- Creates comprehensive test suites
- Covers edge cases and error conditions
- Follows testing best practices
- Integrates with project test framework
**`/audit` - Security Audit**
- Security vulnerability scanning
- Dependency vulnerability check
- Configuration security review
- Compliance verification
### 🔹 Project Management
**`/todo` - Task Management**
- Manages project todos in `todos.md`
- Supports due dates and priorities
- Tracks completion status
- Generates progress reports
**`/docs` - Documentation**
- Generates API documentation
- Creates user guides
- Updates README files
- Maintains changelogs
**`/plan` - Project Planning**
- Creates development plans
- Estimates effort and complexity
- Identifies dependencies and risks
- Generates timeline estimates
## 📝 Skill Examples
### Complete PR Skill:
```markdown
---
name: "Create Pull Request"
description: "Automated PR creation with branch management and commit splitting"
version: "1.0.0"
tools: ["read", "write", "edit", "bash"]
permissions: ["project"]
---
# Create Pull Request
Automatically creates a pull request from current changes with proper commit hygiene.
## Behavior
1. Check for uncommitted changes
2. Create feature branch based on current changes
3. Format code using project formatter (Biome/Prettier/ESLint)
4. Analyze changes and split into logical commits
5. Create descriptive commit messages
6. Push branch to remote
7. Create pull request with summary and test plan
## Guidelines for Commit Splitting
- Split by feature, component, or concern
- Keep related changes together
- Separate refactoring from feature work
- Ensure each commit stands alone
- Follow conventional commit format
## Examples
### Basic PR creation
```bash
/pr
```
### PR with specific branch name
```bash
/pr feature/user-authentication
```
### PR with custom description
```bash
/pr --description "Add user authentication with JWT"
```
```
### Complete TDD Skill:
```markdown
---
name: "Test-Driven Development"
description: "Complete TDD workflow with Red-Green-Refactor cycle"
version: "1.0.0"
tools: ["read", "write", "edit", "bash"]
permissions: ["project"]
---
# Test-Driven Development
Implements features using strict Test-Driven Development methodology.
## Behavior
1. **RED**: Write failing test for desired feature
2. **GREEN**: Implement minimal code to pass test
3. **REFACTOR**: Improve code while keeping tests green
4. Repeat for each requirement
5. Maintain feature notes in `notes/features/`
## TDD Principles
- Write tests first, code second
- Minimal implementation to pass tests
- Refactor only when tests are green
- One assertion per test (ideally)
- Test behavior, not implementation
## Examples
### Start TDD for new feature
```bash
/tdd "User registration with email validation"
```
### Continue TDD session
```bash
/tdd continue
```
### TDD with specific test framework
```bash
/tdd --framework jest "API endpoint testing"
```
```
## 📋 Skill Management
### Listing Skills:
```bash
# See available skills
/skills list
# Filter by category
/skills list --category development
# Search skills
/skills search "review"
```
### Skill Information:
```bash
# View skill details
/skills show review
# Check skill permissions
/skills permissions pr
```
### Skill Installation:
```bash
# Install from URL
/skills install https://github.com/user/repo/skills/review.md
# Install from local file
/skills install ./custom-skills/audit.md
# Install from directory
/skills install ./skills-directory/
```
### Skill Updates:
```bash
# Update all skills
/skills update
# Update specific skill
/skills update review
# Check for updates
/skills check-updates
```
## ⚡ Advanced Skill Features
### 1. Skill Arguments:
```markdown
## Behavior
- Use $ARGUMENTS for all arguments
- Use $1, $2, $3 for positional arguments
- Use $OPTIONS for parsed options
## Examples
```bash
/skill-name arg1 arg2 --option value
# $ARGUMENTS = "arg1 arg2 --option value"
# $1 = "arg1", $2 = "arg2"
```
```
### 2. Shell Command Integration:
```markdown
## Behavior
- Execute shell commands with !command
- Capture output for use in skill
- Handle command failures gracefully
## Examples
```bash
# Get git status
!git status
# Check Node.js version
!node --version
```
```
### 3. File References:
```markdown
## Behavior
- Reference files with @filename
- Support fuzzy file search
- Handle multiple file references
## Examples
```bash
# Review specific file
/review @src/auth/index.ts
# Compare files
/compare @old-version.ts @new-version.ts
```
```
### 4. Agent & Model Overrides:
```markdown
---
model: "claude-sonnet-4.6"
temperature: 0.1
agent: "code-reviewer"
---
# Skill uses specific model and agent
```
## 🔒 Skill Security Best Practices
### 1. Permission Management:
- Use minimal required permissions
- Restrict bash access for sensitive skills
- Review third-party skills before installation
### 2. Input Validation:
- Validate skill arguments
- Sanitize file paths
- Handle edge cases gracefully
### 3. Error Handling:
- Provide clear error messages
- Log skill execution
- Roll back changes on failure
### 4. Testing Skills:
```bash
# Test skill in safe environment
/skills test review --dry-run
# Test with sample data
/skills test audit --sample @test-data.json
```
## 🏗️ Creating Skill Templates
### Skill Template Repository Structure:
```
skills-templates/
├── development/
│ ├── pr-template.md
│ ├── tdd-template.md
│ └── refactor-template.md
├── quality/
│ ├── review-template.md
│ ├── test-template.md
│ └── audit-template.md
├── project/
│ ├── todo-template.md
│ ├── docs-template.md
│ └── plan-template.md
└── README.md
```
### Template Usage:
```bash
# Create skill from template
/skills create-from-template development/pr-template.md my-pr-skill
# Customize template
cp skills-templates/development/pr-template.md .opencode/skills/my-pr.md
# Edit my-pr.md for project specifics
```
## 🤝 Skill Sharing & Collaboration
### Team Skill Repository:
```bash
# Clone team skills
git clone https://github.com/team/skills-repo.git
ln -s skills-repo/skills .opencode/skills
# Update team skills
cd .opencode/skills && git pull
# Contribute new skills
cd .opencode/skills
git add new-skill.md
git commit -m "Add new code review skill"
git push
```
### Skill Versioning:
```markdown
---
name: "Code Review"
description: "Comprehensive code review"
version: "1.2.0"
changelog: |
v1.2.0: Added security scanning
v1.1.0: Improved performance analysis
v1.0.0: Initial release
compatibility: "opencode>=1.5.0"
---
```
### Skill Documentation:
```markdown
## Documentation
### Usage
```bash
/skill-name [options] [arguments]
```
### Options
- `--focus <area>`: Focus on specific area (security, performance, style)
- `--output <format>`: Output format (markdown, json, html)
- `--verbose`: Enable verbose output
### Examples
See [EXAMPLES.md](EXAMPLES.md) for more examples.
### Support
Report issues at: https://github.com/team/skills-repo/issues
```
## 🐛 Troubleshooting Skills
### Common Issues:
**1. Skill not found**
```bash
# Check skill location
ls -la .opencode/skills/
# Reload skills
/skills reload
```
**2. Permission errors**
```bash
# Check skill permissions
/skills permissions skill-name
# Run with elevated permissions (careful!)
/skills run skill-name --permissions elevated
```
**3. Skill execution failed**
```bash
# Enable debug mode
/skills run skill-name --debug
# Check skill logs
!cat ~/.local/share/opencode/skills.log
```
**4. Skill conflicts**
```bash
# List conflicting skills
/skills conflicts
# Disable conflicting skill
/skills disable old-skill
```
### Debug Commands:
```bash
# Dry run skill
/skills run skill-name --dry-run
# Step through skill execution
/skills run skill-name --step
# Profile skill performance
/skills run skill-name --profile
```
> **💡 Pro Tip**: Create a "skill-tester" skill that validates other skills. This helps maintain quality and catch issues before they affect your workflow.
## 🌐 Skill Ecosystem
Consider building a skill ecosystem for your organization:
### Central Skill Registry:
- Curated list of approved skills
- Version control and changelogs
- Quality assurance process
- Team skill ratings and reviews
### Skill Development Workflow:
1. **Proposal**: Suggest new skill idea
2. **Development**: Create skill with tests
3. **Review**: Peer review and security audit
4. **Approval**: Add to central registry
5. **Distribution**: Deploy to team projects
### Skill Metrics:
- Usage statistics per skill
- Performance metrics
- User satisfaction ratings
- Bug reports and fixes
By building a robust skill ecosystem, you can standardize workflows, improve quality, and accelerate development across your entire organization.
---
## 📚 What's Next?
- [Commands Reference](COMMANDS-REFERENCE.md) - Complete command list
- [Workflows Guide](WORKFLOWS.md) - Design development workflows
- [MCP Guide](MCP-GUIDE.md) - Extend OpenCode with servers
- [Back to Main Guide](../README.md)
---
*Last updated: February 2026*
+373
View File
@@ -0,0 +1,373 @@
# TUI Mastery Guide
## 🎯 Overview
OpenCode's Terminal User Interface (TUI) is where the magic happens. This guide covers everything you need to master the TUI for maximum productivity.
## 🖥️ TUI Layout Overview
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ OpenCode v1.5.2 │ Project: /Users/you/project │ Model: gpt-5.2-codex │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ You: Can you help me fix the bug in @src/utils/validation.ts? │
│ │
│ OpenCode: I'll analyze the validation.ts file and identify the bug... │
│ │
│ [Thinking...] │
│ • Reading file: src/utils/validation.ts │
│ • Analyzing validation logic... │
│ • Found potential issue on line 45... │
│ │
│ The bug is in the email validation regex. Here's the fix: │
│ │
│ ```typescript │
│ // Before: │
│ const emailRegex = /^[^@]+@[^@]+\.[^@]+$/; │
│ │
│ // After: │
│ const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/; │
│ ``` │
│ │
├─────────────────────────────────────────────────────────────────────────────┤
│ [Build] Press Tab to switch agents • Type /help for commands • Ctrl+C to exit│
└─────────────────────────────────────────────────────────────────────────────┘
```
## ⌨️ Essential Keyboard Shortcuts
| Shortcut | Action | Description |
|----------|--------|-------------|
| **Tab** | Switch agents | Toggle between Build and Plan modes |
| **Ctrl+C** | Exit | Exit OpenCode (press twice to force) |
| **Ctrl+R** | Redo | Redo last undone change |
| **Ctrl+U** | Undo | Undo last change |
| **Ctrl+L** | Clear | Clear terminal screen |
| **Ctrl+K** | Search | Search command history |
| **↑/↓** | History | Navigate command history |
| **@** | File search | Fuzzy search for project files |
| **!** | Shell prefix | Execute shell command |
| **/** | Command mode | Enter slash command mode |
| **Esc** | Cancel | Cancel current operation |
## 📁 File Reference System (@ Syntax)
OpenCode's `@` syntax revolutionizes how you reference files:
### Basic File Reference:
```bash
# Reference a specific file
Can you explain the authentication logic in @src/auth/index.ts?
# Fuzzy search - OpenCode will help you find the file
I need to update the configuration in @config
```
### Multiple File References:
```bash
# Compare two files
Compare the implementation in @src/old-impl.ts and @src/new-impl.ts
# Analyze entire directory
What's the structure of @src/components/?
```
### Line-Specific References:
```bash
# Reference specific lines
Check lines 45-60 in @src/utils/validation.ts
# Error location
There's an error on line 123 in @src/api/server.ts
```
## 💻 Shell Command Integration
Execute shell commands directly within OpenCode:
### Basic Shell Commands:
```bash
# Run any shell command with ! prefix
!ls -la
!git status
!npm install
!docker ps
```
### Command Output in Context:
```bash
# Use command output in your prompt
!pwd
# OpenCode sees: "/Users/you/project"
Now create a new directory here called "tests"
```
### Chaining Commands:
```bash
# Multiple commands
!git status && !git diff
# Capture output for analysis
!cat package.json | grep version
What version of React are we using based on the output above?
```
## 🖼️ Image Analysis
OpenCode can analyze images dragged into the terminal:
### Using Images:
1. **Drag and drop** any image file into the terminal
2. OpenCode automatically adds it to the prompt
3. Reference the image in your queries
### Example Workflow:
```bash
# 1. Drag UI mockup into terminal
# 2. OpenCode detects: [Image #1: dashboard-mockup.png]
Create a React component that matches this design [Image #1]
```
### Supported Image Types:
- PNG, JPEG, GIF, WebP
- Screenshots, mockups, diagrams
- UI designs, architecture diagrams
## 🔄 Agent Switching (Build vs Plan)
OpenCode's dual-agent system is its secret weapon:
### Plan Mode (Read-Only):
- **Activate**: Press `Tab` (shows `[Plan]` in status bar)
- **Purpose**: Analyze, plan, brainstorm without making changes
- **Use Case**: "How would you implement this feature?"
### Build Mode (Read-Write):
- **Activate**: Press `Tab` (shows `[Build]` in status bar)
- **Purpose**: Make actual code changes
- **Use Case**: "Go ahead and implement the plan"
### Workflow Example:
```bash
# Start in Plan mode (default)
[Plan] How would you add dark mode to this React app?
# Review the plan, ask questions
What about CSS variables vs Tailwind?
# Switch to Build mode (Tab)
[Build] Sounds good! Implement it.
```
## 💬 Conversation Management
### Session Persistence:
- Conversations are automatically saved
- Resume where you left off
- Git-based undo/redo system
### Multiple Sessions:
```bash
# List sessions
/sessions
# Switch sessions
/sessions switch session-name
# Delete session
/sessions delete old-session
```
### Export Conversations:
```bash
# Export to markdown
/export
# Creates: opencode-conversation-2025-02-26.md
```
## ⚡ Advanced TUI Features
### 1. Compact Mode:
```bash
# Summarize long conversations
/compact
# Focus on specific topics
/compact "Focus on the authentication changes"
```
### 2. Editor Integration:
```bash
# Open external editor for long messages
/editor
# Uses $EDITOR environment variable
```
### 3. Theme Customization:
```bash
# Change TUI theme
/themes
# Select from available themes
# Popular: catppuccin, dracula, nord, solarized
```
### 4. Real-time Cost Display:
- Token usage shown in status bar
- Cost estimates for current session
- Provider-specific pricing
## 🚀 Productivity Tips
### 1. Quick File Navigation:
```bash
# Use @ with partial names
@utils # Finds utils/ directory or utils.ts
@.env # Finds .env files
@test # Finds test files
```
### 2. Command History:
- Press `↑` to cycle through previous commands
- `Ctrl+K` to search history
- History persists across sessions
### 3. Multi-line Input:
```bash
# Shift+Enter for new lines
This is a multi-line
query that spans
multiple lines
```
### 4. Quick Provider Switching:
```bash
# Change model on the fly
/models
# Select from list
# Changes apply immediately
```
## 🛠️ Troubleshooting TUI Issues
### Common Issues:
**1. TUI not rendering properly**
```bash
# Check terminal compatibility
echo $TERM
# Try different terminal emulator
# WezTerm or Alacritty recommended
```
**2. Input lag or slow response**
```bash
# Check system resources
!top
# Try lighter model
/models
# Select smaller model
```
**3. Images not working**
```bash
# Check terminal image support
# Use WezTerm for best image support
# Alternative: describe image in text
```
**4. File references not found**
```bash
# Check current directory
!pwd
# Use absolute paths if needed
@/full/path/to/file.ts
```
### Performance Optimization:
```bash
# Use lighter themes
/themes
# Select "minimal" or "simple"
# Disable thinking steps
/thinking off
# Reduce verbosity in agent settings
```
## 🎨 TUI Customization
### Keybind Customization:
```json
// ~/.config/opencode/keybinds.json
{
"switch_agent": "Tab",
"exit": ["Ctrl+C", "Ctrl+D"],
"clear": "Ctrl+L",
"history_search": "Ctrl+K"
}
```
### Theme Configuration:
```json
// ~/.config/opencode/themes.json
{
"current": "catppuccin",
"custom": {
"background": "#1e1e2e",
"foreground": "#cdd6f4",
"accent": "#89b4fa"
}
}
```
### Status Bar Customization:
```json
// ~/.config/opencode/config.json
{
"ui": {
"status_bar": {
"show_cost": true,
"show_tokens": true,
"show_model": true,
"show_agent": true
}
}
}
```
## 🎯 Mastery Checklist
- [ ] Can switch between Plan and Build modes with Tab
- [ ] Know how to reference files with @ syntax
- [ ] Can execute shell commands with ! prefix
- [ ] Understand how to use image analysis
- [ ] Know essential keyboard shortcuts
- [ ] Can manage conversations and sessions
- [ ] Know how to troubleshoot common issues
- [ ] Have customized TUI to personal preferences
> **💡 Pro Tip**: Master the `Tab` key switching between Plan and Build modes. This single habit will dramatically improve your OpenCode workflow efficiency.
---
## 📚 What's Next?
- [Agents Guide](AGENTS-GUIDE.md) - Work with AI agents
- [Skills Guide](SKILLS-GUIDE.md) - Create reusable workflows
- [Workflows Guide](WORKFLOWS.md) - Design development workflows
- [Back to Main Guide](../README.md)
---
*Last updated: February 2026*
+582
View File
@@ -0,0 +1,582 @@
# Workflow Design Guide
## 🎯 Overview
This guide covers proven workflows for AI-assisted development with OpenCode. Choose the workflow that best fits your task.
## 🔄 1. Explore → Plan → Code → Commit
The most versatile workflow for complex problems:
### Explore:
- Read relevant files, images, URLs
- Use subagents for verification
- Do **not** code yet - understand first
### Plan:
- Ask OpenCode to create a plan
- Review and refine the approach
- Consider alternatives and trade-offs
### Code:
- Implement the solution
- Verify reasonableness as you go
- Use tests to validate
### Commit:
- Commit results with clear messages
- Create pull requests if needed
- Update documentation
### Example:
```bash
# Explore: Understand the codebase
@explore Analyze @src/auth/ for authentication implementation
# Plan: Design the solution
[Plan] How would you add OAuth2 support to the existing authentication?
# Code: Implement
[Build] Implement OAuth2 support as planned
# Commit: Save changes
!git add .
!git commit -m "feat: Add OAuth2 authentication support"
```
## 🧪 2. Test-Driven Development (TDD)
Ideal for changes verifiable with unit/integration tests:
### Write Tests:
- Create tests based on expected behavior
- Mark as TDD to guide OpenCode
- Ensure tests fail initially (Red)
### Run & Fail Tests:
- Confirm tests fail as expected
- No implementation yet
### Write Code:
- Implement minimal code to pass tests (Green)
- Iterate with verification
### Refactor:
- Improve code while keeping tests green
- Maintain test coverage
### Commit:
- Final commit after all tests pass
### Example:
```bash
# Start TDD session
/tdd "User registration validation"
# OpenCode guides through:
# 1. Write failing test
# 2. Implement minimal solution
# 3. Refactor
# 4. Repeat for each requirement
# Complete and commit
!git add .
!git commit -m "test: Add user registration validation"
```
## 🎨 3. Visual Iteration
Perfect for UI/design work:
### Provide Visual Reference:
- Drag and drop images into terminal
- Provide screenshots or mockups
- Describe desired outcome
### Implement Code:
- Create code matching visual reference
- Take screenshots of result
### Iterate:
- Compare result with reference
- Make adjustments
- Repeat until satisfied
### Commit:
- Commit final implementation
### Example:
```bash
# Drag dashboard-mockup.png into terminal
[Image #1: dashboard-mockup.png]
# Implement based on image
Create a React dashboard component matching [Image #1]
# Iterate based on results
The spacing looks off. Adjust to match the mockup more closely.
# Finalize
!git add .
!git commit -m "feat: Add dashboard component"
```
## 🐛 4. Bug Fix Workflow
Systematic approach to debugging:
### Reproduce:
- Understand the bug report
- Reproduce the issue
- Identify error conditions
### Diagnose:
- Analyze logs and error messages
- Trace through code execution
- Identify root cause
### Fix:
- Implement solution
- Test the fix
- Ensure no regressions
### Verify:
- Run existing tests
- Add regression tests
- Confirm fix works
### Example:
```bash
# Reproduce bug
The user reports: "Registration fails with invalid email error"
# Diagnose
@debugger Analyze @src/auth/registration.ts for email validation issues
# Fix
[Build] Fix the email validation regex in @src/auth/registration.ts
# Verify
!npm test -- --testPathPattern=registration
!git add .
!git commit -m "fix: Correct email validation regex"
```
## 🚀 5. Feature Development Workflow
Complete feature implementation:
### Requirements Analysis:
- Understand feature requirements
- Identify dependencies
- Plan implementation steps
### Architecture Design:
- Design solution architecture
- Plan database schema (if needed)
- Design API endpoints
### Implementation:
- Implement backend components
- Implement frontend components
- Connect pieces together
### Testing:
- Write unit tests
- Write integration tests
- Perform user acceptance testing
### Deployment:
- Prepare for deployment
- Update documentation
- Deploy to environment
### Example:
```bash
# Multi-agent feature development
@product-manager Define requirements for user profile feature
@architect Design profile feature architecture
@backend Implement profile API endpoints
@frontend Implement profile UI components
@tester Create comprehensive test suite
@devops Prepare deployment configuration
@documentation Update user and developer docs
```
## 🧩 Workflow Customization
Create your own workflows by combining:
### Agent Chains:
```bash
# Custom workflow using agent chain
@explore → @plan → @implement → @test → @review → @deploy
```
### Skill Sequences:
```bash
# Custom workflow using skills
/analyze → /plan → /implement → /test → /review → /deploy
```
### Hybrid Approaches:
```bash
# Mix agents and skills
@explore Analyze requirements
/plan Create implementation plan
@implement Write code
/test Run tests
/review Code review
/deploy Deploy changes
```
## 🤖 The BMAD Method (AI Agent Framework)
BMAD (Brainstorm, Model, Act, Deliver) is a systematic framework for AI-assisted development.
### Phase 1: Brainstorm
**Purpose:** Explore the problem space without constraints
**Activities:**
- Research existing solutions
- Generate multiple approaches
- Consider edge cases and constraints
- Gather requirements and context
**OpenCode Commands:**
```bash
# Explore the codebase
@explore Analyze @src/ for related functionality
# Research requirements
What are the requirements for user authentication?
# Generate ideas
Brainstorm 3 different approaches to implement OAuth2
# Consider constraints
What are the security considerations for this feature?
```
**Output:**
- Problem understanding
- Multiple solution approaches
- Requirements list
- Constraints and considerations
### Phase 2: Model
**Purpose:** Create detailed, actionable plans
**Activities:**
- Select best approach from brainstorming
- Create detailed implementation plan
- Design architecture and components
- Plan testing and validation
**OpenCode Commands:**
```bash
# Create implementation plan
[Plan] Create detailed plan for OAuth2 implementation
# Design architecture
Design the authentication system architecture
# Plan testing strategy
What tests are needed for this feature?
# Create timeline
Estimate effort and create implementation timeline
```
**Output:**
- Detailed implementation plan
- Architecture diagrams
- Test plan
- Timeline and milestones
### Phase 3: Act
**Purpose:** Execute the plan with precision
**Activities:**
- Implement code according to plan
- Follow best practices and patterns
- Validate implementation continuously
- Adapt based on findings
**OpenCode Commands:**
```bash
# Switch to Build mode
[Build] Implement the authentication system as planned
# Follow implementation steps
1. Create OAuth2 configuration
2. Implement callback handler
3. Add user session management
4. Update frontend components
# Validate as you go
Test each component as it's implemented
```
**Output:**
- Working implementation
- Passing tests
- Documentation updates
- Code review feedback addressed
### Phase 4: Deliver
**Purpose:** Complete and deploy the solution
**Activities:**
- Final testing and validation
- Performance optimization
- Documentation completion
- Deployment and monitoring
**OpenCode Commands:**
```bash
# Final testing
/test --all
# Performance optimization
/analyze --focus performance
# Documentation
/docs update
# Deployment preparation
/deploy prepare
```
**Output:**
- Production-ready feature
- Comprehensive documentation
- Deployment artifacts
- Monitoring setup
### Complete BMAD Workflow Example:
```bash
# Brainstorm: Explore authentication options
@explore Analyze current authentication in @src/auth/
What OAuth2 providers should we support?
Brainstorm implementation approaches
# Model: Create detailed plan
[Plan] Create OAuth2 implementation plan including:
1. Google OAuth2 integration
2. GitHub OAuth2 integration
3. Session management
4. Frontend components
5. Testing strategy
# Act: Implement
[Build] Implement Google OAuth2 first
[Build] Implement GitHub OAuth2
[Build] Create session management
[Build] Update frontend login components
/test each component
# Deliver: Complete and deploy
/test --integration
/analyze --security
/docs --api
/deploy --staging
/monitor --setup
```
### BMAD Variations:
**Lightweight BMAD:** For small changes
```bash
# Brainstorm: Quick analysis
What's the best way to fix this null pointer?
# Model: Simple plan
[Plan] Fix by adding null check on line 45
# Act: Implement
[Build] Add null check: if (user) { ... }
# Deliver: Test and commit
/test --unit
!git commit -m "fix: Add null check for user object"
```
**Extended BMAD:** For complex projects
```bash
# Multi-phase BMAD with multiple agents
@product-manager Brainstorm feature requirements
@architect Model system architecture
@team-lead Model implementation timeline
@developers Act: Implement in parallel
@qa-engineers Act: Test implementation
@devops Deliver: Deploy and monitor
@documentation Deliver: Update all docs
```
### BMAD Benefits:
- **Consistency:** Structured approach for all tasks
- **Quality:** Each phase validates previous work
- **Efficiency:** Reduces rework and mistakes
- **Documentation:** Natural documentation through process
- **Collaboration:** Clear handoffs between phases
## ⚡ Workflow Automation
### Scheduled Tasks:
```bash
# Daily code review
0 9 * * * opencode run "/review changed --since yesterday"
# Weekly dependency audit
0 10 * * 1 opencode run "/audit dependencies"
# Monthly performance analysis
0 11 1 * * opencode run "/analyze @src/ --focus performance"
```
### Event-Triggered Workflows:
```bash
# On git push
git push && opencode run "/test && /review"
# On file change
inotifywait -m -e modify @src/ | while read; do
opencode run "/analyze $REPLY"
done
```
### CI/CD Integration:
```yaml
# GitHub Actions workflow
name: OpenCode Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: anomalyco/opencode-action@v1
with:
command: "/review changed"
token: ${{ secrets.OPENCODE_TOKEN }}
```
## 📊 Workflow Optimization
### Metrics to Track:
- Time from idea to implementation
- Bug rate per feature
- Test coverage changes
- Code review feedback quality
- Deployment frequency
### Optimization Strategies:
1. **Identify bottlenecks**: Which steps take longest?
2. **Parallelize**: Can steps run concurrently?
3. **Automate**: Which manual steps can be automated?
4. **Simplify**: Can workflows be made simpler?
5. **Standardize**: Create templates for common workflows
### Continuous Improvement:
```bash
# Regular workflow review
@analyzer Analyze our development workflow for improvements
# Implement improvements
[Build] Create workflow automation for repetitive tasks
# Measure impact
!opencode stats --workflow-metrics
```
## 🎯 Choosing the Right Workflow
### For New Features:
- **Complex features**: Explore → Plan → Code → Commit
- **Simple features**: Lightweight BMAD
- **Team projects**: Extended BMAD with multiple agents
### For Bug Fixes:
- **Complex bugs**: Bug Fix Workflow
- **Simple bugs**: Lightweight BMAD
### For UI/Design:
- **Visual changes**: Visual Iteration
- **Component updates**: TDD or Explore → Plan → Code → Commit
### For Refactoring:
- **Major refactoring**: Explore → Plan → Code → Commit
- **Minor improvements**: TDD
## 📋 Workflow Templates
### BMAD Template:
```markdown
# BMAD: [Feature Name]
## Brainstorm
- Requirements:
- Approaches:
- Constraints:
## Model
- Architecture:
- Implementation Plan:
- Testing Strategy:
- Timeline:
## Act
- Implementation Steps:
- Validation:
- Adjustments:
## Deliver
- Final Testing:
- Documentation:
- Deployment:
- Monitoring:
```
### Workflow Automation Template:
```bash
# .opencode/workflows/feature-development.sh
#!/bin/bash
# Feature Development Workflow
FEATURE_NAME=$1
echo "Starting feature development: $FEATURE_NAME"
# 1. Explore
@explore Analyze related code for $FEATURE_NAME
# 2. Plan
[Plan] Create implementation plan for $FEATURE_NAME
# 3. Implement
[Build] Implement $FEATURE_NAME as planned
# 4. Test
/test --feature $FEATURE_NAME
# 5. Review
/review changed
# 6. Deploy
/deploy --feature $FEATURE_NAME
echo "Feature development complete: $FEATURE_NAME"
```
By designing and optimizing your workflows, you can maximize OpenCode's potential and achieve consistent, high-quality results.
---
## 📚 What's Next?
- [FAQ & Troubleshooting](FAQ-TROUBLESHOOTING.md) - Common issues and solutions
- [Back to Main Guide](../README.md)
---
*Last updated: February 2026*
+176
View File
@@ -0,0 +1,176 @@
# Zen Model Router Guide
## 🎯 What is Zen?
**OpenCode Zen** is a curated model gateway that provides verified, optimized AI models specifically for coding tasks with pay-as-you-go pricing.
### Key Benefits:
- **Verified Models**: Tested and benchmarked for coding
- **Cost Transparency**: Pay per token, no monthly subscriptions
- **No Lock-in**: Works alongside other providers
- **Team Features**: Workspace management, centralized billing
- **BYOK Support**: Bring your own OpenAI/Anthropic keys
## 📊 Key Specifications
| Feature | Specification |
|---------|---------------|
| **Model Support** | 75+ providers via AI SDK |
| **Pricing Model** | Pay-as-you-go per token |
| **Free Models** | MiniMax M2.5 Free, Big Pickle (beta) |
| **Cost Example** | GPT 5.2 Codex: $1.75/1M input, $14/1M output |
| **Team Features** | Workspace management, centralized billing |
| **BYOK Support** | ✅ Yes (bring your own keys) |
## 🚀 How Zen Works
### Step-by-Step Setup:
1. **Sign Up**: Visit [opencode.ai/auth](https://opencode.ai/auth)
2. **Add Billing**: Add credit card for pay-as-you-go usage
3. **Get API Key**: Copy your unique Zen API key
4. **Configure in OpenCode**:
```bash
opencode
/connect
# Select "opencode" and paste your key
```
5. **Select Models**: Use `/models` to see available curated models
## 💰 Available Models & Pricing
| Model | Input Cost | Output Cost | Best For |
|-------|------------|-------------|----------|
| **GPT 5.2 Codex** | $1.75/1M | $14/1M | General coding, complex tasks |
| **Claude Sonnet 4.6** | $3-6/1M | $15-22.50/1M | Reasoning, analysis |
| **Gemini 2.5 Pro** | $2.50/1M | $10/1M | Multimodal tasks |
| **Qwen 2.5 Coder** | $0.50/1M | $2/1M | Budget coding, simple tasks |
| **MiniMax M2.5 Free** | Free | Free | Learning, experimentation |
## 🤔 Zen vs Direct Providers
### ✅ Use Zen When:
- You want curated, optimized models for coding
- You prefer pay-as-you-go over monthly subscriptions
- You need access to multiple providers with one API key
- You want the latest models without manual configuration
- You're new to AI coding and want a guided experience
### 🔧 Use Direct Providers When:
- You already have existing API credits
- You need specific model versions not in Zen
- You have enterprise agreements with specific providers
- You're using local/self-hosted models
## 💸 Cost Comparison
| Tool | Pricing Model | Monthly Cost (Avg) | Model Flexibility |
|------|---------------|-------------------|------------------|
| **OpenCode Zen** | Pay-as-you-go | $5-50 (based on usage) | 75+ models |
| **Claude Code Pro** | Subscription | $20/month | Claude only |
| **Cursor Pro** | Subscription | $20/month | Limited selection |
| **GitHub Copilot** | Subscription | $10/month | GitHub models only |
> **💡 Pro Tip**: Start with Zen's free models (MiniMax M2.5 Free) to learn OpenCode, then upgrade to paid models as needed.
## 🛠️ Advanced Zen Features
### 1. Model Switching
```bash
# Switch between models on the fly
/models
# Select from the list using arrow keys
```
### 2. Usage Monitoring
```bash
# Check your token usage
!opencode stats
# or in TUI, costs are shown in real-time
```
### 3. Team Workspaces
- Create team workspaces for shared billing
- Set monthly usage limits per team member
- Centralized model curation for consistency
### 4. BYOK (Bring Your Own Key)
- Use your existing OpenAI/Anthropic keys
- Still access Zen's curated models
- Unified billing and management
## 🚨 Troubleshooting Zen
### Common Issues:
**1. "Invalid API key"**
- Regenerate key at [opencode.ai/auth](https://opencode.ai/auth)
**2. "No models available"**
- Check billing status, may need to add payment method
**3. "Rate limited"**
- Upgrade plan or wait for reset
**4. "Model not responding"**
- Try alternative model or check provider status
### Debug Commands:
```bash
# Check connection status
!opencode models --provider opencode
# Test API key
curl -H "Authorization: Bearer YOUR_API_KEY" https://api.opencode.ai/v1/models
```
> **🚨 SECURITY NOTE**: Never commit your Zen API key to version control. Use environment variables or OpenCode's secure credential storage.
## 📊 Zen vs Traditional Subscriptions
### Traditional Model (Claude Code, Cursor):
- Monthly subscription ($20/month)
- Limited to specific models
- Pay even if you don't use it
- Vendor lock-in
### Zen Model:
- Pay per token used
- Access to 75+ models
- No monthly commitment
- Mix and match providers
- Transparent pricing
### Example Cost Calculation:
- 100,000 tokens input + 50,000 tokens output
- Using GPT 5.2 Codex: (0.1 * $1.75) + (0.05 * $14) = $0.175 + $0.70 = $0.875
- Same usage on Claude Code: $20/month (minimum)
> **📊 Real-World Usage**: Most developers spend $5-20/month with Zen, significantly less than fixed subscriptions, while getting access to better models.
## 🎯 Best Practices
1. **Start Free**: Begin with MiniMax M2.5 Free to learn
2. **Monitor Usage**: Use `!opencode stats` regularly
3. **Choose Wisely**: Match model to task (coding vs analysis)
4. **Set Limits**: Use team workspace limits for cost control
5. **Stay Updated**: New models added regularly
## 🔗 Related Resources
- [OpenCode Website](https://opencode.ai)
- [Zen Dashboard](https://opencode.ai/auth)
- [Model Status](https://status.opencode.ai)
- [Community Discord](https://opencode.ai/discord)
---
## 📚 What's Next?
- [TUI Mastery Guide](TUI-MASTERY.md) - Master the terminal interface
- [Agents Guide](AGENTS-GUIDE.md) - Work with AI agents
- [Skills Guide](SKILLS-GUIDE.md) - Create reusable workflows
- [Back to Main Guide](../README.md)
---
*Last updated: February 2026*