Orca 핵심 정리

# 개요

Orca는 MIT 라이선스로 공개된 무료 오픈소스 앱이며, 자체 AI 모델을 제공하지 않습니다.
내 컴퓨터에 설치된 Claude Code, Codex 같은 CLI 에이전트를 Orca 안의 터미널에서 실행하는 방식이라서, 사용량도 각 도구의 구독에서 차감됩니다.
Orca가 더하는 것은 그 터미널들을 작업 단위로 묶고, 상태를 표시하고, 결과를 검토하는 화면입니다.

Orca의 화면을 이해하는 데 필요한 개념은 세 가지입니다.

• 프로젝트: Orca에 등록한 폴더입니다. 보통 Git 저장소 하나가 프로젝트 하나입니다.
• 워크스페이스(Workspace): 작업 하나를 진행하는 공간입니다. 프로젝트에서 갈라져 나온 별도의 폴더와 브랜치를 가집니다.
• 탭: 워크스페이스 안에서 여는 에이전트 터미널, 브라우저, diff 화면입니다.

프로젝트에서 작업마다 갈라져 나온 워크스페이스

워크스페이스의 폴더는 Git 워크트리(Worktree)로 만들어집니다.
워크트리는 저장소 하나를 여러 폴더에 동시에 체크아웃하는 Git 기능이며, 폴더마다 다른 브랜치를 사용합니다.
그래서 두 에이전트가 동시에 파일을 고쳐도 변경 사항이 섞이지 않고, 마음에 드는 결과만 골라서 반영할 수 있습니다.
워크트리는 Orca 화면에서 만들고 지우므로 git worktree 명령을 직접 입력할 일은 없습니다.

# 설치와 첫 실행

운영체제에 맞는 설치 파일을 공식 사이트나 GitHub Releases에서 다운로드해서 설치합니다.

1
brew install --cask stablyai/orca/orca

# 에이전트 준비

Orca는 에이전트 CLI를 설치하거나 로그인해 주지 않습니다.
이미 설치된 CLI를 찾아서 목록에 표시하고, 선택하면 그 CLI를 터미널에서 실행할 뿐입니다.
그래서 준비할 것은 상황에 따라 다음과 같습니다.

• 터미널에서 claude나 codex를 이미 사용하고 있다면 따로 연결할 것이 없습니다. Orca가 설치된 CLI를 감지하고, 로그인 정보도 각 CLI가 저장해 둔 것(~/.claude, ~/.codex)을 그대로 사용합니다.
• 아직 설치하지 않았다면 Orca를 사용하기 전에 CLI를 설치하고 터미널에서 한 번 실행해서 로그인합니다.

1
2
3
4
5
curl -fsSL https://claude.ai/install.sh | bash
claude

npm install -g @openai/codex
codex

감지 결과는 설정의 에이전트 항목에서 확인합니다.

설정의 에이전트 항목에 표시된 설치됨과 설치 가능 목록

설치됨에는 감지된 에이전트와 Orca가 실행할 명령이, 설치 가능에는 Orca가 지원하지만 아직 설치되지 않은 에이전트가 표시됩니다.
각 행의 링크 아이콘을 누르면 그 에이전트의 설치 문서가 열리고, 설치를 마친 다음 새로고침을 누르면 설치됨으로 옮겨집니다.
실행 명령에 붙은 --dangerously-skip-permissions 같은 플래그는 아래의 Yolo 모드 때문입니다.

# 첫 실행

Orca를 처음 실행하면 세 단계의 안내 화면이 나타납니다.

첫 실행 안내의 기본 agent 선택 단계

1. 기본 agent: 시스템에서 감지됨에 표시된 에이전트 중에서 새 작업을 만들 때 기본으로 실행할 것을 고릅니다.
2. 테마: 다크, 라이트, 시스템 설정 중에서 고릅니다.
3. 알림: 에이전트가 작업을 마치거나 답을 기다릴 때 받을 시스템 알림과 소리를 정합니다.

마지막 단계에서 첫 프로젝트 추가를 누르면 바로 작업할 폴더를 등록하는 창이 열립니다.

