oh-my-openagent-orchestration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Oh My OpenAgent Orchestration

Oh My OpenAgent 编排

Skill by ara.so — AI Agent Skills collection.
Oh My OpenAgent (omo) is an AI agent orchestration framework that coordinates multiple specialized AI agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore) to work in parallel on complex development tasks. It provides hash-anchored editing to prevent stale-line errors, LSP integration for IDE-level precision, background agents for parallel work, and Team Mode for coordinating up to 8 agents simultaneously.
ara.so开发的Skill——AI Agent技能合集。
Oh My OpenAgent (omo) 是一款AI Agent编排框架,可协调多个专业AI Agent(Sisyphus、Hephaestus、Oracle、Librarian、Explore)并行处理复杂开发任务。它提供哈希锚定编辑功能以防止 stale-line 错误、LSP集成实现IDE级精度、后台Agent支持并行工作,以及团队模式可同时协调最多8个Agent。

Installation

安装

Quick Install (Recommended)

快速安装(推荐)

bash
undefined
bash
undefined

Install via npm

通过npm安装

npm install -g oh-my-opencode
npm install -g oh-my-opencode

Or via npx (no install)

或通过npx使用(无需安装)

npx oh-my-opencode
undefined
npx oh-my-opencode
undefined

Configuration Setup

配置设置

Create
opencode.json
or
opencode.jsonc
in your project root:
jsonc
{
  "mcpServers": {
    "oh-my-openagent": {
      "command": "npx",
      "args": ["-y", "oh-my-opencode"]
    }
  }
}
For legacy compatibility,
oh-my-opencode
entries are still supported but will show a deprecation warning.
在项目根目录创建
opencode.json
opencode.jsonc
文件:
jsonc
{
  "mcpServers": {
    "oh-my-openagent": {
      "command": "npx",
      "args": ["-y", "oh-my-opencode"]
    }
  }
}
为兼容旧版本,
oh-my-opencode
配置项仍受支持,但会显示弃用警告。

Environment Variables

环境变量

bash
undefined
bash
undefined

Disable anonymous telemetry (optional)

禁用匿名遥测(可选)

export OMO_SEND_ANONYMOUS_TELEMETRY=0
export OMO_SEND_ANONYMOUS_TELEMETRY=0

or

export OMO_DISABLE_POSTHOG=1
export OMO_DISABLE_POSTHOG=1

Custom configuration path (optional)

自定义配置路径(可选)

export OMO_CONFIG_PATH=/path/to/custom/config.json
undefined
export OMO_CONFIG_PATH=/path/to/custom/config.json
undefined

Key Commands

核心命令

ultrawork
/
ulw

ultrawork
/
ulw

The primary command that activates all discipline agents and doesn't stop until the task is complete.
bash
undefined
激活所有专业Agent的主命令,任务完成前不会停止。
bash
undefined

In your AI agent (Claude Code, Cursor, etc.)

在你的AI Agent(Claude Code、Cursor等)中输入

ultrawork: Implement user authentication with OAuth2

or shorthand:

```bash
ulw: Refactor the payment module to use Stripe
ultrawork: 用OAuth2实现用户认证

或简写形式:

```bash
ulw: 重构支付模块以使用Stripe

Ralph Loop (
/ulw-loop
)

Ralph Loop (
/ulw-loop
)

Self-referential loop that continues iterating until 100% done.
bash
/ulw-loop: Fix all TypeScript errors in the codebase
自引用循环,持续迭代直到任务100%完成。
bash
/ulw-loop: 修复代码库中所有TypeScript错误

Team Mode Commands

团队模式命令

Team Mode (v4.0+) allows a lead agent to coordinate up to 8 parallel member agents.
typescript
// Enable team mode in your configuration
{
  "teamMode": {
    "enabled": true,
    "maxMembers": 8,
    "visualization": "tmux"
  }
}
Available team tools:
  • team_spawn
    - Create a new team member agent
  • team_message
    - Send message to a team member
  • team_status
    - Check status of all team members
  • team_terminate
    - Terminate a team member
