Orca 입문 가이드 — 여러 AI 에이전트를 동시에 돌리기

Windows 11 기준입니다. AI CLI(Claude Code 등)를 이미 써 본 사람을 위한 다음 단계 안내서입니다.
아직 AI CLI를 써 본 적이 없다면 터미널 AI 에이전트 입문 가이드 를 먼저 보세요.
예상 소요 시간: 설치 10분 + 첫 병렬 세션 20분

이 문서를 읽는 방법

• 1부~5부만 읽으면 쓸 수 있습니다. 순서대로 따라 하세요.
• 부록은 필요할 때만 펼치세요. Mac·Linux 설치, 작업공간(worktree)의 내부 동작, 스크립트 자동화, 원격 실행이 들어 있습니다.
• 회색 상자 안의 글자는 컴퓨터에 입력하는 명령어입니다.

1부. Orca란 무엇인가

1.1 정의

Orca는 여러 AI 코딩 에이전트를 동시에 돌리기 위한 프로그램입니다.

Claude Code나 Codex CLI를 대체하는 것이 아닙니다. 그것들을 여러 개 띄워서 한 화면에서 관리해 주는 껍데기입니다. 자동차를 바꾸는 게 아니라 주차장을 마련하는 것에 가깝습니다.

만든 곳은 Stably AI이고, 스스로를 ADE(Agent Development Environment, 에이전트 개발 환경) 라고 부릅니다.

1.2 무엇이 달라지는가

지금까지의 방식은 이렇습니다.

터미널 하나 → claude 실행 → 지시 → 기다림 → 결과 확인 → 다음 지시

한 번에 한 가지 일만 됩니다. 에이전트가 5분간 작업하는 동안 사람은 기다립니다. 터미널을 두 개 열어 같은 폴더에서 두 에이전트를 돌리면 서로 같은 파일을 고쳐서 뒤엉킵니다.

Orca의 방식은 이렇습니다.

작업공간 A → 폴더 사본 A → Claude Code    ┐
작업공간 B → 폴더 사본 B → Codex          ├─ 한 화면에서 동시에
작업공간 C → 폴더 사본 C → Antigravity    ┘

핵심은 하나입니다 — 작업공간마다 폴더 사본을 따로 만들어 준다. 사본이 다르니 서로 건드릴 파일이 없고, 따라서 충돌하지 않습니다. 이 사본을 만드는 데 Git의 worktree 기능을 씁니다(자세한 동작은 부록 B).

1.3 기본 정보

들어 있는 기능

• 작업공간(Workspace) 탭 — 작업공간 하나 = 폴더 사본 하나
• 에이전트 터미널 — 화면을 원하는 대로 분할
• 변경 내용 비교(diff) 화면 — 바뀐 부분에 직접 코멘트를 달아 에이전트에게 되돌려 줌
• 내장 브라우저 — 화면 요소를 집어서 "이걸 고쳐" 라고 지시
• GitHub · Linear · Jira 연동
• 모바일 앱(iOS/Android) — 밖에서 진행 상황 확인
• orca 명령어 — 셸에서 스크립트로 조종 (부록 C)

1.4 이름 혼동 주의

GitHub에 orca라는 이름의 AI 에이전트 도구가 최소 셋 있습니다.

검색할 때는 orca stablyai 또는 onorca.dev 를 함께 넣으세요. 그러지 않으면 다른 프로젝트의 설치법이 섞여 나옵니다.

2부. 설치 — Windows

2.1 먼저 준비할 것

Orca는 에이전트를 대신 설치해 주지 않습니다. 쓰려는 AI CLI가 먼저 설치되고 로그인까지 되어 있어야 합니다.

Node.js는 Orca 자체에 필요하지 않습니다.

왜 미리 로그인해 두어야 하나요?
Orca는 각 CLI가 이미 저장해 둔 로그인 정보를 그대로 가져다 씁니다. Orca에 API 키를 따로 입력하지 않습니다. 로그인이 안 된 CLI는 Orca에서 띄워도 로그인 화면만 나옵니다.

2.2 공식 홈페이지에서 내려받기