첫 단계의 Yolo 모드는 기본으로 켜져 있습니다.
켜져 있으면 에이전트가 명령 실행이나 파일 수정을 사용자에게 묻지 않고 진행하므로, 승인을 기다리느라 작업이 멈추지 않습니다.

# Orca 스킬

안내 화면을 마치면 사이드바에 온보딩 체크리스트가 남습니다.
그중 에이전트에 Orca 스킬 제공 단계는 Orca가 자동으로 처리하지 않습니다.

온보딩 체크리스트의 Orca 스킬 설치 단계

스킬은 에이전트가 Orca를 다루는 방법을 담은 안내 파일이며, Orca를 설치해도 자동으로 설치되지 않습니다.
워크스페이스를 만들고 에이전트에게 작업을 맡기는 기본 사용에는 스킬이 필요하지 않고, 이 글에서 다루는 기능 중 스킬이 꼭 필요한 것은 뒤에서 다룰 오케스트레이션입니다.
설치하려면 스킬 설치를 누르고, 체크리스트 안의 터미널에 입력된 명령을 Enter로 실행한 다음 스킬을 넣을 에이전트를 고릅니다.
오케스트레이션만 쓸 계획이라면 일을 나눠 줄 에이전트(예: Claude Code) 하나만 골라도 됩니다.

설치 직후의 상태를 정리하면 다음과 같습니다.

# 화면 구성

작업을 몇 개 진행하고 있는 Orca의 화면은 다음과 같습니다.

Orca 화면의 다섯 영역

1. 왼쪽 사이드바: 프로젝트와 그 아래의 워크스페이스 목록입니다. 위쪽에는 검색, 작업(GitHub, Linear 같은 이슈 목록), 자동화가 있고, 아래쪽에는 설정과 워크스페이스 보드 버튼이 있습니다.
2. 작업 영역: 선택한 워크스페이스의 탭입니다. 위 화면에서는 Claude Code 터미널과 개발 서버 터미널이 탭으로 열려 있습니다.
3. 분할한 패인(Pane): 탭을 나란히 배치한 영역입니다. 위 화면에서는 내장 브라우저로 개발 서버의 화면을 열어 두었습니다.
4. 오른쪽 사이드바: 탐색기, 에이전트(세션 기록), 소스 제어, 체크(GitHub의 검사 결과) 네 개의 탭을 전환합니다. 위 화면은 변경된 파일을 보여 주는 소스 제어 탭입니다.
5. 상태 표시줄: 에이전트별 사용량과 한도 초기화 시각, 컴퓨터 절전 방지, 실행 중인 터미널 수, 감지된 개발 서버 포트가 표시됩니다.

탭 표시줄의 +를 누르면 새 탭의 종류를 고르는 메뉴가 열립니다.

탭 표시줄의 새 탭 메뉴

터미널, 브라우저, 마크다운 문서가 위쪽에 있고, 그 아래에 감지된 에이전트가 나열됩니다.
에이전트를 고르면 새 탭에서 그 CLI가 실행되므로, 한 워크스페이스에서 Claude Code와 Codex를 함께 열어 둘 수도 있습니다.

탭을 패인의 가장자리로 끌어다 놓거나, 탭을 마우스 오른쪽 버튼으로 클릭한 다음 탭을 분할로 이동에서 방향을 고르면 화면이 나뉩니다.
배치는 워크스페이스별로 기억되기 때문에, 다른 작업으로 전환했다가 돌아와도 보던 탭과 화면이 그대로 남아 있습니다.

자주 사용하는 단축키는 다음과 같습니다.

# 작업 시작

# 프로젝트 추가

사이드바의 프로젝트 옆에 있는 폴더 아이콘(프로젝트 추가)을 누르면 프로젝트를 추가하는 창이 열립니다.
폴더 찾아보기로 내 컴퓨터의 폴더를 고르거나, URL에서 복제로 원격 저장소를 복제하거나, 새 프로젝트 만들기로 빈 폴더에서 시작합니다.

