orca orchestration CLI로 에이전트 간 메시지·태스크·완료 신호까지 구조화된 방식으로 조율한다. (저장소: stablyai/orca · Electron + React + React Native · MIT 라이선스 · ★7,900+ · TrendShift Daily #23 · 2026-03-17 공개, 매일 릴리스)
음악 오케스트라를 떠올려 보세요. 바이올린·첼로·트럼펫이 따로따로 연습하면 소음이지만, 지휘자가 악보와 큐(cue)를 주면 곡이 됩니다. Orca는 Claude Code·Codex·Gemini 같은 코딩 에이전트들을 악단원으로, 사용자를 지휘자로 세우는 앱입니다. 각 에이전트는 자기만의 격리된 Git 브랜치(워크트리)에서 "이 버그를 고쳐봐" 같은 지시를 동시에 수행하고, 결과를 한 화면에서 비교·병합합니다.
더 정확히는, Orca가 내세우는 개념인 ADE(Agent Development Environment)는 IDE처럼 에이전트 '팀'을 위한 개발 환경입니다. 코드 편집기, 터미널, 브라우저, 깃 뷰어, 모바일 컴패니언 앱까지 하나의 틀 안에 묶여 있습니다.
2024년까지만 해도 AI 코딩 도구의 사용 패턴은 단순했습니다. 터미널 하나를 열고, Claude Code 혹은 Codex를 실행하고, 하나의 질문에 하나의 답을 받는 것이었습니다. 그런데 에이전트가 점점 강력해지면서 새로운 문제가 생겼습니다.
에이전트 하나가 "로그인 기능을 리팩터링해줘"를 받으면, 그 에이전트가 작업을 마칠 때까지 다른 일을 시킬 수 없습니다. 실패하면 처음부터 다시 시작해야 합니다. 게다가 같은 코드베이스에서 두 에이전트가 동시에 파일을 수정하면 서로의 변경이 충돌합니다.
Git에는 워크트리(worktree)라는 기능이 있습니다. 하나의 저장소에서 여러 브랜치를 동시에 다른 폴더에 체크아웃하는 기술입니다. Orca는 에이전트마다 워크트리를 자동으로 생성해, 각자 서로를 건드리지 않고 동시에 작업하도록 격리합니다. 5개의 에이전트 = 5개의 독립된 작업 공간.
| 도구 | 특징 | Orca와의 차이 |
|---|---|---|
| Claude Code (단독) | CLI에서 에이전트 1개 실행 | Orca는 여러 에이전트를 동시에 관리하는 상위 계층 |
| Cursor / Windsurf | IDE 내장 AI 에이전트 | 특정 AI 모델에 종속, 에이전트 병렬 실행 불가 |
| Claude Code MCP 서버 | 클로드 에이전트 간 연결 | Orca는 모든 CLI 에이전트를 아우르는 범용 오케스트레이터 |
| tmux + 직접 스크립트 | 터미널 분할로 여러 에이전트 | Orca는 결과 비교·병합·모바일 알림 등 UX가 통합됨 |
Orca가 주목받는 핵심 이유는 특정 AI 회사나 모델에 종속되지 않는다는 점입니다. Claude Code, Codex, Grok, Cursor, Gemini, Devin 등 터미널에서 실행되는 CLI 에이전트라면 무엇이든 Orca 안에서 돌릴 수 있습니다. 실제로 README에는 30여 개의 지원 에이전트가 나열되어 있습니다. "AI 에이전트 시장의 수혜자 — 어떤 에이전트가 이겨도 Orca는 쓰인다"는 전략입니다.
Orca는 특정 브랜드의 기계를 파는 게 아니라, 어떤 기계든 꽂을 수 있는 범용 공장 관리 시스템입니다. 삼성 로봇을 쓰든 LG 로봇을 쓰든, 공장 라인(워크트리)을 배분하고, 생산 현황(터미널 출력)을 모니터링하고, 불량품(실패한 에이전트)을 재작업 라인으로 돌리는 것은 Orca가 합니다.
| 계층 | 기술 | 역할 |
|---|---|---|
| 앱 프레임 | Electron | Node.js + Chromium으로 macOS·Windows·Linux 네이티브 앱을 단일 코드베이스로 제공 |
| 빌드 도구 | electron-vite + Vite | Electron 전용 빠른 빌드. Main·Preload·Renderer 세 진입점을 한 번에 번들 |
| UI 프레임워크 | React + TypeScript | 렌더러(화면) 전담. 컴포넌트 단위로 탭·터미널·diff 뷰어 등을 조합 |
| 스타일링 | Tailwind CSS (v4) | 유틸리티-퍼스트 CSS. shadcn/ui 컴포넌트 라이브러리와 연동 |
| 터미널 엔진 | xterm.js (headless + WebGL) | 브라우저에서 실제 터미널을 렌더링. 스크롤백 영구 보존 |
| PTY(가상 터미널) | node-pty | Node.js에서 실제 셸 프로세스를 의사 터미널로 실행 |
| 코드 에디터 | Monaco Editor (VS Code 코어) | 파일 편집·diff 뷰어. VS Code와 같은 엔진 |
| 상태 관리 | Zustand | 클라이언트 전역 상태(워크트리 목록·터미널 상태 등) 관리 |
| 자동 업데이트 | electron-updater | 앱 실행 중 백그라운드 자동 업데이트 |
| 계층 | 기술 | 역할 |
|---|---|---|
| 앱 프레임 | React Native + Expo | iOS·Android 동시 지원. Expo Router로 파일 기반 화면 라우팅 |
| 통신 프로토콜 | WebSocket (ws 라이브러리) | 데스크탑 Orca와 포트 6768로 실시간 연결. 터미널 출력 스트리밍 |
| 암호화 | TweetNaCl | QR 코드 페어링 시 공개키 교환 및 메시지 암호화. 중간자 공격 방지 |
| 터미널 렌더링 | WebView + xterm.js | 모바일에서도 터미널 출력을 색상·ANSI 코드까지 정확히 표시 |
| 음성 입력 | expo-two-way-audio (자체 제작) | 폰 마이크로 에이전트에게 음성 명령 전송. 내부 패키지 |
| 알림 | expo-notifications | 에이전트가 작업을 완료하면 푸시 알림 발송 |
| 보안 저장소 | expo-secure-store | 디바이스 토큰·서버 공개키 등 민감 정보를 키체인에 암호화 저장 |
| 계층 | 기술 | 역할 |
|---|---|---|
| 릴레이 데몬 | Node.js (JSON-RPC over stdio) | SSH 원격 호스트에 배포되는 경량 데몬. SSH 채널로 Electron과 통신 |
| 훅 서버 | Unix 도메인 소켓 | 에이전트가 작업 중 Orca에 이벤트(알림·요청)를 보내는 채널 |
| 오케스트레이션 CLI | orca orchestration 명령어 | 에이전트 간 메시지·태스크·완료 신호를 구조화하는 CLI API |
| 플러그인 오버레이 | 자체 구현 (plugin-overlay.ts) | OpenCode·Pi 등 특정 에이전트 CLI에 Orca 스킬을 주입하는 메커니즘 |
| Git 연산 | child_process → git 바이너리 | 워크트리 생성·삭제·diff·스테이징 등 직접 git 명령 실행 |
| 테스트 | Vitest | 단위·통합 테스트. relay 계층에 수십 개의 테스트 파일 존재 |
| 도구 | 역할 |
|---|---|
| pnpm (워크스페이스) | 모노레포 패키지 관리. 데스크탑·모바일·네이티브 패키지를 단일 저장소에서 관리 |
| oxlint | 빠른 Rust 기반 JS/TS 린터. ESLint보다 수십 배 빠름 |
| Husky | Git 훅으로 커밋 전 자동 린트 실행 |
| GitHub Actions | CI 빌드·릴리스 자동화. 공식 빌드만 PostHog 원격 측정 활성화 |
Git의 git worktree add 명령은 하나의 저장소에서 여러 디렉토리를 동시에 체크아웃합니다. Orca는 에이전트를 만들 때마다 자동으로 새 워크트리를 생성합니다. 각 에이전트는 자기 폴더에서만 파일을 수정하므로 다른 에이전트와 절대 충돌하지 않습니다. Git 오브젝트 데이터베이스(실제 파일 이력)는 공유하므로 디스크를 낭비하지 않습니다.
Orca의 모든 파일 I/O·Git 연산·PTY 생성은 Relay 데몬이 담당합니다. 이 데몬은 로컬에서 실행될 수도 있고, SSH를 통해 원격 서버에 배포될 수도 있습니다. Electron 메인 프로세스와 표준 입출력(stdin/stdout)으로 JSON-RPC 프레임을 교환합니다. 덕분에 "로컬 맥북에서 리눅스 클라우드 서버의 에이전트를 제어"하는 것이 동일한 코드로 가능합니다.
단순히 여러 에이전트를 실행하는 것을 넘어, Orca는 에이전트끼리 메시지를 주고받는 버스를 제공합니다. 코디네이터 에이전트가 태스크를 만들고(task-create), 워커 에이전트에게 배정하고(dispatch), 완료 신호를 기다립니다(check --wait). 워커는 막히면 질문(ask)을 보내고, 끝나면 worker_done을 보냅니다. DAG(방향 비순환 그래프) 형태의 태스크 의존성도 지원합니다.
모바일 앱과 데스크탑 앱은 QR 코드를 통해 페어링합니다. 이때 TweetNaCl을 사용해 공개키를 교환하고, 이후 모든 WebSocket 메시지를 암호화합니다. 같은 LAN 안에 있는 다른 기기가 엿들어도 내용을 알 수 없습니다. 프로토콜 버전 호환성도 체크해, 앱스토어 업데이트가 늦은 모바일 앱이 데스크탑과 통신 불가 상태가 되면 명시적인 오류 화면을 보여줍니다.
특이한 점: AGENTS.md는 사람 개발자가 아닌 AI 에이전트를 위한 코딩 규칙 문서입니다. "파일 이름을 utils·helpers처럼 모호하게 짓지 마라", "max-lines 린트 규칙을 disable하지 마라", "SSH 사용 케이스를 항상 고려하라" 등의 규칙이 담겨 있습니다. 에이전트가 코드를 수정할 때 이 파일을 읽고 지침을 따르도록 의도된 것입니다.
Electron 앱은 Main 프로세스(Node.js, OS 자원 접근), Renderer 프로세스(Chromium, UI 렌더링), Preload 스크립트(두 프로세스를 잇는 다리) 세 부분으로 나뉩니다. Orca의 electron.vite.config.ts는 이 세 진입점을 하나의 설정 파일에서 관리하며, 빌드 타임에 환경 변수를 코드에 직접 주입(compile-time constant injection)하는 기법을 보여줍니다 — PostHog 분석 키를 공식 빌드에만 활성화하는 방식이 좋은 예시입니다.
git worktree add ../repo-wt1 feature/login 한 줄로 같은 저장소를 다른 폴더에 체크아웃할 수 있습니다. 브랜치마다 별도 폴더가 생기므로, 여러 브랜치를 동시에 편집할 수 있습니다. Orca는 이 기능을 API로 감싸 에이전트마다 자동으로 워크트리를 생성·삭제합니다. Git 내부에서는 오브젝트 DB를 공유하므로 디스크 낭비도 없습니다.
Expo Router는 app/ 폴더의 파일 이름이 곧 URL 경로가 되는 파일 기반 라우팅을 제공합니다. app/pair-scan.tsx가 있으면 /pair-scan 화면이 생깁니다. Orca 모바일의 expo-two-way-audio는 Expo 공식 패키지가 아닌 자체 제작 네이티브 모듈로, Expo Module API를 직접 구현하는 방법을 배울 수 있습니다.
Orca 모바일과 데스크탑의 QR 페어링은 NaCl(TweetNaCl) 비대칭 암호화를 직접 구현합니다. TLS/HTTPS를 쓰지 않고 애플리케이션 레이어에서 암호화하는 이유는 자체 서명 인증서나 CA 신뢰 문제를 피하기 위해서입니다. tweetnacl 라이브러리의 박스(box) API 사용법을 소스에서 직접 볼 수 있습니다.
Orca CLI는 에이전트가 직접 호출하도록 설계된 CLI입니다. --json 플래그로 기계 파싱 가능한 JSON 출력, 명확한 동사(create·list·dispatch·check·send), 선택적 매개변수 설계 등이 에이전트-친화적 CLI의 좋은 교과서입니다. skills/orchestration/SKILL.md는 에이전트에게 이 CLI를 어떻게 사용하는지 설명하는 "에이전트를 위한 매뉴얼"입니다.
Orca는 macOS·Windows·Linux를 모두 지원합니다. AGENTS.md와 소스 곳곳에는 플랫폼별 분기가 숨어 있습니다. Windows의 .cmd 배치 스크립트를 실행할 때는 cmd.exe /d /s /c로 감싸야 Node.js가 실행할 수 있습니다. 단축키는 Mac에서는 metaKey(⌘), 다른 플랫폼에서는 ctrlKey로 분기합니다. 실제 크로스플랫폼 앱이 어떻게 이런 분기를 처리하는지 배울 수 있습니다.
| 플랫폼 | 요구사항 | 설치 방법 |
|---|---|---|
| macOS (Apple Silicon) | macOS 12 이상 권장 | brew install --cask stablyai/orca/orca 또는 .dmg 다운로드 |
| macOS (Intel) | macOS 12 이상 권장 | Intel용 .dmg 다운로드 (onorca.dev/download) |
| Windows | Windows 10/11 | orca-windows-setup.exe 실행 |
| Linux | 최신 Ubuntu/Arch 등 | AppImage 실행 또는 yay -S stably-orca-bin (AUR) |
| 플랫폼 | 설치 | 비고 |
|---|---|---|
| iOS | App Store "Orca IDE" 검색 또는 TestFlight | 데스크탑 Orca와 같은 LAN 필요 |
| Android | GitHub Releases에서 APK 다운로드 | Play Store 미등록, 직접 설치 |
1. 데스크탑 Orca → 설정(Settings) → 모바일(Mobile) 탭을 엽니다.
2. 화면에 QR 코드가 나타납니다.
3. 모바일 앱을 열고 QR 스캔을 합니다.
4. 연결이 되면 데스크탑의 모든 워크트리와 에이전트 상태를 폰에서 볼 수 있습니다.
물리적 폰을 쓸 경우, 데스크탑과 폰이 같은 Wi-Fi에 연결되어 있어야 합니다. Android 에뮬레이터는 ws://10.0.2.2:6768을 호스트 주소로 씁니다.
| 도구 | 버전 요구 | 역할 |
|---|---|---|
| Node.js | 24 이상 | JavaScript 런타임 |
| pnpm | 최신 | 패키지 매니저 (npm install -g pnpm) |
| Git | 2.20 이상 권장 | 워크트리 기능 사용 |
| Xcode (macOS/iOS 개발) | 최신 | iOS 시뮬레이터·네이티브 모듈 빌드 |
| Android Studio (Android 개발) | 최신 | Android 에뮬레이터 |
# 1. 저장소 클론
git clone https://github.com/stablyai/orca.git
cd orca
# 2. 개발 환경 초기화 + 의존성 설치
pnpm install
# 3. 데스크탑 앱 개발 모드 실행
pnpm dev
# 4. (별도 터미널) 모바일 앱 개발 모드 실행
cd mobile
pnpm install
pnpm start # Expo QR 코드 출력 → 폰으로 스캔Orca를 설치하고 자신의 아무 GitHub 저장소를 연결한 뒤, "이 함수의 이름을 더 명확하게 바꿔줘"라는 프롬프트를 Claude Code 2개에 동시에 보내세요. 두 에이전트가 제안하는 이름이 다를 것입니다. diff 뷰어에서 두 변경을 비교하고, 더 나은 것을 선택해 병합해 보세요.
목표: Orca의 병렬 워크트리 워크플로우를 직접 체험합니다.
iOS 또는 Android에 Orca 모바일 앱을 설치하고 QR 코드로 데스크탑과 페어링하세요. 에이전트에게 긴 태스크(예: "README.md를 한국어로 번역해줘")를 맡기고, 폰을 잠금 화면으로 두세요. 에이전트가 완료되면 푸시 알림이 오는지 확인하세요.
목표: 비동기 에이전트 모니터링의 실용성을 체험합니다.
Orca 안에서 Claude Code 터미널을 2개 열고, 하나를 코디네이터, 하나를 워커로 삼으세요. 코디네이터 에이전트에게 다음 지시를 내립니다:
워커 에이전트가 작업을 마치고 worker_done 신호를 보내면 코디네이터가 받는 과정을 관찰하세요.
목표: 에이전트 간 구조화된 메시지 패턴을 직접 구현합니다.
AWS·GCP·개인 VPS 등 리눅스 서버가 있다면, Orca의 SSH 워크트리 기능으로 서버에서 에이전트를 실행하고 로컬에서 화면만 보는 설정을 해보세요. 설정: Orca → Add Worktree → Remote (SSH). 서버의 CPU·RAM을 에이전트가 사용하고, 로컬은 UI만 담당하므로 맥북 배터리가 절약됩니다.
목표: 릴레이 데몬 아키텍처와 원격 개발 워크플로우를 체험합니다.
소스를 클론하고 pnpm dev로 개발 모드를 실행하세요. skills/ 폴더에 새 폴더와 SKILL.md 파일을 만들어 자신만의 에이전트 스킬을 정의해 보세요. 예: 특정 코드 스타일 규칙을 에이전트에게 항상 따르게 하는 스킬. 변경 사항이 실시간으로 앱에 반영되는 Hot Module Replacement(HMR)를 경험하세요.
목표: Electron + Vite HMR 개발 루프를 이해하고, 플러그인 시스템 확장을 실습합니다.
| 주차 | 주제 | 학습 자료 / 실습 |
|---|---|---|
| 1~2주차 | Git 심화 — 워크트리·브랜치 전략 | git worktree add/list/remove 직접 실습. Pro Git 책 7장. "feature 브랜치 5개 동시 체크아웃" 시도해보기 |
| 3~4주차 | Node.js PTY·자식 프로세스 | node-pty 공식 문서. child_process.spawn vs exec 차이. 간단한 터미널 에뮬레이터 직접 만들기 |
| 5~6주차 | Electron 아키텍처 | 공식 Electron 튜토리얼 전체. Main·Preload·Renderer 분리 패턴. IPC 보안 컨텍스트 격리 이해 |
| 7~8주차 | React 고급 패턴 + TypeScript | Zustand 상태 관리 패턴. React Virtual(가상화 리스트). Monaco Editor 임베드 방법 |
| 9~10주차 | React Native + Expo | Expo Router 공식 문서. React Native WebView 통신 패턴. 네이티브 Expo 모듈 직접 작성 |
| 11~12주차 | 암호화 기초 — 공개키 암호화 | NaCl/TweetNaCl 공식 문서. 비대칭 키 교환 원리. 간단한 QR 기반 암호화 페어링 프로토타입 만들기 |
| 13~14주차 | CLI 설계 · JSON-RPC 프로토콜 | JSON-RPC 2.0 스펙 읽기. stdio 기반 데몬 구현. Commander.js 또는 yargs로 에이전트-친화적 CLI 설계 |
| 15~16주차 | 멀티에이전트 오케스트레이션 이론 | DAG(방향 비순환 그래프) 기반 태스크 시스템 구현. 코디네이터-워커 패턴 직접 구현. Orca orchestration 스킬 분석 |
| 용어 | 원어 | 한국어 풀이 |
|---|---|---|
| ADE | Agent Development Environment | 에이전트 개발 환경. IDE가 사람을 위한 것처럼, ADE는 AI 에이전트 팀 운용을 위한 환경 |
| 워크트리 | Git Worktree | 하나의 Git 저장소에서 여러 브랜치를 동시에 다른 폴더에 체크아웃하는 기능 |
| 플릿 | Fleet | Orca가 관리하는 여러 에이전트의 집합. '함대'에서 온 말 |
| 릴레이 데몬 | Relay Daemon | Orca가 원격 서버에 배포하는 경량 Node.js 프로세스. SSH 채널로 Electron 앱과 JSON-RPC 통신 |
| PTY | Pseudo-Terminal (의사 터미널) | 소프트웨어로 구현한 가상 터미널. 에이전트 CLI가 진짜 터미널인 것처럼 느끼게 해줌 |
| 오케스트레이션 | Orchestration | 여러 에이전트의 태스크를 배정·추적·완료 신호 수집하는 구조화된 조율 시스템 |
| 코디네이터 | Coordinator | 태스크를 만들고 워커에게 배정하며 완료 신호를 기다리는 중앙 에이전트 |
| 워커 | Worker | 코디네이터에게 태스크를 받아 실제 작업을 수행하고 완료 신호를 보내는 에이전트 |
| DAG | Directed Acyclic Graph (방향 비순환 그래프) | 태스크 의존 관계를 표현하는 자료 구조. A가 끝나야 B가 시작하는 식의 순서 표현에 사용 |
| IPC | Inter-Process Communication | 프로세스 간 통신. Electron에서 Main과 Renderer가 메시지를 주고받는 방법 |
| HMR | Hot Module Replacement | 코드를 저장하면 앱을 재시작하지 않고 변경 부분만 즉시 반영하는 개발 기능 |
| TweetNaCl | TweetNaCl (암호화 라이브러리) | 100줄 남짓의 작은 코드로 구현된 공개키 암호화 라이브러리. 안전한 통신 채널 수립에 사용 |
| worker_done | worker_done (Orca 메시지 타입) | 워커 에이전트가 태스크를 완료했을 때 코디네이터에게 보내는 구조화된 완료 신호 |
| 스킬(Skill) | Skill (Orca/Claude Code 개념) | 에이전트가 특정 작업을 수행하는 방법을 담은 마크다운 가이드. SKILL.md 파일 형식 |
| 플러그인 오버레이 | Plugin Overlay | Orca가 특정 에이전트 CLI(OpenCode·Pi 등)에 자신의 스킬이나 환경 변수를 주입하는 메커니즘 |