This page is a detailed developer reference for OMC (oh-my-claudecode) built-ins.
For each item, it explains what it does, why it exists, when to use it, and when not to use it.
| Section | Description |
|---|---|
| 1. How to Read This Page | Quick interpretation guide |
| 2. Built-in Agents (Detailed) | Role, intent, usage scenarios |
| 3. Built-in Skills (Detailed) | Practical skill selection |
| 4. Hooks (Detailed) | Automatic lifecycle interventions |
| 5. Practical Selection Guide | What to choose by situation |
| 6. Canonical Sources | Source-of-truth priority |
| 7. Related Documents | Further reading |
OMC docs and code can be slightly out-of-sync across versions. For runtime behavior, prioritize code (
src/*,skills/*) over prose summaries.
| Agent | Role (what it does) | Why it exists | Recommended when | Avoid when |
|---|---|---|---|---|
explore |
Fast discovery of files, symbols, and patterns | Reduce search cost/time before implementation | “Where is X implemented?” questions | Architecture decisions |
analyst |
Requirement gap analysis and constraint extraction | Prevent implementation on vague assumptions | Scope is unclear or conflicting | Direct coding tasks |
planner |
Creates execution plans and sequencing | Prevent ad-hoc coding and rework | Multi-step features or migrations | Tiny single-file edits |
architect |
Read-only architecture/debug guidance | Force evidence-based diagnosis | Complex debugging or design tradeoffs | Direct code editing |
debugger |
Regression isolation and root-cause narrowing | Shorten time-to-fix for incidents | Reproducible bug investigation | Product strategy work |
executor |
Focused implementation with minimal diff | Convert plans into safe code changes | Standard implementation tasks | Requirement definition/review |
deep-executor |
Autonomous deep execution for complex goals | Handle high-complexity multi-file work | Large refactors and difficult integrations | Small obvious fixes |
verifier |
Evidence-driven completion verification | Block “it should work” claims | Final validation before completion | Early design exploration |
| Agent | Role | Why it exists | Recommended when | Avoid when |
|---|---|---|---|---|
style-reviewer |
Style/naming/lint convention review | Keep style checks low-cost and separate | Fast style hygiene pass | Logic/security review |
quality-reviewer |
Logic and maintainability review | Catch non-obvious design debt | Anti-pattern and complexity checks | Formatting-only tasks |
api-reviewer |
API contracts and compatibility review | Prevent interface breakage | Public API changes | Internal-only local change |
security-reviewer |
Security boundary/vuln review | Prevent risky production exposure | Auth, secrets, trust boundaries | Cosmetic UI edits |
performance-reviewer |
Performance hotspot and complexity review | Catch bottlenecks early | Latency-sensitive paths | Early ideation |
code-reviewer |
Comprehensive multi-angle review | Integrate review dimensions in one pass | Pre-merge gate | Single narrow check |
| Agent | Role | Why it exists | Recommended when | Avoid when |
|---|---|---|---|---|
dependency-expert |
Evaluate external SDKs/APIs/packages | Avoid costly dependency mistakes | Library adoption/replacement | Internal refactor only |
test-engineer |
Test strategy and coverage shaping | Minimize verification blind spots | TDD/test architecture | Feature implementation itself |
quality-strategist |
Release readiness and quality gates | Clarify go/no-go criteria | Release planning | Single bugfix task |
build-fixer |
Build/type/compilation error recovery | Restore CI quickly with minimal scope | Broken build incidents | Architecture redesign |
designer |
UI/UX implementation quality | Improve usability and visual clarity | UI components/pages | Backend-only algorithms |
writer |
Docs/README/guides/changelogs | Preserve team understanding | User/dev documentation | Performance tuning |
qa-tester |
Runtime interactive validation | Catch issues static checks miss | CLI/service behavior testing | Pure static analysis |
scientist |
Data/statistical analysis | Enable evidence-based decisions | Experiment/result analysis | Code implementation |
git-master |
Commits, rebases, history workflows | Keep history clean and auditable | Commit strategy/history cleanup | Non-git code tasks |
| Agent | Role | Why it exists | Recommended when | Avoid when |
|---|---|---|---|---|
product-manager |
Problem framing/JTBD/PRD direction | Align work to user value | Feature prioritization | Urgent code hotfix |
ux-researcher |
Usability/accessibility evidence | Reduce user-facing UX risk | UX risk audits | Build break fixes |
information-architect |
Taxonomy/navigation/IA consistency | Improve findability and naming quality | IA/menu/content structure redesign | Tiny text fixes |
product-analyst |
Metrics/funnel/experiment setup | Ensure measurable outcomes | KPI/event schema planning | Feature coding |
critic |
Critical challenge of plans/assumptions | Catch plan blind spots before coding | Plan review and pressure test | Direct implementation |
vision |
Image/PDF/diagram interpretation | Add visual understanding to workflows | Screenshot/diagram analysis | Text-only code search |
| Alias | Maps to | Recommendation |
|---|---|---|
researcher |
document-specialist |
Legacy compatibility only |
tdd-guide |
test-engineer |
Legacy compatibility only |
Based on
skills/*/SKILL.md.
| Skill | Role | Why it exists | Recommended when | Avoid when |
|---|---|---|---|---|
autopilot |
End-to-end autonomous flow | One-command delivery from idea to verified output | “Build this completely” requests | Tiny one-off fixes |
ultrawork |
Maximum parallel execution engine | Throughput maximization | Many independent subtasks | Strong sequential dependency |
ralph |
Persistence loop until verified completion | Prevent premature stopping | Must-finish tasks | Open brainstorming |
team |
Native coordinated team pipeline | Canonical multi-agent runtime | Multi-role collaboration | Very small tasks |
swarm |
Shared task-pool collaboration facade | Preserve legacy swarm ergonomics | Legacy workflows | New canonical selection (use Team) |
ultrapilot |
Parallel autopilot with ownership partitioning | Faster autonomous execution | Large partitionable work | Small patches |
pipeline |
Sequential chained stages | Explicit phase dependency | Analyze→implement→verify workflows | Simple direct fix |
ultraqa |
Test/verify/fix loop | Continuous quality convergence | QA-heavy loops | Undefined requirements |
| Skill | Role | Why it exists | Recommended when | Avoid when |
|---|---|---|---|---|
plan |
Structured planning interview | Remove ambiguity before coding | Multi-step implementation | Plan already finalized |
ralplan |
Consensus plan alias | Fast access to multi-agent planning consensus | High-risk planning | Trivial tasks |
review |
Plan review alias | Lightweight plan quality pass | Existing plan validation | Code implementation |
analyze |
Deep analytical investigation | Root-cause clarity before action | Complex uncertain problems | Obvious straightforward edits |
deepsearch |
Exhaustive codebase search | Reduce blind spots in large repos | Unknown architecture exploration | Known-file quick lookup |
deepinit |
Hierarchical AGENTS knowledge bootstrap | Improve onboarding and discoverability | New repo onboarding | Urgent short fix |
sciomc |
Parallel scientist orchestration | Multi-angle evidence collection | Research-heavy questions | Simple implementation |
| Skill | Role | Why it exists | Recommended when | Avoid when |
|---|---|---|---|---|
tdd |
Test-first workflow enforcement | Prevent spec drift and regressions | Critical behavior changes | Disposable scripts |
build-fix |
Minimal-change build recovery | Fast CI stabilization | Build/type failures | Architecture redesign |
code-review |
Comprehensive review workflow | Improve merge quality | Before merge/release | Before any implementation exists |
security-review |
Security review workflow | Detect vulnerabilities early | Auth/secrets/permission work | Style-only update |
git-master |
Git workflow specialization | Preserve clean history and atomicity | Commit/rebase/changelog prep | Non-git problem |
frontend-ui-ux |
UI/UX quality enhancement | Avoid generic or low-quality UI output | Frontend design/interaction tasks | Backend-only tasks |
| Skill | Role | Why it exists | Recommended when | Avoid when |
|---|---|---|---|---|
cancel |
Safe cancellation of active modes | Consistent state cleanup | Stop active orchestration | Must continue active run |
omc-setup |
Initial OMC setup | Lower setup friction | First-time install | Already configured env |
omc-doctor |
Installation/health diagnostics | Fast issue triage | Setup/runtime anomalies | Feature implementation |
omc-help |
Usage guidance | Fast user recall path | Command/mode uncertainty | As a replacement for execution |
mcp-setup |
MCP provider setup | Enable model/tool integrations | Codex/Gemini/tool onboarding | Local-only simple tasks |
hud |
HUD configuration | Increase execution visibility | Monitoring active long tasks | Pure coding tasks |
trace |
Agent-flow tracing | Improve explainability/debuggability | Investigate orchestration behavior | One-off tiny updates |
note |
Notepad persistence | Preserve context across compaction | Keep durable decisions | Disposable chatter |
learner |
Extract reusable skills from sessions | Convert patterns into reusable assets | Repeated workflow patterns | Single-use ad hoc work |
skill |
Local skill lifecycle management | Organize skill operations | List/add/remove/edit skills | Regular code implementation |
release |
Release automation workflow | Standardize release process | Version cut and release prep | Early development exploration |
project-session-manager |
Isolated worktree+tmux sessions | Safe parallel project execution | Multi-branch parallel work | Single short branch task |
psm |
Alias of project-session-manager | Shortcut usability | Same as above | Same as above |
writer-memory |
Writing-focused memory system | Preserve long-form writing context | Doc/book/article continuity | Build/type fixes |
external-context |
External docs/search collection | Fill gaps beyond repo context | Unfamiliar external libs/APIs | Fully internal problem |
learn-about-omc |
Usage pattern learning | Improve personal OMC workflow | Workflow optimization | Immediate implementation demand |
configure-discord |
Discord notification setup | Better async visibility | Team/personal completion alerts | No Discord usage |
configure-telegram |
Telegram notification setup | Same purpose on Telegram | Team/personal completion alerts | No Telegram usage |
| Skill | Role | Why it exists | Recommended when | Avoid when |
|---|---|---|---|---|
ralph-init |
PRD bootstrap for ralph loop | Add structure before persistent execution | Starting long ralph cycles | Tiny tasks |
Hooks are automatic lifecycle interventions, not primarily user-invoked commands.
| Hook | Role | Why it exists | Recommended context | Caution |
|---|---|---|---|---|
autopilot |
Manage autopilot state flow | Stabilize autonomous execution | End-to-end autonomous runs | Overkill for tiny edits |
ultrawork |
Manage parallel execution state | Throughput and coordination | High parallel workload | Sequentially coupled tasks |
ralph |
Manage persistence loop state | Prevent unfinished exits | Must-complete workflows | Open-ended exploration |
ultrapilot |
Coordinate parallel autopilot | Accelerate partitioned work | Large partitionable scope | Small local updates |
ultraqa |
QA cycle state handler | Ensure repeated verification | QA-heavy completion gates | Unclear requirements |
team-pipeline |
Team stage state/transitions | Canonical Team runtime control | team-plan→fix loop | Team mode disabled |
mode-registry |
Central active-mode detection | Prevent mode conflicts | All mode interactions | - |
persistent-mode |
Stop-event continuation enforcement | Prevent accidental stop | Active ralph/autopilot/team loops | Force-stop without /cancel |
| Hook | Role | Why it exists | Recommended context | Caution |
|---|---|---|---|---|
thinking-block-validator |
Validate thinking block structure | Reject malformed structured output | Complex reasoning sessions | - |
empty-message-sanitizer |
Sanitize empty responses | Avoid pipeline breakage | Unexpected empty outputs | - |
comment-checker |
Validate comment quality | Reduce noisy/low-value comments | Code comment generation | Documentation-only sessions |
permission-handler |
Handle permission requests | Control risky operations | Pre-tool risk gating | Assuming blanket auto-approve |
think-mode |
Detect/enable deeper think mode | Increase reasoning depth when needed | Complex investigations | Excess cost on trivial tasks |
| Hook | Role | Why it exists | Recommended context | Caution |
|---|---|---|---|---|
recovery |
Recover from failed states | Increase resilience | Tool/session/context failures | Blind retries without diagnosis |
preemptive-compaction |
Early compaction trigger | Prevent context overflow | Long sessions | Ignoring context pressure |
pre-compact |
Pre-compaction state handling | Minimize context loss | Right before compaction | - |
project-memory |
Inject detected project context | Avoid repeated rediscovery | Session start/project switch | Stale cache without rescan |
beads-context |
Inject task-tool-specific guidance | Keep tool variant behavior aligned | beads/beads-rust task tool setups | Mismatched config state |
| Hook | Role | Why it exists | Recommended context | Caution |
|---|---|---|---|---|
omc-orchestrator |
Enforce delegation-oriented behavior | Keep orchestrator from over-implementing | Multi-agent orchestration | Can feel restrictive for direct edits |
todo-continuation |
Continue unresolved todo work | Prevent half-finished delivery | Multi-step tasks | Over-persistence if todos not updated |
subagent-tracker |
Track subagent lifecycle | Improve observability/auditability | Parallel agent runs | - |
background-notification |
Notify background completion | Better async visibility | Long-running background tasks | - |
session-end |
Session cleanup and closure logic | Consistent shutdown behavior | End of sessions | - |
notepad |
Preserve durable memory notes | Context continuity across sessions | Long complex engagements | Notepad bloat/noise |
learner |
Extract reusable lessons into skills | Convert patterns to reusable workflow assets | Repeated solution patterns | Promoting weak patterns |
| Hook | Role | Why it exists | Recommended context | Caution |
|---|---|---|---|---|
keyword-detector |
Detect magic mode/skill keywords | Frictionless mode activation | prompts including autopilot/ralph/team keywords | Keyword collisions in code snippets |
auto-slash-command |
Auto-resolve slash-like intents | Better command UX | Command-oriented workflows | Missing command definitions |
rules-injector |
Inject policy/rule files | Maintain consistency with repo rules | Team standards enforcement | Over-injection noise |
directory-readme-injector |
Inject local directory README context | Improve local-context relevance | Module-specific work | README clutter/noise |
plugin-patterns |
Detect plugin-specific patterns | Context-aware behavior adaptation | Plugin-centric workflows | - |
agent-usage-reminder |
Remind proper agent usage | Avoid single-agent overuse | Delegation gaps | Too many reminders |
non-interactive-env |
Adapt to CI/non-interactive env | Keep workflows robust in automation | CI/headless runs | Interactive assumptions |
setup |
Initialization and maintenance routines | Ensure healthy .omc baseline |
First run / maintenance | Skipping setup on fresh install |
| Situation | Best first choice |
|---|---|
| “Build this from idea to done” | autopilot |
| Must not stop until complete | ralph |
| Need maximum speed via parallelism | ultrawork or team |
| Need staged collaboration + verification loop | team |
| Need strict sequential stages | pipeline |
| Need repeated testing/fixing cycles | ultraqa |
| Build/type errors exploded | build-fix + build-fixer |
| Security/API/performance risk review | security-reviewer, api-reviewer, performance-reviewer |
| External library adoption decision | dependency-expert + external-context |
executor then verifierplan/analyst before coding when requirements are fuzzynote/project memory for long sessions to preserve context/oh-my-claudecode:cancel for safe mode termination| Domain | Primary source |
|---|---|
| Agents | src/agents/definitions.ts, agents/*.md |
| Skills | skills/*/SKILL.md |
| Hooks | src/hooks/*, src/hooks/index.ts |
| Plugin/MCP | .claude-plugin/plugin.json, .mcp.json |
| User docs | docs/REFERENCE.md, README.md |