Git 저장소를 추가하면 기본 브랜치가 기준이 되고, 이후 만드는 워크스페이스는 이 브랜치에서 갈라져 나옵니다.
Git 저장소가 아닌 폴더(예: 문서를 모아 둔 폴더)는 폴더 그대로 열리며, 터미널과 에이전트, 파일 확인은 그대로 사용하고 워크트리, diff, 커밋 같은 Git 기반 기능만 빠집니다.
나중에 그 폴더에서 git init으로 저장소를 만들고 첫 커밋을 하면 모든 기능을 사용할 수 있습니다.

# 워크스페이스 만들기

사이드바의 + 아이콘(새로운 워크스페이스)을 누르거나 Cmd+N을 입력하면 워크스페이스를 만드는 창(작업 트리 만들기)이 열립니다.

작업 트리 만들기 창

• 프로젝트: 워크스페이스를 만들 프로젝트를 고릅니다.
• 실행 위치: 이 컴퓨터(Local Mac)에서 실행할지, 연결해 둔 원격 장비에서 실행할지 고릅니다.
• 다음에서 만들기: 워크스페이스 이름을 입력합니다. 오른쪽의 main은 갈라져 나올 기준 브랜치입니다.
• 에이전트: 첫 탭에서 실행할 에이전트입니다. 안내 화면에서 고른 기본 에이전트가 미리 선택되어 있고, 빈 터미널로 시작할 수도 있습니다.
• 더 만들기: 켜 두면 만든 뒤에도 창이 닫히지 않아서, 같은 설정으로 연달아 만들 수 있습니다.

작업 트리 만들기를 누르면 사이드바에 워크스페이스가 추가되고, ~/orca/workspaces/프로젝트/이름 폴더에서 에이전트가 실행됩니다.
에이전트의 입력창에 프롬프트를 입력하면 작업이 시작됩니다.

브랜치 이름에는 기본으로 Git 사용자 이름이 접두사로 붙어서 이름/add-dark-mode 형태가 됩니다.
접두사는 설정의 Git 및 소스 제어에 있는 브랜치 접두사에서 바꾸거나 없앨 수 있습니다.

새 워크스페이스는 깨끗한 체크아웃이라서 node_modules 같은 설치 파일이 없습니다.
저장소에 pnpm-lock.yaml 같은 잠금 파일이 있으면, 처음 워크스페이스를 만들 때 설치 명령을 설정 스크립트로 저장할지 묻는 카드가 나타납니다.

감지된 설치 명령을 저장하는 카드

저장을 누르면 이후 만드는 워크스페이스마다 이 명령이 자동으로 실행됩니다.

# 진행 상황 확인

워크스페이스는 사이드바에 카드로 표시됩니다.

사이드바의 워크스페이스 카드

카드에는 워크스페이스 이름과 브랜치, 그 아래에 실행 중인 에이전트 행이 표시됩니다.
에이전트 행의 제목은 첫 프롬프트에서 자동으로 만들어지고, 앞쪽의 아이콘이 에이전트의 현재 상태를 나타냅니다.

위 화면에서 fix-cart-total은 질문에 대한 답을 기다리는 중이고, add-dark-mode와 add-category-filter는 작업을 마쳤으며, product-search는 작업 중입니다.
여러 작업을 동시에 진행할 때는 주황색 물음표와 종 표시가 붙은 것부터 확인하고, 작업 중인 것은 그대로 두면 됩니다.

에이전트가 작업을 마치거나 답을 기다리기 시작하면 시스템 알림과 소리로 알려 주고, macOS에서는 Dock 아이콘에 확인하지 않은 개수가 표시됩니다.
알림의 종류와 소리는 설정의 알림 항목에서 바꿉니다.

작업이 많아져서 사이드바만으로 파악하기 어렵다면 사이드바 아래쪽의 보드 아이콘을 눌러 워크스페이스 보드를 엽니다.

워크스페이스 보드

모든 워크스페이스를 Todo, In progress, In review, Done 칸으로 나누어 보여 주며, 카드를 다른 칸으로 끌어다 놓으면 상태가 바뀝니다.
칸은 직접 정하는 진행 단계이고, 카드 안의 아이콘은 앞에서 본 에이전트 상태입니다.

