Skip to content
/
Tier A A8 Cross-runtime harness

oh-my-agent

oh-my-agent · first-fluke/oh-my-agent · ★ 1.0k · last commit 2026-05-26

Portable multi-agent harness that models an engineering team as specialized agents and projects them across 27+ AI tools from a single .agents/ source of truth

Best whenThe agent harness should be a vendor-neutral SSOT that any AI tool can consume — not locked to one runtime
Skip ifAgents modifying .agents/ files, Business logic in HTTP routes
vs seeds
bmad-methodin using markdown persona files with YAML frontmatter for named domain-expert agents, but differs fundamentally: BMAD ta…
Primitive shape 69 total
Commands 14 Skills 40 Subagents 10 Hooks 4 MCP tools 1
00

Summary

oh-my-agent — Summary

oh-my-agent is a portable, vendor-agnostic multi-agent harness that models an engineering team as specialized agents (frontend, backend, architecture, QA, DB, mobile, etc.) and dispatches work to them through a cross-runtime skill distribution system. Its core innovation is a .agents/ canonical directory that acts as a single source of truth, with the CLI projecting the skills and agent definitions into each runtime's native format (.claude/agents/, .codex/agents/, .gemini/agents/, .cursor/rules/, etc.) so that 27+ AI tools share the same agent definitions. The harness ships a oma CLI binary with 12+ subcommands including oma agent:parallel, oma dashboard, oma verify, and oma retro. It provides per-session token budgets, a ralph loop (independent judge re-verification), and keyword-auto-detection that activates agents without slash commands. Version 8.9.0 bundles 10+ agent definitions, 40+ skills, 10+ workflow slash commands, and a web dashboard for real-time monitoring.

Compared to seeds, oh-my-agent is closest to BMAD-METHOD in using named persona-based agent definitions, but differs fundamentally: where BMAD targets Claude Code exclusively with markdown personas, oh-my-agent uses TypeScript-compiled definitions projected across 10+ AI tools via a CLI-managed sync mechanism, making it the most cross-tool-portable framework in this batch.

01

Overview

oh-my-agent — Overview

Origin

Developed by first-fluke. Currently at version 8.9.0, indicating substantial iteration. The tagline is "Portable, vendor-agnostic agent harness for project-specific skills, workflows, and agent teams aligned with your codebase, conventions, and engineering standards."

Core Metaphor

From the README:

"Ever wished your AI assistant had coworkers? That's what oh-my-agent does. Instead of one AI doing everything (and getting confused halfway through), oh-my-agent splits work across specialized agents — frontend, backend, architecture, QA, PM, DB, mobile, infra, debug, design, and more. Each one knows its domain deeply, has its own tools and checklists, and stays in its lane."

Design Principles (from README)

  • Portable — .agents/ travels with your project, not trapped in one IDE
  • Role-based — Agents modeled like a real engineering team, not a pile of prompts
  • Token-efficient — Two-layer skill design saves ~75% of tokens
  • Quality-first — Charter preflight, quality gates, and review workflows built in
  • Multi-vendor — Mix Claude, Codex, Cursor, and Qwen per agent type
  • Observable — Terminal and web dashboards for real-time monitoring

Portability Mechanism

The CLI maintains .agents/ as the canonical single source of truth, then projects it into each AI tool's native format. The oma link command regenerates tool-specific directories from .agents/. Supports APM (Microsoft's Agent Package Manager) for skills-only distribution.

Keywords from README

"ohMyAgent splits work across specialized agents" — the framework is explicitly designed as a team simulation.

02

Architecture

oh-my-agent — Architecture

Distribution

  • Type: npm package (oh-my-agent on npm) + curl installer
  • Version analyzed: 8.9.0
  • Install options:
    • curl -fsSL https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.sh | bash (macOS/Linux, auto-installs bun, uv, serena)
    • irm https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.ps1 | iex (Windows)
    • bunx oh-my-agent@latest (manual)
    • brew install oh-my-agent (via Homebrew formula)
    • apm install first-fluke/oh-my-agent (skills-only via APM)
  • Required runtime: Bun, uv, serena (auto-installed by curl installer)

Repository Layout

