DOCSEARCHbyAlgolia
Submit Docs

oh-my-claudecode (OMC) Documentation

repository·main·Indexed 31 days ago

https://github.com/yeachan-heo/oh-my-claudecode

An orchestration layer for Claude Code that transforms it into a coordinated team of specialized agents. Features multiple execution modes including Autopilot, Ultrawork, Swarm, Pipeline, and Ralph. Includes benchmarking suites for SWE-bench and Harsh-Critic, and a template system for multi-tier agent prompt engineering (LOW, MEDIUM, HIGH).

Tokens
165.3K
Snippets
317
Records
722
Agent score
98%

What's inside oh-my-claudecode

  1. Overview of oh-my-claudecode (OMC) orchestration

    main

    oh-my-claudecode (OMC) is a multi-agent orchestration layer for Claude Code. It coordinates specialized agents, tools, and skills to complete engineering tasks accurately and efficiently.

    Core Operating Principles:

    • Delegate: Assign specialized work to the most appropriate agent.
    • Evidence-First: Verify outcomes with evidence (builds, tests, logs) before claiming completion.
    • Efficiency: Choose the lightest-weight path (model/agent) that preserves quality.
    • Consultation: Always consult official documentation before implementing new SDKs or APIs.

  2. Overview of OMC Seminar Demo sequences

    main

    The OMC seminar consists of 5 progressive demonstrations showcasing different orchestration capabilities:

    1. Autopilot: Full autonomous execution from initial idea to working code.
    2. Ultrawork: Demonstrates maximum parallelism using multiple agents working simultaneously.
    3. Pipeline: Shows sequential agent chaining where data is passed between agents for complex workflows.
    4. Planning: An interactive planning workflow using an interview process to clarify requirements.
    5. Ralph: Demonstrates persistent execution and self-correction for mission-critical tasks.

    Total estimated time: ~15 minutes.

  3. Understand the Executor agent role and constraints

    main

    The Executor is a specialized agent (using the sonnet model) focused exclusively on implementing code changes precisely as specified. Unlike planners or architects, its goal is to write, edit, and verify code with the smallest viable diff.

    Key Responsibilities

    • Implement code changes end-to-end.
    • Perform autonomous exploration and planning for multi-file changes.
    • Verify changes using lsp_diagnostics, builds, and tests.
    • Match existing codebase patterns (naming, error handling, imports).

    Core Constraints

    • Smallest Viable Change: Avoid over-engineering or introducing new abstractions for single-use logic.
    • No Scope Creep: Do not refactor adjacent code or fix unrelated issues unless explicitly requested.
    • Work Alone: Implementation must be done by the Executor. While it can spawn up to 3 parallel explore agents for reading/searching, all code changes must be its own.
    • Plan Files are Read-Only: Never modify files in .omc/plans/*.md.
    • Escalation: If an issue cannot be resolved after 3 failed attempts, the Executor must escalate to the architect agent with full context.
    • No Debug Leaks: Ensure no console.log, TODO, HACK, or debugger statements remain in the code before completion.

  4. Understand Native Team Worktree Mode

    main

    Native Team Worktree Mode is an opt-in feature for runtime-v2 that allows omc team workers to run in dedicated git worktrees. This isolates worker edits while maintaining a single, leader-owned coordination root for task, mailbox, status, and manifest state. This prevents workspace fragmentation during complex team operations.

    Key Characteristics

    • Isolation: Worker edits occur in separate git worktrees.
    • Centralized Coordination: All workers communicate via a single team-specific coordination root.
    • Safety: The system prevents provisioning worktrees if the leader workspace is dirty and preserves dirty worker worktrees during cleanup to prevent data loss.

  5. Use the LLM Wiki for persistent knowledge management

    main
    The LLM Wiki is a persistent, self-maintained markdown knowledge base used to compound project and session knowledge across different sessions. It uses keyword and tag matching for queries rather than vector embeddings. Knowledge is stored locally in .omc/wiki/ as markdown files with YAML frontmatter and is git-ignored by default.

  6. Understand the MCP/Plugin Compatibility Layer

    main

    The Compatibility Layer allows Oh-My-ClaudeCode (OMC) to discover, register, and use external plugins, MCP servers, and tools. It consists of four main systems:

    1. Discovery System: Automatically finds plugins and MCP servers from user directories (e.g., ~/.claude/plugins/) and configuration files.
    2. Tool Registry: A central hub that manages all external tools, handles name conflicts via a priority system, and provides namespaced tool lookups.
    3. Permission Adapter: Ensures safe execution by auto-approving read-only operations (like filesystem reads or documentation queries) and prompting users for dangerous operations (like writes or executions).
    4. MCP Bridge: Manages connections to MCP servers using JSON-RPC 2.0 over process stdio.

  7. Understand Ecomode Smart Model Routing

    main

    Ecomode uses a smart routing algorithm to assign tasks to different AI model tiers (Low, Medium, High) based on task complexity. This optimizes for cost and token usage without sacrificing quality by using the most efficient model for the specific job.

    Model Tiers

    • LOW TIER (Haiku): Used for quick lookups, simple edits, file searches, and config files. Fast and low cost.
    • MEDIUM TIER (Sonnet): Used for feature implementation, bug fixes, testing, UI work, and documentation. Medium speed and cost.
    • HIGH TIER (Opus): Used for architecture, complex debugging, refactoring, security, and planning. Thorough and higher cost.

    Selection Logic

    Tasks are routed based on the following criteria:

    • HIGH: If task.linesChanged > 100 or task.filesChanged > 5.
    • MEDIUM: If the task requiresReasoning or fileExists.
    • LOW: All other tasks.

  8. Compare Hephaestus and Deep-Executor architectures

    main

    The project contains a comparative analysis between two agent architectures: Hephaestus (a distributed, multi-agent conductor/delegator model) and Deep-Executor (a self-contained, single-agent monolith model).

    Key Architectural Differences

    • Hephaestus: Uses parallel background agents (2-5 agents) for exploration, documentation, and architecture. It optimizes for wall-clock speed and broad capability at the cost of higher token usage (~2.5x more).
    • Deep-Executor: Uses a single-agent sequential model. It optimizes for token efficiency and self-sufficiency but is slower for large codebase exploration and lacks external research capabilities.

    Comparison Summary

    FeatureHephaestusDeep-Executor
    Execution ModelMulti-agent parallelSingle-agent sequential
    Tool StrategyAgents as toolsDirect MCP/LSP tools
    External ResearchSupported (Document-Specialist)Not supported
    Token EfficiencyLower (~30k-50k per task)Higher (~10k-20k per task)
    Failure RecoveryStructured 3-failure protocolVerification loops only

  9. Understand the Claude Code `/goal` Adapter Design

    main

    The /goal Adapter is a design contract for integrating Claude Code's native /goal work loop with OMC (oh-my-claudecode). It ensures that while Claude Code handles the session-scoped loop, OMC maintains a durable audit trail, enforces hook safety, and prevents loop authority conflicts.

    Key Responsibilities:

    • Capability Detection: Verifies if /goal is available before suggesting a handoff.
    • Measurable Handoffs: Renders explicit /goal <completion condition> prompts instead of writing to hidden session state.
    • Auditability: Records requested conditions, status snapshots, evaluator reasons, and command evidence in OMC-owned artifacts.
    • Conflict Management: Enforces a single active loop authority (e.g., preventing /goal from competing with Ralph, Team, or Autopilot).
    • Fallback Support: Degrades to artifact-only mode if workspace trust is low or hooks are restricted.

  10. Understand Self-Improvement Data Contracts

    main
    The self-improvement loop uses canonical JSON schemas to facilitate communication between specialized agents (Planner, Critic, Executor, Researcher, Orchestrator, and Tournament). These contracts ensure structured data exchange for planning, benchmarking, research, and iteration history. Developers building new agents or tools for the self-improvement loop must adhere to these schemas to ensure compatibility.

  11. Understand the Oh-My-ClaudeCode (OMC) Architecture

    main

    Oh-My-ClaudeCode (OMC) is a multi-agent orchestration system for Claude Code that transforms the AI from a single performer into a conductor. It uses a three-layer architecture to manage complex development tasks:

    1. Keyword Detection: Identifies trigger words in user input.
    2. Skill Layer: Resolves keywords into specific orchestration workflows (e.g., autopilot, ultrawork, ralph).
    3. Agent Layer: Skills coordinate specialized agents (e.g., analyst, architect, executor, critic) to perform the actual work.

    This structure allows for parallel execution, automatic task decomposition, and smart model routing (using Haiku, Sonnet, or Opus based on task complexity) to optimize for both speed and cost.

  12. Understand the oh-my-claudecode orchestration architecture

    main

    oh-my-claudecode (OMC) uses a skill-based routing system to orchestrate multi-agent workflows. The architecture consists of four interlocking systems that operate in sequence:

    1. Hooks: Detect lifecycle events.
    2. Skills: Inject specific behaviors into the orchestrator.
    3. Agents: Execute specialized tasks (e.g., coding, reviewing, analyzing).
    4. State: Tracks progress across context resets.

    Workflows are triggered by user input, which is processed through CLAUDE.md auto-routing to identify the task type and activate the appropriate skills and agents.