1. 웹브라우저로 https://www.onorca.dev 에 접속합니다.
2. Download 버튼을 누릅니다.
3. Windows 용 설치 파일(orca-windows-setup.exe)을 내려받습니다.
4. 내려받은 파일을 더블클릭합니다.
5. 설치 창이 뜨면 기본값 그대로 계속 진행합니다.

Windows가 "알 수 없는 발행자" 경고를 띄울 수 있습니다. 추가 정보 → 실행 을 누르면 진행됩니다. 반드시 onorca.dev 또는 공식 GitHub Releases 에서 받은 파일인지 확인하세요.

Mac이나 Linux를 쓰거나, 터미널 명령어로 설치하고 싶다면 부록 A 를 보세요.

2.3 첫 실행

설치가 끝나고 Orca를 처음 열면 순서대로 이런 것들을 묻습니다.

1. 홈 디렉터리 접근 권한 — 프로젝트로 쓸 폴더를 찾기 위한 것입니다. 허용합니다.
2. 기존 설정을 가져올지 — ~/.claude, ~/.codex, 터미널 설정을 가져오겠다고 묻습니다. 가져오세요. 로그인 정보와 설정이 그대로 넘어와서 추가 작업이 없어집니다.
3. 빈 화면 — 프로젝트를 추가하기 전이라 아무것도 없습니다. 정상입니다.

터미널(셸) 확인

Windows에서는 Settings → Terminal 에서 기본 셸을 PowerShell 또는 CMD 중 고를 수 있습니다. 특별한 이유가 없으면 PowerShell 로 둡니다.

2.4 업데이트

기본적으로 자동 업데이트됩니다. 안정 버전 채널로 알아서 올라갑니다.

즉시 확인하려면 앱 메뉴의 "Check for Updates" 를 누릅니다. 릴리스 주기가 대단히 빠릅니다(사실상 매일). 화면 구성이 이 문서와 조금 달라져 있을 수 있으니, 이름이 아니라 위치와 역할로 찾으세요.

3부. AI CLI 연결하기

3.1 원리

Orca는 이미 설치·로그인된 CLI를 감지해서 실행해 줄 뿐입니다.

Settings → Agents 를 열면 감지된 CLI 목록이 나옵니다. 여기서 켜고 끄고, 기본 에이전트를 지정합니다. 40종 이상이 미리 설정되어 있습니다.

3.2 도구마다 통합 수준이 다릅니다

같은 "지원"이라도 얻는 것이 다릅니다.

3.3 Claude Code

추가 설정이 없습니다. Claude Code를 설치하고 한 번 로그인해 두면 Orca가 ~/.claude 를 자동으로 읽습니다.

얻는 것:

• 상태바에 사용량과 한도 근접도 표시 — 병렬로 돌릴 때 이게 중요합니다
• 계정 여러 개 원클릭 전환 — 전환 중 인증 갱신이 겹치지 않게 막아 줍니다
• 프로젝트별 훅·메모리 파일 지원
• 작업 디렉터리가 해당 작업공간 폴더로 맞춰진 채 실행됨

Claude Agent Teams(에이전트가 하위 에이전트를 부리는 기능)는 기본 꺼져 있습니다. 켜면 하위 에이전트들이 작업공간 목록의 하위 항목으로 펼쳐져 보입니다. 처음에는 꺼 두세요. 무엇이 무엇을 하는지 알기 어려워집니다.

3.4 Codex CLI

~/.codex 를 가져옵니다. 원클릭 실행은 되지만 사용량 표시는 없습니다. ChatGPT 구독 한도를 얼마나 썼는지는 Orca 밖에서 확인해야 합니다.

3.5 Antigravity CLI (agy)

agy 를 먼저 설치·로그인해 두면(입문 가이드 4.4절) Orca가 감지합니다. 사용량 표시까지 되는 깊은 통합 수준입니다.

문서와 실제가 어긋나는 지점
Orca 공식 문서의 지원 목록에는 아직 낡은 이름인 "Gemini"만 적혀 있습니다. 그러나 저장소 코드에는 Antigravity 전용 사용량 미러링, 훅 주입, 세션 기록 파서가 별도로 들어 있습니다. 문서 쪽 표기가 갱신되지 않은 것으로 판단됩니다.
설치 후 Settings → Agents 목록에서 직접 확인해 보시는 게 확실합니다.

3.6 반드시 바꿀 설정 — 권한 우회 기본값

