시작하기 — Orca란 무엇이고 어떻게 설치·설정하나
Orca는 여러 AI 코딩 에이전트를 한 화면에서 나란히 돌리는 데스크톱 앱입니다. 이 장에서는 Orca가 어떤 도구인지, 설치와 첫 실행, 세 에이전트를 동시에 경주시키는 첫 세션, 알림·설정·개인정보, 그리고 문제가 생겼을 때 고치는 방법까지 한 번에 훑습니다.
1. Orca란?
Orca는 여러 AI 코딩 에이전트를 나란히 실행하는 데스크톱 앱, ADE(에이전트용 개발 환경 — 코드 편집·실행·검토를 에이전트와 함께 한곳에서 하는 프로그램)입니다. AI 코딩 에이전트(말로 시키면 스스로 코드를 고치는 AI 프로그램)를 여러 개 동시에 부리는 “작업 지휘실”이라고 보면 됩니다. 핵심은 “작업 하나 = 독립된 작업 공간 하나”라는 점입니다. 작업마다 다음 세 가지가 따로 주어집니다.
같은 저장소(프로젝트 파일과 변경 기록을 담은 폴더)를 폴더만 하나 더 만들어 다른 브랜치로 꺼내 둔 사본입니다. 에이전트끼리 서로의 파일을 덮어쓰지 않습니다.
Claude Code, Codex, Cursor CLI 같은 에이전트가 그 워크트리 안에서 실행됩니다. 터미널(글자로 명령을 입력하는 검은 창)에서 돌아갑니다.
작업별로 웹 화면을 따로 띄워 결과를 확인할 수 있습니다.
git(코드 변경 이력을 저장·관리하는 도구)은 코드의 “저장 기록장”입니다. 브랜치(branch)(원래 코드에서 갈라져 나온 별도의 작업 줄기)는 “원본을 건드리지 않고 따로 고쳐 보는 갈림길”이고, 워크트리(worktree)(한 저장소의 브랜치를 별도 폴더에 동시에 꺼내 두는 git 기능)는 그 갈림길마다 책상을 하나씩 더 놓아 주는 것이라고 생각하면 됩니다. 책상이 따로 있으니 세 명(에이전트)이 동시에 일해도 서류가 섞이지 않습니다. 그래서 작업을 바꿀 때마다 변경을 잠시 치워 두는 stash(고치던 것을 임시 보관함에 넣기)나 브랜치를 이리저리 바꾸는 번거로움이 없습니다.
언제 Orca를 쓰면 좋은가
- 같은 버그를 에이전트 셋에게 동시에 시켜 보고 가장 잘한 쪽을 고르고 싶을 때
- AI가 만든 diff(파일이 어떻게 바뀌었는지 줄 단위로 보여 주는 비교 결과)를 내보내기 전에 꼼꼼히 검토하고 싶을 때
- 이미 Claude Code, Codex, Cursor CLI 요금을 내고 있고, 이들을 한곳에서 지휘하고 싶을 때
- 에이전트를 다른 컴퓨터에서 돌리고 싶을 때 — SSH(다른 컴퓨터에 암호화된 통로로 접속하는 방법), 직접 운영하는 Orca 서버, 필요할 때만 켜는 VM(클라우드에 빌려 쓰는 가상 컴퓨터) — 그러면서도 화면은 그대로 쓰고 싶을 때
누구를 위한 도구인가
Orca는 이미 코드를 직업으로 쓰는 사람이 AI를 “대체재”가 아니라 “지렛대”로 쓰도록 설계됐습니다. diff를 읽고, 커밋(변경 내용을 하나의 저장 단위로 기록하는 것)을 신경 쓰고, 워크트리를 깔끔하게 관리하는 사람을 전제로 합니다. 코드를 몰라도 되는 노코드(no-code) 도구를 찾는다면 Orca는 그런 도구가 아닙니다.
- AI 모델이 아닙니다. 이미 쓰는 에이전트를 실행할 뿐입니다. Claude, Codex, OpenCode 구독은 본인 것을 가져옵니다.
- git을 대체하지 않습니다. 모든 워크트리는 진짜 git worktree입니다. 언제든 터미널에서 그 폴더로 들어가(
cd(폴더 이동 명령)) 평범한 git 명령을 써도 됩니다. - 서버를 빌려주는 서비스가 아닙니다. VPS(월세로 빌리는 인터넷 서버 컴퓨터) 같은 상품을 팔지 않습니다. 기본은 내 컴퓨터에서 돌고, 다른 컴퓨터를 쓰더라도 내가 관리하는 기기·클라우드 계정(SSH 대상, 직접 운영하는 Orca 서버, Cloud VM/워크트리별 환경)을 씁니다.
설치 → 첫 3-에이전트 세션(공식 문서가 “가장 중요한 페이지”라고 부르는 부분) → 노트북 밖에서 돌리고 싶어지면 실행 방식(Ways to run).
2. 설치
Orca는 보통 프로그램처럼 다운로드 → 더블클릭 → 설치하면 끝입니다. 공식 사이트의 Send download link(다운로드 링크 보내기)로 내 메일에 링크를 보내 두고, 설치할 컴퓨터에서 열 수도 있습니다. 내 운영체제 탭의 첫 줄만 읽으면 됩니다.
다운로드 → 더블클릭 → 설치. Apple Silicon(M1 이후 칩)용과 Intel용 중 내 Mac에 맞는 것을 받습니다. 첫 실행 때 macOS가 “정말 열까요?” 하고 물으면 열기를 누르면 됩니다.
다운로드 → 더블클릭 → 설치. 설치 프로그램(installer)을 받아 실행합니다.
다운로드 → 더블클릭(또는 설치) → 실행. 자동 업데이트를 원하면 AppImage(설치 없이 파일 하나로 실행되는 형식)를 고르세요.
예전 버전은 GitHub Releases 페이지에서 언제든 받을 수 있습니다. 지금 업데이트가 마음에 안 들면 이전 버전으로 돌아가도 됩니다.
첫 실행 때 일어나는 일
① 홈 폴더 접근 권한 요청 — 저장소(repo)를 추가할 수 있도록 홈 폴더(내 사용자 이름으로 된 기본 폴더) 접근을 물어봅니다. 허용하면 됩니다.
② 기존 설정 가져오기 제안 — ~/.claude, ~/.codex, Ghostty 터미널 설정이 있으면 가져올지 물어봅니다. (~는 내 홈 폴더라는 뜻입니다.) 처음 쓰는 사람은 가져올 것이 없으니 넘어가면 됩니다.
③ 빈 시작 화면 — 아무것도 없는 랜딩 화면이 나오고, 여기서 첫 저장소를 추가합니다.
사이드바: (비어 있음) Add Repo
업데이트: 안정판과 RC
Orca는 기본적으로 자동 업데이트되며 stable(안정) 채널을 따라갑니다. 초보자는 아무것도 바꾸지 않아도 됩니다. 안정판은 검증을 거친 버전이고, RC(release candidate, 출시 후보 — 새 기능이 먼저 들어간 시험판)는 거의 매일 나오기도 합니다.
4. 첫 3-에이전트 세션
- AI 코딩 에이전트 1개 설치·로그인. Orca는 AI 모델을 주지 않고, 내가 이미 쓰는 에이전트(Claude Code, Codex 등)를 돌립니다 — 그 에이전트의 구독(대부분 유료)은 직접 준비해야 합니다. 에이전트를 설치한 뒤 아무 터미널에서 한 번 로그인해 두면, Orca가 그 로그인 정보를 자동으로 가져다 씁니다. 아래 예시처럼 세 종류를 비교하려면 각 에이전트마다 이 준비가 필요합니다.
- git 저장소 폴더 1개. 1단계에서 고를 “프로젝트 폴더”는 git으로 관리되는 폴더(저장소)여야 합니다 — Orca의 워크트리는 모두 진짜 git 워크트리이기 때문입니다. 그런 폴더가 없다면 팀의 개발자에게 쓸 저장소를 받아 내 컴퓨터에 받아 두거나(clone(서버의 저장소를 내 컴퓨터로 복사해 오기)), 저장소 주소(clone URL)로 추가하는 방법을 물어보세요.
공식 문서가 “가장 중요한 페이지”라고 부르는 흐름입니다. 빈 앱에서 시작해 5분 안에 같은 작업을 에이전트 셋에게 동시에 시켜 보고, 그중 가장 잘한 것으로 PR(Pull Request — “내 변경을 원본에 합쳐 주세요”라는 요청서)을 냅니다. 아래 그림에서 빨간 테두리가 깜빡이는 곳을 차례로 누르면 됩니다.
1. 저장소 추가 — Add Repo 누르기: 사이드바의 Add Repo를 누르고 내 컴퓨터에 있는 프로젝트 폴더를 고릅니다.
Orca는 그 폴더의 git 상태를 읽고 기본 브랜치를 기준 브랜치(base ref(저장소의 기본 기준 — 보통 서버에 있는 원본 줄기 origin/main))로 잡습니다. 새 워크트리는 기본적으로 여기서 갈라져 나옵니다. 기준 브랜치는 나중에 저장소 설정에서 바꿀 수 있습니다.
2. 워크트리 만들기 — + 누르고 이름 적기: 저장소 이름 옆 +를 누르고 작업 이름을 적습니다(예: fix-login-race). 비워 두면 Orca가 해양 생물 이름을 붙여 줍니다.
- 화면에는 Workspace(워크스페이스 — 워크트리와 같은 것)라는 말도 나옵니다. 원클릭 Workspace 실행기(launcher)가 열리고, 기본 에이전트가 미리 선택돼 있습니다(Settings → Agents에서 변경). 빈 터미널만 열 수도 있습니다.
- 출발점(start-from ref(이 새 워크트리가 갈라져 나오는 지점))은 보통 그대로 둡니다. 대개 기준 브랜치와 같은 기본값
origin/main은 “인터넷 서버(GitHub 등)에 있는 원본 줄기”라는 뜻입니다. 원하면 다른 브랜치나 커밋에서 시작해도 됩니다.
3. 에이전트 고르기 — 선택 상자에서 고르기: 새 워크트리에 터미널이 열리고 에이전트 선택 상자가 보입니다. Claude Code, Codex, Cursor CLI 등을 고르면 됩니다.
Orca가 올바른 작업 폴더에서 그 에이전트의 CLI(글자 명령으로 쓰는 프로그램)를 실행하고, 내 구독 자격 증명(내가 이미 결제·로그인한 계정 정보)을 넘겨줍니다. 그래서 시작 전 준비물 ①대로 터미널에서 한 번 로그인해 두었다면 Orca 안에서 따로 로그인할 필요가 없습니다.
4. 세 에이전트 경주 — 사이드바에 워크트리 3개: 2~3단계를 두 번 더 반복해 워크트리를 셋으로 만들고, 세 곳에 똑같은 부탁(프롬프트)을 붙여 넣습니다.
브랜치 셋, diff 셋, 프롬프트 하나. 이제 일하게 둡니다.
5. 창을 셋으로 나누기 — 탭을 가장자리로 끌기: 워크트리의 탭을 다른 창(pane)의 오른쪽이나 아래쪽 가장자리로 끌어다 놓으면 화면이 분할됩니다.
세 에이전트가 일하는 모습을 동시에 지켜볼 수 있습니다.
6. 승자 고르기 → diff 검토 → 내보내기: 에이전트들이 멈추면 각 워크트리의 diff 화면을 엽니다. Annotate AI Diff로 줄마다 의견을 달아 가장 잘한 에이전트에게 돌려보내고, 다 되면 Commit(저장)과 Push(내 컴퓨터의 저장 기록을 인터넷 서버에 올리기)를 Orca 안에서 바로 합니다.
- 결과 화면 비교 — 워크트리마다 있는 브라우저 탭에서 결과를 직접 눌러 보고, 내가 부탁한 대로 동작하는 쪽을 고릅니다.
- 바뀐 줄 수 — diff 화면 위쪽 작은 표시(칩)에 더한 줄·지운 줄 수가 나옵니다. 결과가 비슷하면 덜 바꾼 쪽이 검토하기 쉽습니다.
- 자동 검사 통과 여부 — PR을 올린 뒤 Checks 패널에서 검사(CI)가 통과했는지 봅니다. 셋의 결론이 같으면 아마 정답입니다.
자세한 검토 순서는 6장 레시피: AI diff를 줄 단위로 리뷰하기를 보세요.
나머지 두 워크트리는 클릭 한 번으로 지울 수 있고, 그 브랜치도 함께 지워집니다.
레시피: 같은 작업으로 에이전트 셋 경주시키기
같은 작업을 여러 에이전트에게 병렬로 시키는 것은 Orca의 “필살기”입니다. 정리하면 다음과 같습니다.
- 같은 출발점에서 워크트리 3개같은 출발점(start-from ref)에서
fix-bug,fix-bug-2,fix-bug-3을 만듭니다. - 서로 다른 에이전트각각 Claude Code, Codex, Cursor CLI를 띄웁니다.
- 같은 프롬프트세 곳에 똑같이 붙여 넣습니다.
- 창 분할탭을 가장자리로 끌어 일하는 모습을 함께 봅니다.
- diff 검토끝나면 각 diff를 보고, 승자에게 Annotate AI Diff를 씁니다. 승자는 결과 화면·바뀐 줄 수·검사 통과로 고릅니다(위 4절 6단계의 “고르는 법” 참고).
- 승자에서 PR이긴 워크트리에서 커밋·push·PR 열기.
- 패자 정리나머지 둘을 삭제합니다. 클릭 한 번이면 워크트리와 브랜치가 함께 지워집니다.
6. 알림과 받은 편지함(Notifications & Inbox)
Orca는 그냥 터미널이 아니라 에이전트를 돌리기 때문에, 에이전트가 진짜로 끝났는지 잠시 멈춘 건지 구분할 수 있습니다. 알림은 이 신호를 이용합니다. 에이전트 셋을 걸어 두고 자리를 비웠다가, 첫 번째가 끝나면 돌아오면 됩니다.
| 기능 | 설명 |
|---|---|
| Agent-finished pings(완료 알림) | 에이전트가 작업 중 → 쉬는 중으로 바뀌면 시스템 알림·소리·워크트리 칩(사이드바 워크트리 이름 옆에 붙는 작은 꼬리표 모양 표시)이 나갑니다. 한 에이전트가 끝난 직후 다른 에이전트가 끝나도 완료음은 빠지지 않고 울립니다. |
| Persistent bell(상시 벨) | 머리글 벨에 모든 워크트리의 읽지 않은 알림이 모입니다. 알림을 누르면 해당 워크트리·창으로 이동합니다. |
| Dock 배지 (macOS) | 같은 읽지 않음 개수가 Dock 아이콘에도 표시되어 Orca를 앞으로 꺼내지 않아도 알 수 있습니다. 해당 워크트리를 방문하면 사라집니다. |
| Mark unread(읽지 않음으로 표시) | 알림을 오른쪽 클릭해 다시 읽지 않음으로 만듭니다. 일단 확인했지만 나중에 다시 보고 싶을 때 씁니다. |
| Tuning(세부 조정) | Settings → Notifications에서 종류별(system, sound, chip-only)로 끌 수 있습니다. |
알림을 띄울 기기 고르기, 알림 소리 바꾸기, 채팅 화면에서의 예외 동작은 아래 접힌 상자에 있습니다.
- Orca는 작업마다 워크트리·에이전트 터미널·브라우저 탭을 따로 주는 ADE(에이전트용 개발 환경)입니다. AI 에이전트의 구독은 직접 준비합니다.
- 설치는 다운로드 → 더블클릭 → 설치. macOS·Windows·Linux를 지원합니다.
- 실행 위치는 로컬 · SSH · 원격 Orca 서버 · Cloud VM(실험) 네 가지지만, 초보자는 화면과 일하는 곳이 같은 “로컬”만 알면 됩니다.
- 첫 세션 전에 에이전트 1개 설치·로그인과 git 저장소 폴더를 준비합니다. 흐름은 저장소 추가 → 워크트리 → 에이전트 → 창 분할 → 변경 검토 → 내보내기입니다.
- 같은 부탁을 에이전트 셋에게 시키고, 결과 화면·바뀐 줄 수·검사 통과로 승자를 고릅니다. 셋이 일치하면 아마 정답, 갈리면 어려운 지점이라는 신호입니다.
- Agents 피드는 자리 비운 뒤의 따라잡기 화면이고, 에이전트가 끝나면 시스템 알림·소리·칩·벨·Dock 배지로 알려 줍니다.
- 설정은 Cmd+,(macOS)로 열어 검색하며, 처음엔 General·Agents·Notifications만 보면 됩니다.
- 텔레메트리는 익명이고 내용·경로를 보내지 않으며, Settings → Privacy에서 끕니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 1장에 있습니다.
Orca의 핵심 모델 — 워크트리·세션·화면 배치·복원·빠른 이동
Orca는 "작업 하나 = 폴더 하나(워크트리)"라는 생각 위에 세워져 있습니다. 이 장에서는 그 바탕이 되는 git 워크트리부터, 에이전트 세션의 상태 표시, 탭과 화면 분할, 앱을 껐다 켜도 그대로 돌아오는 세션 복원, 그리고 키보드로 순식간에 이동하는 검색창까지 Orca의 뼈대를 차례로 살펴봅니다.
먼저 알아 둘 것 — 브랜치·체크아웃·워크트리
Orca의 모든 것은 git(파일이 바뀐 기록을 저장하고 되돌리거나 합칠 수 있게 해 주는 버전 관리 도구)의 워크트리라는 기능 위에 있습니다. git을 처음 들어도 괜찮도록 세 단어부터 풀어 보겠습니다.
저장소(repo)
프로젝트 파일과 그 변경 기록 전체를 담은 상자입니다. 보통 컴퓨터의 폴더 하나로 보입니다.
브랜치(branch)
기록의 "갈래"입니다. main이라는 큰 줄기에서 feature/login 같은 가지를 뻗어, 원본을 건드리지 않고 따로 고쳐 볼 수 있습니다.
체크아웃(checkout)
어떤 브랜치의 파일들을 실제 폴더에 "꺼내 놓는" 일입니다. 폴더 안 파일은 지금 체크아웃된 브랜치의 모습입니다.
워크트리(worktree)
같은 저장소를 폴더 여러 개에 동시에 체크아웃하는 git 기능입니다. 폴더마다 다른 브랜치가 꺼내져 있습니다.
Orca는 워크트리 중심(worktree-native)으로 설계되었습니다. 한 체크아웃에서 브랜치를 바꾸고 stash(하던 변경을 잠시 치워 두기)하는 대신, 모든 기능 개발이나 버그 수정마다 git worktree로 저장소의 디스크 사본을 따로 만듭니다. 이것이 여러 에이전트를 병렬로 돌려도 안전한 이유입니다 — 에이전트끼리 서로의 파일을 건드리지 않습니다.
에이전트 세션과 상태 표시
에이전트 세션이란 워크트리 하나 안의 터미널 하나에서 도는 CLI 에이전트 하나입니다. CLI(마우스 대신 글자 명령으로 쓰는 프로그램) 에이전트는 Claude Code·Codex처럼 터미널 창 안에서 일하는 AI 도우미를 말합니다. Orca는 그 일생을 추적해서, 탭마다 들어가 보지 않아도 어떤 세션이 일하고 어떤 세션이 쉬는지 알려 줍니다. 모든 워크트리 카드 안에 상태 기호가 바로 보입니다.
| 기호 | 뜻 |
|---|---|
| Spinner(돌아가는 원) | 작업 중 |
| ? 주황 물음표 | 나를 기다림(권한 요청 / 입력 필요). 사이드바 "Needs You" 개수도 같은 기호 |
| 초록 체크(대시보드) 또는 초록 점(사이드바) | 완료 / 조용히 활성 |
| 빨간 점 | 막힘, 중단됨, 실패 |
| 회색 점 | 쉬는 중(idle) — 끝난 뒤 오래 조용한 상태 |
| 표시 없음 | 평범한 셸 — Orca가 아는 에이전트 CLI가 아님 |
Orca는 이 상태를 어떻게 알까요? 에이전트가 일하는 동안 "나 지금 일해요", "끝났어요" 하고 신호를 보내기 때문입니다. Claude Code, Codex 등 여러 에이전트가 이 신호를 내보냅니다.
세션의 일생
콤보 상자에서 에이전트를 고르면 Orca가 CLI를 띄웁니다.
에이전트가 보내는 신호로 상태 기호가 바뀝니다. 터미널 출력은 검색·복사가 됩니다.
Orca가 "작업 중 → 조용해짐"으로 바뀌는 순간을 감지해 agent-finished(에이전트 끝남) 알림을 보냅니다. 그대로 오래 두면 회색 "쉬는 중"으로 보입니다.
에이전트 프로그램이 끝나면 탭에 Restart 칩이 나타납니다.
Restart 칩
에이전트가 끝나면(정상 종료든 충돌이든) 탭에 Restart 칩이 뜹니다. 한 번 누르면 같은 에이전트를 같은 작업 폴더에서 다시 살립니다.
실행 기본값 — 에이전트가 허락을 묻는가
에이전트는 파일을 고치거나 명령을 실행하기 전에 "이거 해도 될까요?" 하고 사람에게 물을 수 있습니다. Orca는 기본으로 묻지 않게 해서 에이전트를 띄웁니다. 매번 허락 창이 떠서 흐름이 끊기지 않게 하려는 것이고, 그래도 되는 이유로 워크트리 자체가 안전 울타리라는 점을 듭니다 — 에이전트는 자기 작업 폴더에서 일하고, 그 결과(변경점)는 합치기 전에 사람이 골라 담거나 버릴 수 있습니다.
"묻지 않게"는 에이전트를 켤 때 권한 생략 플래그(프로그램을 켤 때 뒤에 붙이는 옵션 글자. 여기서는 "확인 절차를 건너뛰어라"라는 뜻)를 미리 붙여 두는 방식으로 이루어집니다. 이 기본값은 Settings → Agents(설정 → 에이전트)의 Agent permissions(에이전트 권한)에서 바꿀 수 있습니다 — 플래그가 붙은 지금 상태가 Yolo(묻지 않음)이고, Manual(매번 묻기)로 바꾸면 허락 창이 돌아옵니다. 그 사이의 Auto는 지원하는 에이전트(Claude, Claude Agent Teams, Codex)가 일상적인 동작만 스스로 승인하는 모드입니다.
세션 복원 — 껐다 켜도 그대로
Orca를 닫았다가 다시 열면 작업 공간 전체가 되살아납니다. 어떤 브랜치에서 어떤 에이전트를 돌리고 있었는지 기억하는 건 사용자가 아니라 Orca의 일입니다.
비결은 데몬(화면 없이 뒤에서 계속 도는 프로그램)입니다. 데몬을 앱을 꺼도 뒤에서 터미널을 붙잡고 있는 관리인이라고 생각하면 됩니다. 에이전트가 일하는 터미널은 앱 창이 아니라 이 관리인이 쥐고 있어서, 창을 닫아도 일이 멈추지 않습니다. 다만 관리인도 컴퓨터 안에 사는 프로그램이라, 컴퓨터 자체가 꺼지면 함께 꺼집니다.
복원되는 것
- 열린 워크트리 — 사이드바에 열려 있던 모든 워크트리
- 탭과 분할 — 워크트리별 창 배치(중첩 분할 포함)와 초점이 있던 탭
- 실행 중인 에이전트 — 데몬(관리인)이 터미널을 쥐고 있으므로 앱 창을 닫아도 Claude Code·Codex 등이 작업 도중 죽지 않습니다. 다음 실행 때 새로 띄우지 않고 살아 있던 그 에이전트에 그대로 다시 연결합니다.
- 터미널 스크롤백(위로 굴려 다시 볼 수 있는 지난 출력) — 각 터미널의 출력 기록. Orca가 닫혀 있던 동안 나온 출력도 포함
- 초점 워크트리와 탭 — 닫을 때 보던 화면으로 열림
복원되지 않는 것
- 데몬은 컴퓨터와 운명을 같이합니다. 재부팅, OS 업데이트, 커널 패닉(운영체제가 심각한 오류로 갑자기 멈추는 일), 강제 전원 끄기처럼 기계 전체가 꺼지면 실행 중인 에이전트는 모두 끝납니다. 다음 실행 때 워크트리·탭·분할·마지막 스크롤백은 돌아오지만 에이전트 프로세스는 없습니다. 아무 탭에서 에이전트를 다시 실행해 이어 가세요.
- Orca가 닫혀 있는 동안 데몬이 충돌해도 그 데몬이 붙잡던 세션은 같은 결과가 됩니다. 레이아웃과 스크롤백은 여전히 복원됩니다.
언제 복원이 일어나나 — 상황별로 보기
데몬 살아남음 → 에이전트 계속 실행. Cmd-Q(macOS)는 평소의 종료 방법이며, 에이전트는 뒤에서 계속 일합니다.
데몬 살아남음. 업데이트 설치를 위해 Orca가 다시 켜져도 에이전트는 영향받지 않습니다.
데몬 살아남음. Orca 자체가 충돌해도 데몬이 세션을 살려 두고, 다음 실행 때 다시 붙습니다.
데몬 죽음 → 에이전트 사라짐, 레이아웃은 복원. 노트북 재시작, OS 업데이트, 커널 패닉, 강제 전원 끄기. 워크트리·탭·분할·마지막으로 저장된 스크롤백은 돌아옵니다.
- 워크트리 = 같은 저장소를 작업마다 다른 폴더에 꺼내 둔 것. 에이전트끼리 파일을 밟지 않아 병렬 작업이 안전합니다.
- 일생: Create → Work → Review → Ship → Archive/Delete. 생성은 백그라운드, 출발점은 보통 기준 브랜치(base ref), 필요하면 로컬 브랜치·커밋·원격 브랜치.
- gitignore된 파일은 Shared Paths·
orca.yaml(공유) /.worktreeinclude(복사)로 채웁니다. - 사이드바: 프로젝트별 묶음, 숨기기 필터, 고정·다중 선택·자식 칩. 일괄 삭제 시 미병합 브랜치는 보존 후 검토.
- 상태 기호: 돌아가는 원(작업) · 주황 ?(나를 기다림) · 초록(완료) · 빨강(실패) · 회색(쉬는 중). 끝나면 초록 → 오래 두면 회색. 대시보드는 실험 기능.
- 에이전트는 묻지 않는 모드(Yolo, 권한 생략 플래그)가 기본 — 원치 않으면 Settings → Agents의 Agent permissions에서 Manual(매번 묻기)로.
- 탭은 끌어서 분할, 레이아웃은 워크트리별 저장. 데몬 덕에 앱을 꺼도 에이전트는 계속, 재부팅 땐 레이아웃만 복원.
- Cmd-P 파일, + 탭·파일·URL·웹 검색, Cmd-J 워크트리·탭 이동(macOS 키).
이 장의 나머지 소절과 🔧 세부는 완전 가이드 2장에 있습니다.
에이전트와 터미널 — 지원 에이전트, 채팅 UI, 기록, 사용량
Orca의 심장은 “코딩 에이전트를 터미널에서 돌리는 일”입니다. 이 장에서는 코딩 에이전트와 터미널이 무엇인지부터 시작해, Orca가 어떤 에이전트를 지원하고, 그 에이전트와 대화하는 두 가지 화면(터미널·채팅), 지난 대화 다시 열기, 쉬는 에이전트 재우기, 사용량 확인, 그리고 터미널의 모든 기능을 차례로 살펴봅니다.
코딩 에이전트와 터미널, 먼저 쉽게 알기
터미널(Terminal)이란
마우스로 아이콘을 누르는 대신, npm test처럼 글자로 명령을 입력해 컴퓨터를 움직이는 창입니다. 명령을 받아 실행해 주는 프로그램을 셸(shell)(터미널 안에서 명령을 알아듣고 실행하는 프로그램. zsh, bash, PowerShell 등)이라 부릅니다. 이렇게 글자 명령으로 쓰는 프로그램을 CLI(Command Line Interface — 버튼 화면 없이 글자 명령으로 쓰는 프로그램)라고 합니다.
코딩 에이전트(Coding Agent)란
Claude Code, Codex 같은 AI가 들어 있는 CLI 프로그램입니다. 일반 챗봇과 달리 내 컴퓨터의 코드를 읽고, 파일을 고치고, 명령을 실행할 수 있습니다. 대부분 터미널 안에서 돌아가는 글자 화면, 즉 TUI(Terminal User Interface — 터미널 안에 글자로 그린 화면)를 갖고 있습니다.
지원 에이전트 한눈에 보기
Orca의 기본 에이전트 선택기(built-in agent picker)에는 40여 개 에이전트가 미리 들어 있고, 모두 한 번 클릭으로 실행·설정됩니다. 그중 Orca 기능을 가장 많이 함께 쓰는 것은 깊은 통합이 붙은 아래 네 가지입니다. 어느 것을 고를지 모르겠다면 이 넷 중에서 시작하세요.
| 에이전트 | Orca에서 되는 것 | 만든 곳 |
|---|---|---|
| Claude Code | 깊은 통합 사용량 계정 전환, 훅, 계정별 폴더 | Anthropic |
| Codex | 깊은 통합 사용량 계정 전환 | OpenAI |
| Muse Code | 깊은 통합 훅 상태, 사용량 세션 기록 | Meta |
| Cursor CLI | 깊은 통합 | Cursor |
표에 쓰인 표시의 뜻은 다음과 같습니다.
깊은 통합
사용량, 계정 전환, 훅 등 여러 기능을 깊이 연결한 에이전트(Claude Code, Codex, Muse Code, Cursor CLI).
자동 설정 Auto-setup
선택기에서 고르면 Orca가 알아서 실행 준비를 해 줍니다.
훅 · 상태
에이전트가 “작업 중 / 입력 대기 / 완료”를 Orca에 알려 탭·사이드바에 상태 점이 뜹니다.
네이티브 채팅
터미널 대신 Orca의 구조화된 채팅 화면으로 대화할 수 있습니다.
사용량
상태 표시줄에 사용량·한도까지 남은 정도를 보여 줍니다.
세션 기록 · 재개
지난 대화를 목록에서 찾아 그대로 이어갈 수 있습니다.
권한 기본값 — 왜 “확인 없이” 실행할까
코딩 에이전트는 보통 명령을 실행하기 전에 “이거 실행해도 될까요?”라고 매번 묻습니다. 예를 들어 파일을 지우거나 고치기 전에 “이 파일 지워도 될까요? [예/아니오]” 같은 확인 창을 띄우는 식입니다. Orca는 새로 실행하는 에이전트에 이 확인을 건너뛰는 옵션(flag(프로그램을 실행할 때 명령 뒤에 붙이는 켜기/끄기 스위치. 예: --yolo))을 미리 붙여 둡니다. 이런 “확인 없이 실행” 상태를 흔히 Yolo라고 부릅니다.
무엇이 위험할까
확인을 건너뛰면 에이전트가 파일을 고치거나 지우는 셸 명령도 여러분에게 묻지 않고 바로 실행합니다. 잘못된 명령이 있어도 중간에 막을 기회가 없습니다.
그래도 괜찮다고 보는 이유
에이전트는 원본이 아니라 자기 전용 워크트리(버려도 되는 작업용 복사본)에서 일합니다. 결과는 원본에 합치기(병합) 전에 사람이 보고 마음에 드는 것만 골라 담거나 통째로 버릴 수 있습니다.
main은 보통 기본 갈래), 체리픽(cherry-pick)(변경 중 마음에 드는 것만 골라 가져오기), 병합(merge)(작업 결과를 원본 갈래에 합치기).
권한 모드 바꾸기
- 전체 전환: Settings → Agents → Agent Permissions따로 손대지 않은(uncustomized) 터미널 에이전트 실행을 Yolo(확인 없이)와 Manual(매번 확인) 사이에서 한 번에 바꿉니다.
- Claude·Codex 새 세션의 기본값같은 곳에서 새 Claude·Codex의 터미널 세션과 구조화 채팅 세션 기본값도 정합니다. 이미 열린 채팅은 자기 모드를 그대로 유지합니다.
- 한 에이전트만 다시 묻게 하기Settings에서 그 에이전트의 기본 인수(arguments)나 환경 변수(environment)(프로그램이 시작할 때 읽어 가는 이름=값 설정)를 직접 고칩니다.
직접 고친 에이전트 설정은 전체 전환 스위치가 건드리지 않습니다. 구조화 채팅에서는 Manual · Auto · Yolo 세 가지 중 고를 수 있습니다(뒤의 네이티브 채팅 참고).
네이티브 채팅 UI (Chat UI)
터미널의 글자 화면 대신, 메신저처럼 대화 기록 + 작성창(composer)으로 에이전트와 이야기하는 선택형 화면입니다. 구조화된 대화 기록, 스킬, 모델 선택, 답변 안 그림(inline visuals)을 지원합니다. 아래에서 자주 나오는 턴(내 메시지 하나에 에이전트가 일하고 답하는 한 차례)은 대화의 한 차례를 뜻합니다. 같은 부탁을 두 화면에서 하면 이렇게 보입니다.
✓ 원인 찾기 ◻ 수정하기 ◻ 테스트
src/login.ts +6 −2 — 인라인 diff 카드
에이전트마다 Chat(채팅 화면) 또는 CLI(터미널)를 고릅니다. Chat을 고르면 자격이 되는 새 세션이 Orca의 구조화 네이티브 채팅으로 열립니다. 세션 상태를 Orca가 갖고 있으므로, 앱을 다시 켜도 탭과 대화가 복원됩니다.
- 구조화 채팅 대상: Claude, Codex, Grok, OpenCode(2.x 포함), Pi, OMP, Antigravity.
- 설정 위치: Settings → Chat UI 또는 Settings → Agents. 에이전트별로 고르고, 따로 고르지 않은 에이전트를 위한 기본값도 정할 수 있습니다.
- 새로 설치하면 기본은 Terminal입니다.
- WSL(Windows 안에서 리눅스를 돌리는 기능)·SSH(다른 컴퓨터에 원격으로 접속해 명령을 내리는 방식) 세션은 터미널을 바탕으로 한 Chat UI를 씁니다.
- 어디서 되나: 내 컴퓨터(macOS·Linux·Windows)와, 짝지은 Orca Server가 맡은 워크트리.
- 모양: Settings → Chat UI에서 글꼴·크기·폭·대비를 정하고, Match terminal interface로 터미널과 같은 모양을 쓸 수 있습니다.
- Inline visuals: 켜면 에이전트가 답변 안에 차트·다이어그램·목업을 그립니다.
- 권한 모드: Manual · Auto · Yolo 중 고릅니다(권한 기본값의 그림 참고).
- Orca가 재시작돼 끊긴 채팅은 다시 연결될 때 이어서 하자고 제안합니다.
보내기 · 멈추기 · 첨부
메시지를 보내거나 진행 중인 턴을 멈춥니다. 호스트(에이전트가 실제로 돌아가는 컴퓨터 — 내 컴퓨터나 짝지은 서버)가 지원하면 파일·이미지를 첨부합니다. 파일 트리나 바탕화면에서 작성창(또는 채팅 화면 아무 곳)으로 끌어다 놓으면 에이전트가 읽을 수 있는 경로로 추가됩니다. 첨부 파일은 파일 이름 알약(pill)으로 보입니다.
이미지 붙여넣기 (Codex)
업데이트된 로컬 Codex 채팅에서는 앱 메뉴나 클립보드로 이미지를 붙여넣습니다. 보내기 전 지울 수 있는 썸네일로 보이고, 눌러서 크게 볼 수 있습니다.
끊겨도 남는 초안
보내지 않은 글과 첨부는 호스트가 복원할 수 있으면 연결이 끊겼다 이어져도 남습니다. 같은 세션이 재연결되는 동안 이미 끝난 대화 기록도 화면에서 지워지지 않습니다(데스크톱·모바일 공통).
@ 파일 고르기
초안에 @를 치면 워크트리 파일을 골라 경로로 넣습니다. 모바일 Chat UI에도 같은 팝오버가 뜹니다.
찾기 · 인용 · 이전 프롬프트
Cmd+F(macOS) / Ctrl+F(Windows·Linux)로 채팅 내 검색. 답변 일부를 선택하고 Add to chat으로 작성창에 인용. 빈 초안에서 ↑/↓로 보냈던 모든 프롬프트를 불러옵니다.
숫자 키로 답하기
에이전트가 번호 선택지가 있는 질문을 하면 숫자 키로 답하고, 다음 질문으로 넘어갑니다.
분할 · 이동
패널 동작으로 Chat UI를 나누거나 다른 패널로 옮겨도 같은 세션이 유지됩니다.
diff 카드 · 링크
에이전트의 파일 수정은 인라인 diff 카드로 보입니다. 대화 속 파일 경로·링크를 누르면 Orca에서 열립니다.
복사
답변 속 코드 상자(펜스 코드 블록(답변 안에 테두리로 따로 묶여 보이는 코드 부분))와 셸 명령은 문법 강조되고 블록마다 Copy code 버튼이 있어 코드만 복사합니다. 데스크톱에서 보낸 메시지에 마우스를 올리면 타임스탬프 옆 버튼으로 복사합니다.
대기열(Queue)과 끼어들기(Steer)
멈추기 · 전송 상태 · 되감기
| Stop | 진행 중인 턴을 끝냅니다. |
|---|---|
| Sending… | 보내는 중. 상대(호스트)가 받았다고 확인할 때까지 이렇게 보입니다. |
| Not sent | 보내지 못했음. 이유가 함께 나오고 Retry로 다시 보냅니다. |
| 미확인(unconfirmed) | 보냈는지 확실치 않을 때, 같은 메시지가 두 번 가는 것을 막으려고 “미확인”으로 둡니다. |
| Rewind to here | 대화를 그 메시지 시점으로 되돌리고, 그 메시지를 작성창에 돌려놓아 고쳐 다시 보내게 합니다. |
긴 대화는 생각·도구 호출 묶음이 한 줄로 접히고, 가장자리 메시지 레일로 원하는 턴에 뛸 수 있어 읽기 쉽습니다.
/ 명령과 스킬
/를 치면 명령과 스킬(에이전트가 불러 쓰도록 저장해 둔 작업 지침 묶음) 목록이 열립니다.
/clear
같은 패널에서 새 대화를 시작합니다. 이전 대화는 기록에 남습니다.
/compact
에이전트에게 지금까지의 대화 분량(문맥(에이전트가 한 번에 기억하며 참고하는 대화·파일 내용))을 줄여 달라고 해 계속 작업하게 합니다.
모델·옵션 알약
작성창 아래 알약에서 모델과 생각 수준(effort(에이전트가 답하기 전에 얼마나 깊이 생각할지 정하는 단계)) 등을 고릅니다.
새 채팅은 가능하면 첫 메시지로 이름이 지어지고, 탭 동작에서 이름을 바꿀 수 있습니다.
구조화 채팅은 맡긴 일·뒤에서 도는 일을 메인 턴 동안과 그 뒤에도 보이게 합니다.
- 백그라운드 작업 띠: 뒤에서 도는 작업 수와 상태가 작성창 근처에 보입니다.
- 계획 체크리스트: 에이전트가 세운 계획이 체크리스트로 보입니다.
- 끝나면: 바뀐 파일과 추가/삭제 줄 수 요약이 나오고, 백그라운드에서 끝난 채팅에는 안 읽음 표시가 붙습니다.
- 에이전트의 질문: 에이전트가 묻는 것은 질문 카드로 보이고, 카드의 Submit으로 답합니다.
- 채팅 ↔ 터미널: 탭을 우클릭해 같은 대화를 채팅 화면과 터미널 화면 사이에서 바꿉니다.
- Hand Off: 다른 에이전트에게 일을 넘깁니다.
- 한도 후 자동 이어가기: 사용 한도에 걸려 멈춘 채팅을, 한도가 풀리면 Orca가 이어 가게 할 수 있습니다.
에이전트 세션 기록 (Agent Session History)
Claude, Codex, Muse Code, Cursor, Gemini 등 에이전트 CLI는 대화 기록(transcript)을 디스크에 파일로 남깁니다. Orca는 이 파일들을 훑어 오른쪽 사이드바의 Agent Session History 패널에 목록으로 보여 줍니다. 지난 세션을 골라 Resume을 누르면, 같은 작업 폴더·같은 세션 ID로 에이전트의 재개 명령을 새 터미널에서 실행합니다. --resume 옵션을 손으로 챙길 필요가 없습니다.
패널 열기와 검색
오른쪽 사이드바를 열고 Agents 탭으로 바꾸면 머리글에 “Agent Session History”가 보입니다. 머리글의 12 shown · 47 recent 같은 개수 옆 검색 상자에 입력하면 세션 제목, 작업 폴더, 브랜치, 모델, 대화 미리보기 글로 거릅니다.
연결된 다른 컴퓨터의 기록까지 검색할 수도 있습니다.
| Workspace | Workspace(워크스페이스 — 워크트리와 같은 것): 현재 워크트리의 세션(활성 워크트리 맥락에 따라) |
|---|---|
| Project | 활성 Orca 프로젝트로 연결되는 세션 |
| All | 이 컴퓨터의 모든 에이전트에서 찾은 모든 세션 |
원격 워크트리에서도 로컬 기록을 둘러볼 수는 있지만, 재개(Resume)는 로컬 워크트리에서만 됩니다. 활성 워크트리가 원격이면 패널이 알려 줍니다.
- Agents: 목록에 넣을 에이전트를 하나씩 켜고 끕니다. Select all / Clear로 한 번에 바꿉니다.
- Group: Project, Folder(작업 폴더마다 제목), Agent(CLI마다 제목).
- Hide empty sessions: 기록된 메시지가 0개인 세션을 숨깁니다.
- 정렬: 둘러볼 때는 Last updated / Created. 검색할 때는 Most relevant / Newest로 바뀌고, 관련도가 같으면 새 세션이 먼저입니다. 검색 정렬은 둘러보기 정렬과 따로 기억됩니다. 검색이 훑기 한도에 닿으면 결과 아래 Show more로 더 과거까지 찾습니다.
세션 행을 누르면 상세가 열립니다: 작업 폴더, 브랜치, 모델, 메시지 수, First prompt, 최근 대화 턴. First prompt는 펼칠 때 기록 파일에서 잘리지 않은 첫 사용자 메시지를 불러오며(목록 행은 검색용 짧은 미리보기만 가짐), 카드의 Copy로 긴 프롬프트 전체를 복사해 다시 쓸 수 있습니다. 활성화된 세션 행을 워크트리로 끌어다 놓아도 재개됩니다.
| Resume | 그 세션의 작업 폴더에서 새 터미널을 열고, 에이전트별 “이어서 하기” 명령을 대신 입력해 줍니다(명령 예시는 아래 접힌 상자). |
|---|---|
| Resume in New Native Chat | 이전 대화가 보이는 새 구조화 채팅 탭으로 엽니다(자격 있는 세션). Claude는 원래 워크트리에서만, Codex는 다른 워크트리에서도 재개됩니다. 폴더 워크트리에서 시작한 채팅은 같은 폴더에서 재개됩니다. 반대로 Resume in New CLI는 구조화 채팅을 터미널로 갈라 냅니다. 둘 다 탭 우클릭 메뉴에도 있습니다. 채팅용으로 예약된 대화는 터미널 Resume을 쓸 수 없습니다. |
| Copy resume command | 같은 셸 명령을 클립보드에 복사(외부 터미널용) |
| Copy session ID / Copy log path | 스크립트나 버그 보고에 기록 첨부용 |
| Open log / Reveal log | 원본 기록 파일을 Orca에서 열거나 OS 파일 관리자에서 보여 줌 |
| Open cwd | 세션의 작업 폴더를 워크트리로 엶 |
--session <path>)로 재개합니다. 그 파일이 없으면 세션 id가 있어도 그 행의 Resume은 쓸 수 없습니다.Orca는 각 에이전트가 원래 쓰는 기록 저장소를 읽습니다. 따로 켤 것은 없고, CLI가 기록을 쓰면 다음 훑기 때 패널에 나타납니다. 머리글의 Refresh Session History로 바로 다시 훑습니다.
| Codex | ~/.codex/sessions |
|---|---|
| Claude | ~/.claude 기록 |
| Muse Code | ~/.local/share/muse/sessions |
| Cursor | Cursor 세션 로그 |
| OpenCode | 예전 세션 파일 또는 ~/.local/share/opencode/opencode.db |
| CodeBuddy | .codebuddy/projects 아래 프로젝트 기록 |
| ZCode | 저장된 기록 |
| Qoder | ~/.qoder/projects 기록 |
- Orca는 어떤 CLI 에이전트든 터미널에서 띄울 수 있고, 40여 개는 한 번 클릭으로 실행·설정됩니다. 가장 깊게 통합된 것은 Claude Code·Codex·Muse Code·Cursor CLI입니다.
- 에이전트는 “설치 → 한 번 로그인 → Orca 선택 상자에서 고르기” 순서로 씁니다.
- 워크트리는 버려도 되는 복사본이라 새 실행에는 확인 생략(Yolo)이 미리 켜져 있고, Settings → Agents → Agent Permissions에서 Manual로 바꿀 수 있습니다.
- Codex·Claude 계정은 다시 로그인하지 않고 바꿔 끼우며, 바꾼 계정은 새 세션부터 쓰입니다.
- Chat UI는 터미널 대신 메신저 같은 화면으로 에이전트와 대화하게 해 주고, 대기열·끼어들기·되감기·@파일·/ 명령·모델 고르기를 지원합니다.
- Agent Session History로 지난 대화를 찾아 Resume으로 이어 갈 수 있고, 재개는 로컬 워크트리에서만 됩니다.
- 휴면(실험 기능)은 일을 마치고 오래(기본 30분) 손대지 않은 에이전트를 멈춰 컴퓨터 자원을 아끼고, 워크트리를 다시 열면 같은 대화로 자동으로 이어 갑니다.
- 저장소의 훅과
CLAUDE.md/AGENTS.md는 그대로 따르고, 상태 훅 덕분에 탭에 작업 중·대기·완료 점이 뜹니다. - 터미널은 찾기, 링크 메뉴, 테마, 기본 셸 고르기를 지원하고, 플로팅 터미널은 단축키 한 번으로 뜨며, Quick Commands로 자주 쓰는 명령·부탁 문장을 저장합니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 3장에 있습니다.
워크트리별 내장 브라우저와 디자인 모드
Orca에는 워크트리마다 따로 쓰는 진짜 Chromium 브라우저가 들어 있습니다. 사람은 이 브라우저로 만든 화면을 확인하고, 에이전트는 글자 명령(CLI)으로 같은 브라우저를 조작합니다. 디자인 모드를 켜면 화면의 요소를 클릭하는 것만으로 “이걸 고쳐 줘”를 에이전트에게 전할 수 있습니다.
워크트리마다 하나씩 있는 브라우저
이 브라우저는 흉내만 낸 미리보기 창이 아니라 진짜 Chromium(Google Chrome의 바탕이 되는 공개 브라우저 엔진) 창입니다. 주소창, 방문 기록(history), 개발자 도구(DevTools)를 모두 갖추고 Orca의 한 pane(칸)(Orca 화면을 나눈 한 구역. 터미널·편집기·브라우저 등을 칸마다 띄움)에 들어 있습니다. 탭이 워크트리 단위로 묶이기 때문에, 지금 만들고 있는 앱의 화면이 다른 작업의 탭과 섞이지 않습니다.
화면 구성과 조작법
일반 브라우저와 거의 같지만, Orca 안에서 쓰기 좋게 몇 가지가 더해져 있습니다.
localhost:3000/loginDesign ModeDevTools⋯- 주소창(address bar): 방문 기록과 퍼지(fuzzy) URL 자동 완성(철자가 조금 틀려도 비슷한 주소를 찾아 주는 자동 완성)을 지원합니다.
- 주소가 아닌 글자를 입력하면 Default Search Engine(기본 검색 엔진)으로 검색합니다. 새 탭의 검색창(omnibox — 주소와 검색어를 함께 받는 입력칸)과 같은 엔진입니다.
- 새 탭(+) 화면의 검색칸에서 검색어 앞에
?를 붙이면 주소처럼 보이는 글자라도 무조건 검색합니다. - 단어를 더블클릭하면 다른 브라우저처럼 그 단어가 선택됩니다.
- 뒤로 / 앞으로 / 새로 고침 / 중지 버튼이 있습니다. 새로 고침 버튼에 마우스를 올리면 일반 새로 고침 단축키가 보입니다.
- 새로 고침 버튼을 오른쪽 클릭(또는 길게 누르기)하면 Reload(새로 고침)와 Hard Reload(강력 새로 고침)가 단축키와 함께 나옵니다. Hard Reload는 캐시(한 번 받은 파일을 다시 받지 않으려고 저장해 두는 임시 보관함)를 건너뛰므로, 내 컴퓨터에서 화면 파일(CSS·JS 등 — 웹 페이지의 모양과 동작을 정하는 파일)을 고치며 확인할 때 유용합니다.
| 단축키 (원문에는 macOS 키만 나옴) | 동작 |
|---|---|
| Cmd+T (macOS) | 새 탭 열기(이 워크트리 전용) |
| Cmd+Option+B (macOS) | 오른쪽에 화면을 나눠(split) 브라우저 탭 열기. Settings → Keyboard(설정 → 키보드)에서 바꿀 수 있음 |
| Cmd+Shift+T (macOS) | 마지막으로 닫은 탭 다시 열기 |
| Cmd+F (macOS) | 페이지 안에서 찾기 |
- 소리가 나는 탭에는 스피커 표시가 붙습니다. 그 표시를 누르면 그 탭만 음소거하거나 다시 켭니다.
- 새 탭은 화면에 보이지 않아도 뒤에서 미리 로드되므로, 전환했을 때 주소·제목·이동 상태가 이미 준비되어 있습니다. 단, 재시작 후 되살린 탭 가운데 아직 보고 있지 않은 탭은 열어 볼 때 로드될 수 있습니다.
- DevTools(개발자 도구) 버튼으로 현재 페이지를 검사합니다. 도구 창을 칸의 한쪽에 붙이거나(dock), 크기를 조절하거나, 공간이 부족하면 별도 창으로 떼어 낼(pop out) 수 있습니다.
- 링크에 마우스를 올리거나 포커스를 주면 페이지 아래쪽에 목적지 주소가 표시됩니다.
- 칸이 좁아지면 부가 도구는 overflow 메뉴(⋯)로 접히고, 이동 버튼·주소창·Cmd+F는 계속 쓸 수 있게 남습니다.
- 터미널이나 채팅에서 연 링크는 그 링크를 준 칸 옆에 열립니다.
- 에이전트가 브라우저를 쓰는 중이면 페이지 위에 에이전트 커서와 활동 배지가 나타납니다. 채팅에 있는 브라우저 링크를 누르면 그 페이지로 바로 이동합니다.
새 창·팝업이 열리는 규칙, HTML 미리보기와 브라우저 탭의 전환, 페이지에 포커스가 있을 때의 단축키 동작은 아래 접힌 상자에 있습니다.
원격 워크트리에서 화면 그리기
회사 서버 등 원격 컴퓨터에서 작업하지 않으면 이 절은 건너뛰세요.
왜 필요할까? 작업 폴더가 내 PC가 아니라 다른 컴퓨터(예: 회사 서버)에 있을 때가 있습니다. Orca에서는 이런 작업 공간을 Workspace(워크스페이스 — 워크트리와 같은 것)라고도 부르는데, 이 장에서는 “원격 워크트리”라고 하겠습니다. 이럴 때도 브라우저를 쓸 수 있고, 연결 방식은 두 가지입니다.
- Remote Orca Server(Orca 원격 서버)와 짝지은(paired) 원격 워크트리 — 다른 컴퓨터에 Orca 서버를 띄워 내 Orca와 짝지은 경우
- SSH(다른 컴퓨터에 안전하게 접속해 명령을 실행하는 방법) 원격 워크트리
짝지은 원격 서버에서는 기본적으로 화면은 내 PC에서 그리고, 웹사이트와 주고받는 인터넷 통신은 원격 컴퓨터를 거쳐 나갑니다. 그래서 키보드 입력·글자 선택·팝업은 내 PC에서 자연스럽게 동작하면서도, 웹사이트 입장에서는 원격 컴퓨터에서 접속한 것으로 보입니다. 브라우저 툴바의 호스트 표시(통신이 어느 컴퓨터를 거쳐 가는지 보여 주는 표시)로 확인할 수 있습니다.
Settings → Browser → Remote server workspaces(설정 → 브라우저 → 원격 서버 워크트리)에서 This device(이 기기)를 고르면 위 그림처럼 동작합니다(기본값). 입력·선택·팝업이 이 기기에서 자연스럽게 처리됩니다.
다만 이렇게 내 PC에서 그리는 페이지는 내 PC가 켜져 있어야 합니다. 에이전트가 이 페이지를 조작하는데 PC가 꺼지거나 잠들거나 연결이 끊기면 오류가 납니다.
같은 설정에서 Server (streamed)(서버, 스트리밍)를 고르면 페이지가 원격 서버에서 실행되고 화면만 내 PC로 전송됩니다. 내 PC가 연결되어 있지 않아도 돌아가므로, 오래 걸리거나 사람이 지켜보지 않는 자동화에 더 알맞습니다.
SSH 원격 워크트리에서는 Browse through SSH workspace hosts(SSH로 접속한 컴퓨터를 거쳐 탐색) 설정이 브라우저의 인터넷 통신(주소 찾기 포함)을 SSH로 접속한 컴퓨터로 보낼지, 이 기기에서 직접 보낼지를 정합니다.
내 PC에서 그리는 원격 페이지에서 받은 다운로드는 원격 컴퓨터에 저장되고, 업로드할 파일도 먼저 그 컴퓨터에 옮겨 놓은 뒤 페이지에 전달됩니다.
디자인 모드(Design Mode)
디자인 모드는 Orca 브라우저를 “화면을 가리키면 그 부분의 코드로 이어지는” 도구로 바꿉니다. 켜고 나서 화면의 아무 버튼·글상자 같은 요소나 클릭하면, 그 요소의 정보가 에이전트 채팅에 첨부됩니다. 함께 가는 정보는 DOM(웹 페이지를 이루는 부품 구조), 계산된 CSS(그 부품에 실제로 적용된 색·글꼴·간격 같은 모양 값), 그리고 스크린숏입니다.
켜기
브라우저 툴바의 Design Mode 토글을 누릅니다. 마우스 커서가 요소를 고르는 도구(picker)로 바뀌고, 마우스를 올린 요소가 강조 표시됩니다. Annotate page element(페이지 요소에 메모 달기) 동작은 Settings → Shortcuts(설정 → 단축키)에서 원하는 키로 바꿀 수 있는 단축키로도 제공됩니다.
클릭하면 채팅으로 들어가는 것
HTML
그 부품의 코드(outer HTML)와 주변 조금
계산된 CSS
색, 글꼴, 간격 등 실제 적용 값
스크린숏
그 요소만 잘라 낸 이미지
소스 위치
개발 모드 소스 맵(화면 코드가 원래 어느 파일 몇째 줄인지 알려 주는 지도 파일)이 있으면 파일·줄 번호
이것들이 첨부 하나로 묶여 지금 쓰고 있는 에이전트 창에 들어가고, 사용자는 바꾸고 싶은 내용을 글로 적기만 하면 됩니다.
디자인 모드 순환
에이전트가 코드를 고치면 핫 리로드(코드를 고치면 화면이 저절로 새로 고쳐지는 기능)로 브라우저 화면이 바로 바뀝니다. 다시 클릭해 확인하고, 맞을 때까지 반복합니다.
페이지 메모 모아 보내기(annotation tray)
요소마다 메모를 달아 두었다가 한꺼번에 보낼 수도 있습니다.
- 메모 트레이에 여러 개의 메모를 쌓아 두었다가 한꺼번에 에이전트에게 보낼 수 있습니다.
- 메모 위에 마우스를 올리고 Edit(편집)을 누르면 그 자리에서 코멘트나 의도(intent)를 고칠 수 있고, 끝나면 Save(저장) 또는 Cancel(취소)을 누릅니다.
- Send(보내기)와 Copy(복사)는 기본적으로 메모마다 짧은 요약만 담습니다. 메모에 이미지를 붙여 넣을 수도 있습니다.
- 페이지 전체 세부 정보까지 보내려면 Send 메뉴에서 Include page details(페이지 세부 정보 포함)를 고릅니다. Orca는 이 선택을 그 브라우저 칸에 기억합니다.
- 프롬프트가 전달되면 Orca는 보낸 메모를 페이지에서 지웁니다. 전달이 진행되는 동안 새로 추가하거나 고친 메모는 페이지에 남습니다.
레시피: 디자인 모드로 UI 버그 고치기
디자인 모드는 “저 버튼 이상해 보여”에서 “고친 결과를 저장”까지의 과정을 1분 안쪽으로 줄여 줍니다.
그 워크트리의 브라우저 칸을 열고 버그가 있는 페이지로 이동합니다.
툴바의 Design Mode 토글을 켭니다.
망가진 요소를 클릭합니다. 그 요소가 풍부한 첨부로 에이전트 채팅에 들어갑니다.
예: “이 padding(안쪽 여백)이 너무 좁아. 위쪽 카드들과 같게 늘려 줘.”
에이전트가 코드를 고치면 핫 리로드(화면 자동 새로 고침)로 브라우저가 바로 바뀝니다.
요소를 다시 클릭해 확인합니다. 아직 틀리면 4단계부터 반복합니다.
맞게 되면 commit(지금까지 바꾼 내용을 기록에 한 덩어리로 저장해, 나중에 돌아올 수 있는 지점을 만드는 일)합니다.
스크린숏을 직접 찍을 필요도, 페이지의 부품 구조(DOM)를 뒤질 필요도, 그 부품을 가리키는 주소(선택자, selector)를 복사할 필요도 없습니다. 에이전트는 사용자가 가리킨 바로 그 요소의 코드(HTML), 실제 모양 값(계산된 CSS), 잘라 낸 이미지를 받습니다. 사람 검토자라도 받고 싶어 할 바로 그 정보입니다.
- 워크트리마다 진짜 Chromium 브라우저가 있고, 탭·스크롤 위치는 워크트리별로 저장·복원됩니다.
- (macOS) Cmd+T 새 탭, Cmd+Shift+T 닫은 탭 복원, Cmd+F 찾기, Cmd+Option+B 오른쪽 분할 탭. Hard Reload는 캐시를 건너뜁니다.
- 쿠키는 Chrome·Edge·Vivaldi·파일에서 가져오되 Google 로그인은 Orca 안에서 직접 해야 합니다.
- 원격 워크트리는 기본적으로 화면은 내 PC, 인터넷 통신은 원격 컴퓨터를 거침. 사람이 지켜보지 않는 자동화엔 Server (streamed).
- 링크 라우팅·Hold Shift…로 Orca/시스템 브라우저를 고르고, 확장은 실험 기능, 아티팩트 공유는 파일당 10 MiB(약 10MB)·같은 폴더의 사진 등 따로 불러오는 파일은 제외.
- 프로필은 쿠키·저장소·캐시가 완전히 분리된 신원이며, 에이전트 명령도 활성 프로필을 따릅니다.
- 디자인 모드: 요소 클릭 → HTML·CSS·스크린숏·소스 위치가 채팅에 첨부 → 에이전트 수정 → 핫 리로드(화면 자동 새로 고침) → 다시 확인 → commit(저장 지점 만들기).
- 에이전트는 마우스 대신 화면 요소에 번호표를 붙이고, 그 번호표를 보고 누르거나 입력합니다. 같은 브라우저·같은 탭이라 하는 일을 화면에서 지켜볼 수 있습니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 4장에 있습니다.
파일 편집과 보기 — 에디터, 마크다운, 뷰어, 파일 탐색기
Orca 안에서 파일을 직접 고치고, 문서를 보기 좋게 다듬고, PDF·이미지·영상·표·노트북을 열어 보고, 파일을 찾아 에이전트에게 건네는 방법을 다룹니다.
한눈에 보는 편집 영역
Orca의 각 워크트리(에이전트마다 따로 꺼내 주는 프로젝트 폴더의 작업용 복사본)에는 왼쪽에 파일 탐색기, 가운데에 파일을 여는 탭이 있습니다. 파일을 열면 종류에 맞는 화면이 자동으로 열립니다. 코드는 Monaco 에디터, 마크다운 문서는 리치 에디터, PDF·이미지·영상·표·노트북은 전용 뷰어로 열립니다.
코드 에디터(Monaco)와 자동 저장
Orca의 코드 에디터는 Monaco입니다. VS Code(널리 쓰이는 코드 편집 프로그램)가 쓰는 바로 그 편집기라서 VS Code를 써 본 사람은 거의 같은 감각으로 쓸 수 있고, 여기에 Orca만의 몇 가지 조정이 더해졌습니다.
자동 저장과 "디스크에서 바뀜" 배너
무엇인가 — 파일은 저절로 저장됩니다. 다른 곳을 클릭해 에디터에서 벗어날 때, 그리고 잠깐 타이핑을 멈추고 있을 때 저장됩니다. 그래서 다른 편집기에서 흔히 보는 "아직 저장 안 됨" 표시 점이 없습니다. 평소에는 저장 안 된 변경이 생기지 않기 때문입니다.
왜 검사가 필요한가 — Orca에서는 사람과 에이전트가 같은 파일을 만질 수 있습니다. 그래서 Orca는 저장하기 직전에 "이 탭이 마지막으로 파일을 읽거나 저장한 뒤에 디스크의 파일이 바뀌었나?"를 확인합니다.
파일을 고치고 다른 탭이나 터미널을 클릭하면(또는 잠시 손을 멈추면) 자동 저장됩니다.
탭이 마지막으로 읽거나 쓴 뒤 디스크의 파일이 바뀌었습니다. 다음 저장 직전 Orca가 이를 알아챕니다.
배너가 뜨고 자동 저장이 멈춥니다. 내가 친 내용은 탭 안에 그대로 남아 있어 사라지지 않습니다.
- compare(비교) — 디스크 쪽 내용과 내 편집을 비교합니다.
- reload(다시 불러오기) — 디스크 쪽 내용으로 탭을 새로 고칩니다.
- keep your edits(내 편집 유지) — 탭의 내용을 그대로 둡니다.
- overwrite(덮어쓰기) — 디스크 쪽 내용을 내 편집으로 바꿉니다. 내가 직접 골라야만 일어납니다.
SSH로 접속한 원격 컴퓨터의 파일을 열 때만 해당하는 내용(같은 경로의 파일이라도 컴퓨터마다 편집 내용을 따로 보관)은 아래 접힌 상자에 있습니다.
마크다운 문서 에디터(리치 에디터)
마크다운(#를 붙이면 제목, -를 붙이면 목록이 되는 식으로, 간단한 기호로 서식을 다는 글 문서 형식. 확장자 .md) 파일은 기본으로 리치 에디터로 열립니다. 기호 대신 완성된 모양(제목은 큰 글씨, 목록은 점)을 보면서 바로 고치는 방식이라 워드 프로그램과 비슷합니다. 슬래시 메뉴, 도구 모음, 이미지·코드 미리보기, 내부 링크 자동완성을 갖추고 있습니다.
- Cmd+Shift+M (macOS) — 기호가 그대로 보이는 원문(raw) 에디터와 리치 에디터를 언제든 오갑니다.
- 운영체제의 "다음으로 열기" — Orca는 macOS·Windows·Linux에서 마크다운 파일의 Open With(다음으로 열기) 목록에 자신을 등록합니다. 원래 쓰던 기본 편집기를 바꾸지는 않습니다. 리치 에디터로 열고 싶을 때 그 메뉴에서 Orca를 고르면 됩니다.
- 600 KB보다 큰 파일은 타이핑이 느려지지 않도록 원문(raw) 에디터로 먼저 열립니다. 안내 배너에서 Open anyway(그래도 열기)를 누르면 리치 에디터로 열리며, 이 선택은 그 탭을 닫을 때까지 유지됩니다.
- 리치 에디터가 망가뜨리지 않고 지킬 수 없는 마크다운 문법을 쓴 파일은 원문 에디터에 머뭅니다.
파일 탐색기
파일 탐색기는 각 워크트리 왼쪽에 있으며 디스크의 파일을 실시간으로 따라갑니다. 만들기·이름 바꾸기·삭제·이동이 모두 실제 파일에 그대로 적용되고, 에이전트처럼 바깥에서 생긴 변경도 바로 나타납니다. 정렬은 폴더 먼저, 그다음 파일이며, 이름 속 숫자를 수로 이해하는 순서(9, 99, 100)입니다.
git 상태 색 — 파일 이름 색이 다른 이유
탐색기의 파일 이름은 git(파일의 변경 이력을 기록하는 도구)이 보는 상태에 따라 색이 다릅니다. 색만 봐도 "새로 만든 파일인지, 고친 파일인지"를 알 수 있습니다.
그림의 색은 설명을 위한 예시입니다.
| 상태 | 뜻 · 왜 생기나 |
|---|---|
| untracked | 새로 만들어서 git이 아직 기록해 본 적 없는 파일. 에이전트나 내가 새 파일을 만들면 생깁니다. |
| modified | 기록된 적 있는 파일을 그 뒤에 고친 상태. |
| staged | 고친 내용을 다음 커밋(변경을 하나의 저장 지점으로 기록하는 일)에 넣기로 표시해 둔 상태. 오른쪽 클릭 → stage 등으로 생깁니다. |
| ignored | 프로젝트가 "git이 신경 쓰지 않을 파일"로 정해 둔 것. 임시 파일처럼 기록할 필요 없는 파일이 해당합니다. |
- 코드는 Monaco 에디터로 열리고, 다른 곳을 클릭하거나 잠깐 멈추면 자동 저장됩니다. 그 사이 디스크의 파일이 바뀌었으면 저장을 멈추고 비교/다시 불러오기/유지/덮어쓰기 중 고르게 합니다.
- (macOS) Cmd+D 다음 같은 단어 선택, Cmd+F 파일 안 찾기, Cmd+Shift+F 전체 찾기, Alt+Z 줄 바꿈. 파일 저장(자동)과 커밋(돌아올 수 있는 기록)은 다릅니다. 변경 보기(Changes view)는 빨강=지운 줄, 초록=더한 줄(n/p/s).
- 마크다운은 리치 에디터(macOS Cmd+Shift+M로 원문). 600 KB 초과는 원문 먼저. 슬래시 메뉴·토글·콜아웃·
[[링크·리뷰 노트·프런트 매터·표·목차·공개 링크 공유(설정에서 허용, 10 MiB(약 10MB)까지). - HTML은 격리된 미리보기, Mermaid·PDF·이미지·오디오/비디오·CSV(약 1MB 이상은 보기 전용)·Jupyter(신뢰 후 내 컴퓨터의 Python으로 실행) 전용 뷰어.
- 탐색기는 실시간·숫자 순 정렬, 파일 색은 git 상태(새 파일·고친 파일·커밋 대기·무시). 끌어다 놓으면 커서 아래 대상으로: 트리=복사, 마크다운=이미지 삽입, 터미널=경로 붙여넣기, SSH=올린 뒤 경로.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 5장에 있습니다.
리뷰와 배포 — diff 보기부터 PR·이슈 연동까지
에이전트가 코드를 고쳤다면 이제 사람이 꼼꼼히 확인하고, 저장(커밋)하고, 서버로 올리고(푸시), 동료에게 검토를 부탁(PR)할 차례입니다. 이 장은 그 과정을 Orca 안에서 한 번에 끝내는 방법과, GitHub·GitLab·Bitbucket·Jira·Linear 같은 바깥 서비스와 연결하는 방법을 다룹니다.
먼저 알아 둘 말: diff · 스테이징 · 커밋 · 푸시 · PR · CI
이 장에는 git 용어가 많이 나옵니다. 처음 보는 분도 따라올 수 있게 먼저 하나씩 풀어 보겠습니다. 바탕이 되는 말은 세 가지입니다. git(파일을 언제 누가 어떻게 바꿨는지 기록해 두는 도구), 브랜치(같은 프로젝트에서 갈라져 나온 독립된 작업 줄기 — 다른 작업과 섞이지 않음), 워크트리(브랜치 하나를 위한 별도 작업 폴더. Orca는 작업마다 하나씩 만듭니다).
- diff(차이) — 어제 원고와 오늘 원고를 나란히 놓고 빨간 펜(지운 부분)과 초록 펜(새로 쓴 부분)으로 표시한 것입니다.
- 스테이징(staging) — 고친 것 중 “이번에 낼 부분”만 골라 봉투에 넣어 두는 것입니다. 명령으로는
git add입니다. - 커밋(commit) — 봉투를 봉하고 “무엇을 고쳤는지” 메모(커밋 메시지)를 붙여 내 서랍에 보관하는 것입니다. 아직 내 컴퓨터 안에만 있습니다.
- 푸시(push) — 서랍 속 봉투를 학교 사물함(원격 저장소, 보통
origin이라 부르는 GitHub 같은 서버)에 갖다 넣는 것입니다. - PR(풀 리퀘스트) / MR(머지 리퀘스트) — “제 작업 좀 봐 주시고 괜찮으면 본 원고(main 브랜치)에 합쳐 주세요” 하는 검토 요청서입니다. GitHub·Bitbucket은 PR, GitLab은 MR이라고 부릅니다. 이 장에서는 둘을 묶어 호스팅 리뷰(hosted review)라고도 합니다.
- CI(지속적 통합) / 체크(checks) — 요청서를 내면 자동 채점기가 돌아 테스트·검사를 해 주는 것입니다. GitHub에서는 GitHub Actions, GitLab에서는 파이프라인(pipeline)이 이 일을 합니다.
- 머지(merge, 병합) — 검토가 끝난 작업을 본 원고에 합치는 것입니다.
여기에 몇 가지 용어를 더 알아 두면 뒤가 편합니다.
| 용어 | 쉬운 뜻 |
|---|---|
| GitHub · GitLab · Bitbucket | 코드를 올려 두고 여러 사람이 함께 검토하는 웹사이트. 위 그림의 “원격(학교 사물함)”이 바로 이런 곳입니다. Azure DevOps·Gitea도 같은 종류의 서비스입니다. |
| 이슈(issue) | 할 일·버그 신고를 적은 카드. 엑셀 할 일 목록의 한 줄이라고 생각하면 됩니다. GitHub·Jira·Linear 모두 이슈를 다룹니다. |
| 칸반(kanban) 보드 | “할 일 · 하는 중 · 끝남” 같은 칸에 포스트잇을 붙여 두고 칸에서 칸으로 옮기는 보드. |
| 토큰(token) | 비밀번호 대신 쓰는 출입증 문자열. 서비스 설정 화면에서 만들어 Orca에 붙여 넣으면, Orca가 그 출입증으로 대신 들어갑니다. 필요 없어지면 언제든 폐기할 수 있습니다. |
| ref / start-from ref | “어느 시점의 코드”를 가리키는 이름표(브랜치 이름, 커밋 번호 등). start-from ref는 워크트리를 만들 때 출발점으로 삼은 지점입니다. |
| base 브랜치 | PR이 최종적으로 합쳐질 대상 브랜치(보통 main). |
| hunk(헝크) | diff 안에서 붙어 있는 변경 덩어리 하나. 파일 하나에 여러 hunk가 있을 수 있습니다. |
| upstream | 내 로컬 브랜치와 짝을 이루는 원격 브랜치. 처음 푸시할 때 정해집니다. |
| merge base(분기점) | 내 브랜치와 base 브랜치가 갈라진 지점. |
| rebase · amend · squash | 이미 만든 커밋 기록을 다시 쓰는 방법들(다른 지점 위로 옮기기 / 마지막 커밋 고치기 / 여러 커밋 합치기). 기록이 바뀌므로 원격과 어긋날 수 있습니다. |
| 병합 충돌(merge conflict) | 두 쪽이 같은 줄을 다르게 고쳐서 git이 어느 쪽을 택할지 모르는 상태. |
| pre-commit hook | 커밋 직전에 저장소가 자동으로 돌리는 검사(코드 모양·실수 자동 검사). 실패하면 커밋이 막힙니다. |
Diff viewer — AI가 만든 코드를 제대로 읽는 화면
무엇인가. Orca의 Diff viewer(차이 보기 화면)는 AI가 만든 코드를 “슬쩍 훑어보는” 용도가 아니라 진지하게 리뷰하도록 설계되었습니다. 모든 워크트리에는 자기 start-from ref와 비교한 diff가 기본으로 들어 있습니다.
왜 필요한가. 에이전트는 빠르게 많은 줄을 바꿉니다. 무엇이 바뀌었는지 정확히 보지 않고 커밋하면 버그도 함께 배포됩니다.
기능 목록
합친 diff (Combined diff)
스테이징된 것, 스테이징 안 된 것, git이 아직 추적하지 않는 새 파일(untracked)까지 모두 한 화면에 모아 보여 줍니다.
줄 번호
바뀌기 전·후 양쪽 줄 번호를 표시하며, 켜고 끌 수 있습니다.
이미지 diff
이미지 같은 바이너리 파일(글자가 아닌 파일)은 side-by-side(나란히), swipe(밀어서 비교), onion-skin(반투명 겹치기) 세 가지 방식으로 비교합니다.
HTML 미리보기
HTML 파일이면 눈 모양 아이콘을 눌러 옆 화면에서 웹페이지 모습으로 미리 봅니다.
병합 충돌 UI
충돌이 나면 3방향 보기(three-way view: 내 쪽 · 상대 쪽 · 결과)로 보여 주고, 그 자리에서 해결할 수 있습니다. 그림 보기
hunk·줄 단위 스테이징
git add -p(변경을 조각조각 골라 스테이징하는 명령)와 같은 일을 눈으로 보며 클릭으로 합니다.
Show Whitespace
공백·탭 같은 보이지 않는 문자를 드러냅니다. diff viewer의 actions 메뉴에서 켜고 끕니다.
Collapse unchanged regions
파일 diff에서 바뀌지 않은 긴 구간을 접어 바뀐 줄만 눈에 들어오게 합니다. diff editor actions 메뉴에서 켜며, 기본값은 꺼짐입니다.
비교 범위 바꾸기 (Scoping)
기본으로는 워크트리의 start-from ref와 비교합니다. diff 툴바에서 비교 대상을 아무 커밋, 아무 브랜치, 또는 base ref로 바꿀 수 있습니다. 예를 들어 “마지막 커밋 이후 바뀐 것만” 보고 싶을 때 유용합니다.
Word wrap (자동 줄바꿈)
켜면 긴 줄이 그 자리에서 접혀 내려가서 가로 스크롤 없이 위에서 아래로 읽을 수 있습니다. 기본값은 꺼짐입니다. 합친 diff에서는 왼쪽 파일 트리를 접었다 펴고 너비를 바꿀 수 있습니다.
단축키
Annotate AI Diff — 코멘트를 모아 한 번에 돌려보내기
무엇인가. Annotate AI Diff는 에이전트가 만든 코드를 위한 Orca의 줄 단위 리뷰 순환입니다. AI가 만든 hunk의 아무 줄에나 코멘트를 남긴 뒤, 그 코멘트들을 한 묶음(batch)으로 에이전트에게 보내 고치게 합니다. 줄 번호를 복사해 붙이거나 다른 창으로 오갈 필요가 없습니다.
코멘트 남기기
- 줄 위에 마우스를 올립니다거터(줄 번호 옆 여백)에 +가 나타납니다. 여러 줄에 달고 싶으면 이웃한 줄들을 끌어서 고르거나, Shift를 누른 채 선택을 넓힙니다. Orca는 선택 범위를 그 hunk 안으로 제한하고, 고른 줄 범위를 라벨로 붙입니다.
- +를 클릭합니다또는 커서를 그 줄에 두고 c를 누릅니다.
- 의견을 씁니다마크다운(제목·목록·코드 표시 같은 간단한 서식 문법)을 쓸 수 있습니다.
- 저장하거나 취소합니다Enter 또는 Cmd/Ctrl+Enter로 저장, Shift+Enter로 줄바꿈, Esc로 취소합니다.
코멘트는 정확히 그 줄에 고정(pin)됩니다. 코드가 수정되어 diff 위치가 밀려도 Orca가 추적해서 코멘트가 그 줄을 따라갑니다.
묶음 보내기 (Send the batch)
리뷰를 다 했으면 diff 맨 위의 Send to agent(에이전트에게 보내기)를 누릅니다. Orca가 모든 코멘트를 줄 위치와 함께 하나의 프롬프트로 엮은 뒤, 그 워크트리에서 쓸 수 있는 에이전트 목록이 담긴 Send notes to 메뉴를 엽니다. 수정을 맡길 에이전트를 고르거나, 같은 메뉴에서 새 에이전트를 시작할 수 있습니다.
왜 묶어서 보내나요?
답하기 · 해결 처리 · 재리뷰
- 에이전트가 고친 뒤에도 코멘트는 그 자리에 고정되어 남습니다. 고쳐졌는지 확인하는 체크리스트로 쓰면 됩니다.
- Resolve(해결)를 누르면 그 코멘트 스레드가 접힙니다.
- 해결하지 않은 코멘트는 Send를 다시 누를 때 다음 묶음에 포함됩니다.
커밋 · 푸시 · PR 만들기 — Orca를 떠나지 않고
Orca 안에서 커밋하고, 푸시하고, 리뷰(PR)까지 열 수 있습니다. 커밋 패널은 Diff viewer 바로 옆에 있으며, 가장 흔한 흐름인 리뷰 → 스테이징 → 커밋 → 푸시 → 다음 일에 맞춰 설계되어 있습니다.
- 스테이징diff에서 hunk 단위 또는 파일 단위로 스테이징합니다.
- 커밋 메시지 쓰기아래 패널에 직접 쓰거나, 스테이징한 변경을 바탕으로 Orca가 초안을 써 주길 원하면 Generate with AI(AI로 생성)를 누릅니다.
- CommitmacOS는 Cmd+Enter, Windows/Linux는 Ctrl+Enter. 단, 포커스가 Source Control에 있고 주 버튼이 Commit일 때 동작합니다.
저장소에 있는 pre-commit hook(커밋 직전에 코드 모양·실수를 자동으로 검사하는 장치)은 평소처럼 실행됩니다. hook이 실패하면 Orca가 그 출력을 그 자리에 보여 줍니다.
Push는 워크트리의 브랜치를 origin(원격, 학교 사물함)으로 올립니다. 처음 푸시할 때는 upstream(내 브랜치와 짝을 이루는 원격 브랜치)도 함께 정합니다. 브랜치가 원격보다 뒤처져 있으면 Orca는 몰래 강제 푸시하지 않습니다.
정리하면, rebase·amend·squash로 기록을 다시 써서 원격에는 내 로컬 커밋의 옛날 사본만 있는 상황이면 Source Control 패널이 Force push with lease(조건부 강제 푸시)를 따로 떨어진 버튼으로 보여 줍니다. 일반 Push가 실패했을 때 대신 쓰이는 일은 절대 없습니다.
- 버튼 라벨에 바뀌게 될 커밋 개수와 upstream 브랜치 이름이 표시되어, 무엇이 바뀌는지 정확히 알 수 있습니다.
--force-with-lease를 쓰므로, 내가 알고 있는 원격 상태가 오래된 것이면 푸시가 중단됩니다. 그 사이 다른 사람이 올린 커밋을 덮어쓰지 않습니다.
브랜치를 푸시한 뒤에는 Source Control 패널의 호스팅 리뷰 동작으로 PR(또는 MR)을 만듭니다. 만들기 전에 base 브랜치·제목·설명·초안(draft) 여부를 확인하세요.
- Bitbucket Cloud도 같은 작성 화면에서 PR을 만들 수 있습니다. Bitbucket Cloud에는 초안 PR이 없어서 Draft 항목이 숨겨집니다.
- GitHub에서 고른 base에 이미 열린 PR이 있으면 Stack this PR above #N(#N 위에 이 PR 쌓기)을 고를 수 있습니다(아래 스택 PR 참고).
PR 제목·설명은 AI가 초안을 써 줄 수 있고, 만드는 도중 문제가 생기면 이유와 Fix with AI 버튼이 담긴 안내가 나옵니다.
Amend(마지막 커밋 고치기)는 명시적으로만 합니다: Commit → Amend. 이미 푸시된 커밋은 사용자가 확인하지 않으면 Orca가 amend하지 않습니다.
Source Control 패널
사이드바의 Source Control(소스 관리) 패널은 지금 보고 있는 화면을 떠나지 않고 같은 동작을 할 수 있게 해 줍니다. 파일을 스테이징하거나 변경을 버리고(discard), 커밋 메시지를 쓰고, Commit · Push · Pull · Sync를 한 번 클릭으로 실행합니다.
- Push(푸시) — 내 서랍의 봉투를 학교 사물함(원격)으로 갖다 넣기.
- Pull(풀) — 사물함에 있는 봉투(다른 사람이나 다른 컴퓨터가 넣은 것)를 내 서랍으로 가져오기.
- Sync(싱크) — 가져오기와 올리기를 함께 하기. 양쪽에 다 새 봉투가 있을 때 씁니다.
- upstream — 내 서랍과 짝으로 정해진 사물함 칸. 처음 Push할 때 정해집니다.
→ main+128 −34
맨 위 줄에는 지금 브랜치와 합칠 대상(branch → base)이, 그 옆 작은 칩에는 늘어난/줄어든 줄 수가 보입니다.
패널 맨 아래 주 버튼은 상태에 따라 바뀌어서, 다음에 할 일이 항상 클릭 한 번 거리에 있습니다.
충돌이 났을 때
병합 충돌(두 쪽이 같은 줄을 다르게 고쳐서 git이 어느 쪽을 택할지 모르는 상태)이 생기면 Diff viewer가 3방향 보기로 보여 주고 그 자리에서 해결할 수 있습니다.
merge·rebase·cherry-pick(다른 브랜치의 커밋 하나만 가져오기)·revert(커밋 되돌리기) 후 충돌이 남으면, Source Control은 Review conflicts(충돌 검토) 옆에 Resolve with AI(AI로 해결)를 보여 줍니다. 충돌 묶음을 에이전트에게 넘기거나, 직접 확인한 뒤 진행하면 됩니다. 진행 중인 merge나 rebase를 그만두고 싶다면 Source Control의 Abort merge 또는 Abort rebase를 쓰세요.
저장소별 AI 액션 레시피 (Action recipes)
“Generate with AI”처럼 AI가 움직이는 버튼들이 어떤 지시문으로 어떤 에이전트를 부를지 바꾸는 설정입니다. 기본값 그대로 써도 되므로 처음에는 건너뛰어도 됩니다.
레시피: AI diff를 줄 단위로 리뷰하기
AI diff를 잘 리뷰하느냐가 “빠르게 배포”와 “버그를 배포”를 가릅니다. 아래 순환을 그대로 따라 해 보세요. 이전/다음 버튼으로 한 단계씩 넘길 수 있습니다.
1. diff 열기
워크트리의 diff 보기를 엽니다.
2. 파일별로 훑기
j / k로 파일을 하나씩 넘깁니다. hunk마다 세 가지를 물어보세요.
- 이 변경이 꼭 필요한가?
- 최소한으로 바꿨나?
- 파일의 나머지 부분과 어울리나(스타일·구조)?
3. 코멘트 남기기
바꾸고 싶은 곳에 c로 코멘트를 답니다. 완전한 문장으로 쓰는 것이 가장 효과적입니다.
4. Send to agent
diff 전체를 다 봤으면 Send to agent를 누릅니다. Orca가 모든 코멘트를 프롬프트 하나로 묶습니다.
5. 에이전트가 고치는 모습 지켜보기
6. 쉬는 상태가 되면 다시 diff 열기
에이전트가 idle(쉬는 상태)이 되면 diff를 다시 엽니다. 코멘트는 그대로 고정되어 있습니다. 고쳐진 것은 Resolve하고, 나머지에는 후속 코멘트를 남깁니다.
7. 깨끗해질 때까지 반복, 그다음 커밋
더 고칠 것이 없을 때까지 3~6단계를 반복한 뒤 커밋합니다. 이후는 커밋 · 푸시 · PR 만들기를 따르세요.
코드를 모른다면
2단계의 세 질문은 코드를 읽을 줄 알아야 답할 수 있습니다. 코드를 모르면 대신 이렇게 확인하세요.
- 바뀐 파일 수·범위가 요청과 맞는지 보기 — “메모 화면 글자색만 바꿔 줘”라고 했는데 파일이 열 개 넘게 바뀌었다면 이상한 신호입니다. 파일 트리와 늘어난/줄어든 줄 수 칩만 봐도 알 수 있습니다.
- 모르는 줄에는 질문 코멘트 달기 — 그 줄에서 c를 누르고 “이 줄이 하는 일을 쉬운 말로 설명해 줘”라고 적어 보내면, 에이전트가 설명해 줍니다. 설명이 요청과 어긋나면 그때 고쳐 달라고 하면 됩니다.
- 결과 화면을 직접 보기 — 화면(HTML)을 바꾼 작업이면 Diff viewer의 눈 모양 아이콘이나 내장 브라우저로 결과 화면을 열어, 원하던 모습인지 눈으로 확인합니다.
- 변경은 작업 폴더 → 스테이징 → 커밋 → 원격 → PR/MR 순서로 이동하고, Orca는 이 전 과정을 Diff viewer·커밋 패널·Source Control 패널에서 처리합니다.
- Diff viewer: 합친 diff, 이미지·HTML 미리보기, 3방향 충돌 해결, hunk/줄 스테이징, 공백 표시, 구간 접기·줄바꿈(둘 다 기본 꺼짐), 비교 대상 변경, 파일 트리. 단축키 j/k, n/p, F7, s, c.
- Annotate AI Diff: 줄에 코멘트를 고정하고 Send to agent로 한 번에 보냅니다. 보내기 단축키는 기본으로 비어 있으니 Settings → Shortcuts에서 지정합니다.
- Attribution: AI가 쓴 줄을 거터에 표시하며 Orca 로컬 전용입니다(커밋되지 않음, 필요하면 내보내기).
- Push는 몰래 강제 푸시하지 않고, 기록을 다시 쓴 경우에만 별도의 Force push with lease가 나타납니다. Amend는 명시적이고, 푸시된 커밋은 확인을 받습니다.
- Generate/Fix/Resolve with AI와 PR 내용 생성은 Action recipes(AI 버튼이 어떤 지시문으로 움직이는지 정하는 설정)로 에이전트·인자·템플릿을 저장소별로 바꿀 수 있습니다.
- GitHub는 Orca가 가장 많은 기능을 지원하는 서비스로, 자동 병합·스택 PR·반응·Fix broken checks·Actions 빨간 칩·Projects 칸반까지 지원하고, GitLab·Bitbucket·Azure DevOps·Gitea도 같은 리뷰 흐름에 들어옵니다.
- Jira(Cloud/Self-hosted, 여러 사이트)와 Linear(API 토큰, 팀 선택, 이미지 맥락 포함)는 작업 패널(옆에서 밀려 나오는 패널)에서 이슈를 다루고 워크트리와 연결합니다.
- 리뷰 레시피: 열기 → j/k로 훑기 → c로 코멘트 → Send to agent → 지켜보기 → Resolve·후속 코멘트 → 깨끗해지면 커밋. 코드를 모르면 바뀐 범위 확인 · “쉬운 말로 설명해 줘” 코멘트 · 결과 화면 확인으로 대신합니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 6장에 있습니다.
Orca CLI와 자동화 — 명령, 예약 작업, 오케스트레이션, Computer Use, 스킬
마우스로 하던 Orca 조작을 글자 명령으로 할 수 있게 해 주는 orca 명령줄 도구를 배웁니다. 사람이 스크립트로 쓸 수도 있고, AI 에이전트가 직접 Orca를 움직이는 데도 씁니다.
CLI란 무엇이고, 왜 에이전트가 Orca를 조작하나
Orca 앱은 보통 버튼과 메뉴로 씁니다. 그런데 같은 일을 글자로 된 명령으로 시킬 수도 있습니다. 예를 들어 “새 작업 공간 만들어 줘”를 버튼 대신 orca worktree create --name my-task라고 타이핑하는 식입니다. 이렇게 글자 명령을 입력하는 창을 터미널(글자로 명령을 입력하고 결과를 글자로 돌려받는 창. 맥의 ‘터미널’ 앱, 윈도우의 PowerShell 등)이라 하고, 그 안에서 쓰는 조작 방식을 CLI(Command-Line Interface, 명령줄 인터페이스 — 버튼 대신 명령어로 프로그램을 조작하는 방식)라고 부릅니다.
글자 명령의 큰 장점은 사람이 아니어도 칠 수 있다는 것입니다. Claude·Codex 같은 AI 에이전트는 화면의 버튼을 누르기는 어렵지만 터미널에 명령을 치는 건 아주 잘합니다. 그래서 에이전트가 orca 명령을 치면, 에이전트가 직접 Orca를 움직여 새 워크트리를 만들고, 다른 에이전트에게 일을 시키고, 브라우저를 클릭하고, 진행 상황을 남길 수 있습니다. 이것이 “에이전트가 Orca를 조작한다”는 뜻입니다.
- 런타임(지금 켜져서 일하고 있는 Orca 프로그램 본체) —
orca명령은 혼자 일하지 않고, 이 런타임에게 “이것 좀 해 줘” 하고 말을 전합니다. 그래서 Orca가 켜져 있어야 대부분의 명령이 동작합니다. - 셸(shell — 터미널 창 속에서 명령을 받아 실행하는 프로그램. zsh, bash, PowerShell 등) — “셸에서 실행한다” = “터미널에 쳐서 실행한다”로 읽으면 됩니다.
- 스크립트(명령 여러 개를 적어 둔 작업 순서표. 엑셀 매크로와 비슷합니다) — 사람이 한 줄씩 치지 않아도 순서대로 자동 실행됩니다.
명령 한 줄 읽는 법 — 해부도
orca 명령이 이 순서입니다. 옵션(--로 시작하는 부분)은 여러 개 붙을 수 있고, 값이 필요 없는 옵션(--json처럼)은 이름만 씁니다. JSON(프로그램끼리 주고받기 좋게 정해진 틀로 적은 글자 데이터)은 사람보다 스크립트·에이전트가 읽기 편한 형식입니다.orca CLI는 이미 실행 중인 Orca에게 말을 걸어 일을 시킵니다. 에이전트도 사람과 똑같은 명령을 씁니다.정리하면 Orca CLI는 “아무 셸에서나, 실행 중인 Orca를 스크립트로 조작하는 orca 명령”입니다. 할 수 있는 일은 다음과 같습니다.
워크트리
워크트리(작업마다 따로 꺼내 놓은 프로젝트 폴더)를 만들고, 목록을 보고, 상태를 기록합니다.
에이전트 터미널
에이전트가 돌고 있는 터미널을 읽고, 글자를 보내고, 끝날 때까지 기다립니다.
파일·diff
파일과 diff(무엇이 바뀌었는지 이전과 비교해 보여 주는 화면)를 Orca 탭으로 엽니다.
내장 브라우저
Orca 안 브라우저 탭을 이동·클릭·입력·스크린샷합니다.
예약 자동화
정해진 시간에 프롬프트를 실행합니다.
아티팩트 공유
HTML·Markdown을 공개 링크로 공유합니다.
Orca 고유 도구
오케스트레이션, Computer use, 에뮬레이터, Linear 등을 스크립트나 AI 에이전트가 제어합니다.
설치·등록과 동작 확인
CLI는 데스크톱 앱에 함께 들어 있습니다. 따로 내려받는 게 아니라, 앱 설정에서 “터미널에서 orca를 쓸 수 있게 등록”만 하면 됩니다.
orca status --json으로 연결만 확인하면 됩니다.- CLI 등록앱 설정에서 Orca CLI를 등록합니다. 버전에 따라 Settings → General → Orca CLI(설정 → 일반) 또는 Settings → Experimental → CLI(설정 → 실험 기능)에 있습니다.
- 명령이 보이는지 확인
command -v orca—orca명령의 위치가 출력되면 등록된 것입니다. 성공: 경로가 한 줄 나옵니다. 실패: 아무것도 나오지 않으면 ①(설정에서 등록)로 돌아갑니다. - Orca와 연결되는지 확인
orca status --json— CLI가 실행 중인 Orca 런타임에 닿는지 확인합니다. - Orca가 꺼져 있다면
orca open --json으로 연 뒤 다시orca status --json을 실행합니다.
command -v orca
orca status --json
# Orca가 실행 중이 아니라면
orca open --json
orca status --json
코드 속 #로 시작하는 줄은 설명 메모입니다. 실행되지 않습니다.
--json을 붙이는 이유
다른 도구(스크립트·에이전트)가 결과를 읽어야 할 때는 --json을 붙이세요. 사람이 읽기 좋은 출력은 터미널에서 빠르게 확인할 때만 씁니다.
에이전트에게 CLI 사용법 가르치기 — 에이전트가 이 명령들을 정확히 쓰도록, 앱 버전과 맞는 orca-cli 스킬(에이전트용 사용 설명서)을 설치할 수 있습니다. 스킬은 뒤의 스킬 레지스트리에서 다룹니다.
명령 레퍼런스 — 분야별
여기는 에이전트·스크립트가 정확한 명령을 찾아보는 사전입니다. 처음 읽는다면 아래 지도와 탭마다 맨 위 한 문장(“이걸로 할 수 있는 일”)만 훑고 다음 절로 넘어가세요. 명령 목록은 탭 안의 🔧 접힌 상자에 있습니다. 모든 명령 끝의 --json은 “기계가 읽을 결과로 달라”는 뜻입니다.
이걸로 할 수 있는 일 — Orca를 켜고(open), 연결을 확인하고(status), 화면 없는 컴퓨터에서 Orca를 서버로 계속 돌려 둘(serve) 수 있습니다.
이걸로 할 수 있는 일 — Orca에 저장소(프로젝트 폴더)를 추가·확인하고, 지난 에이전트 대화 기록에서 “rate limit” 같은 낱말을 검색할 수 있습니다.
이걸로 할 수 있는 일 — 예: “fix-login이라는 워크트리를 만들고 Codex에게 ‘로그인 테스트를 조사해 줘’라고 바로 시켜라” — 이런 일을 한 줄로 시킬 수 있습니다.
이걸로 할 수 있는 일 — 이미 있는 워크트리에서 에이전트를 하나 더 띄우거나, 워크트리에 PR·Linear 이슈 링크를 여러 개 붙여 두고 나중에 이슈 번호로 그 작업과 담당 에이전트를 찾을 수 있습니다.
이걸로 할 수 있는 일 — 에이전트가 돌고 있는 터미널 화면을 읽고, “continue”를 입력해 주고, 일이 끝날 때까지 기다릴 수 있습니다.
이걸로 할 수 있는 일 — 바뀐 파일이나 그 변경 내용(diff)을 Orca 화면의 탭으로 열어 줍니다.
이걸로 할 수 있는 일 — 사람이 웹 화면을 확인하듯, Orca 안의 내장 브라우저에서 주소로 이동하고, 입력칸을 채우고, 버튼을 누르고, 스크린샷을 찍을 수 있습니다.
이걸로 할 수 있는 일 — Orca 밖의 데스크톱 앱을 누르거나, iOS 시뮬레이터(컴퓨터 속 가상 아이폰)를 탭·회전할 수 있습니다.
이걸로 할 수 있는 일 — 에이전트가 Linear(팀 업무 티켓 관리 서비스)의 티켓을 읽고, 상태를 “진행 중”으로 바꾸고, 댓글을 다는 등 티켓을 관리합니다.
이걸로 할 수 있는 일 — 에이전트용 설명서(스킬)를 설치하고, 원격 컴퓨터에 Claude/Codex 계정을 추가하고, 보고서 HTML·Markdown 파일을 공개 링크로 공유할 수 있습니다.
이걸로 할 수 있는 일 — 예약 프롬프트를 만들고, 관리하는 원격 Orca 서버를 업데이트·복구하고, 에이전트 상태 훅을 켜고 끌 수 있습니다.
- 결과를 프로그램이 읽어야 하면
--json을 붙인다(기계가 읽기 쉬운 형식). - 화면에 보이는 글자로 대상을 짐작하지 말고,
id:같은 정확한 선택자(대상을 가리키는 이름표)로 고른다. - 다음에 무엇을 입력할지 분명하지 않으면, 보내기 전에 터미널 화면을 먼저 읽어 본다.
- 진행 상황은 워크트리 카드의 코멘트로 남긴다(체크포인트).
- 누가 무엇을 맡았고 끝났는지 따라가야 하는 여러 에이전트 작업은, 터미널에 그때그때 지시를 넣는 대신 오케스트레이션을 쓴다.
오케스트레이션 — 여러 에이전트를 감독하며 일 나누기 Experimental
팀장(코디네이터 에이전트)이 할 일 목록(Task)을 만들고, 팀원(워커 에이전트)에게 하나씩 맡긴 뒤(Dispatch), 우편함(Inbox)으로 “다 했어요”(worker_done)나 “질문 있어요”(question) 편지를 받는 구조입니다. 중요한 결정은 팀장이 “결정 관문”(Decision gate)을 세워, 답이 나올 때까지 그 일을 멈춰 둡니다.
언제 쓰나 — 누가 맡았는지(소유), 끝났는지(완료 추적), 작업 간 순서(DAG(“A가 끝나야 B 시작” 같은 순서 관계를 화살표로 이은 그림))가 필요할 때 씁니다. 한 번 던지는 프롬프트라면 orca terminal send, 감독 없이 일을 통째로 넘기려면 orca-cli 스킬의 worktree/terminal 명령을 쓰세요.
- 이 명령을 쓰기 전에 Settings → Experimental(설정 → 실험 기능)에서 orchestration을 켜야 합니다.
- 실험적 Orchestration 패널은 성능 문제로 v1.4.247에서 꺼져 있지만, 명령은 여전히 동작합니다.
- CLI는 실행 중인 Orca 런타임과 대화하므로
orca status --json이 먼저 성공해야 합니다.
핵심 낱말 다섯 가지 — 비유로
Run = 프로젝트 폴더
이번 일 전체를 담는 폴더이자 팀장의 우편함입니다. 폴더가 일을 직접 나눠 주지는 않습니다 — 나눠 주는 건 팀장입니다.
Task = 할 일 카드
카드 한 장에 무엇을 할지, 먼저 끝나야 할 카드, 지금 상태(대기·준비·배정됨·완료·실패·막힘)가 적혀 있습니다.
Dispatch = 1회 배정
카드 한 장을 팀원 한 명(터미널 하나)에게 한 번 맡기는 것. 다시 맡기면 새 Dispatch(시도 2)가 됩니다. “다 했어요” 보고는 지금 맡은 배정으로만 받아 줍니다.
Message = 우편함 편지
“다 했어요”(worker_done), “질문 있어요”(question), “아직 일하는 중이에요”(heartbeat) 같은 편지입니다.
Decision gate = 자물쇠
팀장이 답해야 풀리는 자물쇠. 답이 정해질 때까지 그 카드를 잠가 둡니다.
그래서 워커가 “다 했어요”나 “아직 일하는 중이에요”를 보낼 때는 카드 번호(taskId)와 배정 번호(dispatchId)를 둘 다 적습니다. 예전 시도가 엉뚱하게 지금 카드를 완료 처리하지 못하게 하려는 것입니다.
task-update --status blocked로 막힌 상태).권장 감독 루프 — 단계별
아래 ①~⑥ 명령은 보통 코디네이터(팀장 역할 에이전트)와 워커 에이전트가 스스로 칩니다. 사람이 할 일은 코디네이터에게 목표를 말해 주고, 질문·결정이 올라오면 답하고, 결과를 확인하는 것입니다.
① Run 만들기
orca orchestration run-create --objective "Split checkout QA and summarize blockers" --json
목표(objective)를 가진 이름 공간과 코디네이터 우편함이 생깁니다.
② Task 만들기
orca orchestration task-create --spec "Audit billing settings for mobile layout" --task-title "Billing audit" --json
③ 워커 시작(= Dispatch 생성)
할 일 카드를 팀원(에이전트)에게 맡깁니다. 이 순간 Dispatch(1회 배정)가 하나 생깁니다.
orca orchestration worker-start --task <taskId> --worktree current --agent codex --json
④ 우편함 확인하며 기다리기(다 읽으면 ack = 받았음 도장)
orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
orca orchestration check --ack <deliveryId> --wait --types worker_done,escalation,question --timeout-ms 900000 --json
--timeout-ms 900000 = 900,000밀리초 = 15분까지 기다린다는 뜻입니다.
팀장은 편지가 올 때까지 기다렸다가, 한 번에 배달된 편지 묶음을 모두 처리한 뒤 --ack로 “받았음” 도장을 찍습니다. 기다리는 동안에도 CLI는 주기적으로 “살아 있어요” 신호(heartbeat)를 냅니다.
⑤ 워커가 완료 보고(워커 창에서)
orca orchestration send \
--type worker_done \
--subject "Completed mobile audit" \
--body "Fixed footer overlap; no follow-ups." \
--task-id <taskId> \
--dispatch-id <dispatchId> \
--outcome succeeded \
--files-modified "src/app/settings/Billing.tsx" \
--json
worker_done은 --outcome succeeded|failed가 필수입니다. ID는 워커에게 주입된 값을 씁니다.
⑥ 정리 — release 또는 retain
orca orchestration worker-release --dispatch <dispatchId> --json
orca orchestration worker-retain --dispatch <dispatchId> --json
받아들여진 worker_done 뒤에는 같은 터미널을 다음 Dispatch에 재사용하거나, release로 내보냅니다(살펴볼 출력은 보관하고 코디네이터 소유 에이전트 터미널만 닫음). 사용자가 남겨 달라고 했다면 디버깅용으로 retain.
코디네이터 ↔ 워커 메시지 흐름
더 깊은 운영 — 접어 둔 부분
워커마다 다른 모델 고르기, 멈춘 워커 살펴보기·복구, 다른 컴퓨터에서 워커 띄우기(연합), 직접 조립하는 저수준 배정, 여러 에이전트에게 한꺼번에 보내는 그룹 주소는 아래 접힌 상자에 있습니다.
워커 계약(Worker contract)
일을 배정받은 워커는 팀장과 연락하는 법이 적힌 안내문(preamble)을 함께 받습니다. 약속은 다섯 가지입니다.
- worker_done은 정확히 한 번실패해도 보내고,
--outcome을 붙입니다. - 짧은 --body 요약한 일, 찾은 것, 남은 것.
- task ID와 dispatch ID 둘 다오래된 재시도가 엉뚱한 Dispatch를 완료 처리하지 못하게 합니다.
- heartbeat배정 안내문이 요구하면, 오래 걸리는 작업 중에 “살아 있어요” 신호를 보냅니다.
- 막히는 질문은 ask로자기 터미널 화면에서 사용자에게 묻지 말고
orca orchestration ask로 팀장에게 묻습니다.
결정 관문(Decision gates)
ask — 워커 → 코디네이터 질문.
gate — 코디네이터가 Task DAG를 만들어 두고, 결정이 기록될 때까지 특정 Task를 막고 싶을 때.
어떤 명령을 고를까
| 상황 | 명령 |
|---|---|
| 지켜보고 있는 에이전트에게 가벼운 프롬프트 | orca terminal send |
| 워커가 worker_done을 보고하고, 코디네이터를 통해 질문하고, Task ID로 추적돼야 함 | orca orchestration worker-start (또는 dispatch --inject) |
| Run(프로젝트 폴더)으로 오래 묶어 두고 감독하는 다중 에이전트 작업 | run-create + Task + 워커 (은퇴한 orchestration run 아님) |
명령 옵션은 앱과 함께 바뀝니다. 설치 후 에이전트는 orca skills get orchestration --full을 실행해 버전에 맞는 전체 가이드를 읽어야 합니다.
워크트리 체크포인트 — 진행 상황 남기기
무엇인가 — 모든 Orca 워크트리에는 UI에 보이는 가벼운 자유 글 코멘트 칸이 있습니다. “이 워크트리가 지금 무엇을 하는 중인지” 보여 주는 상태 스냅샷입니다. 왜 — 에이전트가 CLI로 갱신할 수 있어서, 채팅을 강요하지 않고도 사람 동료에게 진행을 알리는 권장 방법입니다. 일하는 사람이 책상 위에 붙여 두는 “지금 하는 일” 메모지와 같습니다.
fix-search-debounce in-review
added debounce to SearchBar onChange (src/components/SearchBar.tsx); ready for review
goal: reduce redundant API calls per #298
위 카드는 코멘트와 상태가 함께 보이는 모습을 설명하는 흉내입니다.
기본 패턴과 카드 상태
orca worktree set --worktree active --comment "reproduced auth failure; testing credential-chain fix" --json
# 단계가 바뀌면 카드 상태도 함께(선택)
orca worktree set --worktree active \
--comment "fix implemented; running integration tests" \
--workspace-status in-progress \
--json
상태 값: todo in-progress in-review completed 또는 워크트리가 쓰는 사용자 정의 id.
체크포인트를 남기기 좋은 순간
한 조각 완성
구현의 의미 있는 한 조각을 끝냈을 때
추측 확인
가설을 확인하거나 반박했을 때
리뷰 끝
코드 리뷰를 마쳤을 때
막힘
외부 입력 대기, 상위 버그, 접근 권한 없음
단계 전환
조사 → 수정, 수정 → 검증으로 넘어갈 때
쓰는 형식
첫 줄은 행동입니다: 방금 무엇을, 어디서 했고, 상태나 다음 단계는 무엇인지. 그 아래 줄에 목표 같은 맥락을 둡니다.
| 줄 | 무엇을 쓰나 | 예 |
|---|---|---|
| 첫 줄 | 행동 — 방금 무엇을, 어디서, 상태·다음 단계 | added debounce to SearchBar onChange (src/components/SearchBar.tsx); ready for review |
| 다음 줄 | 맥락 — 목표 등 | goal: reduce redundant API calls per #298 |
orca worktree set --worktree active --comment "added debounce to SearchBar onChange (src/components/SearchBar.tsx); ready for review
goal: reduce redundant API calls per #298" --json
코멘트에 사용자가 직접 쓴 맥락(목표·제약)이 있을 수 있으니, 덮어쓰기 전에 읽으세요.
orca worktree current --json
여전히 유효한 것은 남기고, 낡은 것은 버리고, 내 갱신을 그 사이에 엮어 넣습니다.
orca명령은 앱에 들어 있습니다. 설정에서 등록하고orca status --json으로 켜져 있는 Orca(런타임)와 연결되는지 확인합니다.- 명령은 “프로그램 → 대상 → 동작 → 옵션 → 결과 형식” 순서로 읽고, 스크립트·에이전트는
--json과id:·path:같은 정확한 선택자를 씁니다. - 명령 레퍼런스는 에이전트용 사전입니다. 워크트리·터미널·파일·브라우저·에뮬레이터·Linear·아티팩트까지 명령으로 다룹니다.
- 예약 자동화는 꺼진 채 만들고 → 확인하고 → 한 번 돌려 보고 → 켭니다.
- 오케스트레이션(실험 기능): Run(프로젝트 폴더) 안의 Task(할 일 카드)를 Dispatch(1회 배정)로 맡기고, 워커는 “다 했어요”를 정확히 한 번 보냅니다. 질문은 ask, 결정은 자물쇠(gate).
- Computer Use(Beta)는 접근성 권한이 필요하고, 화면을 읽고 → 하나 조작하고 → 다시 읽습니다.
- 스킬은 표지만 설치하고 본문은 앱에서 최신으로 꺼내 읽습니다. 진행 상황은
orca worktree set --comment로, 쓰기 전에 먼저 읽습니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 7장에 있습니다.
원격과 모바일 — SSH, 원격 Orca 서버, 폰 앱
노트북이 아닌 다른 컴퓨터(성능 좋은 개발 서버, GPU 장비, 집에 둔 Mac mini)에서 에이전트를 돌리고, 그 모습을 노트북이나 휴대폰으로 지켜보고 조종하는 방법을 다룹니다.
먼저 알아 둘 말: SSH · 원격 서버 · 페어링
SSH
SSH(Secure Shell — 다른 컴퓨터에 암호화된 통로로 접속해 명령을 실행하게 해 주는 표준 방법)는 인터넷이나 사내망 너머의 다른 컴퓨터에 안전하게 접속하는 통로입니다. 접속할 컴퓨터를 호스트(host — 접속해 들어갈 그 컴퓨터), Orca에 저장한 접속 정보를 SSH 대상(target — 주소·사용자 이름을 적어 둔 즐겨찾기)이라고 부릅니다. 로그인은 보통 비밀번호 대신 키 파일(identity file — 내 컴퓨터에 보관하는 비밀 파일. 이 파일을 가진 사람만 로그인할 수 있음)로 합니다.
원격 Orca 서버
다른 컴퓨터에서 Orca 전체를 계속 실행해 두고, 노트북·휴대폰·브라우저는 화면만 보여 주는 방식입니다. 프로젝트·워크트리(작업마다 따로 쓰는 작업 폴더)·터미널·탭·계정·에이전트 세션이 모두 서버 쪽에 있습니다.
페어링(pairing)
클라이언트(화면을 보여 주는 쪽 — 노트북·폰)와 서버를 한 번 짝지어 서로 믿게 만드는 절차입니다. 서버가 만든 접속 링크나 코드·QR을 클라이언트에 넣으면, 그 기기 전용 토큰(출입증 같은 비밀 문자열. 서버가 이 출입증만 취소하면 그 기기만 내보낼 수 있음)이 생깁니다.
LAN
LAN(Local Area Network — 근거리 네트워크)은 같은 사무실이나 집의 공유기 안에 묶인 네트워크입니다. 같은 Wi‑Fi·공유기에 붙은 기기끼리 바로 통하는 길이라고 보면 됩니다. 이 장에서 "믿을 수 있는 LAN", "집 LAN"이라고 할 때 이 뜻입니다.
Orca Relay
Relay(중계)는 이름 그대로 Orca가 중간에서 폰과 데스크톱 사이를 전달해 주는 중계소입니다. 모바일 페어링에서 쓸 수 있으면 권장되는 길이며, 이 길을 쓸 때만 데스크톱과 폰 두 기기 모두 같은 Orca 계정 로그인이 필요합니다. Relay로 짝지은 폰은 데스크톱의 Relay 연결을 따라갑니다.
Tailscale·tailnet
Tailscale(여러 기기를 하나의 사설 네트워크로 묶어 주는 VPN 서비스)은 내 기기들끼리만 쓰는 비공개 네트워크를 만들어 주는 도구입니다. 그 네트워크를 tailnet이라 하고, 각 기기는 보통 100.으로 시작하는 사설 주소를 받습니다.
헤드리스(headless)
모니터·창 없이 돌아가는 컴퓨터나 프로그램. 클라우드 리눅스 서버, VM(가상 머신 — 한 컴퓨터 안에 소프트웨어로 만든 또 하나의 컴퓨터)이 대표적입니다. orca serve가 Orca를 창 없이 실행합니다.
포트 포워딩
포트(한 컴퓨터 안의 프로그램마다 붙은 문 번호) 포워딩은 원격에서 띄운 개발 서버(예: 3000번 포트)를 내 노트북 브라우저에서 localhost(내 컴퓨터 자신을 가리키는 주소)처럼 열게 해 주는 연결입니다.
어떤 방식을 고를까: SSH 워크트리 vs 원격 Orca 서버
Orca를 실행하는 방법은 네 가지(로컬, SSH, 자체 호스팅 서버, 일회용 VM)이며, 이 장은 그중 SSH와 원격 Orca 서버를 다룹니다. 둘 다 "다른 컴퓨터에서 일을 시킨다"는 점은 같지만, 누가 Orca의 두뇌(런타임 — 실제로 판단하고 기억하는 Orca 본체)를 가지느냐가 다릅니다. 아래 그림에서 초록 상자(두뇌)가 어디 있는지만 보세요.
노트북의 Orca가 주인입니다. 다른 컴퓨터는 고른 워크트리와 터미널만 실행하는 "작업장"으로 씁니다. 편집기와 diff는 노트북에 있고, 에이전트는 원격 호스트에서 돕니다.
- 좋은 경우: 오래 걸리는 빌드, GPU 장비, 노트북이 적합하지 않은 환경
- 설정: Settings → SSH에 호스트 추가
다른 컴퓨터의 Orca가 주인입니다. 그 컴퓨터가 Orca 런타임 전체를 갖고, 데스크톱·브라우저·모바일·자동화 클라이언트가 같은 세션을 공유합니다.
- 좋은 경우: 늘 켜 둘 Mac mini·데스크톱·헤드리스 리눅스 서버, 여러 기기에서 같은 세션 보기
- 설정: Settings → Remote Orca Servers 또는
orca serve - Beta 베타 기능입니다.
호스트 키 확인 — "이 서버가 진짜 그 서버인가?"
known_hosts 파일입니다.Orca의 내장 SSH 연결은 내 컴퓨터에서 실제로 적용되는 OpenSSH(컴퓨터에 깔린 표준 SSH 프로그램) known_hosts 파일들과, Orca가 예전에 저장해 둔 키를 기준으로 확인합니다.
| 상황 (관련 설정) | Orca의 동작 |
|---|---|
| 전에 접속한 서버이고 지문이 같을 때 | 아무것도 묻지 않고 조용히 접속 |
| 처음 접속하는 서버일 때 (기본 설정) | 받아들이고 기억하며, 지문(fingerprint)을 보여 줌 |
엄격 모드를 켠 경우 (StrictHostKeyChecking yes) | 처음 보는 호스트는 거부 |
확인을 끈 경우 (StrictHostKeyChecking no / off) | 받아들이지만 신뢰 기록은 저장하지 않음 |
| 지문이 바뀌었거나, 폐기된(revoked) 키이거나, 키 종류가 예상과 다를 때 | 비밀번호나 키 암호를 묻기 전에 거부 |
고급 연결 옵션과 인증(암호 · MFA · Kerberos · 보안키)
한 줄 요약: 키 암호는 Orca가 켜져 있는 동안만 기억하고, 인증 코드(OTP·MFA)를 묻는 서버는 Orca가 질문을 화면에 띄워 줍니다. 회사 로그인(Kerberos)이나 USB 보안키처럼 특별한 방식은 Orca가 알아서 컴퓨터에 깔린 표준 SSH 프로그램으로 넘겨 처리합니다.
원격 Orca 서버 Beta
한 컴퓨터가 일을 하고, 다른 컴퓨터는 화면만 제공합니다. 서버가 프로젝트·워크트리·터미널·탭·제공자 계정·에이전트 세션을 가지고, 노트북은 실행 중인 그 Orca에 접속합니다. 가장 쉬운 방법은 양쪽 모두 Orca 데스크톱 앱 + Tailscale이며, 이 경우 orca serve는 필요 없습니다.
권장: 데스크톱 앱 + Tailscale
준비 0단계 — 먼저 두 컴퓨터를 같은 Tailscale에 묶어 둡니다.
- 두 컴퓨터 모두에 Tailscale 설치 — 설치 방법은 Tailscale 공식 안내를 따릅니다. 두 컴퓨터 모두 최신 Orca도 설치해 둡니다.
- 두 컴퓨터 모두 같은 Tailscale 계정으로 로그인 — 그래야 같은 tailnet(내 기기끼리만 쓰는 비공개 네트워크)에 들어갑니다.
- 서버 컴퓨터는 켜 두기 — 깨어 있고, 인터넷에 연결돼 있고, Orca가 실행 중이어야 합니다.
- 준비 완료 확인 — 서버 컴퓨터의 Orca 연결 주소 목록(아래 서버 ③단계)에
100.으로 시작하는 주소가 보이면 준비 완료입니다. Orca는 이 주소를 목록 맨 위에 둡니다.
세션을 계속 돌릴 컴퓨터에서 Orca 데스크톱 앱을 열고 Settings → Remote Orca Servers로 갑니다.
Advertise this app as a server(이 앱을 서버로 알리기) 아래의 New Link를 누릅니다.
Connection address에서 Tailscale 주소(보통 100.x.y.z)를 고릅니다. 목록에 없으면 Tailscale이 연결됐는지 확인하고 Connection address 옆 새로고침 버튼을 누르세요.
Connection address:
100.64.1.20 ⟳Generate Access Link
Generate Access Link를 누르고 Pair another Orca client 아래의 링크를 복사합니다. 이 접근 권한은 나중에 취소할 수 있습니다.
노트북에서 Settings → Remote Orca Servers → Add Server를 누르고, 알아보기 쉬운 이름(예: Remote Server)을 넣고, 서버에서 받은 링크를 붙여 넣은 뒤 Add Server를 누릅니다.
저장된 서버가 Disconnected로 보이면 Connect를 누릅니다. 서버를 추가해도 새 프로젝트가 모두 그 서버로 가지는 않습니다. 새로 여는 프로젝트(와 그 터미널·브라우저·모바일 연결)를 기본으로 이 서버에서 열고 싶으면 Advanced → Active Server를 켜세요.
서버 사용하기
서버가 Connected가 되면 서버나 그 프로젝트를 골라 평소처럼 Orca를 씁니다. 터미널·에이전트 프로세스·파일·워크트리·세션 상태는 모두 서버 컴퓨터에 있습니다. 그래서:
- 클라이언트 노트북이 잠들거나 끊겨도 에이전트는 계속 돕니다.
- 서버에는 에이전트가 쓰는 저장소·도구·자격 증명(로그인 정보)이 있어야 합니다.
- 서버는 깨어 있고 tailnet에 연결된 상태여야 합니다.
접근 권한과 보안
Orca는 페어링한 클라이언트마다 따로따로, 취소 가능한 토큰을 만들고, 서버의 Shared Server Access에 목록으로 보여 줍니다. 지킬 일은 세 가지입니다.
🗑 필요 없어진 기기는 바로 내보내기
Shared Server Access에서 그 기기 옆 휴지통 버튼을 누르면 취소되고, 그 권한을 쓰던 클라이언트는 즉시 끊깁니다.
🎯 닿을 수 있는 기기를 최소로
Tailscale 관리 화면에서 이 서버에 닿을 수 있는 기기를 꼭 필요한 것만 남기세요.
🚫 인터넷에 직접 열지 않기
Orca 서버는 Tailscale이나 믿을 수 있는 LAN 같은 사설 경로로만 쓰세요.
대안: orca serve (헤드리스 서버)
데스크톱 창 없이 돌려야 할 때 — 예를 들어 헤드리스 리눅스 서버나 서비스로 관리되는 VM — orca serve를 씁니다. 로그인한 채 둘 수 있는 MacBook·데스크톱이라면 위의 앱 안 설정이 더 간단합니다. 서버에 Orca와 함께 들어 있는 CLI를 설치하고 실행합니다.
orca serve --pairing-address <server-tailscale-ip-or-hostname>
# 예
orca serve --pairing-address 100.64.1.20
# 방화벽·터널·서비스 정의가 고정 포트를 요구할 때
orca serve --port 6768 --pairing-address 100.64.1.20
실행하면 터미널에 페어링 URL이 찍힙니다. 이 URL을 클라이언트의 Settings → Remote Orca Servers → Add Server에 붙여 넣으면 됩니다.
orca serve 프로세스를 띄우지 마세요.헤드리스 서버에 폰 연결하기
모바일 앱용으로는 모바일 범위의 QR 코드와 링크를 요청합니다.
orca serve --pairing-address 100.64.1.20 --mobile-pairing
폰을 같은 tailnet에 두고, Orca Mobile에서 Pair를 고른 뒤 터미널에 뜬 QR 코드를 찍거나 출력된 링크를 붙여 넣습니다.
서비스로 계속 돌리기
한 줄 요약: 컴퓨터가 켜지면 자동으로 Orca 서버를 띄워 두는 등록입니다. 등록·상태 확인·해제 명령 세 개만 기억하면 됩니다(아직 Windows에서는 쓸 수 없음).
orca serve service install --port 6768
orca serve service status
orca serve service uninstall
데스크톱 앱인가, orca serve인가?
| 서버에서 데스크톱 앱 | orca serve | |
|---|---|---|
| 잘 맞는 곳 | 오래된 노트북, Mac mini, 데스크톱 | 헤드리스 리눅스, VM, 관리형 서비스 |
| 설정 | 설정 화면과 버튼 | 터미널 명령과 서비스 설정 |
| 서버 창 | 열려 있음 | 없음 |
| 접근 링크 | New Link → Generate Access Link | 터미널에 출력 |
| 살아 있는 기간 | 데스크톱 앱이 실행 중인 동안 | 앞 프로세스나 서비스가 실행 중인 동안 |
원격 서버 문제 해결
Tailscale 주소가 목록에 없음
서버에서 Tailscale이 연결됐는지 확인하고 Connection address 옆 새로고침을 누르세요. 두 컴퓨터가 같은 tailnet에 로그인해야 합니다. Tailscale IPv4 주소는 보통 100.으로 시작합니다.
서버가 Disconnected
서버 컴퓨터가 깨어 있는지, Orca가 실행 중인지, Tailscale에서 두 기기가 온라인인지 확인하세요. 한쪽이 닿지 않으면 Tailscale 관리 화면에서 두 기기가 서로 닿도록 허용돼 있는지(ACL·grant — 어느 기기가 어느 기기에 닿을 수 있는지 정하는 규칙) 확인하세요. 서버 줄에 호환되지 않는 프로토콜 버전이 보이면 두 컴퓨터 모두 Orca를 업데이트하세요.
접근 링크를 엉뚱한 사람에게 보냈음
서버에서 Settings → Remote Orca Servers → Shared Server Access를 열고 그 권한을 취소한 뒤, 원래 클라이언트용 새 링크를 만드세요.
서버가 에이전트 CLI를 찾지 못함
그 CLI를 서버 컴퓨터에 설치하고 로그인하세요. 원격 세션은 클라이언트가 아니라 서버의 PATH·홈 디렉터리·자격 증명을 씁니다.
orca serve가 잘못된 주소를 알림
명령을 멈추고 클라이언트가 닿을 수 있는 주소로 다시 시작하세요: orca serve --pairing-address <reachable-tailscale-ip-or-hostname>. 원격 클라이언트용으로 와일드카드 주소(특정 주소 대신 "아무 주소나"를 뜻하는 값)나 127.0.0.1을 쓰지 마세요.
모바일 앱(Orca Mobile) Beta
Orca 모바일 컴패니언은 iOS·Android 앱으로, 데스크톱 Orca와 짝을 지어 주로 보기 위한(read-mostly) 화면을 제공합니다. 에이전트 상태, 최근 터미널 출력, 그리고 폰에서 정말 필요한 조작(질문에 답하기, 워크트리 재우기, 소스 컨트롤 검토, 에이전트 계정 바꾸기)이 들어 있습니다. 페어링은 한 번이면 되고, 진짜 데이터와 작업은 언제나 데스크톱에 있고 폰은 그걸 보여 줄 뿐입니다. iOS는 App Store에서, Android는 최신 APK로 설치합니다(아래 절 참고).
모바일에서 할 수 있는 일
👀 보기
연결된 모든 컴퓨터의 워크트리·에이전트 상태(작업 중 / 완료 / 입력 대기), 파일, 최근 터미널 출력을 한 화면에서.
💬 답하기
에이전트가 기다리면 짧은 답장, 사진·파일 첨부, 받아쓰기로 답하기. 저장해 둔 명령(Quick Commands) 실행.
🌳 워크트리·호스트
폰에서 워크트리를 만들고 에이전트 시작. 저장된 컴퓨터의 이름·주소 고치기.
🔔 기타
에이전트가 끝나면 푸시 알림. 브라우저 탭을 폰 크기로 확인. 바뀐 파일 검토·커밋, 에이전트 계정 바꾸기.
페어링하기
데스크톱 Orca의 계정 / 상태 메뉴(account / status menu)에서 페어링 흐름을 엽니다. Orca가 일회용 페어링 코드를 보여 줍니다.
Orca 모바일 앱에서 Pair를 고르고 코드를 붙여 넣습니다. 데스크톱의 딥 링크를 눌러 모바일 페어링 화면으로 바로 갈 수도 있습니다.
가능하면 Orca Relay(Orca가 중간에서 전달해 주는 중계소)로 페어링하세요. Relay를 쓸 때만 데스크톱과 폰 두 기기 모두 같은 Orca 계정으로 로그인해야 합니다(LAN·Tailscale로 짝지을 때는 로그인이 필요 없습니다). Relay에서는 로컬 네트워크 주소 선택이 선택 사항이며(같은 공유기 안의 LAN으로 빠르게 가고 싶을 때 펼침), LAN 페어링에는 주소가 꼭 필요합니다.
페어링 교환으로 그 폰 전용 기기 토큰이 생깁니다. 고른 경로로 데스크톱에 계속 닿을 수 있게 두세요.
페어링 후 폰은 데스크톱의 기기 이름으로 호스트를 부르고 운영체제를 보여 줍니다. 기기 이름은 데스크톱 Settings → Remote Orca Servers에서 바꿀 수 있으며, 폰은 다시 연결될 때 바뀐 이름을 가져옵니다.
orca serve --mobile-pairing을 쓰세요.Chat UI · Quick Commands · 세션 탭
한 줄 요약: 지원되는 에이전트(Claude, Codex 등)는 폰에서 메신저 같은 대화 화면(Chat UI)으로 열 수 있고, 데스크톱에 저장해 둔 명령 목록(Quick Commands)을 폰에서 그대로 실행할 수 있습니다. 세션 탭을 길게 누르면 닫기·화면 바꾸기 메뉴가 나옵니다.
계정 전환기 · 워크트리 만들기
폰에서 계정을 바꾸면 페어링된 데스크톱의 계정이 바뀝니다. 폰 홈 화면의 Create Workspace / New Workspace로 데스크톱에 새 워크트리를 만들 수도 있습니다.
페어링된 호스트 편집
호스트 목록에서 카드의 ⋯(또는 카드 길게 누르기) → Edit host.
| 항목 | 설명 |
|---|---|
| Name | 이 폰에서만 쓰는 표시 이름. 데스크톱 기기 이름보다 우선하며, 비우면 데스크톱 이름으로 돌아감 |
| Address | IP, host:port, 또는 ws:///wss://. 포트를 빼면 현재 포트를 유지(없으면 기본 6768). 이 폰이 접속하는 곳만 바뀌고 다시 페어링하지 않음. 같은 데스크톱에 다른 경로(집 LAN ↔ Tailscale)로 닿을 때 사용 |
주소를 바꿔 저장하면 새 엔드포인트로 다시 연결하며, 페어링 토큰은 그대로입니다.
소스 컨트롤 · 브라우저 · 화면 설정
한 줄 요약: 브랜치 아이콘으로 바뀐 파일을 보고 커밋하고, 브라우저 창의 Web / Mobile 스위치로 폰 크기 화면을 확인하며, Settings에서 화면 테마(밝게·어둡게)와 언어를 고릅니다.
터미널 설정 (Settings → Terminal)
글자 크기(50%–200%)와 자동 고침 켜기/끄기를 폰마다 따로 정할 수 있습니다.
모바일 문제 해결
워크트리에서 스피너가 계속 돎
폰은 데스크톱 에이전트 프로세스의 하트비트(살아 있다는 신호)를 따라갑니다. 데스크톱은 idle인데 폰은 working이면 그 워크트리 줄을 강제로 새로 고쳐 상태를 맞추세요.
페어링 실패
Relay로 페어링한다면 데스크톱과 폰 두 기기 모두 같은 Orca 계정에 로그인했는지 확인하세요. 페어링 코드는 몇 분 뒤 만료되므로, 화면에 오래 떠 있었다면 새로 만드세요.
Authentication failed / pairing invalid
데스크톱이 이 기기 토큰을 더 이상 받지 않는 상태입니다(예: 데스크톱이 페어링된 기기를 지웠을 때). 먼저 배너의 Retry를 눌러 보세요(일시적 거부는 다시 페어링하지 않아도 회복될 수 있음). 계속 실패하면 Re-pair from desktop을 쓰거나, 호스트를 Remove하고 다시 페어링하세요.
Update Orca Mobile / Update Orca on your computer
폰과 데스크톱은 버전이 있는 모바일 프로토콜로 대화합니다. 어느 한쪽이 너무 오래되면 모바일이 그 호스트를 막고 App Store(iOS)나 GitHub Releases(Android APK 또는 데스크톱)로 안내한 뒤 호스트 목록으로 돌아갑니다. 업데이트 후 연결을 새로 고치고, 메시지가 남아 있으면 호스트를 지우고 다시 페어링하세요.
Quick Commands를 쓸 수 없음
페어링된 데스크톱을 업데이트해 quick-commands 기능을 알리게 하세요.
데스크톱에 닿지 않음
폰과 데스크톱이 같은 네트워크 경로(LAN, Tailscale, 또는 페어링에 쓴 경로)를 공유해야 합니다. 데스크톱 앱을 닫으면 연결이 끊기며, 다시 열면 폰이 자동으로 재연결합니다.
함께 보면 좋은 것: 에이전트 완료 알림이 알맞은 기기로 가도록 모바일 알림과 데스크톱 알림을 짝지으세요. 창 없는 기계는 원격 Orca 서버의 모바일 페어링을, 제공자 사용량은 사용량·한도 추적 장을 참고하세요.
- 다른 컴퓨터(서버)가 없다면 SSH·원격 서버는 건너뛰고 모바일 앱만 보면 됩니다.
- SSH 워크트리: 노트북 Orca가 주인, 원격 호스트는 작업장. Settings → SSH에서 대상 추가(host·user·port는 IT 담당자에게) → Test → Save, 워크트리 위치로 SSH 대상 선택.
- 호스트 키(서버 지문)가 바뀌었다는 경고가 뜨면 직접 처리하지 말고 서버 관리자에게 문의합니다.
- 끊겨도 원격 에이전트는 계속 돌고, 끊기면 워크트리 카드의 재연결 버튼으로 다시 붙습니다.
- 관리형 Orca 서버는 자동으로 설치·업데이트되므로 오류가 날 때만 Settings → Managed servers를 봅니다.
- Ports 탭(Cmd+Shift+I — macOS)으로 원격 포트를 감지해 한 번 클릭으로 내 브라우저에 연결합니다.
- 원격 Orca 서버(베타): 서버가 Orca 전체를 가짐. 두 컴퓨터를 같은 Tailscale에 묶고(
100.주소 확인) → 서버에서 New Link → Generate Access Link → 노트북에서 Add Server → Connect. 접근 링크는 비밀번호처럼, 필요 없어진 기기는 바로 취소. - 모바일 앱(베타): 상태 보기·짧은 답장·푸시 알림·워크트리 만들기. 데스크톱 계정/상태 메뉴에서 코드를 만들어 폰에서 Pair. Relay를 쓸 때만 두 기기 모두 같은 Orca 계정 로그인.
- Android:
app-release.apk설치, 알 수 없는 앱 권한은 설치 후 끄기, Samsung Auto Blocker는 잠시만 끄고 Play Protect는 그대로.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 8장에 있습니다.
봇(Bots) — 일을 받아 오고, 일정대로 돌고, 사람 대신 보고하는 에이전트
봇은 이름·목적·기억을 가진 에이전트입니다. Slack·GitHub·Linear·자기 채팅·정해 둔 일정에서 일을 받아, 내 컴퓨터의 Claude Code나 Codex로 처리하고, 부탁받은 곳에 결과를 보고합니다. 결정이 필요하면 Orca에서 나를 기다립니다.
봇이란 무엇인가
봇은 자기 채팅, Slack, Linear, GitHub, 정해 둔 일정에서 일을 받습니다. 일은 내 컴퓨터에서, 내가 이미 쓰는 Claude Code나 Codex(또는 다른 지원 에이전트)로 합니다. 그래서 봇이 한 일은 그 에이전트 요금제 사용량으로 잡힙니다. 끝나면 부탁받은 곳에 보고하고, 결정이 필요하면 Orca 안에서 나를 기다립니다.
이름과 사진
Slack에서는 @scout처럼 자기 이름으로 보입니다.
목적(soul)
"무엇을 하는 봇인지" 적은 설명. 첫 대화 뒤 봇이 스스로 적어 두어, 이후 모든 대화가 같은 곳에서 시작합니다.
기억(memory)
일하며 배운 것을 적어 두는 곳. 새 일마다 새 채팅을 열어도 같은 설명을 반복할 필요가 없습니다.
자동화
"평일 9시마다", "PR이 열리면"처럼 정해 둔 때에 스스로 시작하는 일.
봇은 한 컴퓨터의 폴더 하나에 삽니다. 목적·기억·능력은 그 폴더 안의 평범한 Markdown 파일이라 직접 읽고 고칠 수 있습니다.
봇 만들기
1. 새 봇 시작 — 사이드바의 Bots 칸에서 +(New bot or group) → New bot → Start from scratch(처음부터). 템플릿 24종 중에서 고르려면 Browse templates를 누릅니다.
2. 이름과 사진 — 봇의 이름과 사진을 정합니다. Slack 등에서 이 이름으로 불립니다.
3. 하는 일 적기(선택) — Who it is and what it does(누구이고 무엇을 하나) 칸에 할 일을 한 문장으로 적습니다. 비워 두고 첫 채팅에서 말해도 됩니다.
4. 어디서 돌지 확인 — 어느 컴퓨터에서, 어느 에이전트로 돌지 적힌 줄을 확인합니다. 바꾸려면 Change. 봇은 고른 컴퓨터에 계속 머뭅니다.
5. 만들기 — Create를 누릅니다. 누르기 전까지는 아무것도 만들어지지 않습니다.
첫 일 맡기기
처음부터 만든 봇은 인사를 하고 "무엇부터 할까요?" 하고 묻습니다. 진짜 할 일 하나로 답합니다.
🤖 봇: 안녕하세요! 무엇부터 할까요?
🙂 나: "매일 아침 acme/web에서 무엇이 바뀌었고 내가 검토할 것이 무엇인지 요약해 줘."
🙂 또는: "PR에서 CI(코드를 올릴 때마다 자동으로 돌아가는 검사)가 실패하면, 우연히 한 번 실패한 것(flaky)인지 진짜 문제인지 알려 줘."
봇은 그 일에 무엇이 필요한지 살펴보고, 작은 조각 하나를 바로 해서 결과를 보여 줍니다. 그다음 자기 목적을 적어 두고, 배운 것은 기억에 남깁니다.
템플릿으로 만든 봇은 목적이 이미 있고, 일부는 능력과 일정도 갖고 있습니다. 템플릿의 일정은 꺼진 채로 시작합니다. 어느 저장소·채널을 쓸지 첫 채팅에서 정하면, 그때 자동화와 연결이 설정됩니다.
연결(Connectors) — Slack · GitHub · Linear · Google · 웹훅
연결은 세 가지 일을 합니다. ① 사람들이 Slack·GitHub·Linear에서 봇을 부르게 하고, ② 그곳에서 무슨 일이 생기거나 웹훅이 호출되면 자동화를 시작하고, ③ Google 같은 다른 앱에서 봇이 일하게 합니다.
봇의 Connectors 탭에서 Add a connector(이미 하나 있으면 Add)를 누르고 서비스를 고릅니다. Slack·GitHub·Linear 카드에는 그 봇을 정확히 어떻게 부르는지 적힌 How to ask 줄이 있습니다. 봇에게 "연결해 줘"라고 해도 되는데, 그러면 채팅에 Connect 카드가 뜨고 내가 끝까지 진행하기 전에는 아무것도 연결되지 않습니다.
| 연결 | 부르는 법 | 봇이 누구로 일하나 | 거치는 길 |
|---|---|---|---|
| Slack | 채널에서 @봇이름, 또는 DM | 봇 자신(봇마다 따로 만든 Slack 앱) | Orca Cloud |
| GitHub | 이슈·PR에서 How to ask 줄대로 언급 | 부른 곳의 답은 Orca 앱, 그 밖의 GitHub 일은 나(push도 내 git 로그인) | Orca Cloud |
| Linear | 이슈에 @Orca <handle>, 또는 라벨 bot:<handle> | 부른 곳의 답은 Orca 앱, 그 밖의 Linear 일은 나 | Orca Cloud |
| 부르는 곳은 아님. 새 메일·다가오는 일정으로 자동화 시작 | 나(Gmail·Calendar·Drive·Docs·Sheets) | 내 컴퓨터 → Google 직접 | |
| 웹훅 | 어떤 도구·스크립트든 봇의 주소(URL)를 호출 | 자동화만 시작, 자기 신분 없음 | Orca Cloud |
<handle>은 봇의 짧은 이름으로, How to ask 줄에 나옵니다.
봇마다 자기 Slack 앱이 생겨서, 사람들은 @봇이름으로 채널에서 부르거나 DM을 보냅니다. 부르면 봇이 자기 컴퓨터에서 일을 시작합니다.
한 Slack 워크스페이스에 봇을 처음 넣을 때 App Configuration Token(Slack이 "이 도구가 나 대신 앱을 만들어도 된다"고 내주는 비밀 문자열)을 한 번 넣습니다. Orca는 이걸로 봇마다 이름·사진이 다른 Slack 앱을 만듭니다. 워크스페이스에 따라 관리자가 봇 앱을 승인해야 들어옵니다.
- 연결Orca에 로그인한 뒤 봇의 Connectors에서 GitHub → Connect GitHub. 브라우저에서 GitHub로 로그인합니다.
- 앱 설치Install the Orca app으로 봇이 일할 저장소에 Orca 앱을 설치합니다. 조직(organization)에서는 소유자 승인이 필요할 수 있습니다.
- 켜기Turn on으로 봇에 켭니다. 나중에 Add repositories or organizations로 일할 곳을 늘립니다.
부른 곳에는 Orca 앱으로 답하고, 그 밖의 GitHub 일은 그 컴퓨터의 내 gh 로그인으로 합니다. 봇은 "내가 시킬 때만 승인·변경 요청·병합(merge)하라"는 지시를 받지만, Orca가 강제하지는 않습니다(→ 권한과 보안).
- 연결Orca에 로그인한 뒤 봇의 Connectors에서 Linear → Connect Linear. 브라우저에서 Linear로 로그인하고 워크스페이스를 고릅니다.
- 앱 설치(한 번)그 워크스페이스에 Orca가 아직 없으면 Linear 관리자가 모두를 위해 한 번 설치합니다.
- 켜기Turn on으로 봇에 켭니다.
사람들은 이슈에 @Orca <handle>(예: @Orca scout — @scout가 아님)을 쓰거나 라벨 bot:<handle>을 붙입니다. Linear 언급은 Orca 앱을 거치기 때문입니다. 자동화 이벤트: 이슈 배정, 언급, 새 이슈, 이슈 이동.
봇이 내 Gmail·Calendar·Drive·Docs·Sheets에서 일하고, 새 메일이나 곧 시작할 일정으로 자동화를 시작하게 합니다. 봇마다 꺼진 채로 시작하며, 그 봇의 Connectors에서 켭니다.
설정할 때는 나만의 Google Cloud 앱을 만들고, 봇이 채팅에서 안내합니다. Orca 브라우저에서 클릭을 대신 해 주거나, 그곳에서 안내하거나, 내 브라우저에서 안내할 수 있습니다. Google 약관 동의 칸은 내가 직접 체크합니다.
앱이 내 것이라 Google 로그인은 내 컴퓨터에 머물고, 봇은 거기서 Google로 바로 호출합니다. 그래도 봇이 읽은 내용은 에이전트의 모델 회사로 갈 수 있고, 봇이 Slack·GitHub·Linear에 올리는 답에 들어갈 수 있습니다. 새 메일·일정 규칙은 내 컴퓨터에서 약 1분마다 확인합니다.
봇은 "시키지 않았으면 메일은 보내지 말고 초안만 쓰라"는 지시를 받지만, Orca가 강제하지는 않습니다. 봇의 Google은 언제든 끌 수 있고, 그 컴퓨터의 다른 봇에는 Google 연결이 그대로 남습니다.
웹훅(webhook)(다른 프로그램이 "일 생겼어" 하고 주소 하나를 호출해 알려 주는 방식)은 어떤 도구·스크립트든 웹 요청 하나로 봇을 시작하게 합니다. 봇 채팅에서 만들어 달라고 하고, 자동화 카드의 Copy URL로 주소를 복사합니다. 호출은 Orca Cloud를 거쳐 내 컴퓨터로 오고, Orca는 호출 내용을 지시가 아니라 정보로 봇에게 넘깁니다.
- Composio: Orca가 직접 연결하지 않는 앱(예: Outlook·Notion·HubSpot)은 내 Composio 키를 넣어 씁니다. 앱 로그인은 Composio가, 키는 Orca가 갖고 있어 봇은 키를 보지 못합니다.
- MCP 서버(에이전트에게 새 도구를 붙여 주는 표준 플러그인): 봇에게 "그 봇만 쓰는 MCP 서버"를 붙여 달라고 합니다. 웹으로 닿는 서버는 Orca가 키·로그인을 암호화해 보관하고 호출할 때마다 직접 붙이므로 봇이 키를 갖지 않습니다. 명령으로 실행하는 서버는 저장된 설정에서 키를 받는데, 그 설정은 암호화되지 않습니다.
Bots 소개 쪽에는 이 밖에 Sentry·Vercel·Notion·Datadog·PostHog·Supabase·Stripe·Atlassian·HubSpot 등이 "봇이 일할 수 있는 곳"으로 나옵니다. MCP 서버나 Composio로 연결하는 곳들입니다.
누가 시킬 수 있나 (Who can ask)
기본으로는 나만 내 봇에게 일을 시킬 수 있습니다. 동료가 Slack·Linear·GitHub에서 시키게 하려면 봇 설정의 Who can ask에 그 사람을 넣습니다. 넣기 전에 알아 둘 것:
- 그 사람 자기 권한이 아니라 내 권한, 내 컴퓨터로 일합니다. 봇이 할 수 있는 일이면 그 사람도 시킬 수 있습니다.
- 봇을 원격으로 조종할 수 있습니다: 시작·방향 바꾸기·승인·멈추기.
- 그래서 내 키보드 앞에 앉혀도 믿을 사람만 넣습니다.
- Orca가 보통 "주인에게 물어보세요"라는 메모로 답하고, 결정은 내가 Orca에서 합니다. Slack에서는 그 사람에게만 보이고, GitHub·Linear에서는 공개 답글입니다.
- 봇이 이미 있는 스레드에서 그 사람들의 메시지는 봇이 맥락으로 읽습니다. 다만 일을 시작하거나 방향을 바꾸지는 못합니다.
이벤트 자동화와 웹훅은 Who can ask와 따로입니다. "#eng에 누가 글을 올리면" 같은 규칙을 켜면, 나만 봇을 부를 수 있어도 나와 봇이 함께 있는 곳의 누구든 그 규칙을 시작시킵니다. 봇에게 듣는 곳을 좁혀 달라고 하거나, 일부 이벤트는 "Maya나 Sam이 올릴 때만"처럼 사람을 정할 수 있습니다. 쓰지 않는 규칙은 멈춰 둡니다. 웹훅은 signing secret이 없으면 주소를 가진 누구나 시작시킵니다.
다른 앱의 봇 가져오기
다른 봇 앱에서 쓰던 봇이 있으면 그 봇의 성격(persona)·기억·능력·일정을 가져올 수 있습니다. 새 Orca 봇이 옛 봇을 읽고, 계획을 보여 주고, 내가 승인하면 스스로 설정합니다. 옛 봇은 읽기만 하고 바꾸지 않습니다. Bots 소개 쪽은 OpenClaw·Hermes에서 가져오는 경우를 예로 듭니다.
- 시작사이드바 Bots 칸에서 + → New bot → Import from another app…. Orca가 이 컴퓨터에서 지원하는 봇 앱의 봇을 찾아 목록으로 보여 줍니다(찾으면 먼저 가져오기를 권할 수도 있습니다).
- 고르기찾은 봇이면 골라서 새 이름을 주고 만듭니다. 못 찾은 봇은 Another app…: Orca가 주는 메시지를 옛 봇에게 보내면 옛 봇이 자기 파일을 한 폴더에 복사합니다. 그 폴더를 넣고, 옛 봇이 답을 썼으면 붙여 넣고, 이름을 주고 만듭니다.
- 계획 검토새 봇이 찾은 것을 묶어서 보여 줍니다. 채팅에서 "전부 가져와" 또는 "이건 빼"라고 답할 때까지 아무것도 설정하지 않습니다.
가져온 뒤
- 자동화는 멈춘 채로 옵니다. 옛 봇과 새 봇이 같은 일을 두 번 하지 않게, 옛 앱에서 옛 봇을 끈 뒤 새 봇에게 자동화를 켜 달라고 합니다. 옛 앱이 아직 돌고 있으면 봇이 어떤 일이 두 번 돌지 알려 줍니다.
- 옛 봇이 쓴 말은 참고용으로 새 봇의 기억에 남되, 지시가 아닌 메모로 표시됩니다.
- 옛 봇이 쓰던 도구는 키 없이 옵니다. 봇이 물어보면 다시 로그인합니다.
- Slack·GitHub·Linear가 필요한 것이 있으면 봇이 연결을 권합니다. 이벤트로 시작하는 자동화는 그 연결이 붙을 때까지 기다립니다.
- 새 봇은 옛 앱의 모델 설정이 아니라 내 Claude Code·Codex(또는 다른 지원 에이전트) 로그인으로 돕니다.
- 이 컴퓨터에서 찾은 봇이면, 나중에 같은 옛 봇으로 가져오기를 다시 시작해 Update할 수 있습니다. 새로 생기거나 바뀐 것만 더하고, Orca에서 내가 고친 것은 지킵니다.
- 봇 = 이름·목적·기억·자동화를 가진 에이전트. 한 컴퓨터의 폴더에 살고, 내 Claude Code·Codex 등으로 일합니다(1.4.265부터).
- 사이드바 Bots 칸 + → New bot으로 처음부터 또는 템플릿 24종에서 만들고, 첫 채팅에 진짜 할 일 하나를 줍니다.
- 결정·승인은 봇 Home의 Needs you에서 기다립니다. 코드 수정은 작업자가 자기 워크트리에서 하고 PR로 돌아옵니다.
- 봇의 컴퓨터가 깨어 있어야 일합니다. Slack·GitHub·Linear 요청은 최대 하루 기다립니다.
- Slack·GitHub·Linear·웹훅은 Orca 로그인과 Orca Cloud가 필요하고, Google은 내 컴퓨터에서 직접 연결합니다.
- Who can ask에 넣은 사람은 내 권한으로 봇을 씁니다. 이벤트 자동화·웹훅은 Who can ask와 따로입니다.
- 새 봇은 기본 Full access로 시작합니다. 다른 사람이 부르거나 바깥 글을 읽는 봇은 Ask for approval로 바꿉니다.
이 장의 나머지 소절과 🔧 세부는 완전 가이드 10장에 있습니다.