Example team mode session:
bash
undefined
团队模式(v4.0+)允许主导Agent协调最多8个并行成员Agent。
typescript
// 在配置中启用团队模式
{
  "teamMode": {
    "enabled": true,
    "maxMembers": 8,
    "visualization": "tmux"
  }
}
可用团队工具:
  • team_spawn
    - 创建新的团队成员Agent
  • team_message
    - 向团队成员发送消息
  • team_status
    - 查看所有团队成员状态
  • team_terminate
    - 终止团队成员
团队模式会话示例:
bash
undefined

Use hyperplan (5 hostile critics)

使用hyperplan(5个严苛评审者)

hyperplan: Review this API design for security vulnerabilities
hyperplan: 审查此API设计的安全漏洞

Use security-research (3 hunters + 2 PoC engineers)

使用security-research(3个漏洞猎手 + 2个PoC工程师)

security-research: Analyze this authentication flow
undefined
security-research: 分析此认证流程
undefined

Discipline Agents

专业Agent

Oh My OpenAgent includes specialized agents that work in parallel:
  • Sisyphus - Lead orchestrator, coordinates other agents
  • Hephaestus - Code implementation and refactoring
  • Oracle - Architecture and design decisions
  • Librarian - Documentation and knowledge retrieval
  • Explore - Codebase exploration and analysis
These agents activate automatically with
ultrawork
.
Oh My OpenAgent包含可并行工作的专业Agent:
  • Sisyphus - 主编排器,协调其他Agent
  • Hephaestus - 代码实现与重构
  • Oracle - 架构与设计决策
  • Librarian - 文档与知识检索
  • Explore - 代码库探索与分析
这些Agent会在执行
ultrawork
时自动激活。

Hash-Anchored Editing

哈希锚定编辑

Prevents stale-line errors by validating content with hash anchors:
typescript
// Traditional edit (prone to stale-line errors)
edit_file({
  path: "src/utils.ts",
  old_content: "function oldName() {",
  new_content: "function newName() {"
});

// Hash-anchored edit (omo)
edit_file({
  path: "src/utils.ts",
  line_id: "L42#a8f3b2c1", // Content hash validates the line
  old_content: "function oldName() {",
  new_content: "function newName() {"
});
The
LINE#ID
format includes a content hash that ensures the line hasn't changed since it was read.
通过哈希锚点验证内容,防止stale-line错误:
typescript
// 传统编辑(易出现stale-line错误)
edit_file({
  path: "src/utils.ts",
  old_content: "function oldName() {",
  new_content: "function newName() {"
});

// 哈希锚定编辑(omo)
edit_file({
  path: "src/utils.ts",
  line_id: "L42#a8f3b2c1", // 内容哈希验证行内容
  old_content: "function oldName() {",
  new_content: "function newName() {"
});
LINE#ID
格式包含内容哈希,确保读取后该行未被修改。

LSP Integration

LSP集成

Access IDE-level features through the agent:
typescript
// Workspace-wide rename
lsp_rename({
  file: "src/models/User.ts",
  position: { line: 10, character: 15 },
  newName: "UserAccount"
});

// Get diagnostics before building
const diagnostics = await lsp_diagnostics({
  file: "src/app.ts"
});

// AST-aware code search
ast_grep({
  pattern: "function $NAME($PARAMS) { $BODY }",
  language: "typescript"
});
通过Agent访问IDE级功能:
typescript
// 工作区全局重命名
lsp_rename({
  file: "src/models/User.ts",
  position: { line: 10, character: 15 },
  newName: "UserAccount"
});

// 构建前获取诊断信息
const diagnostics = await lsp_diagnostics({
  file: "src/app.ts"
});

// 基于AST的代码搜索
ast_grep({
  pattern: "function $NAME($PARAMS) { $BODY }",
  language: "typescript"
});

Background Agents

后台Agent

Fire multiple specialist agents in parallel while keeping context lean:
typescript
// Example: Launch 5 parallel research agents
const tasks = [
  background_agent({ role: "security", task: "Audit auth flow" }),
  background_agent({ role: "performance", task: "Analyze bottlenecks" }),
  background_agent({ role: "testing", task: "Generate test cases" }),
  background_agent({ role: "docs", task: "Update API documentation" }),
  background_agent({ role: "refactor", task: "Clean up legacy code" })
];

