oh-my-braincrew 0.2.4

Multi-agent orchestration harness for Claude Code

oh-my-braincrew

Multi-Agent Orchestration Harness for Claude Code

English | 한국어

---

Turn Claude Code into a coordinated team of 22 specialized AI agents. oh-my-braincrew gives you a structured development workflow where you describe the work and agents deliver it — from planning through pull request.

• Orchestrator-first — you describe, agents deliver. Claude never implements directly.
• 6-step workflow — every change is planned, reviewed, tested, verified, documented, and shipped.
• Pipeline autopilot — a Python session handler runs the entire workflow end-to-end with zero manual steps.
• Full-stack coverage — Python, TypeScript, React, FastAPI, LangChain/LangGraph, Electron, Redis, Postgres.

---

Why oh-my-braincrew?

Claude Code alone	Claude Code + omb
Claude implements directly — one general-purpose agent	Orchestrator delegates to 22 specialized agents
No enforced workflow — easy to skip steps	6-step workflow enforced by hooks and rules
Manual step transitions between plan/execute/verify	Session handler automates the entire pipeline as a state machine
No verification gate	Iron law: no completion claims without fresh evidence
Self-review in same context	Separate author + reviewer passes (never self-approve)

[!TIP] You don't need to adopt everything at once. Start with a single skill like /omb:plan and expand from there.

---

How It Works

graph LR
    A["1. Plan\n:plan"] --> B["2. Review\n:review"]
    B --> C["3. Execute\n:exec"]
    C --> D["4. Verify\n:check"]
    D --> E["5. Document\n:doc"]
    E --> F["6. Create PR\n:pr"]
    D -->|Fail| C

Every non-trivial task flows through this 6-step pipeline. The orchestrator delegates each step to specialized agents, collects evidence at verification, and only claims completion when all checks pass.

Step	Agent	What Happens	Output
1. Plan	planner (opus)	Structured plan with tasks, agents, risks, verification criteria	.omb/plans/<session_id>.md
2. Review	critic (opus)	Independent review + mandatory pre-mortem. Max 2 revisions	APPROVED / NEEDS REVISION / BLOCKED
3. Execute	executor (sonnet)	TDD: Scaffold → Tests (red) → Code (green) → Integration	Passing tests + implementation
4. Verify	verifier (sonnet)	Run tests, read output, check contracts, produce evidence report	Verification report
5. Document	doc-writer (haiku)	Section-level doc updates, ADRs, migration guides	Updated docs
6. Create PR	git-master (sonnet)	Branch + conventional commits + structured PR via gh CLI	Pull request

Behavioral guarantees (what makes this different)

• The plan author cannot review their own plan (no self-approval).
• Every review includes a mandatory pre-mortem: "If this fails in 3 months, the most likely reason is: ___"
• If the plan doesn't match reality during execution, the agent stops and reports back.
• The verifier reads actual output, not just exit codes.
• Maximum retry bounds: 2 revision rounds (review), 3 retry cycles (verify).

---

Quick Start

Phase 1: Install the Harness

Option A: Install from PyPI (recommended)

pip install oh-my-braincrew

Or with uv:

uv tool install oh-my-braincrew

Option B: Install from source

git clone https://github.com/teddynote-lab/oh-my-braincrew.git
cd oh-my-braincrew
make setup

Verify the installation:

omb version
omb doctor

Update to latest:

pip install --upgrade oh-my-braincrew
# or: uv tool upgrade oh-my-braincrew

[!NOTE] Both omb init and omb doctor automatically install LSP servers (TypeScript, Python, JSON, CSS, HTML, YAML, Go) and ast-grep (sg CLI) if they are missing. You can also install them manually with omb setup-lsp (from any directory).

Phase 2: Initialize Your Project

cd /path/to/your/project
omb init

This deploys to your project:

What	Where	Purpose
Config	.omb/config.json	Project settings, pipeline state dir
Hook scripts	.claude/hooks/omb/	Session lifecycle, security policy, plan naming
Settings	.claude/settings.json	Wires all 16 hook events, enables Agent Teams, sets permissions
Skills	.claude/skills/	22 skill definitions for /omb commands
Statusline	.omb/status_line.sh	Terminal statusline config

