# Windows (PowerShell)
irm https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.ps1 | iex

# bun이 설치된 모든 OS: 같은 설정에 전역 `oma` 커맨드까지 설치
bun install --global oh-my-agent
oma

Windows에서는 설치 프로그램이 Antigravity, Hermes, Kimi를 숨기고, hook 래퍼는 bash 스크립트입니다. 기본 Aside 브라우저 MCP는 bash로 설치되므로, bash가 없다면 선택을 해제하세요.

• bun을 설치합니다(필수). uv, Serena(uv tool install), CUE(brew install cue 또는 winget) 설치도 시도하며, 이 중 하나가 실패해도 경고만 남기고 계속 진행합니다.
• 대화형 설정에서 Aside 브라우저 MCP를 미리 선택해 두며, 선택을 유지한 경우에만 curl -fsSL https://releases.aside.com/install.sh | bash로 설치합니다. 브라우저 MCP 단계에서 선택을 해제하거나, 나중에 oma update mcp로 바꿀 수 있습니다.
• 시맨틱 메모리로 AgentMemory를 사용합니다. 이때 bun install -g @agentmemory/agentmemory를 실행하고 로그인 서비스(launchd, systemd 사용자 유닛 또는 Windows 예약 작업)로 등록합니다. 건너뛰려면 프로바이더로 none을 고르거나 OMA_NO_AGENTMEMORY=1을 설정하세요.
• 홈 디렉터리의 벤더 폴더(Antigravity, Hermes, Kimi)에 스킬을 링크하기 전에는 먼저 묻습니다. --global 없이 $HOME에서 실행하면 확인을 요청합니다.
• 프로젝트 밖의 일부 파일은 묻지 않고 씁니다. ~/.claude.json(프로젝트를 신뢰할 수 있는 Claude Code 워크스페이스로 표시), ~/.serena/(OMA 컨텍스트, 응답 크기 하한, 프로젝트 등록), ~/.cursor/cli-config.json(Cursor의 커밋 attribution 끄기), ~/.grok/config.toml(텔레메트리), ~/.gemini/antigravity-cli/(HUD)이며, 각 파일은 선택한 벤더에 대해서만 씁니다.
• 벤더 설정에 텔레메트리 옵트아웃을 씁니다. Claude에는 DISABLE_TELEMETRY=1을 넣고(이 값은 Claude Code Remote Control도 끕니다), Gemini, Qwen, Codex, Grok에서는 사용 통계를 끕니다. 벤더 기본값을 유지하려면 telemetry: true를 설정하세요.
• .claude/settings.json에 아직 설정하지 않은 Claude Code 설정을 추가합니다. skipDangerousModePermissionPrompt: true, effortLevel: high, cleanupPeriodDays: 180과 함께 auto memory, adaptive thinking, 오류 보고, 내장 git 지침을 끄는 env 플래그가 포함됩니다. 이미 설정한 값은 그대로 유지됩니다.
• 공동 작성자 트레일러를 추가합니다. Claude Code의 커밋 attribution이 Co-Authored-By: First Fluke <[email protected]>이 되고, PR에는 "Generated with oh-my-agent" 줄이 붙습니다. 끄려면 scm.co_author.enabled: false를 설정하세요.
• 목록에 없는 Co-authored-by 주소를 거부하는 commit-msg 가드를 .githooks/에 설치하고, 다른 hook이 활성화되어 있지 않으면 git config --local core.hooksPath .githooks를 설정합니다. 사용하지 않으려면 scm.co_author.enforce_hook: false를 설정하세요.
• oma update는 백그라운드에서 oma CLI를 업데이트하고(멈추려면 auto_update_cli: false 또는 OMA_SKIP_VERSION_CHECK=1), uv tool upgrade serena-agent --prerelease=allow를 실행합니다(serena.auto_update: false).
• Serena가 기본 bridge 모드일 때, 공유 Serena 서버를 처음 시작한 에이전트 세션이 정리 타이머를 등록합니다. 이 타이머는 유휴 상태인 공유 Serena 서버를 5분마다 중지합니다(launchd dev.oma.serena-daemon-gc, systemd 사용자 타이머 oma-serena-daemon-gc.timer 또는 Windows 예약 작업 OMA Serena Daemon GC). 공유 서버와 타이머를 건너뛰려면 serena.mode: stdio를 설정하세요. oma uninstall은 이 타이머를 제거하지 않습니다.
• 비대화형 실행(-y, OMA_YES=1, CI=true)은 --preset으로 지정한 스킬 프리셋을 사용하며, 생략하면 All을 사용합니다. model_preset: auto, 백엔드 언어 Python을 사용하고, mcp.devtools_browsers에 이미 브라우저가 들어 있지 않으면 브라우저 MCP를 선택하지 않습니다(Aside 설치 스크립트도 건너뜁니다).

