Oh My OpenAgent (OMO)

Oh My OpenAgent（OMO） 是建立在 OpenCode 上的 multi-agent orchestration layer。

官方 Repository：oh-my-openagent

核心概念不是讓一個 Agent 做完所有事情，而是由主要 Agent 根據任務，把工作交給不同的專業 Subagent。

User
 │
 ▼
Sisyphus
 ├── Explore      → 搜尋 codebase
 ├── Librarian    → 查文件 / OSS
 ├── Oracle       → 架構與疑難問題
 └── Junior       → 實際執行 coding task

一般開發情境下，直接使用 Sisyphus 即可，不需要手動選擇每一個 Subagent。

安裝

前提：

• OpenCode（相關：OpenCode Autocomplete 指南）
• Bun
• Git（git 常用指令指南）
• tmux（建議）

安裝 OMO：

bunx oh-my-openagent install

依照 TUI 選擇目前可使用的 Model Provider。

檢查安裝：

bunx oh-my-openagent doctor

查看版本：

bunx oh-my-openagent version

主要設定檔：

~/.omo/omo.jsonc

Project-specific 設定也可以放：

<repo>/.omo/omo.jsonc

tmux 設定

OMO 可以把 Background Subagent 顯示在獨立的 tmux pane。

基本的 tmux 操作見 tmux 常用指南。

在 ~/.omo/omo.jsonc：

{
  "[opencode]": {
    "tmux": {
      "enabled": true,
      "layout": "main-vertical",
      "main_pane_size": 60,
      "main_pane_min_width": 120,
      "agent_pane_min_width": 40,
      "isolation": "inline"
    }
  }
}

推薦：

main-vertical

┌────────────────────────┬───────────────┐
│                        │ Subagent      │
│                        ├───────────────┤
│       Sisyphus         │ Subagent      │
│                        ├───────────────┤
│                        │ Subagent      │
└────────────────────────┴───────────────┘

啟動 OMO + tmux

建立 tmux session：

tmux new -s omo

在 tmux 中啟動 OpenCode：

opencode --port 4096

建議明確設定：

OPENCODE_PORT=4096 opencode --port 4096

如果同時開多個 OpenCode instance：

Project / Worktree A → 4096
Project / Worktree B → 4097
Project / Worktree C → 4098

每個 instance 使用不同 Port。

自動尋找可用 Port

如果經常同時啟動多個 OpenCode instance，可以在 ~/.zshrc 或是 ~/.bashrc 加一個 wrapper，自動從 4096 開始尋找尚未被使用的 Port。

omo() {
  local port=4096
  local max_port=4196

  while [ "$port" -le "$max_port" ]; do
    if ! lsof -iTCP:$port -sTCP:LISTEN >/dev/null 2>&1; then
      echo "Starting OpenCode on port $port"
      OPENCODE_PORT=$port opencode --port $port "$@"
      return
    fi

    port=$((port + 1))
  done

  echo "No available port found between 4096 and $max_port"
  return 1
}

tmux 常用快捷鍵

如果 Subagent pane 顯示：

Focus this pane to attach

切換到該 pane：

Ctrl-b →

OMO 會 attach 到該 Subagent session。

Agents

OMO 分成 Primary Agent 與 Subagent。

Primary Agents

Sisyphus

平常預設使用這個即可。

負責：

• 理解需求
• 拆解任務
• 呼叫 Subagent
• Coding
• Test / Verify
• 收斂結果

例如：

Fix issue #123 and add regression tests.

或：

Implement pagination for the API.

複雜但不想先 Plan：

ulw

Refactor the authentication flow and make sure all tests pass.

ulw / ultrawork 適合「自己研究、自己拆解、做到完成」。

Hephaestus

適合需要非常深推理的工作：

Why does this race condition happen only under high concurrency?

Refactor this monolith into a modular architecture.

常見場景：

• Architecture redesign
• 跨大量檔案 Debug
• Race condition
• Memory leak
• 大型 Migration
• 複雜 Refactor

簡單判斷：

一般複雜工作
→ Sisyphus + ulw

需要深度 architecture / debugging reasoning
→ Hephaestus

Prometheus

專門負責 Planning。

適合：

• 大型 Feature
• Scope 不明確
• 多階段 Migration
• Architecture change
• Implementation 前需要先 review 設計

可以直接切換到 Prometheus，或：

@plan "Add CodeGraph support to project ingestion"

Prometheus 會：

需求訪談
 ↓
Explore / Librarian Research
 ↓
Metis Gap Analysis
 ↓
建立 Implementation Plan
 ↓
Momus / Oracle Review

Plan 通常存放：

.omo/plans/

Atlas

Atlas 是 Plan Executor。

主要工作：

Read Plan
  ↓
拆分 Tasks
  ↓
Delegate
  ↓