[!TIP] On your first Claude Code session after omb init, run /omb setup. This collects your username, Slack config, and project preferences, then scans your codebase to generate project-specific CLAUDE.md and PROJECT.md. Your profile is saved at ~/.omb/profile.json and reused across all projects. Requires gh CLI (gh auth login) for community features — skip gracefully if unavailable.

Then use /omb:* skills for your workflow:

/omb:plan Add JWT refresh endpoint with Redis session store
/omb:review .omb/plans/2026-03-22-jwt-refresh.md
/omb:exec .omb/plans/2026-03-22-jwt-refresh.md
/omb:check .omb/plans/2026-03-22-jwt-refresh.md
/omb:doc .omb/plans/2026-03-22-jwt-refresh.md
/omb:pr .omb/plans/2026-03-22-jwt-refresh.md

---

Pipeline Autopilot — Session-Driven Mode

The session handler runs the entire 6-step workflow as a state machine. Each Claude Code session is identified by CLAUDE_SESSION_ID. You activate a session with omb run — the handler drives each step automatically, including checkpoint pauses for human review.

# In Claude Code — start the fix pipeline
/omb:plan Add JWT refresh endpoint with Redis session store

# In terminal — activate a session
omb run

Pipeline Variants

fix (full 6-step pipeline)

graph LR
    A["1. Plan"] -->|:plan| B["2. Review"]
    B -->|:review| C["3. Execute"]
    C -->|:exec| D["4. Verify"]
    D -->|:check| E["5. Document"]
    E -->|:doc| F["6. PR"]
    D -.->|Fail| C

    style A fill:#4a9eff,color:#fff
    style B fill:#4a9eff,color:#fff
    style C fill:#22c55e,color:#fff
    style D fill:#22c55e,color:#fff
    style E fill:#22c55e,color:#fff
    style F fill:#22c55e,color:#fff

full (7-step greenfield pipeline with interview)

graph LR
    I["0. Interview"] -->|:interview| A["1. Plan"]
    A -->|:plan| B["2. Review"]
    B -->|:review| C["3. Execute"]
    C -->|:exec| D["4. Verify"]
    D -->|:check| E["5. Document"]
    E -->|:doc| F["6. PR"]
    D -.->|Fail| C

    style I fill:#a855f7,color:#fff
    style A fill:#4a9eff,color:#fff
    style B fill:#4a9eff,color:#fff
    style C fill:#22c55e,color:#fff
    style D fill:#22c55e,color:#fff
    style E fill:#22c55e,color:#fff
    style F fill:#22c55e,color:#fff

plan (planning only) / exec (approved plan)

graph LR
    A["1. Plan"] -->|:plan| B["2. Review"]

    style A fill:#4a9eff,color:#fff
    style B fill:#4a9eff,color:#fff

graph LR
    C["3. Execute"] -->|:exec| D["4. Verify"]
    D -->|:check| E["5. Document"]
    E -->|:doc| F["6. PR"]
    D -.->|Fail| C

    style C fill:#22c55e,color:#fff
    style D fill:#22c55e,color:#fff
    style E fill:#22c55e,color:#fff
    style F fill:#22c55e,color:#fff

Pipeline	Steps	Use When
fix	plan → review (checkpoint) → execute → verify → document → PR	Full end-to-end task
full	interview → plan → review (checkpoint) → execute → verify → document → PR	Greenfield feature with requirements gathering
plan	plan → review	Produce and review a plan without executing
exec	execute → verify → document → PR	Execute an already-approved plan

Checkpoints: The review-plan step in the fix pipeline pauses after completion, waiting for your approval before continuing to execution. This prevents unreviewed code from being written.

Retries: The review step supports up to 2 retries on NEEDS REVISION before the pipeline stalls.

Recovery: If a session stops mid-pipeline, the inline handle_reject() Python handler resumes from the last completed step. No separate CLI command is needed.

Pipeline state is stored in .omb/sessions/ as JSON. Each step maps to an omb sub-skill invoked by the session handler.

Worktree support

Pipelines support isolated git worktrees to keep your main checkout clean. The worktree is created at worktrees/wt-{timestamp}/ with branch worktree/wt-{timestamp}. Pipeline state for worktree sessions is stored inside the worktree's own .omb/sessions/ directory.

