mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-18 18:04:22 +00:00
chore: remove obsolete docs, scaffolding, and third-party assets
- Delete eight pre-refactor doc files under docs/ (AGENTS-GUIDE,
COMMANDS-REFERENCE, FAQ-TROUBLESHOOTING, MCP-GUIDE, MIGRATION-GUIDE,
SKILLS-GUIDE, TUI-MASTERY, ZEN-GUIDE). They were inaccurate to current
OpenCode behavior; replacements land in a follow-up commit.
- Remove .opencode/skills/{pr,review}.md — these were placed as files,
but OpenCode skills require folder-with-SKILL.md format. Equivalent
content is being re-shipped as .opencode/commands/ entries.
- Remove Images/opencode.png and opencode-installation.png — these are
OpenCode's own branding assets; not appropriate to redistribute from
a non-affiliated community guide.
- Remove Images/.gitkeep — superseded by Images/README.md in a later commit.
This commit is contained in:
@@ -1,43 +0,0 @@
|
||||
---
|
||||
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"
|
||||
```
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 195 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 205 KiB |
@@ -1,532 +0,0 @@
|
||||
# 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*
|
||||
@@ -1,625 +0,0 @@
|
||||
# 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*
|
||||
@@ -1,550 +0,0 @@
|
||||
# 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*
|
||||
@@ -1,530 +0,0 @@
|
||||
# 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*
|
||||
@@ -1,448 +0,0 @@
|
||||
# Migration Guide for Experienced Developers
|
||||
|
||||
> **Switching from Claude Code, Cursor, or GitHub Copilot to OpenCode**
|
||||
|
||||
## 🎯 Why Migrate to OpenCode?
|
||||
|
||||
If you're already using AI coding tools, OpenCode offers significant advantages:
|
||||
|
||||
| Advantage | OpenCode | Other Tools |
|
||||
|-----------|----------|-------------|
|
||||
| **Model Freedom** | 75+ providers | Limited selection |
|
||||
| **Pricing** | Pay-as-you-go | Monthly subscriptions |
|
||||
| **Customization** | Unlimited skills/agents | Limited plugins |
|
||||
| **Workflow** | Terminal-native | Desktop/IDE-bound |
|
||||
| **Open Source** | Full control | Proprietary |
|
||||
|
||||
### Quick Comparison Table
|
||||
|
||||
| Feature | OpenCode | Claude Code | Cursor | GitHub Copilot |
|
||||
|---------|----------|-------------|--------|----------------|
|
||||
| **Primary Interface** | Terminal TUI | Desktop app | Desktop app | IDE plugin |
|
||||
| **Model Selection** | 75+ providers | Claude only | Limited | GitHub models |
|
||||
| **Pricing Model** | Pay-per-token | $20/month | $20/month | $10/month |
|
||||
| **File Context** | Entire project | Current file | Project | Current file |
|
||||
| **Customization** | Skills, agents, MCP | Limited | Limited | Very limited |
|
||||
| **Team Features** | Workspaces, SSO | Basic | Basic | Organization |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Migration from Claude Code
|
||||
|
||||
### What You'll Recognize
|
||||
- **AI-assisted coding** in your development environment
|
||||
- **Conversation history** and context awareness
|
||||
- **File references** and analysis capabilities
|
||||
- **Multi-step task execution**
|
||||
|
||||
### What's Different
|
||||
1. **Model Flexibility**: Use any AI model, not just Claude
|
||||
2. **Pricing**: Pay only for what you use vs $20/month
|
||||
3. **Interface**: Terminal-based vs desktop application
|
||||
4. **Extensibility**: Create custom skills and agents
|
||||
|
||||
### Step-by-Step Migration
|
||||
|
||||
#### Week 1: Foundation
|
||||
```bash
|
||||
# 1. Install OpenCode
|
||||
curl -fsSL https://opencode.ai/install | bash
|
||||
|
||||
# 2. Set up Zen (includes Claude models)
|
||||
opencode
|
||||
/connect
|
||||
# Select "opencode" and get your API key
|
||||
|
||||
# 3. Try familiar workflows
|
||||
[Plan] How would you implement this feature?
|
||||
[Build] Implement it as planned
|
||||
```
|
||||
|
||||
#### Week 2: Advanced Features
|
||||
```bash
|
||||
# 1. Create Claude-specific agent
|
||||
# ~/.config/opencode/agents/claude-style.md
|
||||
name: Claude-Style Coder
|
||||
model: claude-sonnet-4.6
|
||||
temperature: 0.3
|
||||
|
||||
# 2. Set up project skills
|
||||
# .opencode/skills/review.md
|
||||
/review @src/ --focus security
|
||||
|
||||
# 3. Learn TUI shortcuts
|
||||
# Tab: Plan/Build switch
|
||||
# @: File references
|
||||
# !: Shell commands
|
||||
```
|
||||
|
||||
#### Week 3: Optimization
|
||||
```bash
|
||||
# 1. Monitor costs
|
||||
!opencode stats
|
||||
# Compare: Claude Code $20/month vs OpenCode usage
|
||||
|
||||
# 2. Create team workspace (if applicable)
|
||||
# Visit: https://opencode.ai/team
|
||||
|
||||
# 3. Set up CI/CD integration
|
||||
# Use OpenCode in your build pipeline
|
||||
```
|
||||
|
||||
### Cost Comparison Example
|
||||
**Claude Code**: $20/month (unlimited usage on Claude models)
|
||||
|
||||
**OpenCode with Claude**:
|
||||
- 100,000 tokens input + 50,000 tokens output
|
||||
- Using Claude Sonnet 4.6: (0.1 * $5) + (0.05 * $20) = $0.50 + $1.00 = $1.50
|
||||
- **Savings**: $18.50/month for same usage
|
||||
|
||||
> **💡 Tip**: Use Zen's free models (MiniMax M2.5 Free) for experimentation, then switch to Claude for production work.
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Migration from Cursor
|
||||
|
||||
### What You'll Recognize
|
||||
- **AI-powered code generation** and editing
|
||||
- **Project context understanding**
|
||||
- **Edit commands** and refactoring
|
||||
- **Multi-file operations**
|
||||
|
||||
### What's Different
|
||||
1. **Philosophy**: Open-source community vs proprietary company
|
||||
2. **Integration**: Terminal workflow vs IDE integration
|
||||
3. **Extensibility**: Skills system vs limited plugins
|
||||
4. **Pricing**: Transparent usage-based vs subscription
|
||||
|
||||
### Step-by-Step Migration
|
||||
|
||||
#### Week 1: Core Workflow
|
||||
```bash
|
||||
# 1. Install and configure
|
||||
curl -fsSL https://opencode.ai/install | bash
|
||||
opencode
|
||||
/connect
|
||||
|
||||
# 2. Practice file referencing
|
||||
# Cursor: Click files in sidebar
|
||||
# OpenCode: Use @ syntax
|
||||
Can you explain @src/components/Button.tsx?
|
||||
|
||||
# 3. Learn edit patterns
|
||||
# Instead of Cursor's edit commands:
|
||||
[Build] Refactor this function to use async/await @src/utils/api.ts
|
||||
```
|
||||
|
||||
#### Week 2: Advanced Patterns
|
||||
```bash
|
||||
# 1. Create project-specific skills
|
||||
# .opencode/skills/refactor.md
|
||||
/refactor @src/ --pattern "callback-to-async"
|
||||
|
||||
# 2. Set up code review workflow
|
||||
@code-reviewer Review @src/
|
||||
[Build] Implement suggested changes
|
||||
|
||||
# 3. Use shell integration
|
||||
# Cursor: Limited terminal access
|
||||
# OpenCode: Full shell integration
|
||||
!git status | /analyze-changes
|
||||
```
|
||||
|
||||
#### Week 3: Customization
|
||||
```bash
|
||||
# 1. Build custom agents
|
||||
# ~/.config/opencode/agents/frontend.md
|
||||
name: Frontend Specialist
|
||||
model: gpt-5.2-codex
|
||||
# Specialized for React/TypeScript
|
||||
|
||||
# 2. Create MCP servers
|
||||
# Extend OpenCode with custom tools
|
||||
# See: docs/MCP-GUIDE.md
|
||||
|
||||
# 3. Optimize model usage
|
||||
/models
|
||||
# Select best model for each task type
|
||||
```
|
||||
|
||||
### Workflow Comparison
|
||||
**Cursor Workflow**:
|
||||
1. Open project in Cursor IDE
|
||||
2. Use AI commands from command palette
|
||||
3. Edit files directly in editor
|
||||
4. Limited to Cursor's feature set
|
||||
|
||||
**OpenCode Workflow**:
|
||||
1. Work in your preferred editor/IDE
|
||||
2. Use OpenCode TUI in separate terminal
|
||||
3. Reference files with `@` syntax
|
||||
4. Extend with custom skills and agents
|
||||
5. Execute shell commands with `!`
|
||||
|
||||
> **💡 Tip**: Keep using your favorite editor (VS Code, Neovim, etc.) and use OpenCode as an AI assistant in a separate terminal window.
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Migration from GitHub Copilot
|
||||
|
||||
### What You'll Recognize
|
||||
- **AI code completion** and suggestions
|
||||
- **Multi-language support**
|
||||
- **IDE integration** (though different)
|
||||
- **Context-aware suggestions**
|
||||
|
||||
### What's Different
|
||||
1. **Scope**: Full AI assistant vs autocomplete
|
||||
2. **Interaction**: Conversational vs predictive
|
||||
3. **Context**: Entire project vs current file
|
||||
4. **Pricing**: Usage-based vs $10/month subscription
|
||||
|
||||
### Step-by-Step Migration
|
||||
|
||||
#### Week 1: Mindset Shift
|
||||
```bash
|
||||
# 1. Install OpenCode
|
||||
curl -fsSL https://opencode.ai/install | bash
|
||||
|
||||
# 2. Think beyond autocomplete
|
||||
# Copilot: Predicts next line
|
||||
# OpenCode: Conversational assistant
|
||||
How would you implement user authentication in this project?
|
||||
|
||||
# 3. Use project-wide context
|
||||
# Copilot: Current file context
|
||||
# OpenCode: Entire project context
|
||||
Based on @src/auth/ and @src/models/user.ts, design auth system
|
||||
```
|
||||
|
||||
#### Week 2: Integration
|
||||
```bash
|
||||
# 1. Use both tools together
|
||||
# Keep Copilot for line completion
|
||||
# Use OpenCode for complex tasks
|
||||
|
||||
# 2. Create Copilot-like skills
|
||||
# .opencode/skills/complete.md
|
||||
/complete "function to validate email"
|
||||
|
||||
# 3. Set up quick access
|
||||
# Alias for common tasks
|
||||
alias oc="opencode ."
|
||||
```
|
||||
|
||||
#### Week 3: Advanced Usage
|
||||
```bash
|
||||
# 1. Create documentation skills
|
||||
/docs api --output markdown
|
||||
|
||||
# 2. Set up testing workflow
|
||||
/tdd "User registration"
|
||||
# Creates tests first, then implementation
|
||||
|
||||
# 3. Monitor and optimize
|
||||
!opencode stats
|
||||
# Compare costs with Copilot $10/month
|
||||
```
|
||||
|
||||
### Complementary Usage Pattern
|
||||
**For line completion**: Keep GitHub Copilot
|
||||
**For complex tasks**: Use OpenCode
|
||||
|
||||
**Example workflow**:
|
||||
1. Write code with Copilot suggestions
|
||||
2. When stuck, switch to OpenCode terminal:
|
||||
```bash
|
||||
opencode .
|
||||
Help me debug this issue in @src/utils/validation.ts:45
|
||||
```
|
||||
3. Implement solution with OpenCode's help
|
||||
4. Return to editor with Copilot for continued coding
|
||||
|
||||
### Cost Analysis
|
||||
**GitHub Copilot**: $10/month (unlimited usage)
|
||||
|
||||
**OpenCode**:
|
||||
- Light usage (10K tokens/day): ~$3-5/month
|
||||
- Heavy usage (100K tokens/day): ~$30-50/month
|
||||
- **Strategy**: Use both - Copilot for daily coding, OpenCode for complex tasks
|
||||
|
||||
> **💡 Tip**: OpenCode complements Copilot well. Use Copilot for 80% of coding (autocomplete) and OpenCode for the 20% of complex problems.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Technical Migration Checklist
|
||||
|
||||
### Phase 1: Setup (Day 1)
|
||||
- [ ] Install OpenCode
|
||||
- [ ] Set up Zen or preferred providers
|
||||
- [ ] Test basic commands
|
||||
- [ ] Configure shell aliases
|
||||
|
||||
### Phase 2: Workflow (Week 1)
|
||||
- [ ] Practice TUI navigation
|
||||
- [ ] Learn keyboard shortcuts
|
||||
- [ ] Create first custom agent
|
||||
- [ ] Set up project skills
|
||||
|
||||
### Phase 3: Integration (Week 2)
|
||||
- [ ] Integrate with existing tools
|
||||
- [ ] Set up team workspace (if applicable)
|
||||
- [ ] Create CI/CD pipeline integration
|
||||
- [ ] Monitor usage and costs
|
||||
|
||||
### Phase 4: Optimization (Week 3+)
|
||||
- [ ] Fine-tune agent configurations
|
||||
- [ ] Build custom MCP servers
|
||||
- [ ] Create skill templates
|
||||
- [ ] Share with team/community
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Configuration Examples
|
||||
|
||||
### Claude Code Migration Config
|
||||
```yaml
|
||||
# ~/.config/opencode/config.yaml
|
||||
providers:
|
||||
opencode:
|
||||
api_key: ${ZEN_API_KEY}
|
||||
default_model: claude-sonnet-4.6
|
||||
|
||||
agents:
|
||||
claude-style:
|
||||
path: ~/.config/opencode/agents/claude-style.md
|
||||
default: true
|
||||
|
||||
skills:
|
||||
project:
|
||||
path: .opencode/skills/
|
||||
auto_load: true
|
||||
```
|
||||
|
||||
### Cursor Migration Config
|
||||
```yaml
|
||||
# ~/.config/opencode/config.yaml
|
||||
ui:
|
||||
theme: dracula
|
||||
compact_mode: true
|
||||
|
||||
keybinds:
|
||||
switch_agent: "Tab"
|
||||
file_search: "@"
|
||||
shell_command: "!"
|
||||
|
||||
agents:
|
||||
frontend: .opencode/agents/frontend.md
|
||||
backend: .opencode/agents/backend.md
|
||||
```
|
||||
|
||||
### GitHub Copilot Integration
|
||||
```yaml
|
||||
# ~/.config/opencode/config.yaml
|
||||
integration:
|
||||
editors:
|
||||
vscode:
|
||||
command: "code {file}:{line}"
|
||||
neovim:
|
||||
command: "nvim +{line} {file}"
|
||||
|
||||
skills:
|
||||
copilot:
|
||||
- name: "complete"
|
||||
command: "Suggest completion for: {query}"
|
||||
- name: "explain"
|
||||
command: "Explain this code: @{file}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ❓ Common Migration Questions
|
||||
|
||||
### Q: Can I use OpenCode alongside my current tool?
|
||||
**A**: Yes! Many developers use:
|
||||
- GitHub Copilot for line completion
|
||||
- OpenCode for complex tasks
|
||||
- Their preferred editor for writing code
|
||||
|
||||
### Q: How do I handle keyboard shortcut conflicts?
|
||||
**A**: OpenCode keybinds are customizable:
|
||||
```json
|
||||
// ~/.config/opencode/keybinds.json
|
||||
{
|
||||
"switch_agent": "Ctrl+Space",
|
||||
"file_search": "Ctrl+F",
|
||||
"shell_command": "Ctrl+!"
|
||||
}
|
||||
```
|
||||
|
||||
### Q: What about my existing workflows?
|
||||
**A**: Recreate them as OpenCode skills:
|
||||
```bash
|
||||
# Old workflow: Manual steps
|
||||
# New workflow: Single command
|
||||
/pr "Add user authentication"
|
||||
# Creates branch, commits, tests, PR
|
||||
```
|
||||
|
||||
### Q: How do I train my team?
|
||||
**A**:
|
||||
1. Share this migration guide
|
||||
2. Create team skill templates
|
||||
3. Set up shared workspace
|
||||
4. Schedule weekly knowledge sharing
|
||||
|
||||
---
|
||||
|
||||
## 📈 Success Metrics
|
||||
|
||||
### Track Your Migration Success
|
||||
|
||||
| Metric | Before | After 1 Month | Goal |
|
||||
|--------|--------|---------------|------|
|
||||
| **Monthly Cost** | $20 (Claude Code) | $5-15 | Reduce by 25-75% |
|
||||
| **Task Completion Time** | X hours | X-30% hours | Reduce by 30% |
|
||||
| **Code Quality** | Manual review | Automated review | Improve consistency |
|
||||
| **Team Onboarding** | Weeks | Days | Reduce by 70% |
|
||||
|
||||
### Example Success Story
|
||||
**Team**: 5 developers switching from Claude Code
|
||||
**Timeline**: 4-week migration
|
||||
**Results**:
|
||||
- **Cost**: Reduced from $100/month to $35/month (65% savings)
|
||||
- **Productivity**: 40% faster code reviews
|
||||
- **Quality**: 25% fewer bugs in production
|
||||
- **Satisfaction**: 4.8/5 team rating
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Getting Help
|
||||
|
||||
### Migration Support
|
||||
- **Community**: [Discord](https://discord.gg/opencode)
|
||||
- **Documentation**: [docs.opencode.ai](https://docs.opencode.ai)
|
||||
- **Examples**: [GitHub Examples](https://github.com/anomalyco/opencode-examples)
|
||||
|
||||
### Professional Services
|
||||
- **Consulting**: Migration planning and training
|
||||
- **Custom Development**: Tailored skills and agents
|
||||
- **Team Training**: Workshops and certification
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
1. **Start small**: Migrate one project or workflow
|
||||
2. **Measure results**: Track costs and productivity
|
||||
3. **Share learnings**: Contribute to community
|
||||
4. **Scale up**: Expand to entire team/organization
|
||||
|
||||
Remember: Migration is a journey, not a destination. Start with what works for you and gradually adopt more OpenCode features as you become comfortable.
|
||||
|
||||
> **🚀 Ready to begin?** Start with the [Quick Start Guide](../README.md#-quick-start-5-minutes) and take it one step at a time.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: February 2026*
|
||||
*For migration assistance, join our [Discord community](https://discord.gg/opencode)*
|
||||
@@ -1,592 +0,0 @@
|
||||
# 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*
|
||||
@@ -1,373 +0,0 @@
|
||||
# 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*
|
||||
@@ -1,176 +0,0 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user