OpenCode + oh-my-opencode Best Practices Guide

Aimed at developers with experience in using AI programming assistants, focusing on the real world, and based on the latest official documentation (2026-04).

I. What is OpenCode

OpenCode is an open source AI programming agent running in the terminal, supporting 75+ models such as Claude, GPT, Gemini, etc., and providing three forms of TUI/IDE plugin/desktop application.

Biggest difference from Claude Code:No model locking, fully open source, Agent system is deeply extensible.

II. Installation and configuration

# 方式一：官方安装脚本（推荐）
curl -fsSL <https://opencode.ai/install> | bash

# 方式二：Homebrew（最新版本）
brew install anomalyco/tap/opencode

# 方式三：Node.js
npm install -g opencode-ai

Configure the API Key:

export ANTHROPIC_API_KEY="sk-ant-..."
# 或在 TUI 里运行 /connect，按提示授权

OpenCode Core Concepts: The Agent System

This is the key to understanding OpenCode, as opposed to Claude Code's single Agent model.

3.1 Two types of Agent

There are two types of Agent for OpenCode:

Primary Agent: The person you're talking to directly, with Tab key to switch between them.

Subagent: The main Agent schedules automatically, or you can manually @mention Specialized assistants for calls.

After installing oh-my-opencode, both the main Agent and the sub-Agents are greatly expanded, see Section V.

3.2 @ The two uses of

@ is the most important input symbol in the TUI and has two completely different uses:

① References(fuzzy search)

这段鉴权逻辑有没有问题？@src/middleware/auth.ts

Triggers a fuzzy file search, with the contents of the file automatically injected into the context when selected.

② @mention Sub Agent(direct call)

@explore 找出所有调用了 sendEmail 的地方
@general 帮我并行处理这三个模块的文档生成

The master Agent can also automatically @mention sub-Agents to accomplish specialized tasks during execution.

Both can be mixed in the same message:

@explore 分析 @src/api/ 目录下所有接口的结构

3.3 Tab Key: Switch main Agent

Tab key in allPrimary Agent Rotation between.Shift+Tab Reverse switching.

Tab          # 切换主 Agent（Build → Plan → 自定义 Agent → ...）
Shift+Tab    # 反向切换

⚠️ Common Misconception: Tab is not ”switching Plan/Build mode”, it is switching between two separate Master Agents.

The Plan Agent is essentially a restricted agent that ”requires manual confirmation by default for file writes and bash commands”.

Typical Usage:

# 先切到 Plan Agent 规划，只提方案不改代码
Tab  →  描述需求，拿到方案后审查

# 方案确认后切回 Build Agent 执行
Tab  →  好，按计划执行。

3.4 Shortcut Keys

The Leader key defaults to Ctrl+XThe following is an example of a program that can be used in the tui.json Modified in.

IV. TUI Common Operations

4.1 Initializing the project

cd /path/to/project
opencode

Runs inside the TUI:

/init

Analyze the project structure and generate in the root directory AGENTS.md——Be sure to commit to GitThis is Agent's project memory.

4.2 Executing Shell Commands

The message was delivered in the form of ! starts with a shell command that is run directly, and the output is injected into the context as a result of the tool:

!git log --oneline -20
!npm test -- --coverage
!cat package.json

4.3 Undo/Redo

/undo    # 撤销最近一次修改（含文件变更），可多次执行
/redo    # 重新应用已撤销的修改

rely on Git to manage file changes.The project must be a Git repository。

4.4 Context management

/compact    # 压缩当前会话，保留关键上下文，释放 token（alias: /summarize）
/new        # 开启新会话（alias: /clear）
/sessions   # 查看并切换历史会话（alias: /resume）

4.5 Other common commands

/share      # 生成会话分享链接（复制到剪贴板）
/unshare    # 取消分享
/export     # 导出会话为 Markdown，用外部编辑器打开
/thinking   # 切换是否显示 Extended Thinking 内容
/models     # 列出可用模型
/themes     # 切换主题

V. AGENTS.md and custom extensions

5.1 Three entry-into-force positions

OpenCode is also compatible with Claude Code's CLAUDE.md format (out-of-the-box for migration).

5.2 What to write in AGENTS.md

# 项目名称

