Claude Code를 팀으로: oh-my-claudecode(OMC) 리뷰 — 플러그인 마켓플레이스로 까는 멀티에이전트 오케스트레이션

들어가며

Claude Code를 깊게 쓰다 보면 같은 조립을 반복하게 됩니다. 서브에이전트 정의를 손으로 쓰고, 슬래시 명령을 만들고, 훅 스크립트를 붙이고, 모델 라우팅 규칙과 알림 설정을 매번 손봅니다. oh-my-claudecode(줄여서 OMC)는 그 조립 전체를 미리 배선한 번들로 만들어 Claude Code에 플러그인으로 설치하는 프로젝트입니다.

한 가지 이름 함정을 먼저 짚고 갑니다. 저장소·플러그인 이름은 oh-my-claudecode지만, npm 패키지는 oh-my-claude-sisyphus라는 다른 이름으로 배포됩니다(package.json의 name 필드). "Sisyphus(시시포스)"와 "the boulder never stops(바위는 멈추지 않는다)"는 이 도구의 지속 실행 모드를 상징하는 반복 모티프입니다. 리뷰 시점 버전은 4.15.4, 라이선스는 MIT입니다.

이 글은 저장소를 클론해 코드를 직접 읽고 OMC가 Claude Code에 무엇을 설치하는지, 그것들이 어떻게 배선돼 동작하는지, CLI와 플러그인이 어떻게 나뉘는지를 해부한 기록입니다.

무엇인가

한 문장으로, OMC는 Claude Code용 멀티에이전트 오케스트레이션 레이어입니다. 서브에이전트·스킬(워크플로 프롬프트)·라이프사이클 훅·커스텀 MCP 도구·HUD를 사용자의 Claude Code 설정에 설치해, 평범한 자연어 프롬프트가 특화 에이전트와 모델 티어로 자동 라우팅되게 만듭니다. README 태그라인이 태도를 압축합니다 — "Claude Code를 배우지 마세요. 그냥 OMC를 쓰세요."

마켓플레이스 매니페스트가 규모를 자기소개합니다.

{
  "name": "omc",
  "description": "Claude Code native multi-agent orchestration - intelligent model routing, 28 agents, 32 skills",
  "plugins": [
    { "name": "oh-my-claudecode", "source": "./", "category": "productivity" }
  ]
}

여기서 "28 agents"는 19개 기본 에이전트 프롬프트에서 티어 변형(executor-high, architect-medium 등)을 코드로 생성해 늘린 수입니다. 대상 독자는 Claude Code 파워유저, 코딩 에이전트를 조율하는 OSS 메인테이너, AI 에이전트 워크플로 운영자입니다.

흥미로운 점은 OMC가 자매 프로젝트 계보 위에 있다는 것입니다. package.json 설명이 스스로 "Inspired by oh-my-opencode"라 밝히고, README는 OpenAI Codex CLI를 위한 쌍둥이 프로젝트 oh-my-codex도 함께 언급합니다.

아키텍처와 배포 형태

OMC는 Node/TypeScript로 작성됩니다. src/에만 1,100개가 넘는 .ts 파일이 있고, 빌드는 두 갈래로 갈립니다.

