OpenCode - The Complete Guide to Open-Source AI Coding Agent

curl -fsSL https://opencode.ai/install | bash

# Enter project directory
cd /path/to/project

# Launch TUI
opencode

# Or specify directory
opencode /path/to/project

!ls -la
!git status
!npm test

# Send message directly (without entering TUI)
opencode run "Explain the functionality of src/index.ts"

# Specify directory
opencode run "Help me refactor this code" /path/to/project

# Start HTTP server
opencode serve

# Start Web interface
opencode web

# Specify install directory
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

# XDG standard path
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-haiku-4-20250514",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}

{
  "agent": {
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514"
    },
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

// ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096
  }
}

// Project root opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

// ~/.config/opencode/tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

# Mention with @ in messages
@general help me search for this function
@explore find all authentication-related files
@scout check the source code implementation of this library

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Review code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      },
      "temperature": 0.1
    }
  }
}

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

You are in code review mode. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

---
description: Create a new component
---

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

---
description: Create a new file with content
---

Create a file named $1 in the directory $2
with the following content: $3

---
description: Review recent changes
---

Recent git commits:

!`git log --oneline -10`

Review these changes and suggest any improvements.

---
description: Review component
---

Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.

.opencode/skills/
├── my-skill/
│   └── SKILL.md
└── another-skill/
    └── SKILL.md

{
  "permission": {
    "edit": "deny",
    "bash": {
      "*": "ask",
      "git diff": "allow",
      "git log*": "allow",
      "grep *": "allow",
      "rm -rf *": "deny"
    },
    "webfetch": "deny"
  }
}

{
  "permission": {
    "mymcp_*": "ask"
  }
}

{
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
---

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

.opencode/
├── agents/     # Custom agents
├── commands/   # Custom commands
├── skills/     # Custom skills
└── plugins/    # Plugins

# Installation
curl -fsSL https://opencode.ai/install | bash

# Launch
cd /path/to/project && opencode

# First-time setup
/init

# Connect provider
/connect

# Essential commands
/new          # New session
/compact      # Compress context
/undo         # Undo last change
/models       # List models
/share        # Share session

# Agent modes (Tab to switch)
Build         # Full access
Plan          # Read-only

# File references
@filename     # Reference file

# Bash commands
!command      # Execute shell command

# Subagents
@explore      # Codebase exploration
@general      # General research
@scout        # External docs research

curl -fsSL https://opencode.ai/install | bash

# 進入項目目錄
cd /path/to/project

# 啟動 TUI
opencode

# 或指定目錄
opencode /path/to/project

!ls -la
!git status
!npm test

# 直接發送消息（不進入 TUI）
opencode run "幫我解釋 src/index.ts 的功能"

# 指定目錄
opencode run "幫我重構這段代碼" /path/to/project

# 啟動 HTTP 服務器
opencode serve

# 啟動 Web 界面
opencode web

# 指定安裝目錄
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

# XDG 標準路徑
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-haiku-4-20250514",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}

{
  "agent": {
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514"
    },
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

// ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096
  }
}

// 項目根目錄 opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

// ~/.config/opencode/tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

# 在消息中 @ 提及
@general help me search for this function
@explore 幫我找出所有與認證相關的文件
@scout 幫我查看這個庫的源代碼實現

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Review code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      },
      "temperature": 0.1
    }
  }
}

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

You are in code review mode. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

---
description: Create a new component
---

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

---
description: Create a new file with content
---

Create a file named $1 in the directory $2
with the following content: $3

---
description: Review recent changes
---

Recent git commits:

!`git log --oneline -10`

Review these changes and suggest any improvements.

---
description: Review component
---

Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.

.opencode/skills/
├── my-skill/
│   └── SKILL.md
└── another-skill/
    └── SKILL.md

{
  "permission": {
    "edit": "deny",
    "bash": {
      "*": "ask",
      "git diff": "allow",
      "git log*": "allow",
      "grep *": "allow",
      "rm -rf *": "deny"
    },
    "webfetch": "deny"
  }
}

{
  "permission": {
    "mymcp_*": "ask"
  }
}

{
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
---

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

.opencode/
├── agents/     # 自定義代理
├── commands/   # 自定義命令
├── skills/     # 自定義技能
└── plugins/    # 插件

1. cd /path/to/project
2. opencode                              # 啟動 TUI
3. /init                                  # 初始化項目（首次）
4. Tab → Plan                             # 切換到規劃模式
5. "幫我分析一下當前項目的架構..."          # 分析
6. Tab → Build                            # 切換到構建模式
7. "幫我添加這個功能..."                    # 執行
8. /undo                                  # 如果不滿意，撤銷
9. 調整提示詞，重試                         # 迭代
10. /share                                # 分享給團隊

1. @explore 幫我找出所有與認證相關的文件    # 快速探索
2. @code-reviewer 檢查這段代碼的質量        # 使用自定義代理
3. @general 幫我搜索這個庫的最佳實踐        # 外部研究

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-haiku-4-20250514",
  "agent": {
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3
    },
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514",
      "temperature": 0.1,
      "steps": 10
    },
    "code-reviewer": {
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "permission": { "edit": "deny" }
    }
  }
}

curl -fsSL https://opencode.ai/install | bash

cd /path/to/project && opencode