Management commands

Worktree commands:

omb worktree list     # List all worktrees with path, branch, HEAD
omb worktree remove <path>  # Remove a worktree (refuses if active pipeline uses it)
omb worktree status   # Show worktree info for active/paused pipelines
omb worktree clean    # Remove worktrees whose branches are merged into main

---

---

Loop — Recurring Task Execution

Run any task at a fixed interval — monitoring, log checks, periodic repairs. Loops integrate with the session-driven fix pipeline for automated repair workflows.

/omb:loop 10m "check docker logs for errors and use fix pipeline to auto-repair"

graph LR
    S["Start Loop"] --> I1["Iteration 1\nExecute Task"]
    I1 --> W1["Wait 10m\n(sleep or pause)"]
    W1 --> I2["Iteration 2\nExecute Task"]
    I2 --> W2["Wait 10m"]
    W2 --> IN["...continues until\ncancelled or max failures"]

    style S fill:#a855f7,color:#fff
    style I1 fill:#22c55e,color:#fff
    style W1 fill:#f59e0b,color:#fff
    style I2 fill:#22c55e,color:#fff
    style W2 fill:#f59e0b,color:#fff
    style IN fill:#6b7280,color:#fff

Feature	Behavior
Hybrid wait	Intervals ≤15min: sleep between iterations. >15min: pause loop, auto-resume on next session
Sub-pipelines	Tasks referencing the fix pipeline spawn a full session pipeline within each iteration
Failure threshold	3 consecutive failures → loop fails (configurable)
Max iterations	Unlimited by default; --max-iterations N to cap
Single active	Only 1 active loop at a time

Real-World Example: Monitor FastAPI → Fix → PR

/omb:loop 10m "check past 10 minutes of FastAPI docker logs, find errors, then use fix pipeline to fix and open a PR"

Each iteration follows this flow:

graph LR
    L["Loop\nIteration"] --> C["Check Logs\ndocker logs --since 10m"]
    C -->|No errors| D["Done\nITERATION_DONE"]
    C -->|Errors found| R["fix pipeline\n6-step session"]
    R --> P["Plan"] --> RV["Review\n⏸ checkpoint"]
    RV -->|approve| E["Execute"] --> V["Verify"] --> DC["Document"] --> PR["Create PR"]
    PR --> D

    style L fill:#a855f7,color:#fff
    style C fill:#3b82f6,color:#fff
    style R fill:#ef4444,color:#fff
    style P fill:#4a9eff,color:#fff
    style RV fill:#f59e0b,color:#000
    style E fill:#22c55e,color:#fff
    style V fill:#22c55e,color:#fff
    style DC fill:#22c55e,color:#fff
    style PR fill:#22c55e,color:#fff
    style D fill:#6b7280,color:#fff

Note: The fix pipeline pauses at the review-plan checkpoint for user approval. Type approve to continue to execution. After the PR is created, the loop sleeps for 10 minutes and starts the next iteration.

Usage examples and management commands

# Monitor FastAPI logs every 10 minutes, auto-fix and create PRs
/omb:loop 10m "check FastAPI docker logs for errors, use fix pipeline to fix and open PR"

# Simple monitoring without sub-pipeline
/omb:loop 10m "check docker logs for errors and report findings"

# Max iterations (stop after 5 runs)
/omb:loop 5m --max-iterations 5 "run health check on staging API"

# Show active loop details (ID, task, iteration, next run time)
/omb:loop status

# List all loops (active, paused, completed, failed)
/omb:loop list

# Pause the active loop (resumes automatically on next session)
/omb:loop pause

# Resume a paused loop
/omb:loop resume

# Cancel the active loop
/omb:loop cancel

Loop state is stored in .omb/state/loops/ as JSON.

---

Workflow Tiers

Not every task needs the full 6-step pipeline. The orchestrator selects the tier at task start.

Tier	When	Steps
TRIVIAL	<10 lines, 1 file, no behavior change	3 → 4 → 5 → 6
STANDARD	Most tasks	All 6 steps
EMERGENCY	Production hotfix	3 → 4 → 6 (skipped steps documented in commit trailer)

---

Agents