// Results returned when ready, doesn't block main agent
启动多个专业Agent并行工作,同时保持上下文简洁:
typescript
// 示例:启动5个并行研究Agent
const tasks = [
  background_agent({ role: "security", task: "Audit auth flow" }),
  background_agent({ role: "performance", task: "Analyze bottlenecks" }),
  background_agent({ role: "testing", task: "Generate test cases" }),
  background_agent({ role: "docs", task: "Update API documentation" }),
  background_agent({ role: "refactor", task: "Clean up legacy code" })
];

// 结果就绪后返回,不会阻塞主Agent

Built-in MCPs (Model Context Protocol)

内置MCP(模型上下文协议)

Oh My OpenAgent includes three built-in MCPs:
Oh My OpenAgent包含三个内置MCP:

Exa (Web Search)

Exa(网页搜索)

bash
undefined
bash
undefined

Search the web for current information

搜索网页获取最新信息

exa: latest TypeScript 5.4 features
undefined
exа: TypeScript 5.4最新特性
undefined

Context7 (Official Documentation)

Context7(官方文档)

bash
undefined
bash
undefined

Fetch official documentation

获取官方文档

context7: React useEffect hook documentation
undefined
context7: React useEffect钩子文档
undefined

Grep.app (GitHub Code Search)

Grep.app(GitHub代码搜索)

bash
undefined
bash
undefined

Search public GitHub repositories

搜索公开GitHub仓库

grep.app: how to implement OAuth2 refresh token rotation
undefined
grep.app: 如何实现OAuth2刷新令牌轮换
undefined

Real-World Usage Examples

实际使用示例

Example 1: Full Feature Implementation

示例1:完整功能实现

bash
ultrawork: Build a REST API for a todo app with:
- User authentication (JWT)
- CRUD operations for todos
- PostgreSQL database
- Input validation
- Unit tests
- API documentation
The agent will:
  1. Analyze requirements through IntentGate
  2. Spawn discipline agents (Hephaestus for code, Oracle for architecture, Librarian for docs)
  3. Use LSP for workspace-aware refactoring
  4. Validate all edits with hash-anchored changes
  5. Run until 100% complete
bash
ultrawork: 构建一个待办事项应用的REST API,包含:
- 用户认证(JWT)
- 待办事项CRUD操作
- PostgreSQL数据库
- 输入验证
- 单元测试
- API文档
Agent将:
  1. 通过IntentGate分析需求
  2. 启动专业Agent(Hephaestus负责代码、Oracle负责架构、Librarian负责文档)
  3. 使用LSP实现工作区感知重构
  4. 通过哈希锚定变更验证所有编辑
  5. 持续运行直到任务100%完成

Example 2: Security Audit

示例2:安全审计

bash
undefined
bash
undefined

Use team mode with security-research preset

使用security-research预设启动团队模式

security-research: Audit the authentication system for vulnerabilities
security-research: 审计认证系统的漏洞

This spawns:

这会启动:

- 3 security hunter agents

- 3个安全漏洞猎手Agent

- 2 PoC engineering agents

- 2个PoC工程师Agent

All working in parallel via tmux visualization

全部通过tmux可视化并行工作

undefined
undefined

Example 3: Large-Scale Refactoring

示例3:大规模重构

bash
/ulw-loop: Migrate the entire codebase from JavaScript to TypeScript
bash
/ulw-loop: 将整个代码库从JavaScript迁移到TypeScript

Ralph loop will:

Ralph循环会:

- Convert files iteratively

- 迭代转换文件

- Fix type errors

- 修复类型错误

- Update imports

- 更新导入

- Run tests after each batch

- 每批转换后运行测试

- Continue until 100% complete

- 持续直到100%完成

undefined
undefined

Example 4: Automated Code Review

示例4:自动化代码评审

typescript
// Use hyperplan for hostile code review
hyperplan: Review this pull request for:
- Security vulnerabilities
- Performance issues
- Code quality
- Test coverage
- Documentation completeness