Verify
  ↓
Continue

建立 Plan 後：

/start-work

Atlas 會依照 Plan 持續執行。

適合：

@plan
  ↓
Prometheus
  ↓
plan.md
  ↓
/start-work
  ↓
Atlas
  ↓
Subagents

Subagents

通常不需要手動操作，由 Sisyphus / Atlas 自動呼叫。

Explore vs Librarian

最常見的兩個 Research Agent。

「我們自己的 code 怎麼做？」
→ Explore

「外部 library / framework 怎麼做？」
→ Librarian

例如：

Find where authentication middleware is implemented.
→ Explore

Find the recommended FastAPI authentication pattern.
→ Librarian

Oracle

Oracle 比較像 Senior Architect / Consultant。

適合：

Should this service use event-driven architecture?

Why can this transaction still produce duplicate rows?

Review this architecture and identify hidden failure modes.

通常負責分析與建議，而不是主要 Coding Worker。

Metis + Momus

主要出現在 Planning Workflow。

Prometheus
   │
   ├── Metis
   │     └── 找漏掉的需求 / edge cases
   │
   └── Momus
         └── Review plan 是否真的可執行

日常小型 Issue 通常不需要特別使用。

日常使用場景

小 Issue

直接：

Fix issue #123, add regression tests, and verify the fix.

使用：

Sisyphus
 ├── Explore
 └── Junior

中型 Feature

Implement xxx feature.
Investigate the existing architecture first and reuse existing patterns.

使用：

Sisyphus
 ├── Explore
 ├── Librarian
 ├── Oracle（必要時）
 └── Junior

大型 Feature

推薦：

@plan "Implement xxx feature"

確認 Plan 後：

/start-work

流程：

Prometheus
   ↓
Metis / Momus / Oracle
   ↓
Plan
   ↓
Atlas
   ↓
Workers

複雜 Debug

先嘗試：

ulw

Investigate the root cause of xxx.
Do not patch symptoms; identify and verify the actual root cause.

如果涉及非常深的 architecture / concurrency / cross-system reasoning：

Hephaestus

Cheat Sheet

多個工作同時進行

同一 Repo 如果同時：

Fix Issue
+
Develop Feature

建議使用不同 Git Worktree（清理方法見 macOS 清理 Codex / Claude Code / OpenCode Worktree 指南）：

repo/
repo-fix-123/
repo-feature-x/

並啟動不同 OpenCode instance：

repo-fix-123
└── OpenCode :4096

repo-feature-x
└── OpenCode :4097

原則：

同一 Branch / 同一項工作
→ 同一 OpenCode instance

不同 Branch / 不同 Deliverable
→ Worktree + 不同 OpenCode instance

避免不同 Agent 同時修改相同 working directory。

Team Mode

Team Mode 是額外的 parallel multi-agent orchestration，預設關閉。

一般：

Sisyphus + Background Subagents

已足夠處理大部分開發工作。

Team Mode 比較適合：

• 多個高度獨立 Workstream
• 大型 Investigation
• 大量 Issue 平行處理
• Security Research
• 希望看到多個長生命週期 Agent 同時工作

它支援：

• Lead + 多個 Members
• Shared Task List
• Agent Messaging
• Per-member Git Worktree
• tmux Visualization

因此：

一般 Coding
→ Sisyphus

複雜單一 Task
→ Sisyphus + ulw / Hephaestus

大型且需要規劃
→ Prometheus → Atlas

多個真正獨立 Workstream
→ Team Mode

Quick Reference

日常工作
→ Sisyphus

「幫我自己研究做到完」
→ Sisyphus + ulw

找 Code
→ Explore

找 Documentation / OSS
→ Librarian

Architecture / 疑難問題
→ Oracle

深度 Autonomous Reasoning
→ Hephaestus

大型 Feature Planning
→ Prometheus / @plan

執行 Plan
→ /start-work → Atlas

多 Workstream Parallel
→ Team Mode

常用 Commands

# OMO health check
bunx oh-my-openagent doctor

# tmux
tmux new -s omo
tmux attach -t omo


## inside tmux, enable subanget pane ---------------------------------------

# option1: OMO + OpenCode
OPENCODE_PORT=4096 opencode --port 4096

# option2: 有使用上述 自動尋找可用 Port 腳本
omo

OpenCode 內：

@plan "..."   # 大型 Feature / Architecture Change, 先產生 implementation plan，不直接開始修改程式
/start-work   #已完成並確認 Plan 後, 依照既有 Plan 開始實作，由 Atlas 協調執行

## ------------------------------------------------------


ulw          # 中大型 Issue / 複雜 Debug, 不想先做完整 Plan，希望 Sisyphus 自行探索、拆解、呼叫                        # subagents、實作、測試並持續做到完成

<task>       # 小任務