Oh My Openagent Orchestration

Oh My OpenAgent Orchestration

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.

Installation

Quick Install (Recommended)

# Install via npm
npm install -g oh-my-opencode

# Or via npx (no install)
npx oh-my-opencode

Configuration Setup

Create opencode.json or opencode.jsonc in your project root:

{
  "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.

Environment Variables

# Disable anonymous telemetry (optional)
export OMO_SEND_ANONYMOUS_TELEMETRY=0
# or
export OMO_DISABLE_POSTHOG=1

# Custom configuration path (optional)
export OMO_CONFIG_PATH=/path/to/custom/config.json

Key Commands

ultrawork / ulw

The primary command that activates all discipline agents and doesn't stop until the task is complete.

# In your AI agent (Claude Code, Cursor, etc.)
ultrawork: Implement user authentication with OAuth2

or shorthand:

ulw: Refactor the payment module to use Stripe

Ralph Loop (/ulw-loop)

Self-referential loop that continues iterating until 100% done.

/ulw-loop: Fix all TypeScript errors in the codebase

Team Mode Commands

Team Mode (v4.0+) allows a lead agent to coordinate up to 8 parallel member agents.

// 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:

# Use hyperplan (5 hostile critics)
hyperplan: Review this API design for security vulnerabilities

# Use security-research (3 hunters + 2 PoC engineers)
security-research: Analyze this authentication flow

Discipline Agents

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.

Hash-Anchored Editing

Prevents stale-line errors by validating content with hash anchors:

// 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.

LSP Integration

Access IDE-level features through the agent:

// 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"
});

Background Agents

Fire multiple specialist agents in parallel while keeping context lean:

// 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

Built-in MCPs (Model Context Protocol)

Oh My OpenAgent includes three built-in MCPs:

Exa (Web Search)

# Search the web for current information
exa: latest TypeScript 5.4 features

Context7 (Official Documentation)

# Fetch official documentation
context7: React useEffect hook documentation

Grep.app (GitHub Code Search)

# Search public GitHub repositories
grep.app: how to implement OAuth2 refresh token rotation

Real-World Usage Examples

Example 1: Full Feature Implementation

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

Example 2: Security Audit

# Use team mode with security-research preset
security-research: Audit the authentication system for vulnerabilities

# This spawns:
# - 3 security hunter agents
# - 2 PoC engineering agents
# All working in parallel via tmux visualization

Example 3: Large-Scale Refactoring

/ulw-loop: Migrate the entire codebase from JavaScript to TypeScript

# Ralph loop will:
# - Convert files iteratively
# - Fix type errors
# - Update imports
# - Run tests after each batch
# - Continue until 100% complete

Example 4: Automated Code Review

// 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

Configuration

Basic Configuration (oh-my-opencode.json)

{
  // 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
  }
}

Model Recommendations

For optimal performance with ultrawork:

# Recommended subscriptions (not affiliated)
# - ChatGPT ($20/month) - gpt-4, gpt-5.5
# - Kimi Code ($19/month) - kimi-k2.6
# - GLM Coding ($10/month) - glm-4-plus

# Or pay-per-token:
# - Kimi models (via API)
# - Gemini models (via Google AI Studio)

Common Patterns

Pattern 1: Iterative Development

# Start with broad requirements
ulw: Build a blog platform

# Let it work, then refine
ulw: Add markdown support and syntax highlighting

# Continue iterating
ulw: Implement comment system with moderation

Pattern 2: Multi-Phase Projects

# Phase 1: Architecture
ultrawork: Design the database schema and API structure

# Phase 2: Implementation
ultrawork: Implement the backend API

# Phase 3: Frontend
ultrawork: Build the React frontend

# Phase 4: Testing & Deployment
ultrawork: Add comprehensive tests and deploy to production

Pattern 3: Background Research

# Fire research agents while working
background_agent({ 
  task: "Research best practices for Redis caching strategies"
})

# Continue with main work
ulw: Implement user session management

# Research results available when ready

Troubleshooting

Issue: Stale Line Errors

Problem: Traditional agents fail with "line changed" errors.

Solution: Oh My OpenAgent's hash-anchored editing prevents this automatically. No action needed.

Issue: Agents Getting Stuck

Problem: Agent stops making progress.

Solution: Use ralph loop for self-correcting behavior:

/ulw-loop: Complete the remaining tasks

Issue: Team Members Not Coordinating

Problem: Team mode agents working in silos.

Solution: Check tmux visualization:

# Attach to team session
tmux attach-session -t omo-team

# Review agent communication
team_status

Issue: LSP Features Not Working

Problem: Rename, diagnostics not available.

Solution: Ensure language server is installed:

# For TypeScript
npm install -g typescript typescript-language-server

# For Python
pip install python-lsp-server

# Check LSP status in config
{
  "lsp": {
    "enabled": true,
    "debug": true
  }
}

Issue: High API Costs

Problem: Too many concurrent agents.

Solution: Adjust background agent limits:

{
  "backgroundAgents": {
    "maxConcurrent": 3,  // Reduce from default 5
    "timeout": 1800      // Shorter timeout
  }
}

Issue: IntentGate Misunderstanding

Problem: Agent misinterprets user intent.

Solution: Be more explicit in your prompts:

# Vague
ulw: fix the bug

# Better
ultrawork: Fix the null pointer exception in src/auth/login.ts line 42 
when user email is undefined

Advanced Usage

Custom Agent Presets

Create custom team configurations:

{
  "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:

fullstack-sprint: Build a SaaS dashboard for analytics

Programmatic API

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();

Integration with Popular AI Agents

Claude Code

# In Claude Code, simply type:
ultrawork: your task here

Cursor

# In Cursor's composer:
@oh-my-openagent ultrawork: your task here

AmpCode

# In AmpCode:
/ulw: your task here

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.

Resources

• Documentation
• Team Mode Guide
• Discord Community
• GitHub Repository
• Installation Guide