Orca는 에이전트를 띄울 때 권한 확인을 건너뛰는 옵션을 기본으로 붙입니다. Claude Code의 경우 --dangerously-skip-permissions 입니다.

Settings → Agents → Agent Permissions 에서 두 가지 중 고릅니다.

설계 의도는 분명합니다. 작업 폴더는 버리는 사본이므로 잘못돼도 통째로 지우면 됩니다.

그러나 이 전제는 "Git 저장소 안에서만 작업한다"에 의존합니다. 원본 데이터가 든 폴더를 대상으로 삼으면 전제가 깨집니다. 지워도 복구되는 것은 Git이 추적하는 파일뿐입니다. 어떤 폴더를 대상으로 삼을지는 4.1절에 정리해 두었습니다.

처음에는 Manual 로 바꿔 두세요. 무엇을 하려는지 눈으로 익힌 다음에 Yolo 로 옮기면 됩니다. 순서를 거꾸로 하면 배울 기회 없이 사고가 납니다.

4부. 프로젝트 만들고 병렬로 쓰기

여기가 실제 사용법입니다. 어려운 개념은 나오지 않습니다.

4.0 용어 두 개만 맞춰 둡시다

Orca 화면에서 쓰는 말과, Orca 공식 문서에서 쓰는 말이 다릅니다. 이 문서는 화면에 나오는 말을 기준으로 씁니다.

공식 문서는 아직 Add Repo, worktree 같은 옛 표기를 쓰고 있어서, 문서를 보고 화면에서 그 이름을 찾으면 없습니다. 화면 쪽이 최신입니다.

4.1 프로젝트 추가하기 — 폴더 지정

왼쪽 사이드바 위쪽에 Projects 라는 제목이 있고, 그 오른쪽에 작은 아이콘이 몇 개 있습니다.

1. 폴더에 + 가 붙은 아이콘을 누릅니다. 마우스를 올리면 Add Project 라는 설명이 뜹니다.
2. 작업할 폴더를 고릅니다.
3. 끝입니다. Orca가 그 폴더의 Git 상태를 읽고 기본 브랜치를 기준점으로 잡습니다.

아이콘이 두 개 나란히 있습니다. 헷갈리지 마세요.

아이콘	설명(마우스 올렸을 때)	하는 일
폴더 + +	Add Project	프로젝트(폴더) 추가 ← 지금 누를 것
그냥 +	New workspace	새 작업공간 만들기 (4.2절에서 씁니다)

폴더는 Git 저장소여야 합니다. Orca의 작동 방식이 Git 기능에 기대고 있기 때문입니다. 아직 저장소가 아니라면 그 폴더에서 터미널을 열고 git init 을 한 번 실행하면 됩니다.

기준점을 다른 브랜치로 바꾸려면 프로젝트 설정에서 조정합니다.

클라우드 동기화 폴더(Google 드라이브 등)에 대해

되기는 됩니다. 다만 권하지 않습니다.

Google 드라이브, OneDrive, Dropbox 안의 폴더도 프로젝트로 추가할 수 있고 대부분 정상 동작합니다. 안 되는 것이 아닙니다. 그러나 다음 두 가지가 실제로 문제를 일으킵니다.

1. 저장소 손상 위험 — Git은 .git 폴더 안의 파일 수백 개를 빠르게 읽고 씁니다. 동기화 프로그램이 그 중간 상태를 붙잡아 올리거나 다른 기기의 버전으로 덮어쓰면 저장소가 깨집니다. 여러 기기에서 같은 폴더를 동기화할 때 위험이 커집니다.
2. 속도 — 작업공간을 만들 때마다 폴더 사본이 하나 생기고, 동기화 프로그램이 그것을 전부 업로드하려 듭니다. 병렬로 여러 개를 만들면 체감이 큽니다.

그래서 이렇게 하세요.

요약: 동기화 폴더가 금지는 아니지만, 로컬 경로 + 원격 저장소 조합이 더 안전하고 빠릅니다.

4.2 작업공간 하나 만들어 에이전트 띄우기