Orca 창을 닫거나 앱을 종료해도 에이전트는 멈추지 않습니다.
터미널은 백그라운드 프로세스에서 계속 실행되고, 앱을 다시 열면 실행 중인 에이전트와 그동안의 출력이 그대로 다시 연결됩니다.
컴퓨터를 재시작해서 에이전트까지 종료된 경우에는 워크스페이스와 탭 배치가 복원되고, 중단된 Claude Code와 Codex 세션은 이전 대화로 이어서 실행할 수 있습니다.

# 결과 검토와 반영

# 브라우저와 디자인 모드

웹 화면을 만드는 작업이라면 내장 브라우저로 결과를 확인합니다.
워크스페이스의 터미널에서 개발 서버를 실행하면 상태 표시줄에 포트가 표시되고, 새 브라우저 탭에서 그 주소를 엽니다.
브라우저 탭은 워크스페이스별로 분리되어 있어서, 작업마다 다른 포트의 개발 서버를 열어 두어도 섞이지 않습니다.

주소 표시줄 오른쪽의 조준점 아이콘(페이지 요소 가져오기)을 누르면 디자인 모드(Design Mode)가 켜집니다.

디자인 모드를 켠 내장 브라우저

마우스를 올린 요소에 테두리와 함께 태그 이름과 크기가 표시되고, 요소를 클릭하면 그 요소의 HTML과 계산된 CSS, 잘라낸 화면이 현재 에이전트 터미널에 첨부됩니다.
어떤 파일의 어떤 코드가 그 요소를 만드는지 몰라도, 화면에서 가리킨 다음 "이 제목의 여백을 아래 카드와 같게 맞춰 줘"처럼 말로 수정을 요청하면 됩니다.

# diff 검토와 메모

에이전트가 바꾼 내용은 오른쪽 사이드바의 소스 제어 탭에서 확인합니다.
변경된 파일을 클릭하면 diff 탭이 열리고, 고칠 부분이 보이면 그 줄에 메모를 남깁니다.

diff 화면과 줄에 남긴 메모

1. 줄 번호 왼쪽에 마우스를 올리면 나타나는 +를 누릅니다.
2. 입력 상자에 수정할 내용을 작성하고 메모 추가를 누릅니다.
3. 같은 방식으로 다른 줄에도 메모를 남깁니다. 저장된 메모는 줄에 카드로 고정되고, 도구 모음의 AI notes와 소스 제어 탭에 개수가 표시됩니다.

검토를 마치면 도구 모음의 AI notes 옆에 있는 보내기 아이콘을 누릅니다.

메모를 보낼 대상을 고르는 메뉴

이 파일의 메모만 보낼지 보내지 않은 모든 메모를 보낼지 고른 다음, 받을 에이전트를 선택합니다.
위쪽의 실행 중인 세션을 고르면 작업한 에이전트에게 수정을 요청하고, 아래쪽의 새로운 agent에서 Codex를 고르면 Claude Code가 만든 변경을 Codex에게 고치게 할 수도 있습니다.

에이전트 터미널에 전달된 메모

메모는 파일 경로와 줄 번호가 붙은 하나의 프롬프트로 정리되어 전달됩니다.
메모를 하나씩 보내는 것보다 검토를 마친 다음 한 번에 보내는 것이 에이전트가 수정 방향을 잡기 쉽습니다.

# 커밋과 푸시

결과가 마음에 들면 소스 제어 탭에서 반영까지 처리합니다.
메시지 입력 상자에 커밋 메시지를 작성하거나 오른쪽의 아이콘으로 AI 초안을 만든 다음, 상태에 따라 바뀌는 기본 버튼으로 스테이지, 커밋, 푸시를 차례로 진행합니다.
GitHub 계정을 연결해 두면 푸시한 다음 Orca 안에서 PR도 만들 수 있습니다.

반영이 끝난 워크스페이스는 사이드바에서 마우스 오른쪽 버튼으로 클릭한 다음 삭제를 누르고 확인하면, 폴더와 브랜치가 함께 지워집니다.
다만 병합되지 않은 커밋이 있을 수 있는 브랜치는 Git이 지우지 않으므로, Orca가 그 브랜치를 따로 보여 주고 강제로 지울지 고르게 합니다.

# 여러 에이전트 함께 사용

