DOCSEARCHbyAlgolia
Submit Docs

oh-my-agent

repository·main·Indexed 20 days ago

https://github.com/first-fluke/oh-my-agent

A portable multi-agent harness that allows developers to deploy specialized AI agents (e.g., frontend, backend, QA) across various AI IDEs and runtimes using a single source of truth. It uses the .agents/ directory to project configurations into supported AI runtime layouts, ensuring shared skills, workflows, and rules across tools like Claude Code and Cursor.

Tokens
167.5K
Snippets
466
Records
772
Agent score
73%

What's inside oh-my-agent

  1. Overview of the 32 oh-my-agent specialized agents

    main

    The oh-my-agent ecosystem consists of 32 specialized agents categorized by their functional domain. These agents are designed to work together in a multi-agent paradigm to cover the entire software development lifecycle, from ideation to deployment and maintenance.

    Agent Categories:

    • Ideation, Architecture, & Planning: Includes oma-brainstorm (design-first ideation), oma-architecture (system boundaries and tradeoffs), and oma-pm (requirement decomposition and task prioritization).
    • Implementation: Specialized for specific technical layers: oma-frontend (React/Next.js/TS), oma-backend (API/Server), oma-mobile (Flutter/Swift), oma-db (Database modeling), and oma-design (Design systems).
    • Infrastructure, DevOps, & Observability: Covers oma-tf-infra (Terraform/IaC), oma-dev-workflow (Monorepo/CI/CD), and oma-observability (MELT+P signal routing).
    • Quality & Debugging: Includes oma-qa (Security/Performance/Accessibility), oma-debug (Bug diagnosis), and oma-refactor (Safe code restructuring).
    • Localization, Coordination, & Git: Features oma-translator (Context-aware translation), oma-orchestrator (Automated multi-agent coordination), oma-scm (Git/Branching), and oma-coordination (Manual workflow guide).
    • Search, Retrospective, & Document Processing: Includes oma-search (Intent-based routing), oma-recap (Work retrospectives), oma-hwp (Korean word processor conversion), and oma-pdf (PDF to Markdown).
    • Academic & Research Writing: Includes oma-academic-writer (Prose drafting/auditing) and oma-scholar (Research paper sidecar).
    • Security: Features oma-deepsec (Vulnerability scanning via Vercel's deepsec).
    • Documentation & Meta-tooling: Includes oma-docs (Drift detection) and oma-skill-creator (SSL-lite skill authoring).
    • Market Research: Features oma-market (Community signal intelligence).
    • Media & Content Generation: Includes oma-image (Multi-vendor image routing), oma-slide (HTML deck generation), oma-video (Short-form/Explainer video), and oma-voice (Local-first TTS/STT).

  2. Overview of oh-my-agent

    main

    oh-my-agent is a multi-agent orchestration framework designed for AI-powered IDEs and CLI tools. It moves away from the 'generalist AI' model by decomposing tasks across specialized agents that mimic real engineering team roles.

    Key features include:

    • Specialization: Each agent is an expert in a specific domain (e.g., Frontend, Backend, Security) with its own tech stack knowledge, execution protocols, and error playbooks.
    • Portability: The entire system is stored in a portable .agents/ directory within your project. This allows your agent configurations to travel with your code across different tools like Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, Cursor, and more.
    • Parallelism: Agents can work in parallel (e.g., backend building APIs while frontend builds UI) coordinated via shared memory.
    • Built-in Quality: Agents utilize domain-specific checklists, error playbooks, and 'Charter preflights' to prevent scope creep and ensure quality through integrated QA reviews.

  3. Understand the AI Coding Harness Benchmark

    main

    The AI Coding Harness Benchmark compares different Claude Code harnesses by tasking them to build a children's 3D creative learning platform MVP. It evaluates them across five axes: Functional, Spec, Visual, Engineering, and Efficiency.

    Evaluated Harnesses

    • vanilla: Bare Claude Code (baseline).
    • oma: oh-my-agent source-seeded into the project via .agents/ and .claude/ directories. Focuses on design-rule-driven anti-pattern avoidance.
    • omc: oh-my-claudecode loaded via the --plugin-dir flag.
    • ecc: everything-claude-code installed to the user's ~/.claude/ directory.
    • superpowers: superpowers loaded via the --plugin-dir flag.

    Scoring Axes

    AxisWeightKey Signals
    Functional35Build exit, dev-server boot (HTTP 200 ≤45s), user-journey checks, lint, and tsc --noEmit
    Spec1513 explicit prompt deliverables (docs/replies) and real-API bonus
    Visual20Anti-patterns (e.g., gradient backgrounds, sub-16px text), UX, design-system consistency, and accessibility
    Engineering20Code breadth, TS strictness, max file size/folder depth, deferred-stub markers, and no hardcoded keys
    Efficiency10Turns to complete, wall-clock duration, and cost-per-file

  4. Understand the oh-my-agent monorepo structure

    main

    The oh-my-agent repository is organized as a monorepo. If you are contributing to the project itself, the following directory structure applies:

    • cli/: The CLI tool source (TypeScript, built with bun). Contains src/, package.json, and install.sh.
    • web/: The Docusaurus documentation site, including docs/ (English) and i18n/ (translations).
    • action/: GitHub Action for automated skill updates.
    • docs/: Translated READMEs and specifications.
    • .agents/: The Source of Truth (SSOT). Note that while consumers should not modify this directory, modifications are allowed within the source repository itself.
    • .claude/: IDE integration.
    • .serena/: Development runtime state.
    • CLAUDE.md: Project instructions for Claude Code.
    • package.json: Root workspace configuration.
    oh-my-agent/
├── cli/
│   ├── src/
│   ├── package.json
│   └── install.sh
├── web/
│   ├── docs/
│   └── i18n/
├── action/
├── docs/
├── .agents/
├── .claude/
├── .serena/
├── CLAUDE.md
└── package.json

  5. Key features of oh-my-agent

    main

    oh-my-agent is a portable multi-agent harness designed for engineering teams. Key value propositions include:

    • Portability: The .agents/ directory travels with your project. The oma emit command projects a Single Source of Truth (SSOT) into open standards like Agent Skills, .claude-plugin/marketplace.json, and AGENTS.md.
    • Token Efficiency: Uses a two-tier skill design to reduce token consumption by approximately 75%.
    • Quality Gates: Includes the ralph workflow (an independent JUDGE for regression testing) and an Exploration Loop (where orchestrate spawns parallel hypothesis variants after 2 retries and selects the best score).
    • Monorepo Support: detectWorkspace automatically detects pnpm, nx, turbo, or lerna to route agents to their correct workspaces.
    • Multi-vendor: Supports combining multiple LLM providers like Antigravity, Claude, Codex, Cursor, Kiro, and Qwen.

  7. Load Claude Code plugins via --plugin-dir

    main

    For plugins like omc and superpowers that support Claude Code's plugin architecture, the benchmark avoids using claude plugin install to prevent hangs and global state mutation. Instead, it uses the --plugin-dir flag to load plugins directly from a local directory for the duration of the session.

    When using omc in this mode, you must also export OMC_PLUGIN_ROOT to the plugin's local directory.

    Note: In this mode, omc setup is not run because the plugin provides skills and agents at runtime, and the benchmark does not require the optional HUD or git-hooks installed in ~/.claude/.

    # Pre-clone the plugin
git clone --depth 1 https://github.com/Yeachan-Heo/oh-my-claudecode $BASE/plugins/omc

# Load the plugin during the session
HOME=$BASE/homes/omc \\ 
OMC_PLUGIN_ROOT=$BASE/plugins/omc \\ 
  claude -p "$(cat prompt.md)" \\ 
    --plugin-dir $BASE/plugins/omc

  8. Configure a Skill's routing via SKILL.md description

    main

    The description field in the YAML frontmatter of a SKILL.md file is critical for the system's orchestration. The skill routing system uses the keywords within this description to match incoming tasks to the correct agent.

    When creating a new skill, ensure the description contains specific, searchable keywords related to the domain (e.g., "React", "Tailwind", "SQL") to ensure the orchestrator can route tasks to it correctly.

    ---
name: oma-frontend
description: Frontend specialist for React, Next.js, TypeScript with FSD-lite architecture, shadcn/ui, and design system alignment. Use for UI, component, page, layout, CSS, Tailwind, and shadcn work.
---

  9. Definition of a complete multi-agent project

    main

    A multi-agent project is considered finished only when the following criteria are met:

    • All agents in all priority tiers have completed successfully.
    • Verification scripts pass for every agent (exit code 0).
    • QA review reports zero CRITICAL and zero HIGH findings.
    • Cross-domain API contract alignment is confirmed.
    • The build succeeds and all tests pass.
    • The final report is written to memory and presented to the user.
    • The user provides final approval (via /work or the SHIP_GATE in ultrawork).

  10. Benchmark Methodology for AI Harnesses

    main

    The AI Harness Benchmark evaluates different agentic environments (harnesses) using a standardized prompt for a '3D Creative Learning Platform MVP'.

    Execution Conditions:

    • Isolation: Each harness uses a unique $HOME override to prevent cross-contamination.
    • Initial State: Tests start in an empty directory with git init performed.
    • Permissions: The flag --dangerously-skip-permissions is used to allow the agent to operate without manual intervention.
    • Model Configuration: Uses a high-effort model with a 1M context window.
    • Constraints: A budget cap of $20 per run and a time limit of 60 minutes per run.

    To reproduce the benchmark runs, refer to the benchmarks/run.sh script.

  11. Recommended 3-Terminal layout for multi-agent workflows

    main

    For optimal productivity during multi-agent orchestration, use a three-pane terminal setup:

    1. Terminal 1 (Main Agent): Run your primary agent session (e.g., Gemini CLI, Claude Code) here to interact with workflows like /orchestrate or /work.
    2. Terminal 2 (Dashboard): Run oma dashboard here for passive, real-time monitoring of agent progress.
    3. Terminal 3 (Ad-hoc commands): Use this pane for manual commands like oma agent:status, oma stats, or running verifications.

  12. Validate cross-domain integration

    main

    After individual agent tasks are complete, you must validate integration across domains. The QA agent's Alignment Review performs this systematically by checking:

    1. API contract alignment: Using MCP tools (find_symbol, search_for_pattern) to ensure backend implementations match consumer expectations.
    2. Type consistency: Ensuring shared types (TypeScript, Python, Dart) use consistent field names and types.
    3. Authentication flow: Verifying that clients (frontend/mobile) correctly handle tokens (e.g., JWT) provided by the backend.
    4. Error handling: Ensuring all consumers handle documented error formats (e.g., { "error": "unauthorized", "code": 401 }).
    5. Database schema alignment: Verifying backend ORM models match the database migrations created by the database agent.