1. + 를 누릅니다. 두 곳 중 어디서 눌러도 됩니다.
   - 사이드바에 추가된 프로젝트 이름 위에 마우스를 올리면 오른쪽에 + 가 나타납니다. 설명은 Create workspace for <프로젝트명> 입니다. 프로젝트가 여러 개일 때는 이쪽이 확실합니다.
   - 또는 사이드바 맨 위 Projects 제목 오른쪽의 그냥 + (설명: New workspace). 단축키도 이 설명에 함께 표시됩니다.
2. 작업 이름을 입력합니다. (비워 두면 자동으로 생성됩니다.)
3. 시작 기준점을 고릅니다. 보통 기본 브랜치 그대로 둡니다.
4. 실행 화면이 뜨고 기본 에이전트가 미리 선택되어 있습니다. 터미널의 드롭다운에서 원하는 에이전트를 고릅니다 — Claude Code, Codex, Antigravity CLI 등.
5. 에이전트가 실행됩니다. 평소처럼 한국어로 지시하면 됩니다.

이 시점에 Orca가 배경에서 그 작업공간 전용 폴더 사본을 만들어 둡니다. 사용자가 직접 폴더를 만들거나 관리할 필요는 없습니다.

4.3 두 번째·세 번째 작업공간 추가하기 = 이게 병렬입니다

4.2를 반복하면 끝입니다.

+ 를 다시 눌러 두 번째 작업을 만들고 에이전트를 띄웁니다. 세 번째도 같습니다. 각 작업은 폴더 사본이 다르므로 서로 아무 영향을 주지 않습니다.

첫 에이전트가 일하는 동안 두 번째, 세 번째에게도 지시를 넣을 수 있습니다. 기다리는 시간이 사라집니다.

4.4 화면 분할해서 동시에 보기

작업공간 탭을 화면 오른쪽 가장자리나 아래쪽 가장자리로 끌어다 놓습니다. 화면이 분할되어 여러 작업공간을 나란히 볼 수 있습니다.

세 개를 동시에 관찰하려면 오른쪽으로 한 번, 아래로 한 번 끌어 3분할을 만듭니다.

4.5 결과 검토하고 반영하기

1. 각 작업공간의 변경 내용 비교(diff) 화면을 엽니다.
2. 고칠 부분이 있으면 Annotate AI Diff 로 그 줄에 코멘트를 답니다. 에이전트가 그걸 읽고 수정합니다.
3. 만족하면 Orca 안에서 바로 커밋하고 푸시합니다.

4.6 정리하기

쓸모없어진 작업공간은 원클릭으로 삭제합니다. 폴더 사본과 브랜치가 함께 지워집니다.

아직 반영하지 않은 변경이 남아 있으면 Orca가 먼저 검토 화면을 띄웁니다. 강제로 지워도 문제되는 브랜치는 남겨 둡니다.

4.7 두 가지 사용 패턴

패턴 A — 경쟁: 같은 일을 여러 에이전트에게

작업공간 세 개를 만들고 같은 지시를 세 에이전트에게 각각 넣습니다. 공식 문서의 논리는 이렇습니다.

에이전트마다 다른 실수를 한다. 같은 과제를 병렬로 돌리는 것이 순차 재시도보다 싸고, 의견이 갈리는 것 자체가 신호가 된다.

셋이 같은 답을 내면 맞을 가능성이 높고, 갈리면 사람이 판단해야 하는 지점이라는 뜻입니다. 분석 스크립트 검증에 쓸 만합니다 — 같은 처리를 셋에게 각각 짜게 해서 결과가 어긋나는 곳을 찾는 방식.

패턴 B — 분업: 서로 다른 일을 동시에

작업공간마다 다른 과제를 배정합니다. 파일이 격리돼 있어 충돌하지 않습니다. 이쪽이 실제 처리량을 늘리는 용법입니다.

4.8 처음에 한 번은 해둘 것 — 의존성 공유

새 작업공간 폴더는 깨끗한 사본입니다. 그래서 node_modules, .venv, .env 처럼 Git이 추적하지 않는 것들이 빠져 있습니다. 매번 다시 설치하면 병렬의 이점이 사라집니다.

해결: 저장소 설정의 Worktree Shared Paths 에 공유할 경로를 지정합니다. 한 번 해두면 이후 모든 작업공간 폴더가 그것을 공유합니다.

설정 파일로 관리하는 방법(orca.yaml, .worktreeinclude)은 부록 B 에 있습니다.