Claude Code와 Codex는 각자 별개의 프로그램이라서, Orca에서 나란히 실행해도 서로의 존재를 모릅니다.
직접 열어 둔 두 세션이 알아서 대화하는 기능은 없으며, 한 에이전트의 결과를 다른 에이전트에게 넘기는 방법은 다음과 같습니다.

# 같은 작업 비교

같은 문제를 여러 에이전트에게 동시에 맡기고 결과를 비교하는 방법입니다.

1. 워크스페이스를 만드는 창에서 더 만들기를 켜고, 에이전트만 바꿔 가며 같은 기준 브랜치에서 워크스페이스를 두세 개 만듭니다.
2. 각 에이전트에게 같은 프롬프트를 입력합니다.
3. 작업이 끝나는 대로 diff를 열어 결과를 비교합니다.
4. 가장 나은 결과에 메모를 남겨 보완을 요청하고, 커밋하고 푸시한 다음 나머지 워크스페이스를 삭제합니다.

에이전트마다 틀리는 지점이 달라서, 한 에이전트에게 여러 번 다시 요청하는 것보다 판단하기 쉽습니다.
결과가 같은 방향이면 맞는 답일 가능성이 높고, 서로 갈리는 부분이 그 작업에서 직접 확인해야 할 지점입니다.

# 다른 에이전트에게 인계

대화가 길어져서 응답 품질이 떨어졌거나, Claude Code로 하던 작업을 Codex로 이어 가고 싶을 때 사용합니다.
에이전트 터미널 오른쪽 위의 인계 아이콘(다른 에이전트에게 인계)을 누릅니다.

다른 에이전트에게 인계하는 창

이어서 작업할 에이전트와 넘길 컨텍스트의 범위를 고르고 새 세션 시작을 누르면, 같은 워크스페이스에 새 세션이 열리고 지금까지의 핵심 내용을 담은 프롬프트가 전달됩니다.
원래 세션은 그대로 남습니다.

# 오케스트레이션

오케스트레이션(Orchestration)은 한 에이전트가 다른 에이전트들에게 일을 나누어 맡기고, 완료 보고를 받아서 결과를 종합하게 하는 기능입니다.
일을 나누는 쪽을 조정자(Coordinator), 일을 맡는 쪽을 작업자(Worker)라고 부릅니다.

조정자와 작업자가 Orca를 거쳐 주고받는 흐름

에이전트끼리 직접 대화하는 것은 아니고, 모든 메시지는 Orca를 거칩니다.
조정자가 orca 명령으로 작업자를 실행해서 지시하면, 작업자는 끝난 뒤 같은 방식으로 결과를 보고하고 필요하면 질문합니다.

그래서 준비할 것은 다음과 같습니다.

• 조정자 역할을 할 에이전트에 오케스트레이션 스킬이 설치되어 있어야 합니다. 스킬이 없으면 에이전트는 이 기능이 있다는 것을 모르기 때문에, "Codex에게 맡겨 줘"라고 해도 일을 넘기지 못하고 직접 처리하거나 자체 서브 에이전트로 처리할 수 있습니다.
• 작업자에게는 스킬이 필요하지 않습니다. 조정자가 작업자를 실행하면 Orca가 보고 방법을 담은 안내를 작업 지시 앞에 붙여서 전달합니다.
• 작업자는 조정자가 새로 실행하는 것이 기본이지만, 이미 열어 둔 Codex나 Claude 터미널을 작업자로 쓰라고 요청할 수도 있습니다. 이때도 스킬은 조정자에게만 있으면 됩니다.
• orca 명령은 Orca 안의 터미널에 이미 포함되어 있어서 따로 설치하거나 연결할 것이 없습니다.

스킬의 설치 상태는 설정의 오케스트레이션 항목에서 확인합니다.

설정의 오케스트레이션 항목

설치되지 않음으로 표시되어 있으면 설치를 눌러 앞의 Orca 스킬에서 본 것과 같은 방법으로 설치하고, 끝나면 재확인을 누릅니다.
Agent 적용 범위에는 감지된 에이전트마다 스킬이 설치되었는지가 표시되며, 조정자로 사용할 에이전트가 누락이 아니면 됩니다.