.agents/                    # CANONICAL source of truth
├── agents/                 # Agent persona definitions (10 files)
│   ├── backend-engineer.md
│   ├── frontend-engineer.md
│   ├── architecture-reviewer.md
│   ├── db-engineer.md
│   ├── debug-investigator.md
│   ├── docs-curator.md
│   ├── mobile-engineer.md
│   ├── pm-planner.md
│   ├── qa-reviewer.md
│   └── tf-infra-engineer.md
├── skills/                 # 40+ skills (oma-* prefixed)
│   ├── oma-frontend/
│   ├── oma-backend/
│   ├── oma-brainstorm/
│   ├── oma-orchestrator/
│   ├── work/, ultrawork/, ralph/, orchestrate/, ...
│   └── _shared/
├── hooks/                  # Hook implementations
│   ├── core/               # TypeScript hook files
│   │   ├── keyword-detector.ts
│   │   ├── skill-injector.ts
│   │   ├── state-boundary.ts
│   │   ├── persistent-mode.ts
│   │   └── triggers.json
├── config/                 # Config templates
├── rules/                  # Agent rules
├── workflows/              # Workflow definitions
├── mcp.json                # MCP config
└── oma-config.yaml         # Per-project configuration

cli/                        # CLI source (TypeScript/Bun)
├── cli.ts                  # Main CLI entry
├── dashboard.ts            # Terminal dashboard
├── commands/               # oma subcommands
├── vendors/                # Per-tool adapters
└── generate-manifest.ts    # prompt-manifest.json generator

web/                        # Web dashboard (Next.js)

Config Files

  • .agents/oma-config.yaml — per-project config (language, model_preset, per-agent model overrides, quota caps)
  • prompt-manifest.json — auto-generated manifest of all skill files with hashes
  • .agents/mcp.json — MCP server configuration

Target AI Tools

27+ tools supported: Claude Code, Codex CLI, Gemini CLI, Cursor, Qwen Code, Antigravity, OpenCode, Amp, GitHub Copilot, and more.

03

Components

oh-my-agent — Components

Agent Definitions (10, in .agents/agents/)

Agent Domain
architecture-reviewer Architecture tradeoffs, ADR/ATAM/CBAM analysis
backend-engineer APIs, auth, DB migrations in Python/Node/Rust
db-engineer Schema, migrations, indexes, vector stores
debug-investigator Root cause analysis, regression tests
docs-curator Documentation drift detection
frontend-engineer React/Next.js, TypeScript, Tailwind CSS, shadcn/ui
mobile-engineer Flutter cross-platform mobile
pm-planner Task planning, requirements, API contracts
qa-reviewer OWASP security, performance, accessibility
tf-infra-engineer Terraform multi-cloud provisioning

Named Skills (40+ in .agents/skills/)

Skill Purpose
oma-academic-writer Academic prose to publication quality
oma-architecture Architecture analysis workflow
oma-backend Backend implementation skill
oma-brainstorm Free-form ideation
oma-coordination Cross-agent coordination
oma-db Database design skill
oma-debug Root-cause debugging
oma-deepsec Security scanning
oma-design Design system workflow
oma-dev-workflow CI/CD, releases, monorepo
oma-docs Documentation drift sync
oma-frontend Frontend implementation
oma-hwp HWP/HWPX to Markdown conversion
oma-image Multi-provider image generation
oma-market Market research with SWOT/5F/PESTEL
oma-mobile Flutter mobile skill
oma-observability Metrics, logs, traces, SLOs
oma-orchestrator Parallel agent spawning
oma-pdf PDF to Markdown
oma-pm Planning + task breakdown
oma-qa Quality review
oma-recap Conversation history recap
oma-scholar Academic literature search
oma-scm Git/SCM workflow
oma-search Multi-source search
oma-skill-creator Write new OMA skills in SSL-lite format
oma-tf-infra Terraform provisioning
oma-translator Language translation
oma-voice Voiceover generation + audio transcription

Workflow Slash Commands (14)

/deepinit, /brainstorm, /architecture, /design, /plan, /work, /orchestrate, /ultrawork, /ralph, /review, /deepsec, /debug, /docs, /scm

CLI Subcommands (oma / oh-my-agent)

Command Purpose
oma agent:parallel Spawn multiple agents in parallel
oma agent:spawn Spawn a specific agent with a task
oma dashboard Real-time agent monitoring (web)
oma doctor Health check + per-role model matrix
oma image generate Multi-vendor AI image generation
oma link Regenerate tool-specific dirs from .agents/
oma model:check Detect drift between registered models and live vendor lists
oma recap Cross-tool conversation history recap
oma retro Engineering retrospective with metrics
oma search fetch Web search with auto-escalating strategies
oma verify <agent> 14 deterministic checks per agent type

Hooks (in .agents/hooks/core/)