5부. 실행 위치 — 로컬 데스크톱

기본값이고, 대부분의 경우 이대로 쓰면 됩니다.

에이전트, 터미널, 브라우저가 전부 내 PC에서 돕니다. 별도 설정이 필요 없습니다. 2부대로 설치하면 이 상태입니다.

적합한 경우: 사양이 되는 장비에서 빠르게 반복 작업할 때. 즉 평소 작업 전부.

유의점: 작업공간을 여러 개 띄우면 메모리를 상당히 씁니다. Electron 기반 앱이고 각 작업공간이 폴더 사본과 터미널을 따로 갖기 때문입니다. 처음에는 두세 개로 시작해서 장비가 버티는 선을 확인하세요.

원격 서버에서 돌리거나, 밖에서 휴대폰으로 확인하거나, 작업마다 일회용 클라우드 장비를 쓰는 방식은 부록 D 에 있습니다. 필요해질 때 보면 됩니다.

6부. 주의사항

① 한도도 병렬로 소모됩니다

에이전트 세 개를 동시에 돌리면 구독 사용량도 세 배로 빠집니다. Claude Code는 상태바에 한도 근접도가 표시되므로 이걸 보면서 조절하세요.

② 권한 우회 기본값

3.6절을 다시 확인하세요. Manual 로 시작하는 것을 권합니다.

③ Git 저장소 안에서만 쓰세요

Orca의 안전장치는 "폴더 사본이므로 지우면 된다"는 데 있습니다. 이 전제는 Git 저장소에서만 성립합니다. 원본 데이터·문서가 든 폴더를 대상으로 삼으면 안전장치 없이 권한 우회만 켜진 상태가 됩니다.

④ 아직 어린 프로젝트입니다

저장소가 2026년 3월에 개설되었고 사실상 매일 릴리스됩니다. 공식 문서와 실제 동작이 어긋난 곳이 이미 있습니다(3.5절의 Antigravity 표기). 화면이 이 문서와 다르면 문서가 낡은 것이라고 보시면 대체로 맞습니다.

⑤ 언제 쓰지 말아야 하는가

부록 A. Mac · Linux 설치, 터미널로 설치

Windows — 터미널로 설치

winget install --id StablyAI.Orca

macOS

Homebrew:

brew install --cask stablyai/orca/orca

업데이트:

brew upgrade --cask orca

직접 내려받으려면 Apple Silicon은 orca-macos-arm64.dmg, Intel은 orca-macos-x64.dmg. 서명·공증된 빌드이지만 macOS가 첫 실행 시 확인을 요청할 수 있습니다.

Linux

Releases에서 형식을 골라 받습니다.

Linux 주의: 셸에서는 orca-ide 를 쓰세요. 맨 orca 는 스크린 리더 프로그램을 호출할 수 있습니다.

이전 버전 · 시험판

GitHub Releases 에 전부 있습니다. 시험판(RC)을 받으려면 "Check for Updates" 를 누를 때 보조키를 함께 누릅니다.

부록 B. 작업공간(worktree)의 실제 동작

4부에서 "폴더 사본"이라고 부른 것의 정체는 Git의 worktree 입니다. Orca 화면에서는 이것을 Workspace(작업공간) 라고 부르고, 공식 문서에서는 아직 worktree 라고 씁니다.

저장 위치와 성질

• 진짜 git worktree 입니다. Orca가 관리하는 디렉터리에 별도 체크아웃이 생깁니다
• 터미널에서 그 경로로 cd 해서 평소처럼 git 명령을 쓸 수 있습니다. Orca 전용 형식이 아닙니다
• 각 작업공간이 별도의 파일 공간, 별도 브랜치, 별도 터미널 세션을 가집니다. 이것이 병렬 실행이 안전한 이유입니다

기준점과 브랜치 이름

• 기준점(base ref)은 보통 origin/main 입니다
• 로컬 브랜치, 특정 커밋 SHA, 원격 브랜치에서도 분기할 수 있습니다
• 브랜치 이름은 작업공간 이름에서 자동 생성됩니다. GitHub PR, Linear/Jira 이슈, GitLab MR을 연결하면 그쪽 정보에서 따옵니다
• 직접 지정하려면 Create Worktree 대화상자의 Advanced 를 엽니다