// This spawns 5 hostile critic agents who will:
// - Challenge every decision
// - Find edge cases
// - Suggest improvements
// - Validate assumptions
typescript
// 使用hyperplan进行严苛代码评审
hyperplan: 评审此拉取请求,检查:
- 安全漏洞
- 性能问题
- 代码质量
- 测试覆盖率
- 文档完整性

// 这会启动5个严苛评审Agent,他们将:
// - 质疑每个决策
// - 发现边缘情况
// - 提出改进建议
// - 验证假设

Configuration

配置

Basic Configuration (
oh-my-opencode.json
)

基础配置(
oh-my-opencode.json

jsonc
{
  // Enable team mode
  "teamMode": {
    "enabled": true,
    "maxMembers": 8,
    "visualization": "tmux",
    "presets": ["hyperplan", "security-research"]
  },
  
  // Configure discipline agents
  "agents": {
    "sisyphus": { "enabled": true },
    "hephaestus": { "enabled": true },
    "oracle": { "enabled": true },
    "librarian": { "enabled": true },
    "explore": { "enabled": true }
  },
  
  // LSP settings
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "python", "rust", "go"],
    "features": ["rename", "diagnostics", "hover", "definition"]
  },
  
  // Hash-anchored editing
  "hashAnchoring": {
    "enabled": true,
    "algorithm": "sha256"
  },
  
  // Built-in MCPs
  "mcps": {
    "exa": { "enabled": true },
    "context7": { "enabled": true },
    "grepApp": { "enabled": true }
  },
  
  // Background agents
  "backgroundAgents": {
    "maxConcurrent": 5,
    "timeout": 3600
  }
}
jsonc
{
  // 启用团队模式
  "teamMode": {
    "enabled": true,
    "maxMembers": 8,
    "visualization": "tmux",
    "presets": ["hyperplan", "security-research"]
  },
  
  // 配置专业Agent
  "agents": {
    "sisyphus": { "enabled": true },
    "hephaestus": { "enabled": true },
    "oracle": { "enabled": true },
    "librarian": { "enabled": true },
    "explore": { "enabled": true }
  },
  
  // LSP设置
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "python", "rust", "go"],
    "features": ["rename", "diagnostics", "hover", "definition"]
  },
  
  // 哈希锚定编辑
  "hashAnchoring": {
    "enabled": true,
    "algorithm": "sha256"
  },
  
  // 内置MCP
  "mcps": {
    "exa": { "enabled": true },
    "context7": { "enabled": true },
    "grepApp": { "enabled": true }
  },
  
  // 后台Agent
  "backgroundAgents": {
    "maxConcurrent": 5,
    "timeout": 3600
  }
}

Model Recommendations

模型推荐

For optimal performance with
ultrawork
:
bash
undefined
ultrawork
实现最佳性能:
bash
undefined

Recommended subscriptions (not affiliated)

推荐订阅(非关联)

- ChatGPT ($20/month) - gpt-4, gpt-5.5

- ChatGPT(每月20美元)- gpt-4, gpt-5.5

- Kimi Code ($19/month) - kimi-k2.6

- Kimi Code(每月19美元)- kimi-k2.6

- GLM Coding ($10/month) - glm-4-plus

- GLM Coding(每月10美元)- glm-4-plus

Or pay-per-token:

或按token付费:

- Kimi models (via API)

- Kimi模型(通过API)

- Gemini models (via Google AI Studio)

- Gemini模型(通过Google AI Studio)

undefined
undefined

Common Patterns

常见模式

Pattern 1: Iterative Development

模式1:迭代开发

bash
undefined
bash
undefined

Start with broad requirements

从宽泛需求开始

ulw: Build a blog platform
ulw: 构建一个博客平台

Let it work, then refine

让Agent工作,然后细化需求

ulw: Add markdown support and syntax highlighting
ulw: 添加Markdown支持和语法高亮

Continue iterating

持续迭代

ulw: Implement comment system with moderation
undefined
ulw: 实现带审核功能的评论系统
undefined

Pattern 2: Multi-Phase Projects

模式2:多阶段项目

bash
undefined
bash
undefined

Phase 1: Architecture