tsc가 src/ → dist/로 컴파일(라이브러리 표면)
여러 esbuild 번들 단계가 플러그인이 실제 실행하는 bridge/*.cjs 자립 아티팩트를 생성

특이한 사실은 dist/와 bridge/가 .gitignore에 있으면서도 강제 커밋돼 있다는 점입니다(dist/만 4,000개 이상). 마켓플레이스가 git 저장소에서 직접 설치("source": "./")하기 때문에 빌드된 JS가 저장소에 있어야 하는, 의도된 결정입니다.

배포의 1차 경로는 Claude Code 플러그인입니다. 두 개의 매니페스트가 배선을 담당합니다 — .claude-plugin/plugin.json(플러그인 매니페스트, 스킬·MCP·명령 선언)과 .claude-plugin/marketplace.json(마켓플레이스 등록, 스키마가 anthropic.com/claude-code/marketplace.schema.json). 플러그인이 설치하는 것은 다섯 범주이며, 각각 Claude Code의 확장 지점에 대응합니다.

범주	파일	Claude Code 확장 지점
서브에이전트	`agents/*.md` (19개)	`Task(subagent_type="oh-my-claudecode:executor", …)`
스킬	`skills/*/SKILL.md` (41개)	슬래시 명령 `/oh-my-claudecode:<name>` 또는 키워드 자동 트리거
슬래시 명령 shim	`commands/*.md` (28개)	전체 SKILL을 매 세션에 안 물리려는 얇은 래퍼
라이프사이클 훅	`hooks/hooks.json` + `scripts/*.mjs`	`UserPromptSubmit`·`PreToolUse`·`Stop` 등 이벤트
MCP 도구 서버	`.mcp.json` → `bridge/mcp-server.cjs`	커스텀 도구(LSP·AST·python_repl 등)

작동 원리

CLI와 설치

터미널 진입점 bin/oh-my-claudecode.js는 2줄짜리 shim입니다.

#!/usr/bin/env node
import '../bridge/cli.cjs';

bridge/cli.cjs는 src/cli/index.ts를 esbuild로 번들한 것으로, commander 기반 CLI입니다. 서브커맨드 없이 omc만 치면 tmux에서 Claude Code를 띄우는 launch로 갑니다. 그 밖에 install/setup, team, interop(Claude Code와 Codex를 split-pane tmux로 나란히), ask(다른 provider에게 조언), wait(레이트리밋 대기·자동 재개), teleport(git worktree), doctor, hud 등을 제공합니다.

omc setup(또는 세션 내 /setup)이 부르는 src/installer/index.ts의 install()은 상당히 맥락 인지형입니다. OMC가 플러그인으로 도는지 standalone npm으로 도는지, 플러그인이 이미 에이전트·스킬·훅을 제공하는지 감지해 중복 설치를 피합니다. 대략 다음을 수행합니다.

필요 시 ~/.claude/{agents,skills,hooks,hud} 생성
(standalone일 때만) 에이전트 .md와 번들 스킬을 복사 — 플러그인이 이미 제공하면 건너뛰고 중복은 가지치기(훅 이중 발화 방지)
docs/CLAUDE.md를 백업과 함께 ~/.claude/CLAUDE.md에 트랜잭션 병합
HUD 스테이터스라인(~/.claude/hud/omc-hud.mjs)을 설치하고 settings.json이 그것을 가리키게 함(사용자 커스텀 스테이터스라인은 보존)
훅을 등록한 settings.json을 한 번에 쓰고, nvm/fnm 환경을 위해 감지한 node 경로를 .omc-config.json에 저장

훅이 발화하는 방식

hooks/hooks.json이 Claude Code 이벤트에 커맨드 훅을 겁니다. 모든 훅은 크로스플랫폼 러너 scripts/run.cjs를 통해 실행되는데, 이 러너는 대상 스크립트를 process.execPath로 띄워 Windows에서도 /bin/sh 없이 동작하고, CLAUDE_PLUGIN_ROOT가 낡아 대상이 없으면 플러그인 캐시에서 최신 버전을 찾아보고, 그래도 없으면 process.exit(0)으로 실패해도 열리게(fail-open) 해 호스트 세션을 절대 막지 않습니다. 이벤트별 배선은 대략 이렇습니다.

UserPromptSubmit → keyword-detector.mjs, skill-injector.mjs
SessionStart → session-start.mjs, 프로젝트 메모리·위키 세션 훅
PreToolUse/PostToolUse → 도구 전후 강제·검증기
Stop → context-guard-stop.mjs, workflow-drift-guard.mjs, persistent-mode.mjs, code-simplifier.mjs

"매직 키워드" → 스킬 호출

OMC의 핵심 UX는 자연어에 특정 키워드를 넣으면(예: ultrawork ..., ralph ..., autopilot ...) 훅이 해당 워크플로를 주입하는 것입니다. 그런데 주입 방식이 영리합니다. UserPromptSubmit 훅은 SKILL.md 전문을 프롬프트에 인라인하지 않고(토큰 폭증 방지), 경로와 슬래시 호출을 안내하는 짧은 지시만 hookSpecificOutput.additionalContext로 되돌려줍니다. scripts/keyword-detector.mjs의 생성 함수를 보면 그 형태가 드러납니다.

function createSkillInvocation(skillName, originalPrompt, args = '') {
  const skillPath = resolveSkillPath(skillName);
  const pathStatus = existsSync(skillPath)
    ? `Read fallback: open ${skillPath} and follow its SKILL.md instructions.`
    : `Read fallback: locate skills/${skillName}/SKILL.md in the active oh-my-claudecode plugin/install and follow it.`;

  return `[MAGIC KEYWORD: ${skillName.toUpperCase()}]

Skill routing detected: ${skillName}
Preferred invocation: /oh-my-claudecode:${skillName}${args ? ` ${args}` : ''}
${pathStatus}…`;
}

여러 키워드가 겹치면 고정 우선순위로 하나만 고릅니다(ralph > ultragoal > autopilot > ultrawork > …, cancel은 배타적). ralph·ultrawork 같은 지속 모드는 세션 상태 파일(예: ralph-state.json)을 쓰고, Stop 훅의 persistent-mode.mjs가 그 파일을 읽어 태스크가 끝날 때까지 계속 재프롬프트합니다 — 바로 "바위는 멈추지 않는다"의 구현입니다.

여기서 중요한 사실은, 키워드 라우팅에 LLM 분류기가 없다는 점입니다. 훅이 결정론적으로 텍스트를 주입하고, 실제 작업은 호스트인 Claude Code 모델이 합니다.

OMC 자신의 코드가 LLM을 부르는 곳

OMC 런타임은 raw Messages API가 아니라 @anthropic-ai/claude-agent-sdk를 씁니다. src/index.ts의 createOmcSession()이 시스템 프롬프트·에이전트 레지스트리·MCP 서버·허용 도구·permissionMode: 'acceptEdits'를 담은 query() 옵션을 조립해 라이브러리 소비자에게 제공합니다. 커스텀 도구들(12개 LSP 도구, 2개 ast-grep 도구, python_repl, 상태·노트패드·메모리·트레이스·위키 도구)은 SDK의 createSdkMcpServer/tool로 등록돼 mcp__t__<name> 형태로 노출됩니다. 다만 플러그인 자체는 인프로세스 서버가 아니라 번들된 bridge/mcp-server.cjs를 씁니다.

외부 CLI 팀

omc team은 실제 tmux 워커 페인을 띄워 외부 에이전트 CLI를 굴립니다. 문법은 omc team [N:agent-type[:role]] "task"이고, 유효한 에이전트 타입은 claude, codex, gemini, grok, cursor, antigravity입니다(1~20 워커, 선택적 git worktree 격리). 워커들은 SQLite(better-sqlite3)로 뒷받침되는 메시지 API로 조정됩니다. 이는 세션 안에서 네이티브 Claude 서브에이전트를 쓰는 /team 스킬과는 다른 층입니다.

설치와 사용

권장 경로는 Claude Code 플러그인이며, 슬래시 명령을 한 줄씩 칩니다.

/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode

이후 세션에서 /setup(또는 /omc-setup), 터미널에서는 omc setup으로 설정합니다. npm 런타임 경로를 쓰려면 패키지명에 주의해야 합니다.

npm i -g oh-my-claude-sisyphus@latest

설치 후에는 자연어로 바로 워크플로를 부릅니다 — 예: /autopilot "REST API를 만들어줘..." 또는 프롬프트에 autopilot: ...처럼 키워드를 섞습니다. 스코핑이 필요하면 /deep-interview "..."로 소크라테스식 질문을 받습니다.

유저 관점: 어디서 작업하고, Codex와 어떻게 함께 쓰나

플러그인을 깐 뒤 유저는 평소처럼 claude(Claude Code)를 켜서 거기에 타이핑합니다. 매직 키워드(ultrawork ...)나 /oh-my-claudecode:autopilot이 그 세션 안에서 바로 동작하고, 실제 작업은 Claude Code가 합니다. omc CLI는 tmux 런치·팀 같은 부가 기능용이지, 대화하는 곳은 Claude Code입니다.

Codex와의 병행이 이 툴에서 특히 뚜렷합니다.

omc interop — Claude Code를 왼쪽, Codex CLI를 오른쪽에 둔 split-pane tmux 세션을 만들고 둘이 공유 interop 상태를 갖게 합니다(src/cli/interop.ts).
omc team N:codex "..." — Codex를 tmux 워커로 팀에 투입합니다. 유효한 외부 에이전트 타입은 ['claude', 'codex', 'gemini', 'grok', 'cursor', 'antigravity']입니다(VALID_TEAM_CLI_AGENT_TYPES, src/cli/commands/team.ts).
omc ask codex "..." — Codex를 자문자로 부릅니다.

즉 Claude Code를 주 세션으로 두고 Codex를 나란히 띄우거나(worktree 워커·자문) 붙여 쓰는 것이 설계 의도입니다.

한계와 주의점

코드·문서에서 드러난 사항만 정리합니다.

npm 이름 불일치. 저장소·플러그인은 oh-my-claudecode, npm 패키지는 oh-my-claude-sisyphus입니다. README가 반복해서 경고하는 실수 지점입니다.
플랫폼. tmux 중심이라 Unix 지향입니다. CLI는 시작 시 win32 경고를 출력하고(OMC requires tmux which is not available on native Windows), interop·team·launch가 tmux를 요구합니다. Windows 하드닝(run.cjs가 /bin/sh 회피 등) 노력은 있습니다.
폐기·급변. omc autoresearch는 하드 폐기된 shim이고, 여러 명령이 플러그인 스코프 스킬로 대체됐습니다(설치 시 명령 설치 루프가 비활성). 4.15.4에 #3xxx대 이슈 번호는 빠른 반복을 시사합니다.
보안 기본값. OMC_SECURITY=strict는 옵트인입니다. 이걸 켜야 AST 도구 경로 제한, Python-REPL 샌드박스(위험 모듈·빌트인 차단), 원격 MCP 비활성, 외부 LLM(Codex/Gemini/Grok 워커) 비활성, 자동업데이트 비활성, 지속 모드 200회 하드캡이 적용됩니다. 기본적으로는 전부 꺼져 있어, python_repl·AST 도구·외부 CLI 워커·자기 업데이트가 옵트인 전까지 샌드박스 없이 강력하게 동작합니다.
커밋된 생성물. dist/(4,000+개)와 bridge/가 생성물임에도 커밋돼 있고, 메인테이너의 다른 도구가 남긴 흔적(shellmark/, .omx/plans/, .clawhip/, 빈 .codex)도 저장소에 섞여 있습니다.

결론

OMC의 설계를 한 줄로 요약하면 "Claude Code의 확장 지점(서브에이전트·스킬·명령·훅·MCP)에 잘 배선된 번들을 설치하고, 키워드로 워크플로를 주입한다"입니다. 지능의 상당 부분은 모델 호출 코드가 아니라 훅이 주입하는 텍스트와 41개 skills/·19개 agents/ 프롬프트에 담겨 있고, 실제 작업은 호스트 Claude Code가 수행합니다.

특히 인상적인 세 가지가 있습니다. 첫째, SKILL 전문을 인라인하지 않고 경로+슬래시 호출만 주입해 토큰 폭증을 피하는 매직 키워드 설계. 둘째, 낡은 플러그인 경로에도 절대 세션을 막지 않는 fail-open 훅 러너. 셋째, SWE-bench 대조 하네스(benchmark/), 프롬프트 품질 스코어링(benchmarks/), LLM 가시성(GEO) 스펙(geobench/)이라는 서로 다른 세 평가 시스템까지 갖춘 운영 규율입니다. Claude Code를 이미 쓰고 있고 그 위에 정형 워크플로·모델 라우팅·병렬 실행 레이어가 필요한 사람에게 OMC는 "학습 없이 번들로 강화한다"는 접근의 잘 배선된 사례입니다.

이 글에서 다루지 못한 부분

분량상 다음은 개요만 언급했습니다. omc ultragoal(지속 다중 목표 워크플로)과 ralphthon(자율 해커톤 라이프사이클), missions/의 evaluator 기반 self-improving 루트(optimize omc 같은 자기 최적화 태스크), OpenClaw/Clawhip 이벤트 라우팅(src/openclaw/)으로 모든 훅 이벤트를 외부 게이트웨이에 재방출하는 알림 계층, 그리고 research/의 아키텍처 자기비평 문서입니다. 각각은 저장소의 docs/(ARCHITECTURE.md·HOOKS.md·TOOLS.md 등)와 해당 src/ 모듈에 더 깊은 명세가 있습니다.