이름이 붙은 프리셋 중에서 coordination, orchestration, docs, security, refactor, explanation, recap, video, slide, skill-creation을 포함하는 것은 All뿐입니다(또는 Custom에서 직접 고르세요). Research와 Content에는 /plan, /review, /debug, /architecture, /brainstorm이 쓰는 스킬이 없습니다. 프리셋 밖의 스킬이 필요한 워크플로우를 참고하세요.

인프라 엔지니어(tf-infra-engineer)는 파괴적이거나 프로덕션을 대상으로 하는 apply, destroy를 실행하기 전에 먼저 묻도록 지시받습니다. 나머지 스킬(brainstorm, security, scm, dev-workflow, observability, explanation, recap, translation, coordination, orchestration, skill-creation, 콘텐츠와 미디어)에는 전담 역할이 없습니다. 에이전트가 직접 불러오며, 대부분은 스킬 인젝터가 프롬프트를 보고 알맞은 스킬을 제안합니다.

oma verify triggers는 라벨링된 영어·한국어 프롬프트 212개 코퍼스로 감지기를 평가합니다. 오발화가 10%를 넘거나 미발화가 20%를 넘으면 CI가 실패합니다. 최근 측정값: 미발화 0%, 오발화 5.3%. 전체 레퍼런스: Workflows.

/stack-set은 매니페스트를 읽어 backend, frontend, mobile 스킬용 스택별 레퍼런스를 씁니다. 모노레포에서는 프런트엔드, 백엔드, 모바일 엔지니어가 각자의 workspace(pnpm, npm/yarn/bun workspaces, lerna, nx, turbo, mise.toml)로 안내됩니다.

이 파이프라인들은 소스나 벤더 키가 없을 때 빈약한 결과를 조용히 돌려주는 대신 그 사실을 보고합니다.

oma hook probe는 oma의 프롬프트 hook이 각 런타임의 hook 입력을 받아들이는지 확인합니다(런타임을 실행하지는 않습니다). 런타임별로 어떤 hook이 연결되는지는 호스트별 차이에 있습니다.

• oma agent spawn <role> "<task>" <sid>는 Antigravity, Claude Code, Codex, Cursor, Grok, Kimi Code, Kiro, OpenCode, pi, Qwen Code에서 역할을 실행하며 --isolation worktree와 --fallback-vendors를 지원합니다. oma agent parallel은 여러 역할을 한꺼번에 실행합니다. 이 10개 디스패치 대상은 설치 프로그램이 연동하는 14개 중 일부입니다.
• oma state list --all-projects와 oma state get <sid>: 세션과 기록된 모든 이벤트.
• oma dashboard terminal / oma dashboard web: 실시간 에이전트 상태(웹 대시보드는 127.0.0.1에서만 수신). 대시보드 가이드.
• oma stats get(생산성 지표), oma retro(git 회고), oma recap --window 7d(여러 AI 도구에서 한 일).
• oma visualize --affected <paths>: 변경한 .agents/ 파일에 의존하는 스킬, 워크플로우, 에이전트, 체크.

Serena는 LSP 기반 코드 탐색과 진단을 제공하며, 지원되는 경우 네이티브 편집 피드백도 제공합니다. 프로바이더 선택은 에이전트 런타임과 별개이며, 기능은 프로바이더와 호스트에 따라 다릅니다.