TypeScript files compiled as hook handlers:

  • keyword-detector.ts — detects keywords in 11 languages and activates the right agent
  • skill-injector.ts — injects skill context dynamically
  • state-boundary.ts — manages state across agent sessions
  • persistent-mode.ts — maintains persistent agent mode across turns
  • triggers.json — keyword-to-agent mapping configuration
05

Prompts

oh-my-agent — Prompts

Excerpt 1: backend-engineer.md agent definition (verbatim)

---
name: backend-engineer
description: Backend implementation. Use for API, authentication, DB migration work.
skills:
  - oma-backend
---

You are a Backend Specialist. Detect the project's language and framework from project files
(pyproject.toml, package.json, Cargo.toml, etc.) before writing code. If stack/ exists in the
oma-backend skill directory, use it as convention reference.

## Execution Protocol

Follow the vendor-specific execution protocol:
- Write results to project root `.agents/results/result-backend.md` (orchestrated: `result-backend-{sessionId}.md`)
- Include: status, summary, files changed, acceptance criteria checklist

## Charter Preflight (MANDATORY)

Before ANY code changes, output this block:

CHARTER_CHECK:
- Clarification level: {LOW | MEDIUM | HIGH}
- Task domain: backend
- Must NOT do: {3 constraints from task scope}
- Success criteria: {measurable criteria}
- Assumptions: {defaults applied}

- LOW: proceed with assumptions
- MEDIUM: list options, proceed with most likely
- HIGH: set status blocked, list questions, DO NOT write code

## Architecture

Router (HTTP) → Service (Business Logic) → Repository (Data Access) → Models

## Rules

1. Stay in scope — only work on assigned backend tasks
2. Write tests for all new code
3. Follow Repository → Service → Router pattern (no business logic in routes)
4. Validate all inputs with the project's validation library
5. Parameterized queries only (no string interpolation in SQL)
6. JWT + bcrypt for auth
7. Async/await consistently
8. Custom exceptions via centralized error module
9. Document out-of-scope dependencies for other agents
10. Never modify `.agents/` files

Prompting technique: Persona-based agent definition with frontmatter (name, description, skills). Uses mandatory structured output blocks (Charter Preflight), domain-specific architecture patterns, and numbered hard rules. Classic role-playing pattern with scope constraints.

Excerpt 2: oma-config.yaml per-agent model configuration

language: en
model_preset: mixed   # antigravity | claude | codex | qwen | cursor | mixed

# Optional per-agent overrides
agents:
  backend: { model: openai/gpt-5.5, effort: high }

Prompting technique: Configuration-driven model routing — each agent gets a different model class. The effort parameter maps to model-specific reasoning effort settings.

Prompting Architecture

  • Agent definitions: YAML frontmatter + markdown body in .agents/agents/*.md
  • Skills: markdown files in .agents/skills/*/ following SSL-lite (Skill Specification Language) format
  • Workflows: markdown files in .agents/skills/work/, ultrawork/, ralph/, etc.
  • Keyword detection: triggers.json maps keywords in 11 languages to agent names
  • Two-layer skill design: outer layer describes intent; inner layer provides domain-specific conventions — saves ~75% tokens vs. loading all context upfront
09

Uniqueness

oh-my-agent — Uniqueness

Differs from Seeds

oh-my-agent is closest to BMAD-METHOD among the 11 seeds in using named persona-based agent definitions (markdown with YAML frontmatter) that specialize in domain roles. The critical delta: where BMAD ships 6 persona files for Claude Code exclusively, oh-my-agent ships 10+ agent definitions and 40+ skills that are projected across 27+ AI tools via a TypeScript-compiled CLI that maintains a canonical .agents/ directory as the source of truth. Unlike taskmaster-ai (MCP-anchored, JSON task files) or claude-flow (305-tool MCP server), oh-my-agent relies entirely on file projection with no MCP server of its own. Unlike spec-kit or openspec (spec-driven workflows), oh-my-agent is execution-focused — the emphasis is on dispatching work to the right specialist agent, not on spec authoring.

Distinctive Position

The most cross-tool-portable framework in this entire batch:

  1. Single source of truth (.agents/) projected into 27+ AI tool native formats
  2. Only framework with explicit multi-vendor model routing per agent role in a YAML config
  3. Only framework with a Homebrew formula (oh-my-agent.rb) for macOS installation
  4. Keyword auto-detection in 11 languages activates agents without slash commands
  5. APM (Microsoft Agent Package Manager) distribution for skills-only installs
  6. oma verify provides 14 deterministic checks (TypeScript strict, Flutter analyze, raw SQL detection, hardcoded secret scanning) — the most concrete quality gate specification in this batch