준비가 끝나면 조정자로 쓸 에이전트에게 무엇을 어떻게 나눌지 설명하기만 하면 됩니다.

1
2
3
4
5
orchestration 스킬을 사용해서 상품 검색 기능을 두 작업으로 나눠 진행해 줘.
상품 목록 위의 검색 입력창과 이름 필터링 로직은 Codex에게,
검색 결과가 없을 때 보여 줄 안내 문구와 스타일은 Claude에게
각각 새 워크스페이스에서 맡겨 줘.
두 작업이 끝나면 바뀐 내용을 정리해서 알려 줘.

Claude Code에서는 /orchestration으로 스킬을 직접 불러온 다음 작업을 설명해도 됩니다.
위 요청을 받은 조정자는 작업 항목을 만들고, Codex와 Claude를 각각 새 워크스페이스에서 작업자로 실행한 다음, 두 작업자의 완료 보고를 받아서 정리합니다.

작업자의 보고를 정리한 조정자 터미널

사이드바에서는 작업자의 워크스페이스가 조정자(product-search) 아래에 2 하위로 묶여 표시됩니다.
작업자는 각자의 브랜치에 커밋하고, 조정자 터미널에는 작업자별로 바뀐 내용과 남은 작업(브랜치 합치기 등)이 정리됩니다.

# 자동화

자동화(Automations)는 정해진 시각에 프롬프트를 실행하는 기능입니다.
사이드바의 자동화에서 일일 변경 리뷰 같은 템플릿을 고르거나 새 자동화를 누르면 설정 창이 열립니다.

자동화 생성 창

왼쪽에 실행할 프롬프트를 작성하고, 오른쪽에서 실행 조건을 지정합니다.

• 에이전트: 실행할 에이전트를 고릅니다.
• 프로젝트와 워크스페이스: 기존 워크스페이스(워크트리)에서 실행할지, 실행할 때마다 새로 만들지(새로운 실행) 고릅니다.
• 세션: 매번 새로 시작할지, 이전 세션을 이어서 사용할지 고릅니다.
• 일정과 시간: 매일, 평일, 매주 같은 주기와 실행 시각을 지정합니다.
• 유예 시간: 컴퓨터가 꺼져 있어서 놓친 실행을 지정한 시간 안에서 따라잡습니다.

자동화는 등록한 컴퓨터가 켜져 있어야 실행됩니다.
프롬프트가 안정될 때까지는 일정 없이 직접 실행해서 결과를 확인한 다음 일정을 켜는 것이 좋습니다.

# 휴대폰과 원격

Orca 모바일 앱(iOS, Android)을 연결하면 자리를 비운 동안에도 진행 상황을 확인하고 에이전트의 질문에 답할 수 있습니다.
사이드바의 Orca 모바일에서 시작하기를 눌러 페어링 코드를 만들고, 모바일 앱의 데스크톱 페어링에서 그 코드를 스캔하면 연결됩니다.
휴대폰이 같은 Wi-Fi나 Tailscale 네트워크에 있으면 계정 없이 연결되고, 밖에서 연결하려면 Orca 계정으로 로그인해야 합니다.

에이전트를 다른 컴퓨터에서 실행할 수도 있습니다.
설정의 SSH 호스트에 원격 장비를 등록하면 워크스페이스를 만들 때 실행 위치에서 그 장비를 고를 수 있으며, 에이전트와 Git은 원격에서 실행되고 화면은 내 컴퓨터에 남습니다.

# Orca CLI

Orca CLI는 실행 중인 Orca를 명령줄에서 조작하는 orca 명령입니다.
Orca 안의 터미널에서는 바로 사용할 수 있고, 밖의 터미널에서 사용하려면 설정의 일반에 있는 Orca CLI에서 셸 명령을 등록합니다.

1
2
orca worktree create --name fix-login --agent claude --prompt "로그인 실패 버그를 재현하고 수정해 줘"
orca worktree ps

화면에서 할 수 있는 일은 대부분 CLI로도 할 수 있지만, 사람이 직접 입력할 일은 드물고 주로 에이전트가 사용합니다.
오케스트레이션에서 조정자가 작업자를 실행하고 보고를 받는 것도 이 명령으로 처리됩니다.