의존성 공유 — 세 가지 방법

새 worktree는 깨끗한 체크아웃이라 Git이 추적하지 않는 것들이 없습니다.

macOS는 가능하면 APFS 클론 복사를 쓰고, 아니면 심링크를 만듭니다. Windows·Linux는 심링크 방식입니다.

삭제

• 삭제하면 디렉터리와 브랜치가 함께 지워집니다
• 머지되지 않은 커밋이 있으면 Orca가 검토 단계를 먼저 띄웁니다
• 강제 삭제해도 문제되는 브랜치는 보존해 검사할 수 있게 남깁니다

개수 상한

공식 문서에 명시된 상한은 없습니다. 실질적인 제약은 장비의 메모리와 구독 한도입니다.

부록 C. orca 명령어로 병렬 실행 자동화

앱을 손으로 조작하는 대신 셸에서 스크립트로 돌릴 수 있습니다. 반복되는 병렬 작업을 무인화할 때 씁니다.

등록과 확인

orca CLI는 앱에 함께 설치되지만 Settings → General → Orca CLI 에서 등록해야 활성화됩니다.

orca status --json

orca worktree current --json

주요 명령

create → send → wait → read 를 엮으면 병렬 실행 전체를 스크립트로 돌릴 수 있습니다.

주의점

• 터미널 핸들은 앱 실행 단위입니다. Orca를 재시작하면 terminal list 로 다시 얻어야 합니다
• terminal wait --for tui-idle 에는 반드시 --timeout-ms 를 주세요. 없으면 무한정 매달릴 수 있습니다
• 여러 에이전트를 구조적으로 조율할 때는 맨 terminal send 가 아니라 Orca의 orchestration 기능을 쓰라고 문서가 권합니다
• 실행 파일 이름이 환경에 따라 다릅니다. ORCA_CLI_COMMAND 환경변수가 설정돼 있으면 그 값, 개발 체크아웃에서는 orca-dev, Linux의 Orca 밖 터미널에서는 orca-ide, 그 외에는 orca

MCP 연동

Orca는 MCP 서버를 제공합니다. 에이전트가 Orca를 조종하게 하거나, 반대로 Orca가 에이전트를 조종하게 할 수 있습니다. Settings → Integrations 에서 설정합니다.

부록 D. 로컬 외의 실행 방식

로컬 데스크톱(5부) 외에 세 가지가 더 있습니다. 한 설치에서 섞어 쓸 수 있습니다.

설정 위치:

• SSH — Settings → SSH (점프 호스트, Kerberos 인증 지원)
• 원격 서버 — Settings → Remote Orca Servers (다른 장비와 짝짓거나, 이 장비를 서버로 공개)
• 클라우드 VM — Settings → Experimental

클라우드 VM의 비용은 본인 부담입니다. Orca가 사용자의 생성/파기 스크립트를 실행할 뿐이고, 클라우드 제공자와 요금은 사용자가 직접 관리합니다.

부록 E. 이 문서의 한계와 출처

확인하지 못한 사항

• 실제 UI에서 agy 가 에이전트 드롭다운에 어떤 이름으로 표시되는지 (코드 근거로는 지원, 문서 표기는 "Gemini")
• 4.1~4.2절의 버튼 이름(Add Project, New workspace, Create workspace for ...)은 저장소 소스(src/renderer/src/components/sidebar/)에서 확인한 것입니다. 공식 문서는 아직 Add Repo 로 적고 있습니다
• 동시 작업공간 개수의 실용적 상한 (장비별로 다르며 공식 수치가 없음)
• Windows에서 의존성 공유가 심링크로 동작할 때의 실제 성능
• 시스템 최소 요구사양 (공식 문서에 명시되어 있지 않음)

출처

• stablyai/orca (GitHub) — 저장소, 라이선스, 릴리스, 코드 확인
• Orca 공식 홈페이지
• Orca Docs / Install / First 3-agent session
• Worktrees / Supported agents / Claude Code in Orca
• Recipe: parallel agents / Orca CLI overview / Ways to run / Settings
• orca-cli skill guide

2026년 9월 2일 기준으로 확인한 내용입니다. Orca는 릴리스 주기가 대단히 빠릅니다. 화면 구성이 다르면 이 문서가 낡은 것입니다.