Explicit Anti-Patterns

  • Agents modifying .agents/ files (Rule 10 in every agent definition)
  • Business logic in HTTP routes
  • String interpolation in SQL queries
  • Scope violation across agent domains

Observable Failure Modes

  • The .agents/ → multi-tool projection can drift if oma link is not run after adding agents
  • quota_cap enforcement depends on the oma-orchestrator skill being invoked (not enforced at the harness level)
  • Heavy dependency on Bun + uv + serena — the install requirement is opinionated and may conflict with existing toolchains
  • Version 8.9.0 is substantial but stars (1020) suggest early-stage adoption relative to effort invested

Inspired By

Anthropic's multi-agent documentation, engineering team structures, Microsoft's APM.

04

Workflow

oh-my-agent — Workflow

Standard Development Workflow

Step Command What It Does
0 /deepinit Bootstrap codebase (AGENTS.md, ARCHITECTURE.md, docs/)
1 /brainstorm Free-form ideation
2 /architecture Software architecture review, ADR/ATAM/CBAM analysis
2 /design 7-phase design system workflow
2 /plan PM breaks down feature into tasks
3 /work Step-by-step multi-agent execution
3 /orchestrate Automated parallel agent spawning
3 /ultrawork 5-phase quality workflow with 11 review gates
3 /ralph Wraps /ultrawork in independent verifier loop until criteria pass
4 /review Security + performance + accessibility audit
4 /deepsec Deep agent-powered security scan
5 /debug Structured root-cause debugging
5 /docs Documentation drift verify + sync
6 /scm SCM + Git workflow and Conventional Commit support

Charter Preflight (mandatory per agent)

Each agent definition includes a mandatory Charter Preflight block:

CHARTER_CHECK:
- Clarification level: {LOW | MEDIUM | HIGH}
- Task domain: backend
- Must NOT do: {3 constraints from task scope}
- Success criteria: {measurable criteria}
- Assumptions: {defaults applied}
  • LOW: proceed with assumptions
  • MEDIUM: list options, proceed with most likely
  • HIGH: block, list questions, DO NOT write code

Quality Gates (ultrawork / ralph)

  • oma verify <agent> — 14 deterministic checks per agent type (TypeScript strict, tests, raw SQL, hardcoded secrets, Flutter analyze, inline styles, scope violation, charter alignment)
  • session.quota_cap — per-session token/spawn/per-vendor budget caps; orchestrate Step 5 blocks next spawn when exceeded
  • ralph workflow — independent JUDGE re-verifies every criterion each iteration; heavy-test caching for >30s suites

Artifacts per Phase

Phase Artifact
deepinit AGENTS.md, ARCHITECTURE.md, docs/
plan Task list in .agents/results/
work/orchestrate .agents/results/result-<agent>.md per agent
ultrawork Multi-agent review results + acceptance criteria
scm Conventional Commit, branch, PR

Auto-Detection

Keywords in the user's message (in 11 languages) trigger agents without slash commands. Examples: "architecture", "plan", "review", "debug" auto-activate the relevant workflow.

06

Memory Context

oh-my-agent — Memory and Context

State Storage

  • Result files: each agent writes results to .agents/results/result-<agent>.md (orchestrated: result-<agent>-{sessionId}.md)
  • Recap: oma recap --window 1d produces cross-tool conversation history summaries
  • oma-config.yaml: persists project-level configuration including model assignments and quota caps

Context Management

  • Two-layer skill design: skills load only what the agent needs, saving ~75% tokens vs. monolithic context loading
  • Keyword detection: agents are activated only when relevant — reduces unnecessary context injection
  • Charter Preflight: forces explicit scope definition before execution, limiting context drift
  • Session quota cap: session.quota_cap in oma-config.yaml limits per-session tokens/spawns per vendor
  • Heavy-test caching: ralph workflow caches test results for >30s suites to avoid redundant re-runs

Cross-Session Handoff

  • .agents/results/ directory persists agent outputs across sessions
  • AGENTS.md and ARCHITECTURE.md (from /deepinit) provide persistent project context
  • oma retro 7d --compare produces retrospective reports with metrics and trends from historical data

No Centralized Memory Store

oh-my-agent does not use a database or vector store for memory. All persistence is file-based in the project repository. The oma-recap skill synthesizes conversation history from tool-native conversation logs.

07

Orchestration

oh-my-agent — Orchestration

Multi-Agent Pattern