阶段1:架构设计

ultrawork: Design the database schema and API structure
ultrawork: 设计数据库 schema 和 API 结构

Phase 2: Implementation

阶段2:后端实现

ultrawork: Implement the backend API
ultrawork: 实现后端API

Phase 3: Frontend

阶段3:前端开发

ultrawork: Build the React frontend
ultrawork: 构建React前端

Phase 4: Testing & Deployment

阶段4:测试与部署

ultrawork: Add comprehensive tests and deploy to production
undefined
ultrawork: 添加全面测试并部署到生产环境
undefined

Pattern 3: Background Research

模式3:后台研究

bash
undefined
bash
undefined

Fire research agents while working

在工作时启动研究Agent

background_agent({ task: "Research best practices for Redis caching strategies" })
background_agent({ task: "研究Redis缓存策略的最佳实践" })

Continue with main work

继续主任务

ulw: Implement user session management
ulw: 实现用户会话管理

Research results available when ready

研究结果就绪后即可查看

undefined
undefined

Troubleshooting

故障排除

Issue: Stale Line Errors

问题:Stale Line错误

Problem: Traditional agents fail with "line changed" errors.
Solution: Oh My OpenAgent's hash-anchored editing prevents this automatically. No action needed.
问题:传统Agent出现“行已变更”错误。
解决方案:Oh My OpenAgent的哈希锚定编辑可自动防止此问题,无需额外操作。

Issue: Agents Getting Stuck

问题:Agent停滞

Problem: Agent stops making progress.
Solution: Use ralph loop for self-correcting behavior:
bash
/ulw-loop: Complete the remaining tasks
问题:Agent停止推进任务。
解决方案:使用ralph loop实现自校正行为:
bash
/ulw-loop: 完成剩余任务

Issue: Team Members Not Coordinating

问题:团队成员协作不畅

Problem: Team mode agents working in silos.
Solution: Check tmux visualization:
bash
undefined
问题:团队模式Agent各自为战。
解决方案:查看tmux可视化界面:
bash
undefined

Attach to team session

连接到团队会话

tmux attach-session -t omo-team
tmux attach-session -t omo-team

Review agent communication

查看Agent通信状态

team_status
undefined
team_status
undefined

Issue: LSP Features Not Working

问题:LSP功能无法使用

Problem: Rename, diagnostics not available.
Solution: Ensure language server is installed:
bash
undefined
问题:重命名、诊断功能不可用。
解决方案:确保已安装语言服务器:
bash
undefined

For TypeScript

针对TypeScript

npm install -g typescript typescript-language-server
npm install -g typescript typescript-language-server

For Python

针对Python

pip install python-lsp-server
pip install python-lsp-server

Check LSP status in config

在配置中检查LSP状态

{ "lsp": { "enabled": true, "debug": true } }
undefined
{ "lsp": { "enabled": true, "debug": true } }
undefined

Issue: High API Costs

问题:API成本过高

Problem: Too many concurrent agents.
Solution: Adjust background agent limits:
jsonc
{
  "backgroundAgents": {
    "maxConcurrent": 3,  // Reduce from default 5
    "timeout": 1800      // Shorter timeout
  }
}
问题:并发Agent数量过多。
解决方案:调整后台Agent限制:
jsonc
{
  "backgroundAgents": {
    "maxConcurrent": 3,  // 从默认5个减少
    "timeout": 1800      // 缩短超时时间
  }
}

Issue: IntentGate Misunderstanding

问题:IntentGate误解需求

Problem: Agent misinterprets user intent.
Solution: Be more explicit in your prompts:
bash
undefined
问题:Agent误解用户意图。
解决方案:在提示中更明确:
bash
undefined

Vague

模糊表述

ulw: fix the bug
ulw: 修复bug

Better

更清晰的表述

ultrawork: Fix the null pointer exception in src/auth/login.ts line 42 when user email is undefined
undefined
ultrawork: 修复src/auth/login.ts第42行中用户邮箱未定义时出现的空指针异常
undefined

Advanced Usage

高级用法

Custom Agent Presets

自定义Agent预设