에이전트는 외부 서비스 없이 .agents/state/의 평범한 파일로 서로 조율합니다. /tools는 평이한 말로 MCP 도구를 켜고 끕니다. 자세한 내용: 기능 프로바이더.

• oma skill eval은 홀드아웃 태스크에서 baseline과 비교해 스킬이 성능을 얼마나 끌어올리는지 측정합니다. oma skill optimize는 그 수치를 높이는 수정을 제안하고, --apply를 붙이면 그 수정을 반영합니다(skill-eval 가이드).
• oma harness evolution enable --max-dispatches <n>은 매일 밤 실행되는 사이클을 예약합니다. 이 사이클은 실패한 실행을 회귀 픽스처로 바꾸고, 평가를 통과한 스킬 개선을 프로젝트 오버레이로 적용합니다. --mode propose를 붙이면 기록만 합니다.
• oma emit은 .agents/ 소스를 Agent Skills 패키지, Agent Plugins 패키지, Claude Code 플러그인 마켓플레이스, 또는 AGENTS.md로 내보냅니다.

• 사용자가 소유하는 .agents/oma-config.yaml 하나는 업데이트 후에도 유지됩니다(oma update --force만 초기화합니다). 그 위에 비공개 .local.yaml이나 .local.cue 오버레이를 얹을 수 있습니다. language는 응답 언어를 정합니다.
• 프로젝트 규칙 13개(backend, commit, database, debug, design 등)는 Claude Code와 Cursor에서 네이티브 규칙으로 불러오고, Codex, Qwen Code, Pi용으로 작성되는 관리형 AGENTS.md 블록에 색인됩니다.
• 업데이트할 때 설정과 마이그레이션 백업이 .agents/backup/에 남습니다. 기본 제공 스킬과 워크플로우는 그 자리에서 교체되므로 로컬 변경은 그 밖에 두세요. oma uninstall --dry-run은 무엇이 제거될지 보여 줍니다. first-fluke/oma-update-action@v1은 CI에서 oma update를 실행하고 PR을 엽니다.

네이티브 = oma가 런타임 자체의 설정 파일을 씁니다. 어댑터 = oma가 hook이나 에이전트 shim도 추가합니다. Amp는 .agents/skills/를 스스로 읽으며 설치 프로그램 대상이 아닙니다.

Claude Code 네이티브 + 어댑터	Codex CLI 네이티브 + 어댑터	Antigravity 네이티브 SSOT	Cursor 네이티브 + 어댑터	Qwen Code 네이티브 디스패치	DeepSeek Harness Cordis 플러그인
Pi 네이티브 호환	OpenCode 네이티브 호환	Amp .agents/skills 읽기	GitHub Copilot 심볼릭 링크 스킬	Grok Build 네이티브 hook	Kiro CLI 네이티브 hook + 에이전트

_{& 더 보기}

.agents/oma-config.yaml의 model_preset으로 에이전트 역할마다 어떤 모델을 쓸지 정합니다. 기본값 auto는 실행 중인 런타임 자체의 에이전트·모델 설정을 따릅니다.

language: en
model_preset: auto   # auto | free | antigravity | claude | codex | cursor | kiro | mixed | qwen | <custom_presets key>

# Optional per-agent overrides; they win over the preset
agents:
  backend: { model: openai/gpt-6.1-terra, effort: high }

• mixed는 오케스트레이터, 아키텍처, QA, PM, 문서에 Claude를, 구현 역할에 Codex gpt-6.1-terra를 사용하므로 Claude Code와 Codex CLI가 모두 필요합니다.
• free는 FreeLLMAPI 게이트웨이를 거치며, FREELLM_API_KEY와 실행 중인 서버가 필요합니다.
• kiro는 설치 프로그램 메뉴에 없으므로 설정 파일에서 지정하세요.
• oma doctor --profile은 역할별로 해석된 모델을 출력합니다.
• 전체 가이드: 에이전트별 모델

제한 사항:

• Stop 게이트는 persistent workflow(/orchestrate, /work, /ultrawork, /ralph)에만 적용됩니다. oma goal set --gate가 없으면 에이전트에게 계속하라고 다시 프롬프트할 뿐입니다. /ultrawork는 프로젝트에 가벼운 체크가 있으면 게이트를 설정하라고 에이전트에게 지시하지만, 이를 강제하는 장치는 없습니다. 확실히 하고 싶다면 oma goal set --gate test를 직접 실행하세요. 나머지 persistent workflow는 게이트를 설정하지 않습니다.
• 받아들이는 키워드는 typecheck, test, lint뿐이며, 같은 이름의 package.json 스크립트를 실행합니다. package.json이 없거나 그 이름의 스크립트가 없으면 게이트는 실행되지 않습니다. JS가 아닌 프로젝트는 package.json 래퍼 스크립트가 필요합니다.
• 재강제가 5회에 이르거나 2시간이 지나거나 --budget-minutes가 소진되면 차단이 풀리고 실패로 기록됩니다.
• 예산: session.quota_cap은 토큰, spawn 횟수, 벤더별 토큰에 상한을 겁니다. 어느 한 항목이라도 넘으면 오케스트레이터가 다음 spawn을 거부합니다.

산출물 게이트. 산출물이 없으면 해당 phase는 실행되지 않은 것입니다. 세션 로그에 REFINE을 건너뛴 이유가 기록되어 있으면 refactor 체크도 skip-recorded로 통과합니다.

프롬프트 기반 judge. /ralph 워크플로우 프롬프트는 오케스트레이터에게 judge를 새 컨텍스트를 가진 별도 에이전트로 띄워 기준만 브리핑하고(구현자가 무엇을 고쳤다고 주장하는지는 절대 알려 주지 않음), 매 iteration마다 이미 PASS한 것까지 포함해 모든 기준을 다시 검증하라고 지시합니다. 한 기준을 수정하면 다른 기준이 회귀할 수 있기 때문입니다. judge를 실제로 띄웠는지 확인하는 장치는 없습니다. oma ralph verify는 judge가 아니라 EXEC 산출물을 검사하는 게이트이고, 서브에이전트를 띄울 수 없는 런타임은 인라인으로 판정하고 ralph.judge-inline-fallback을 기록하라는 지시를 받습니다. /ralph는 5회 iteration 후 부분 보고서를 내고 멈춥니다.

이벤트 로그. 세션은 oma state list로 찾고 oma state get <sid>로 읽으세요. 각 이벤트에는 벤더와 런타임 세션 id가 찍힙니다. 파일 위치는 OMA_HOME, OMA_STATE_HOME, OMA_PROFILE과 예전 프로젝트 로컬 세션 폴더에 따라 달라지므로 하드코딩하지 마세요.

에이전트별 체크. 유형: backend, frontend, mobile, qa, debug, pm. 체크가 하나라도 실패하면 커맨드는 1로 종료됩니다. TODO/FIXME Comments와 Inline Styles는 경고만 합니다.

• backend: stack/stack.yaml의 커맨드로 실행하는 <Language> Syntax, SQL Injection(raw SQL 패턴), <Language> Tests. 그 파일이 없으면(/stack-set으로 생성) 건너뜁니다.
• frontend: stack/stack.yaml(oma-frontend 아래, 또는 angular-developer 스킬이 설치되어 있으면 그 아래)의 문법·테스트 커맨드, 또는 TypeScript(tsc --noEmit)와 Frontend Tests(Vitest). Inline Styles와 Any Types는 항상 실행됩니다.
• mobile: stack/stack.yaml의 문법·테스트 커맨드, 또는 Flutter/Dart Analysis와 Flutter Tests.
• debug: Python Tests(uv를 통한 pytest) 또는 Frontend Tests(Vitest).
• pm: PM Plan(plan 파일이 유효한 JSON인지).
• qa: 기계적 체크 없음.