oh-my-agent implements parallel-fan-out as its primary orchestration pattern:

  • /orchestrate spawns multiple agents in parallel based on the PM's task plan
  • oma agent:parallel -i backend:"Auth API" frontend:"Login form" spawns named agents with tasks simultaneously
  • The oma-orchestrator skill manages spawn lifecycle, monitors budget, and prevents overrun
  • Step 5 of orchestrate blocks next spawn when quota_cap is exceeded
  • Exploration Loop: after 2 retries, orchestrate spawns hypothesis variants in parallel and keeps the highest-scoring result

Orchestration Architecture

/work or /ultrawork
  → PM (oma-pm) breaks down task into assignments
  → oma-orchestrator spawns Domain Agents in parallel
  → Domain Agents (frontend, backend, db, ...) execute in isolation
  → Quality Agents (qa, debug) review results
  → SCM Agent (oma-scm) commits and manages git

Sub-Agent Definition Format

persona-md — each sub-agent is a markdown file in .agents/agents/ with YAML frontmatter (name, description, skills) and a role-specific prompt body. This is the same pattern as BMAD-METHOD personas but projected across multiple AI tools.

Multi-Model Routing

Configured via oma-config.yaml:

model_preset: mixed
agents:
  backend: { model: openai/gpt-5.5, effort: high }
  frontend: { model: anthropic/claude-opus-4-7 }
  qa: { model: qwen/qwen-coder }

The mixed preset routes different agents to different providers. Native dispatch uses the generated vendor agent definition (.claude/agents/, .codex/agents/). Cross-vendor dispatch uses .agents/skills/oma-orchestrator/config/cli-config.yaml.

Cross-Tool Runtime Portability

The .agents/ directory is the single source of truth. oma link projects it into:

  • .claude/agents/ — Claude Code native agents
  • .codex/agents/ — Codex CLI agents
  • .gemini/agents/ — Gemini CLI agents
  • .cursor/rules/ — Cursor rules
  • .github/copilot-instructions.md — GitHub Copilot symlinked skills
  • And 20+ more runtimes

Isolation Mechanism

No git worktrees. Each agent operates on the same filesystem. Isolation is logical (scope constraints in Charter Preflight) rather than physical.

Execution Mode

interactive-loop — the keyword detector and slash commands activate agents on demand. The ralph loop runs continuously until all criteria pass.

Quality Gates

  • oma verify <agent> — 14 deterministic checks per agent type
  • ralph — independent JUDGE agent re-verifies every criterion each iteration
  • Charter Preflight: mandatory scope declaration blocks high-ambiguity tasks before execution
08

Ui Cli Surface

oh-my-agent — UI/CLI Surface

CLI Binary: oma / oh-my-agent

  • Binary names: oma and oh-my-agent (both map to ./bin/cli.js)
  • Install: bun install --global oh-my-agent or brew install oh-my-agent or bunx oh-my-agent@latest
  • Is thin wrapper: No — it is its own runtime written in TypeScript/Bun with 12+ subcommands

CLI Subcommands

Subcommand Purpose
oma agent:parallel Spawn multiple agents in parallel with tasks
oma agent:spawn Spawn a specific agent
oma dashboard Open web dashboard for real-time monitoring
oma doctor Health check; --profile prints per-role resolved model matrix
oma image generate Multi-vendor AI image generation
oma link Regenerate .claude/.codex/.gemini/etc. from .agents/
oma model:check Detect drift between registered models and live vendor lists
oma recap --window 1d Cross-tool conversation history recap
oma retro 7d --compare Engineering retrospective with metrics + trends
oma search fetch <url> Mechanical search with auto-escalating strategies
oma verify <agent> 14 deterministic checks per agent type

Terminal Dashboard

  • Type: terminal-tui + web-dashboard
  • oma dashboard launches a real-time web dashboard
  • terminal-dashboard.ts in cli/ provides a terminal TUI fallback
  • The web dashboard is built with Next.js (in the web/ directory)
  • Port: unknown (not documented in inspected files)

IDE Integration

oh-my-agent projects into the native formats of 27+ AI tools. The .claude-plugin/ directory contains a Claude Code plugin manifest. The CLI-generated .claude/agents/ and .claude/skills/ directories integrate natively with Claude Code.

Serena Integration

The install scripts auto-install serena as a dependency, providing semantic code analysis capabilities to agents.

Cross-Tool Portability

high — the explicit design goal. Supports Claude Code, Codex CLI, Gemini CLI, Cursor, Qwen Code, Antigravity, OpenCode, Amp, GitHub Copilot, and 18+ more tools.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.