Create custom team configurations:
jsonc
{
  "teamMode": {
    "customPresets": {
      "fullstack-sprint": {
        "members": [
          { "role": "backend", "model": "claude-sonnet-4" },
          { "role": "frontend", "model": "gpt-4" },
          { "role": "database", "model": "kimi-k2.6" },
          { "role": "testing", "model": "claude-sonnet-4" },
          { "role": "docs", "model": "gpt-4" }
        ]
      }
    }
  }
}
Usage:
bash
fullstack-sprint: Build a SaaS dashboard for analytics
创建自定义团队配置:
jsonc
{
  "teamMode": {
    "customPresets": {
      "fullstack-sprint": {
        "members": [
          { "role": "backend", "model": "claude-sonnet-4" },
          { "role": "frontend", "model": "gpt-4" },
          { "role": "database", "model": "kimi-k2.6" },
          { "role": "testing", "model": "claude-sonnet-4" },
          { "role": "docs", "model": "gpt-4" }
        ]
      }
    }
  }
}
使用方法:
bash
fullstack-sprint: 构建一个分析用SaaS仪表板

Programmatic API

程序化API

typescript
import { OhMyOpenAgent } from 'oh-my-opencode';

const omo = new OhMyOpenAgent({
  teamMode: { enabled: true, maxMembers: 8 },
  lsp: { enabled: true }
});

// Start ultrawork programmatically
await omo.ultrawork({
  task: "Implement payment processing",
  context: { 
    provider: "stripe",
    features: ["subscriptions", "refunds"]
  }
});

// Monitor progress
omo.on('progress', (status) => {
  console.log(`Progress: ${status.percentage}%`);
});

// Wait for completion
await omo.waitForCompletion();
typescript
import { OhMyOpenAgent } from 'oh-my-opencode';

const omo = new OhMyOpenAgent({
  teamMode: { enabled: true, maxMembers: 8 },
  lsp: { enabled: true }
});

// 以程序化方式启动ultrawork
await omo.ultrawork({
  task: "实现支付处理",
  context: { 
    provider: "stripe",
    features: ["subscriptions", "refunds"]
  }
});

// 监控进度
omo.on('progress', (status) => {
  console.log(`进度: ${status.percentage}%`);
});

// 等待任务完成
await omo.waitForCompletion();

Integration with Popular AI Agents

与主流AI Agent集成

Claude Code

Claude Code

bash
undefined
bash
undefined

In Claude Code, simply type:

在Claude Code中直接输入:

ultrawork: your task here
undefined
ultrawork: 你的任务内容
undefined

Cursor

Cursor

bash
undefined
bash
undefined

In Cursor's composer:

在Cursor的编辑器中输入:

@oh-my-openagent ultrawork: your task here
undefined
@oh-my-openagent ultrawork: 你的任务内容
undefined

AmpCode

AmpCode

bash
undefined
bash
undefined

In AmpCode:

在AmpCode中输入:

/ulw: your task here
undefined
/ulw: 你的任务内容
undefined

Best Practices

最佳实践

  1. Start with
    ultrawork
    - Let the orchestration handle complexity
  2. Use ralph loop for completion - Ensures tasks finish to 100%
  3. Leverage team mode for large tasks - Parallel agents = faster results
  4. Trust hash-anchored editing - No need to manually verify line changes
  5. Use background agents for research - Keep main agent focused
  6. Be specific with IntentGate - Clear intent = better results
  7. Monitor team status in tmux - Visual feedback prevents confusion
  8. Use presets for common workflows -
    hyperplan
    ,
    security-research
    , etc.
  1. ultrawork
    开始
    - 让编排功能处理复杂任务
  2. 使用ralph loop确保完成 - 确保任务100%完成
  3. 针对大型任务使用团队模式 - 并行Agent提升效率
  4. 信任哈希锚定编辑 - 无需手动验证行变更
  5. 使用后台Agent进行研究 - 让主Agent专注核心任务
  6. 对IntentGate明确表述 - 清晰意图带来更好结果
  7. 在tmux中监控团队状态 - 可视化反馈避免混乱
  8. 针对常见工作流使用预设 - 如
    hyperplan
    security-research

Resources

资源