oh-my-braincrew organizes 22 agents into three tiers. The orchestrator selects agents based on task requirements and routes work to the appropriate model tier.

Tier 1 — Core (Orchestration Loop)

These six agents form the backbone of every workflow run.

Agent	Model	Purpose
explore	haiku	Find files, symbols, routes across Python + TS/React codebases
planner	opus	Decompose tasks across all stack layers, architecture decisions
executor	sonnet	Implement across Python, TypeScript, Node.js
verifier	sonnet	Run tests, check endpoints, validate state, collect evidence
reviewer	opus	Full code review — Python + TypeScript + Node.js, API contracts
critic	opus	Challenge plans and designs — the final "no" gate

Tier 2 — Domain Specialists (12 agents) and Tier 3 — Ops (4 agents)

Tier 2 — Domain Specialists

Agent	Model	Purpose
api-specialist	sonnet	FastAPI routes, Pydantic models, Node.js APIs, OpenAPI
db-specialist	sonnet	Postgres schema, Alembic, SQLAlchemy, Redis cache/pub-sub
langgraph-engineer	sonnet	LangChain chains, LangGraph state machines, RAG, Deep Agents
prompt-engineer	sonnet	Prompt optimization, few-shot curation, A/B comparison
frontend-engineer	sonnet	React components/hooks, Vite config, Tailwind CSS
web-designer	sonnet	Visual identity, design tokens, typography, color, motion
electron-specialist	sonnet	Main/renderer process, IPC, packaging, desktop security
leak-inspector	sonnet	Memory leaks, connection pool exhaustion, resource leaks
infra-engineer	sonnet	Docker, GitHub Actions, monitoring, Slack alerts
async-coder	sonnet	Python asyncio, Node.js async, React concurrent, race conditions
security-reviewer	opus	OWASP, Electron RCE, XSS, Redis ACLs, Postgres RLS

Tier 3 — Ops

Agent	Model	Purpose
debugger	sonnet	Root-cause analysis across all stack layers
test-engineer	sonnet	pytest, vitest, jest, testcontainers, coverage
git-master	sonnet	Conventional commits, branch strategy, PR creation
doc-writer	haiku	Technical docs, README, ADRs, migration guides

---

Skills

All workflow skills are invoked via colon-namespace. You can also use the /omb <subcommand> dispatcher form.

Workflow Skills (17)

Skill	Description	Example
/omb:interview	Requirements gathering — multi-round questioning across 10 dimensions	/omb:interview Build user authentication system
/omb:plan	Plan workflow — intent analysis, brainstorming, exploration, plan generation	/omb:plan Add LangChain chat on side panel
/omb:review	Multi-agent plan review — 3-13 domain-aware teams, P0-P3 issue tracking	/omb:review .omb/plans/2026-03-22-side-panel-chat.md
/omb:exec	Plan execution — TDD agents with dependency resolution and wave scheduling	/omb:exec .omb/plans/2026-03-22-side-panel-chat.md
/omb:check	Verification — parallel verifier agents per stack layer, fix loops, evidence	/omb:check .omb/plans/2026-03-22-side-panel-chat.md
/omb:doc	Documentation generation — parallel doc-writer agents, i18n README support (auto-detects README.{lang}.md), docs/ folder awareness, document records	/omb:doc .omb/plans/2026-03-22-side-panel-chat.md
/omb:pr	PR creation — branch, tracking-code traceability, category detection, checklist	/omb:pr .omb/plans/2026-03-22-side-panel-chat.md
/omb:prompt	Prompt engineering reference (P1-P8 patterns)	/omb:prompt
/omb:react	Mandatory React quality checklist — hooks, a11y, performance, TypeScript	/omb:react
/omb:design	Design system reference — visual identity, typography, color, motion	/omb:design
/omb:feedback	Submit feedback as a GitHub issue via gh CLI or browser URL	/omb:feedback Add dark mode toggle to settings page
/omb:loop	Recurring task loop — interval execution with sub-pipeline support	/omb:loop 10m "check logs for errors"
/omb:release	Release pipeline — version bump, changelog, tag, build, push	/omb:release patch
/omb:setup	First-time setup — user profile, Slack config, CLAUDE.md + PROJECT.md generation	/omb:setup