flowchart TD
    S[Agent tries to stop] --> P{Persistent workflow active?}
    P -- no --> A[Stop allowed]
    P -- yes --> D{User or agent said workflow done?}
    D -- yes --> A
    D -- no --> R{Budget spent, state older than 2 h, or 5 blocks reached?}
    R -- yes --> F[Stop allowed, logged as gate.failed]
    R -- no --> G{Gate set and package.json script exists?}
    G -- no --> B1[Blocked: workflow still active]
    G -- yes --> X{Script exits 0 within 25 s?}
    X -- yes --> OK[Stop allowed, logged as gate.passed]
    X -- no --> B2[Blocked with output tail, logged as gate.failed]

아닙니다. 스킬 프리셋을 참고하세요. All이 안전한 기본값입니다.

oma doctor는 설치된 스킬을 보여 주고, hook이 oma를 찾지 못하면 경고합니다. persistent workflow 중에는 oma state list가 활성 세션을, oma state get <sid>가 그 세션의 게이트 이벤트를 보여 줍니다.

대체로 그렇습니다. 스킬은 태스크에 필요할 때만 불러오지만, 멀티 에이전트 워크플로우와 새 컨텍스트 리뷰에는 더 많이 듭니다. 단일 프롬프트 벤치마크에서 oma의 비용은 순수 Claude Code의 1.7배였습니다.

"workflow done"(또는 "workflow complete" / "workflow finished", 지원하는 다른 언어의 같은 표현)이라고 말하거나 .agents/state/<workflow>-state-<sid>.json을 삭제하세요. 둘 다 하지 않아도 5번 차단되거나 2시간이 지나면 저절로 풀립니다.

oma update는 설정은 그대로 두고 스킬, 워크플로우, hook을 새로 고칩니다(--with-new-skills는 이번 릴리스에서 새로 나온 스킬을 추가하고, oma update mcp는 브라우저 MCP를 다시 고릅니다). oma uninstall --dry-run은 무엇이 제거될지 보여 주고, oma uninstall은 실제로 제거하되 oma-config.yaml, mcp.json, 직접 작성한 스킬은 남겨 둡니다. 다른 해결 방법: Troubleshooting.

계획과 다음 단계 선택은 에이전트의 모델이 맡습니다. oma에는 고정된 워크플로우 그래프가 없습니다. oma가 모델 바깥에서 강제하는 것은 도구 가드레일(시크릿 가드와 검색 가드), 예산, 재시도와 종료 한도, 이벤트 로그, 그리고 게이트를 설정했을 때 프로젝트 자체 체크가 통과할 때까지 기다리는 종료입니다.

• Li, X., Liu, Y., Chen, W., You, B., Di, Z., He, Y., Zheng, S., Choe, K. W., Sun, J., Wang, S., Tao, C., Li, B., Zhao, X., Geng, H., Wu, X., Zhou, J., Chen, X., Xing, H., Li, Y., … Song, D. (2026). SkillsBench: Benchmarking how well agent skills work across diverse tasks (Version 4) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2602.12670
• Yu, G., & Wang, X. (2026). Knows: Agent-native structured research representations (Version 1) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2604.17309
• Liang, Q., Wang, H., Liang, Z., & Liu, Y. (2026). From skill text to skill structure: The scheduling-structural-logical representation for agent skills (Version 4) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2604.24026
• Chen, C., Yu, Q., Gu, Y., Huang, Z., Li, H., Liu, H., Liu, S., Liu, J., Peng, D., Wang, J., Yan, Z., Meng, F., Qin, E., Che, C., & Hu, M. (2026). The scaling laws of skills in LLM agent systems (Version 1) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2605.16508
• Tang, L., Rashtchian, C., Ferng, C.-S., Tomkins, A., Juan, D.-C., & Vu, T. (2026). WikiSkill: Compiling agent experience into persistent knowledge for skill evolution [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2608.27454
• Huang, Z., Xu, J., Yang, Y., Gong, Z., Yang, Q., Tian, M., Wang, X., Lv, C., Gao, X., Dai, Q., Liu, B., Qiu, K., Yang, X., Chen, D., Zheng, X., & Luo, C. (2026). From raw experience to skill consumption: A systematic study of model-generated agent skills [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2605.23899
• Hong, D. B., Imani, A., & Ahmed, I. (2026). From anatomy to smells: An empirical study of SKILL.md in agent skills (Version 2) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2607.01456