## 技术栈
- 后端：Java 21 + Spring Boot 3.x
- 数据库：PostgreSQL（ORM 用 jOOQ，禁止使用 Hibernate）
- API 风格：RESTful，响应统一用 Result<T> 包装

## 构建与测试
- 构建：`mvn clean package`
- 单元测试：`mvn test`
- 集成测试：`mvn verify -P integration`

## 代码规范
- 所有 public 方法必须有 Javadoc
- 禁止在循环内执行数据库查询
- 异常统一通过 GlobalExceptionHandler 处理

## 架构说明
- 请求链路：Controller → Service → Repository → DB
- 跨模块只能通过 service 层调用，不能跨层调用 repository

5.3 Customizing Agent

在 .opencode/agents/ 或 ~/.config/opencode/agents/ establish .md Documentation:

---
description: 安全审计，检查代码安全漏洞
mode: subagent
model: anthropic/claude-opus-4-6
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

你是一名安全专家，专注以下方面的代码审计：
- SQL 注入、XSS、CSRF 漏洞
- 不安全的反序列化
- 硬编码的密钥或密码
- 权限校验缺失

只提供分析报告，不直接修改代码。

The filename is the Agent name (e.g. security-auditor.md → @security-auditor），mode: subagent denote a property that can be used by @mention Call.

5.4 Customized commands

在 .opencode/commands/ 或 ~/.config/opencode/commands/ Create a command file:

---
description: Code Review，重点关注安全和性能
agent: build
---

请对以下代码进行 Code Review，重点关注：
1. 安全漏洞（注入、权限、加密）
2. 性能问题（N+1 查询、内存泄漏）
3. 边界条件和异常处理
4. 命名和可读性

文件：$ARGUMENTS

Use:/code-review src/api/OrderController.java

Command Support $ARGUMENTS(all parameters) or $1、$2(positional parameter), which can be specified in the frontmatter. agent、model。

VI. oh-my-opencode: Turning OpenCode into a Development Team

oh-my-opencode (now renamed oh-my-openagentThe npm package name is still oh-my-opencode) is the most powerful OpenCode plugin available.

Core Competencies: 11 Specialized Agents + Parallel Sub-Agent + ulw One-click fully automated + LSP/AST-Grep tool + automatic context management.

6.1 Installation

bunx oh-my-opencode install

Verify the installation:

cat ~/.config/opencode/opencode.json
# plugins 数组中应包含 "oh-my-opencode"

6.2 ulw: one of the most important words

ulw(short for ultrawork) is the core keyword of oh-my-opencode.

The cue word only needs to contain ulw 或 ultraworkThe plug-in automatically triggers the ”Strongest Mode”:

• - Self-exploration of the code base and study of implementation patterns
• - Scheduling multiple specialized Agents side by side (of two processes, developments, thoughts etc)(of a machine) operate
• - Continuous execution until completion, without stopping to wait for confirmation.
• - Automated diagnostic validation results

The usage is minimal:

ulw 给 /api/orders 接口增加分页功能，参考 /api/products 的实现方式

ulw 找出所有 N+1 查询问题并修复

ulw 将整个项目的错误处理统一改为 Result 模式

ulw 重构 src/payment/ 为策略模式，现有支付方式三种，对外接口不变

formula: When faced with a large task and don't know where to start, go straight to the ulw, let the system make its own decisions.

Other modes of keyword triggering:

6.3 11 Specialized Agents

After installation, theTab key to switch between these Master Agents (by priority):

Main Agent (Tab Switching):

Sub Agent (@mention call):

Most scenarios do not require manual Agent selection.ulw It will be automatically scheduled.

6.4 /start-work: large feature development workflow

For large functions that are cross-module and have architectural decisions. The process is as follows:

Step 1: Tab to Prometheus, describe requirements

Prometheus asks back for details like a real engineer. After the answer:

好，生成计划。

The plan file is saved in the .sisyphus/plans/*.md, which can be previewed and modified.

Step 2: Confirm the plan and run

/start-work

Atlas takeover, automatic execution on schedule, automatic recovery even if disconnected (status exists) boulder.json）。

⚠️ Prometheus and Atlas must be paired.Do not switch directly to Atlas execution.

When to use ulw and when to use /start-work?

VII. Typical scenarios

Scenario 1: Quickly Understand an Unfamiliar Code Base

@explore 找出所有 API 入口点，列出路由和对应的 Handler

ulw 分析这个项目的整体架构，重点是请求的完整链路，
输出一份给新人的 onboarding 文档

Scenario 2: New Function Development

Small features (1-2 files): Direct Build Agent

在 @src/user/UserService.java 增加手机号登录方法，
参考邮箱登录 @src/user/EmailLoginStrategy.java

Medium function (multiple file linkage): Plan → Build

Tab（切换到 Plan Agent）

给删除订单功能加软删除：deleted_at 标记删除时间，
新增回收站页面支持恢复和彻底删除

（审查方案）

Tab（切回 Build Agent）
好，按计划执行。

Large functions (across modules): ulw or /start-work

ulw 实现完整的优惠券系统：
固定金额/百分比两种折扣，限制使用次数和有效期，与购物车集成

Scenario 3: Code review (no code changes)

@explore 全量扫描 src/api/ 目录，找出所有没有做权限校验的接口

@oracle 对 @src/payment/PaymentService.java 做架构审查，
重点：并发安全、幂等性、异常边界

Scenario 4: Debugging Complex Bugs

ulw 追踪这个 NPE 的根本原因，从堆栈顶部到数据来源全链路分析，
找到根因后给出修复方案。堆栈：

java.lang.NullPointerException
    at com.example.OrderService.process(OrderService.java:142)
    ...

Scenario 5: Extensive Reconfiguration

ulw 将 src/payment/ 模块重构为策略模式，
现有支付方式：支付宝、微信、信用卡，
要求：对外接口不变，所有现有测试继续通过

Scenario 6: UI Restore (Design Draft)

After dragging and dropping the screenshot to the terminal:

@multimodal-looker 分析这张设计稿的布局和样式
按照图中的设计实现 @src/components/Dashboard.tsx

Scenario 7: Generate Documentation

ulw 为 src/api/ 下所有公开接口生成 OpenAPI 3.0 规范，
输出到 docs/openapi.yaml，参考 @docs/openapi-sample.yaml 的格式

VIII. Configuration quick reference

8.1 opencode.json

{
  "$schema": "<https://opencode.ai/config.json>",
  "model": "anthropic/claude-opus-4-6",
  "autoshare": false,
  "plugins": ["oh-my-opencode"]
}

8.2 oh-my-opencode Agent Configuration

~/.config/opencode/oh-my-opencode.json：

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6"
    },
    "oracle": {
      "thinking": {
        "type": "enabled",
        "budgetTokens": 200000
      }
    },
    "explore": {
      "textVerbosity": "low"
    }
  }
}

8.3 Built-in Skills (oh-my-opencode)

Customize the Skill path:

.opencode/skills/my-skill/SKILL.md
~/.config/opencode/skills/my-skill/SKILL.md

IX. Frequently asked questions

Q:@ Citing documents and @mention How is an Agent differentiated?

Shared by both @ Symbols, differentiated logic: enter @ If the match is a path to a file, then the contents of the file will be injected; if the input is a registered Agent name (e.g. @explore), then the child Agent call is triggered.

Q:Tab Toggles between Agent and Ctrl+T What is the difference between switching model variants?

Tab switch modes or data streamsMain Agent(Role switching, along with switching the Agent's exclusive model and tool permissions);Ctrl+T Switch the current Agent'smodel variant(e.g. Standard vs Extended Thinking version of the same model).

Q: What is the difference between ulw and a direct description of requirements?

When described directly, Sisyphus executes in a single thread and may stop and ask when it encounters uncertainty. Add ulw Post-trigger fully automated parallel mode: multiple sub-agents work simultaneously, explore the codebase on their own, don't wait for confirmation in the middle of the process, and continue to validate until they are completely finished.

Q: What should I do if /start-work is interrupted?

re-run /start-workSystem from boulder.json Resume progress and continue unfinished tasks.

Q: What if the context is almost full?

(of a computer) run /compact Compressing the current session, critical context is preserved. Large tasks are prioritized using /start-work Workflows, sub-agents distribute contextual pressure.

bibliography

• - OpenCode Official Documentation
• - OpenCode Agents Documentation
• - OpenCode Keybinds Documentation
• - oh-my-opencode GitHub
• - awesome-opencode plugin collection