Skills are deployed to your project's .claude/skills/ automatically when you run omb init.

For automation, use omb tracking next PLAN|PR. That command is worktree-safe and allocates from the authoritative main-repo .omb/config.json.

LangChain / LangGraph Reference Skills (11)

Reference-only skills (no model invocation) — loaded by the langgraph-engineer agent or explicitly by the user.

Skill	Description
lc-framework-selection	Framework decision guide — LangChain vs LangGraph vs Deep Agents
lc-langchain-deps	Package versions, installation, environment setup
lc-langchain-fundamentals	create_agent(), @tool, middleware, structured output
lc-langchain-middleware	HITL middleware, Command resume, custom hooks
lc-langchain-rag	RAG pipeline: loaders, splitters, embeddings, vector stores
lc-langgraph-fundamentals	StateGraph, nodes, edges, Command, Send, streaming
lc-langgraph-persistence	Checkpointers, thread_id, time travel, Store
lc-langgraph-hitl	interrupt(), Command(resume), approval/validation workflows
lc-deep-agents-core	create_deep_agent(), harness, SKILL.md format
lc-deep-agents-memory	StateBackend, StoreBackend, FilesystemMiddleware
lc-deep-agents-orchestration	SubAgentMiddleware, TodoList, HITL

---

Tech Stack

oh-my-braincrew agents are tuned for this specific stack.

Layer	Technology
Language	Python, TypeScript
Frontend	React, Vite, Tailwind CSS
Desktop	Electron
Backend	FastAPI, Node.js (Express/Fastify)
Database	Redis, Postgres
AI Backend	LangChain / LangGraph
CI/CD	Git, Git Workflow
Notifications	Slack

---

Under the Hood

oh-my-braincrew ships as a Python package (Click CLI + Pydantic models) that provides CLI commands, a terminal statusline, and hook handlers for Claude Code's lifecycle events.

Statusline

[Opus] BC v0.2.0 | 2h 34m
CW: [████████████████████████████░░░░] 88% | cost: $1.23
[BCRW] oh-my-braincrew | main +3 M2 ?1
Pipeline: fix | Step: verify | Status: active

RGB gradient bar (green → yellow → red), dual JSON format support, two display modes (default / full), and conditional pipeline status line.

Hook Handlers

Event	Behavior
PreToolUse	Security policy — blocks writes to .env, secrets, .git/, dangerous bash patterns
PostToolUse	Plan file naming enforcement — validates session_id-based naming convention
SessionStart	Session initialization, pipeline/loop context injection, paused loop auto-resume
UserPromptSubmit	Pipeline/loop keyword detection, prompt preprocessing
Stop	Pipeline step transitions, loop marker processing, hybrid wait logic

---

For Developers

make setup    # Create venv and install with dev dependencies
make test     # Run pytest with verbose output
make cover    # Run tests with coverage report (85% threshold)
make lint     # Run ruff check + pyright strict
make clean    # Remove venv, caches, build artifacts

Local development with Claude Code:

claude --plugin-dir /path/to/oh-my-braincrew

Release a new version (builds, tags, publishes to PyPI):

/omb release patch             # 0.0.1 → 0.0.2
/omb release minor             # 0.0.1 → 0.1.0
/omb release major             # 0.0.1 → 1.0.0

Submit feedback:

omb feedback "your feedback message"

Creates a GitHub issue via gh CLI, or prints a pre-filled URL if gh is not available.

---

Migration from Go Binary (v0.1.x) to Python (v0.2.0+)

If you have an existing installation using the Go-based omb binary (v0.1.x), update as follows:

Upgrade via PyPI (recommended):

pip install oh-my-braincrew

Upgrade from source:

cd /path/to/oh-my-braincrew
git pull
make clean    # Remove old Go artifacts
make setup    # Install Python package

The Go binary (bin/omb, ~/.local/bin/omb) is no longer used. Verify with:

which omb          # Should point to site-packages or .venv/bin/omb
omb version        # Should show v0.2.0+

Command changes: All /omb slash commands and omb <subcommand> terminal commands remain the same. The .omb/ runtime data directory is unchanged.

---

Questions or feedback? Run omb feedback "your message" or open an issue.