Orca — 여러 AI 코딩 에이전트를
한 앱에서 동시에 부리는 개발 환경
Orca는 AI에게 코딩 일을 여러 개 동시에 맡기고, 그 결과를 한곳에서 확인하는 작업장 프로그램입니다. Stably AI가 만들었고, 무료로 쓸 수 있습니다. 홈페이지는 스스로를 ADE(Agent Development Environment — AI 에이전트를 위한 개발 환경)라고 부르며, 표어는 “Ship 100x with the agent IDE”(에이전트 개발 도구로 100배 빠르게 내보내라)입니다.
먼저 알아 두면 좋은 용어
가이드 전체에서 자주 나오는 말입니다. 먼저 굵게 표시한 8개만 알아도 대부분 따라갈 수 있습니다. 각 장에서도 처음 나올 때 괄호로 다시 풀이합니다.
| 용어 | 쉬운 풀이 |
|---|---|
| ⭐ AI 코딩 에이전트 | 사람 대신 코드를 읽고, 고치고, 명령을 실행하는 AI 프로그램. 예: Claude Code, Codex, Cursor CLI, Gemini. |
| ⭐ 터미널 · 셸 | 글자로 명령을 입력해 컴퓨터를 다루는 창. 대부분의 코딩 에이전트는 터미널 안에서 돌아갑니다. |
| ⭐ git · 저장소(repo) | 코드의 변경 이력을 기록하는 도구와, 그 이력이 담긴 프로젝트 폴더. |
| ⭐ 커밋 | “여기까지 저장” 하고 이력에 남기는 한 번의 기록. |
| ⭐ 브랜치 | 이력의 갈래. 원본(main)을 건드리지 않고 따로 작업하기 위한 줄기. |
| ⭐ 워크트리 | 한 저장소의 브랜치를 별도 폴더에 하나 더 꺼내 놓은 것. 폴더가 다르니 여러 작업이 서로 섞이지 않습니다. Orca의 기본 작업 단위. |
| ⭐ diff | 바뀌기 전과 후의 차이. 지운 줄은 빨강, 더한 줄은 초록으로 보입니다. |
| ⭐ PR (Pull Request) | “내 브랜치의 변경을 원본에 합쳐 주세요” 하고 리뷰를 요청하는 것. GitLab에서는 MR. |
용어 24개 더 보기 — 읽다가 모르는 말이 나오면 여기서 찾으세요
| 용어 | 쉬운 풀이 |
|---|---|
| ADE | Agent Development Environment. 사람이 직접 코딩하는 IDE와 달리, 여러 에이전트를 지휘·감독하는 데 맞춘 개발 환경. |
| IDE · 에디터 | 코드를 쓰고 고치는 프로그램. 예: VS Code. |
| CLI | Command Line Interface. 터미널에서 명령어로 쓰는 프로그램. Orca에도 orca라는 CLI가 있습니다. |
| 체크아웃 | 특정 브랜치의 파일을 폴더에 꺼내 놓은 상태. |
| 스테이징 | 다음 커밋에 넣을 변경을 골라 담아 두는 단계. |
| 푸시 · 원격(remote) | 내 컴퓨터의 커밋을 GitHub 같은 서버 저장소로 올리는 것과, 그 서버 저장소. |
| CI · 체크 | PR을 올리면 서버가 자동으로 돌리는 테스트·검사. |
| 이슈 · 티켓 | 할 일이나 버그를 적어 둔 카드. GitHub Issues, Linear, Jira 등. |
| SSH | 다른 컴퓨터(서버)에 안전하게 접속해 명령을 실행하는 방법. |
| 페어링 | 두 기기(예: 데스크톱과 폰)를 서로 믿을 수 있게 연결해 두는 것. |
| 프롬프트 | 에이전트에게 보내는 지시문. |
| 세션 | 에이전트 하나가 실행되어 대화·작업하는 한 번의 흐름. |
| 패인 · 분할 | 앱 화면을 여러 칸으로 나눈 것과 그 한 칸. |
| 데몬 | 화면 없이 뒤에서 계속 도는 프로그램. Orca는 이것으로 앱을 꺼도 에이전트를 살려 둡니다. |
| 스킬 | 에이전트에게 특정 도구 사용법을 알려 주는 안내 문서 묶음. |
| MCP | Model Context Protocol. AI 에이전트가 외부 도구에 연결하는 표준 방식. |
| 실험 기능 실험 | 설정 → Experimental에서 켜야 쓸 수 있는, 아직 다듬는 중인 기능. |
| GitHub · GitLab | 코드를 올려 두고 여러 사람이 함께 검토하는 웹사이트. PR과 이슈가 여기에 있습니다. |
| 런타임 | 지금 켜져서 일하고 있는 Orca 프로그램 본체. 다른 컴퓨터에서 돌 수도 있습니다. |
| 토큰 | ① AI 사용량을 세는 단위, ② 비밀번호 대신 쓰는 출입증 문자열. 문맥에 따라 다릅니다. |
| 환경 변수 | 프로그램이 실행될 때 함께 받는 설정 메모(이름=값). 예: DO_NOT_TRACK=1. |
| localhost | “내 컴퓨터 자신”을 가리키는 주소. 개발 중인 웹 화면을 열 때 씁니다. |
| Workspace(워크스페이스) | Orca 화면에서 워크트리를 부르는 다른 이름. 이 가이드에서는 “워크트리”로 통일합니다. |
| <이름> 표기 | 명령어 예시의 <repoId>처럼 꺾쇠로 감싼 부분은 “직접 바꿔 넣는 칸”입니다. |
Orca 한 장 그림
내가 지시하면(파란 점) 각 워크트리의 에이전트가 따로 일하고, 상태 점(작업 중·질문 대기·완료)이 한 화면에 보입니다. 결과는 리뷰를 거쳐 GitHub로 나가고, 원격 서버나 휴대폰에서도 이어서 볼 수 있습니다.
왜 이런 도구가 필요한가
한 문장으로 말하면 “AI 여러 명이 한 책상에서 일하면 서로의 일을 망치기 때문”입니다. 지금 개발자들은 보통 코드 편집 프로그램(IDE, 예: VS Code)을 쓰거나, AI 에이전트를 터미널 창에 하나씩 띄워 씁니다. 아래 표는 같은 일을 이 두 방법과 Orca로 할 때의 차이입니다.
| 기존 에디터(IDE) | 에이전트를 터미널에서 직접 실행 | Orca (ADE) | |
|---|---|---|---|
| 전제 | 사람 한 명이 직접 타이핑 | 터미널 창 하나에 에이전트 하나 | 여러 에이전트가 동시에 일함 |
| 동시 작업 | 브랜치를 바꿔 가며 하나씩 | 같은 폴더에서 돌리면 서로 덮어씀 | 작업마다 워크트리를 따로 만들어 충돌 없음 |
| 상태 파악 | — | 창을 하나씩 열어 봐야 함 | 작업 중·질문 대기·완료를 한눈에, 알림까지 |
| 결과 검토 | diff 보기 | 직접 git 명령 | 줄마다 코멘트 → 묶어서 에이전트에게 다시 보냄 |
| 범위 | 파일 편집 | 에이전트 실행 | 워크트리·리뷰·브라우저·원격·모바일·자동화 전체 |
Orca가 맞는 경우
같은 버그를 에이전트 셋에게 동시에 시켜 가장 좋은 답을 고르고 싶을 때 · AI가 만든 코드를 진지하게 리뷰하고 싶을 때 · 이미 Claude Code·Codex·Cursor CLI를 쓰고 있어 한곳에서 지휘하고 싶을 때 · 에이전트를 내 컴퓨터가 아닌 다른 컴퓨터(원격 서버·가상 컴퓨터)에서 돌리고 싶을 때
Orca가 아닌 것
AI 모델이 아닙니다(쓰던 Claude·Codex 구독을 가져와 씀) · git을 대체하지 않습니다(모든 워크트리는 진짜 git 워크트리) · 호스팅 서버 상품이 아닙니다(기본은 내 컴퓨터, 원격은 내가 가진 기계) · 코드를 모르는 사람용 노코드 도구가 아닙니다
하루 작업의 기본 순환
1단계 — 작업 공간 만들기. 할 일 하나마다 워크트리를 만듭니다. 이름을 적고, 어느 버전에서 시작할지 고르고, 필요하면 할 일 카드(이슈)를 연결합니다. 생성은 뒤에서 진행되므로 기다리지 않아도 됩니다. → 2장
2단계 — 에이전트에게 맡기기. 워크트리 안에서 Claude Code·Codex 등을 띄우고 일을 지시합니다. 다른 워크트리에서도 동시에 다른 에이전트가 일합니다. 질문이 오면 알림이 뜨고, 결과 화면은 내장 브라우저로 바로 확인합니다. → 3장, 4장
3단계 — 검토하고 내보내기. AI가 바꾼 부분(diff)을 한 줄씩 보며 메모를 달고, 메모를 한꺼번에 AI에게 돌려보내 고치게 합니다(초록 화살표: 수정 요청이 도는 길). 만족하면 저장 지점을 만들고(커밋) 서버에 올려(푸시) 합쳐 달라는 요청(PR)까지 앱 안에서 끝냅니다. → 6장
이 가이드의 구성
- Orca는 AI 코딩 에이전트 여러 개를 워크트리별로 나눠 동시에 돌리고 지휘하는 무료·오픈소스 데스크톱 앱입니다.
- 기본 순환은 워크트리 만들기 → 에이전트에게 맡기기 → 리뷰하고 내보내기입니다.
- 모델이나 호스팅 서비스가 아니라, 내가 쓰던 에이전트와 git을 그대로 쓰는 “작업장”입니다.
출처: onorca.dev 홈, onorca.dev/docs (What is Orca?)
시작하기 — Orca란 무엇이고 어떻게 설치·설정하나
Orca는 여러 AI 코딩 에이전트를 한 화면에서 나란히 돌리는 데스크톱 앱입니다. 이 장에서는 Orca가 어떤 도구인지, 설치와 첫 실행, 세 에이전트를 동시에 경주시키는 첫 세션, 알림·설정·개인정보, 그리고 문제가 생겼을 때 고치는 방법까지 한 번에 훑습니다.
- Orca가 무엇이고 누구를 위한 도구인지, 그리고 무엇이 아닌지
- macOS·Windows·Linux 설치, 첫 실행, 업데이트(안정판·RC) 받는 법
- 에이전트를 어디서 돌릴지 고르는 4가지 방식(로컬·SSH·원격 Orca 서버·Cloud VM) — 처음엔 로컬만 알면 됩니다
- 빈 앱에서 5분 안에 에이전트 3개를 병렬로 돌리는 첫 세션
- Agents 피드(Activity)와 알림·벨·소리
- 설정(Settings) 화면 19개 전체 지도 — 처음엔 3개만 보면 됩니다
- 텔레메트리: 수집하는 것과 절대 수집하지 않는 것, 끄는 법
- 자주 생기는 문제와 GitHub 오류(요청 한도·인증·권한) 해결법
1. Orca란? → 2. 설치(각 탭 첫 줄만) → 4. 첫 3-에이전트 세션(시작 전 준비물부터, 화면 그림을 따라 누르기) → 6. 알림 순서로 읽으면 충분합니다.
건너뛰어도 되는 곳: 3절 실행 방식의 원격 방식(SSH·원격 서버·Cloud VM), 7절 설정 중 General·Agents·Notifications 외의 탭, 9·10절(문제가 생겼을 때 개발자가 보는 참고). “🔧 개발자용 참고” 상자는 모두 접어 두고 읽어도 됩니다.
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가 “정말 열까요?” 하고 물으면 열기를 누르면 됩니다.
Homebrew 설치·서명·공증
Homebrew로 설치 — Homebrew(macOS에서 명령 한 줄로 프로그램을 설치·업데이트하는 도구) cask로도 배포되며, 안정판이 나올 때마다 자동으로 버전이 올라갑니다.
brew install --cask stablyai/orca/orca brew upgrade --cask orca # 새 안정판으로 업데이트
cask는 stable(안정) 채널만 따라갑니다. RC 빌드가 필요하면 GitHub Releases 링크나 앱 안의 Check for Updates 방식(아래 “업데이트”)을 쓰세요.
플랫폼 메모: 앱은 서명(signed)·공증(notarized)(애플이 “출처가 확인된 앱”이라고 도장을 찍어 준 것)되어 있지만, 첫 실행 때 macOS가 “정말 열까요?” 하고 물을 수 있습니다. Electron(웹 기술로 만든 데스크톱 앱의 틀) 기반 앱에서는 정상적인 일입니다.
다운로드 → 더블클릭 → 설치. 설치 프로그램(installer)을 받아 실행합니다.
Windows 기본 셸·orca 명령
- 기본 셸(터미널 안에서 명령을 받아 실행하는 프로그램)은 Settings → Terminal에서 PowerShell 또는 CMD로 정할 수 있습니다. 대부분은 PowerShell을 원합니다.
- 함께 들어 있는
orca명령은 네이티브 프로그램이라 Visual C++ Redistributable(별도 실행 라이브러리) 없이 동작합니다. 설치 프로그램이 PATH(컴퓨터가 명령 프로그램을 찾아보는 폴더 목록)에 추가해 줍니다.
다운로드 → 더블클릭(또는 설치) → 실행. 자동 업데이트를 원하면 AppImage(설치 없이 파일 하나로 실행되는 형식)를 고르세요.
Linux 패키지 형식·CLI 이름
AppImage, .deb, .rpm 세 가지가 있습니다.
| 형식 | 업데이트 방식 |
|---|---|
| AppImage | Orca가 스스로 업데이트합니다. 자동 업데이트를 원하면 이것을 고르세요. |
| .deb / .rpm | 새 버전이 있다고 알려 주고, 설치에 쓸 패키지 관리자 명령을 보여 줍니다. 그 명령을 실행하기 전에 Orca를 종료하세요. |
Linux의 명령줄 도구 이름은 orca가 아니라 orca-ide입니다. GNOME의 화면 낭독기 “Orca”와 이름이 겹치지 않게 하기 위해서입니다.
예전 버전은 GitHub Releases 페이지에서 언제든 받을 수 있습니다. 지금 업데이트가 마음에 안 들면 이전 버전으로 돌아가도 됩니다.
되돌릴 때 데이터 형식
Orca는 되돌아가도 워크트리 데이터를 강제로 낮은 버전 형식으로 바꾸지(force-downgrade) 않습니다.
첫 실행 때 일어나는 일
① 홈 폴더 접근 권한 요청 — 저장소(repo)를 추가할 수 있도록 홈 폴더(내 사용자 이름으로 된 기본 폴더) 접근을 물어봅니다. 허용하면 됩니다.
② 기존 설정 가져오기 제안 — ~/.claude, ~/.codex, Ghostty 터미널 설정이 있으면 가져올지 물어봅니다. (~는 내 홈 폴더라는 뜻입니다.) 처음 쓰는 사람은 가져올 것이 없으니 넘어가면 됩니다.
③ 빈 시작 화면 — 아무것도 없는 랜딩 화면이 나오고, 여기서 첫 저장소를 추가합니다.
사이드바: (비어 있음) Add Repo
업데이트: 안정판과 RC
Orca는 기본적으로 자동 업데이트되며 stable(안정) 채널을 따라갑니다. 초보자는 아무것도 바꾸지 않아도 됩니다. 안정판은 검증을 거친 버전이고, RC(release candidate, 출시 후보 — 새 기능이 먼저 들어간 시험판)는 거의 매일 나오기도 합니다.
RC·사전 출시판 받는 법
RC 채널을 “항상 받기”로 고정하는 앱 내 설정은 없습니다. 대신 Check for Updates 버튼(Settings → General → Updates, 또는 앱/Help 메뉴)을 보조 키와 함께 누르면 받을 빌드가 달라집니다.
| 클릭 방법 | 효과 |
|---|---|
| Shift+클릭 | 최신 RC 사전 출시판(prerelease)까지 포함해 확인 |
| Cmd+클릭 (macOS) / Ctrl+클릭 (Windows·Linux) | 성능(perf) 태그가 붙은 최신 사전 출시판 |
| Option+클릭 (macOS 전용) | 내 컴퓨터에 있는 macOS 빌드 중 Orca 호환성 검사를 통과한 것을 골라 사용. 실패하면 “Could Not Use Local Build”가 뜨고 Choose Another Build(다른 빌드 고르기)를 누를 수 있습니다. |
어떤 빌드든 GitHub Releases 페이지에서 직접 받을 수도 있습니다.
3. 실행 방식(Ways to run Orca)
설치한 내 컴퓨터에서 그대로 돌리는 것이 로컬이고, 대부분의 사람에게 기본입니다. 나머지 세 방식은 “노트북 밖에서 돌리고 싶어질 때” 돌아와 읽으세요.
모든 워크트리는 “어딘가”에서 돌아갑니다. 그 어딘가는 눈앞의 컴퓨터일 수도, 이미 가진 서버일 수도, 늘 켜져 있는 공용 서버일 수도, 그 작업 하나만을 위해 새로 띄운 클라우드 VM(인터넷 회사에서 빌려 쓰는 가상 컴퓨터)일 수도 있습니다.
원격 방식은 회사에 늘 켜져 있는 PC를 집에서 원격 조종하는 것과 비슷합니다. 내 눈앞에는 화면만 있고, 실제 파일과 일하는 프로그램(에이전트)은 멀리 있는 컴퓨터에서 돌아갑니다. 내 노트북을 덮어도 회사 PC는 계속 일합니다.
한 줄로 정리하면: 내가 보는 화면과 실제로 일하는 컴퓨터가 같은 곳이면 로컬, 다른 곳이면 원격 방식입니다. 한 번 설치한 Orca에서 네 방식을 섞어 쓸 수 있고, 원격 방식은 언제나 내가 관리하는 기기·클라우드 계정을 씁니다(Orca가 서버를 빌려주지 않음).
Orca를 설치하고, 프로젝트를 열고, 워크트리를 만듭니다. 에이전트·터미널·브라우저가 화면(UI)과 같은 컴퓨터에서 돌아갑니다. 사이드바의 “Local Mac” 아래 카드 하나하나가 자기 에이전트와 브랜치를 가진 워크트리입니다.
대부분의 사람에게 기본 경로입니다. 아래 “첫 3-에이전트 세션”을 따라 해 보세요.
한 줄 요약: 화면은 내 노트북, 일은 SSH로 접속한 다른 컴퓨터가 합니다. 워크트리를 만들 때 Run on(어디서 실행할지)에서 그 컴퓨터를 고르기만 하면 됩니다.
SSH 대상 설정 자세히
성능 좋은 Mac mini, Linux VPS, GPU 서버, SSH가 되는 클라우드 샌드박스 등 SSH로 접속되는 어떤 호스트든 지정할 수 있습니다. 워크트리를 만들 때 Run on에서 그 호스트를 고르면, 에이전트와 git worktree는 원격에서 돌고 편집기·diff·UI는 노트북에 남습니다.
잘 맞는 경우: 원격에 이미 저장소·도구·자격 증명(로그인 정보)이 있고, 노트북의 Orca 하나로 여러 서버를 부리고 싶을 때.
- 호스트 추가Settings → SSH에 호스트를 등록합니다.
- 연결 테스트저장소 워크트리를 쓰려면 그 호스트에 git이 설치돼 있어야 합니다.
- Run on에서 선택워크트리를 만들며 SSH 대상을 고릅니다. 입력하면 바로 걸러 주는 목록에 준비된 호스트가 나오고, 연결은 됐지만 이 프로젝트용 설정이 아직 안 된 호스트는 “setup-needed”(설정 필요) 줄로 보이며 선택할 수 없습니다.
SSH 워크트리는 VS Code Remote-SSH로 열 수 있고, SFTP가 허용되면 원격 폴더를 내려받을 수 있으며, 원격에서 터미널용 네이티브 모듈을 빌드하지 못해도 파일·git 작업은 계속 쓸 수 있습니다. 첫 연결 때 Orca가 그 호스트에 자체 관리 서버(managed server)를 설치하므로, Node 버전이 다르거나 빌드 도구가 없어도 연결이 막히지 않습니다.
한 줄 요약: “회사의 늘 켜진 PC를 집에서 원격 조종”하는 방식입니다. 한 기기에서 Orca를 계속 켜 두고, 노트북·브라우저·휴대폰은 화면 역할만 합니다.
원격 Orca 서버 설정 자세히
안 쓰는 노트북, Mac mini, 집 서버, 클라우드 VPS, 팀 서버 등 내가 관리하는 기기에서 Orca를 계속 켜 두고, 노트북·브라우저·휴대폰을 그 런타임(에이전트가 실제로 도는 실행 환경)에 “페어링(pairing, 짝 맺기)”합니다. 프로젝트·워크트리·터미널·에이전트 프로세스는 서버가 소유하고, 클라이언트(접속해서 보는 쪽 기기)는 화면 역할만 합니다.
잘 맞는 경우
- 노트북이 잠들어도 에이전트가 계속 돌아야 할 때
- 모바일에서 같은 세션에 다시 붙고 싶을 때
- 자동화나 백엔드가 안정적인 호스트에서 세션을 시작해야 할 때
가장 쉬운 설정: 두 컴퓨터 모두에 Orca와 Tailscale(내 기기들끼리 안전한 사설 네트워크를 만들어 주는 서비스)을 설치합니다.
- 서버 쪽Settings → Remote Orca Servers → Advertise this app as a server → New Link에서 Tailscale 주소를 고르고 접속 링크(access link)를 만듭니다.
- 클라이언트 쪽Add Server를 누르고 그 링크를 붙여 넣습니다.
화면 없는(headless(모니터 없이 돌아가는)) Linux 서버나 서비스로 관리되는 VM이라면 대신 orca serve를 씁니다.
orca serve --pairing-address <접속 가능한 tailscale IP 또는 호스트 이름>
SSH와 원격 Orca 서버 비교
| SSH 워크트리 | 원격 Orca 서버 | |
|---|---|---|
| 런타임 주인 | 노트북의 Orca | 원격 기기(Orca 데스크톱 또는 orca serve) |
| 연결이 끊기면 | 에이전트는 호스트에서 계속 돌고, 노트북이 다시 붙음 | 세션 상태 전체가 서버에 있음 |
| 여러 클라이언트 | 노트북 하나가 호스트를 조종 | 노트북·웹·모바일·자동화가 같은 런타임을 공유 |
| 보통 설정 | SSH config 가져오기, Run on 선택 | 서버 앱을 공유하거나 orca serve 실행 후 URL로 페어링 |
Experimental 한 줄 요약: 작업(워크트리)마다 깨끗한 새 컴퓨터를 빌려 쓰고, 끝나면 버리는 방식입니다. 아직 실험 기능이라 초보자는 건너뛰세요.
Cloud VM 레시피 설정 자세히
각 워크트리가 자기만의 환경(클라우드 샌드박스(격리된 실험 공간), VM, 로컬 Docker(프로그램을 상자에 담아 따로 돌리는 도구) 컨테이너)을 필요할 때 띄울 수 있습니다. 환경은 저장소에 커밋된 레시피(orca.yaml + 수명 주기 스크립트)로 정의합니다. 만들면(create) 켜지고, suspend/resume/destroy(일시정지/재개/삭제)로 정리합니다. Orca는 얇은 포장일 뿐이라 제공자 계정·이미지·요금은 모두 내 것입니다.
제품 화면에서는 Settings → Experimental의 Cloud VM이라는 이름으로 보입니다. 레시피가 만드는 것은 여전히 “워크트리별 환경”(문서상 이름: per-workspace environment)입니다.
현재 사람들이 연결하는 제공자: Vercel Sandbox, Fly, Modal, 일반 SSH 호스트, 로컬 Docker. 연결 방식은 두 가지입니다 — Orca server(레시피가 orca serve를 띄우고 페어링 URL을 돌려줌) 또는 SSH(레시피가 접속 정보를 돌려주면 Orca가 접속).
잘 맞는 경우: 작업마다 깔끔한 격리, 쓰고 버리는 컴퓨팅, 모든 에이전트가 똑같은 표준 환경에서 시작하길 원할 때.
1. 켜기 — Settings → Experimental에서 Cloud VM을 켭니다. 그 화면에 짧은 “Create a Cloud VM” 안내와 레시피/런타임 조작 버튼이 있습니다.
2. 스킬 설치 — 필요하면 Cloud VM / per-workspace environment 스킬을 설치하거나 업데이트합니다.
3. 에이전트에게 부탁 — 아무 워크트리에서 에이전트에게 이렇게 말합니다.
Use the orca-per-workspace-env skill to set up a per-workspace environment for this repo.
4. 스킬이 안내 — 사전 준비 → 기본 스냅샷 → 에이전트 인증 → orca.yaml 레시피 → doctor(진단) 검증 순서로 진행합니다.
5. 사용 — Recipes에 레시피가 나타나면 워크트리를 만들며 Run on에서 그것을 고릅니다.
워크트리 생성 화면에 레시피가 나오려면 environmentRecipes 항목이 프로젝트 기본 체크아웃(primary checkout)의 orca.yaml에 있어야 합니다. 기능 브랜치에만 있으면 안 됩니다. 단, 스크립트를 다듬는 동안 doctor와 실제 프로비저닝은 어느 브랜치에서든 돌릴 수 있습니다.
Cloud VM은 Orca가 호스팅하는 VPS를 주지 않습니다. 제공자는 직접 가져오고(BYO, Bring Your Own) 그 제공자에게 비용을 냅니다. Orca는 내 create/suspend/resume/destroy 스크립트를 실행하고, 스크립트가 출력한 페어링 URL이나 SSH 정보로 접속할 뿐입니다.
네 방식 비교표·고르는 기준(원격을 쓸 때)
| 방식 | 파일과 에이전트가 사는 곳 | 기기 주인 | 잘 맞는 용도 |
|---|---|---|---|
| Local(로컬) | 내 데스크톱 | 나 | 일상 코딩, 빠른 반복 |
| SSH target(SSH 대상) | SSH로 접속하는 원격 호스트(다른 컴퓨터) | 나(또는 팀) | 개발용 서버, GPU 호스트, 상시 켜진 VPS(빌려 쓰는 인터넷 서버) |
| Remote Orca Server(원격 Orca 서버) | Orca 데스크톱 또는 orca serve가 돌아가는 기기 | 나(또는 팀) | 오래 유지되는 공유 런타임(에이전트가 실제로 도는 실행 환경), 모바일, 자동화 |
| Cloud VM / 워크트리별 환경 | 워크트리마다 쓰고 버리는 VM·샌드박스(바깥과 격리된 안전한 실험 공간) | 내 클라우드 계정(제공자는 직접 준비) | 격리된, 일회성 에이전트 컴퓨팅 |
Orca는 서버를 빌려주는 상품(관리형 VPS 호스팅)을 판매하지 않습니다. 원격 방식은 언제나 내가 관리하는 기기와 클라우드 계정을 씁니다.
어떻게 고를까
노트북이 충분히 빠르고 에이전트 작업이 짧을 때.
이미 VPS(빌려 쓰는 서버)나 개발 서버가 있고, 두 번째 Orca를 설치하지 않고 거기서 에이전트를 돌리고 싶을 때.
모바일·브라우저·자동화가 함께 쓰는 상시 켜진 Orca 런타임 하나가 필요할 때.
작업마다 레시피로 정의된 새 샌드박스를 받고, 워크트리가 사라지면 같이 사라지게 하고 싶을 때.
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 등)에 있는 원본 줄기”라는 뜻입니다. 원하면 다른 브랜치나 커밋에서 시작해도 됩니다.
워크트리가 만들어지는 곳·고정
Orca가 관리 폴더 아래에 진짜 git worktree를 만들고, 브랜치를 체크아웃(그 브랜치 내용을 폴더에 꺼내 놓기)해 엽니다. 고정(pinned)한 워크트리는 사이드바에서 눈에 띄게 표시되어 자주 쓰는 것을 놓치지 않습니다.
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 열기.
- 패자 정리나머지 둘을 삭제합니다. 클릭 한 번이면 워크트리와 브랜치가 함께 지워집니다.
5. Agents 피드(Activity)
사이드바의 Agents 항목을 누르면 모든 워크트리의 에이전트 소식을 대화 묶음(thread) 형태로 보여 주는 피드(새 소식이 위아래로 쌓이는 목록 — SNS 타임라인 같은 것)가 열립니다. 자리를 비웠다 돌아와서 “무엇이 끝났고 누가 나를 기다리나”를 한곳에서 확인하고, 처리할 순서를 고르게(triage) 해 줍니다.
줄을 누르면 그 워크트리로 바로 이동합니다. 숫자 배지는 마지막으로 본 뒤 새로 온 소식 수입니다.
- 기본으로 켜져 있습니다. 마지막으로 본 뒤 새 사건이 오면 읽지 않음 배지가 붙습니다.
- 항목을 클릭하면 해당 워크트리와 창(pane)으로 바로 이동합니다 — 시스템 알림을 눌렀을 때와 같은 동작입니다.
- Cmd+F(macOS) / Ctrl+F(Windows·Linux)로 피드 필터에 커서를 옮깁니다. 단, 내장 터미널에 포커스가 있으면 그 단축키는 터미널이 가져갑니다.
- 피드 머리글에는 현재 적용된 필터가 표시됩니다.
- 에이전트 줄을 오른쪽 클릭하면 동작 메뉴가 나옵니다. Cmd(Windows·Linux는 Ctrl)을 누른 채 여러 줄을 고르면 한 동작을 한꺼번에 적용할 수 있고, 동작 후에도 Activity 화면에 그대로 머뭅니다.
- 에이전트가 한 차례(turn)를 마침 — 쉬는 중(idle)이거나 질문에 막힘(blocked)
- 새 워크트리 생성
- 입력을 오래 기다려 “막힘”으로 올라온 에이전트
- 에이전트의 가장 최근 응답 짧은 미리보기 — 스레드를 하나하나 열지 않고 훑어볼 수 있음
스레드는 상태별로 묶이며, 실행 중인 에이전트는 맨 위에 고정됩니다.
Agents 피드는 머리글 벨이나 시스템 알림을 대체하지 않습니다. 그것들은 에이전트 완료 때 계속 울립니다. 피드는 자리를 비웠다 돌아왔을 때 “무엇이 바뀌었나”를 워크트리마다 스크롤하지 않고 한 번에 훑는 따라잡기용 화면입니다.
6. 알림과 받은 편지함(Notifications & Inbox)
Orca는 그냥 터미널이 아니라 에이전트를 돌리기 때문에, 에이전트가 진짜로 끝났는지 잠시 멈춘 건지 구분할 수 있습니다. 알림은 이 신호를 이용합니다. 에이전트 셋을 걸어 두고 자리를 비웠다가, 첫 번째가 끝나면 돌아오면 됩니다.
| 기능 | 설명 |
|---|---|
| Agent-finished pings(완료 알림) | 에이전트가 작업 중 → 쉬는 중으로 바뀌면 시스템 알림·소리·워크트리 칩(사이드바 워크트리 이름 옆에 붙는 작은 꼬리표 모양 표시)이 나갑니다. 한 에이전트가 끝난 직후 다른 에이전트가 끝나도 완료음은 빠지지 않고 울립니다. |
| Persistent bell(상시 벨) | 머리글 벨에 모든 워크트리의 읽지 않은 알림이 모입니다. 알림을 누르면 해당 워크트리·창으로 이동합니다. |
| Dock 배지 (macOS) | 같은 읽지 않음 개수가 Dock 아이콘에도 표시되어 Orca를 앞으로 꺼내지 않아도 알 수 있습니다. 해당 워크트리를 방문하면 사라집니다. |
| Mark unread(읽지 않음으로 표시) | 알림을 오른쪽 클릭해 다시 읽지 않음으로 만듭니다. 일단 확인했지만 나중에 다시 보고 싶을 때 씁니다. |
| Tuning(세부 조정) | Settings → Notifications에서 종류별(system, sound, chip-only)로 끌 수 있습니다. |
알림을 띄울 기기 고르기, 알림 소리 바꾸기, 채팅 화면에서의 예외 동작은 아래 접힌 상자에 있습니다.
기기별 알림 · 사용자 소리 · 채팅 화면 예외
| 기능 | 설명 |
|---|---|
| 구조화된 채팅(structured chat)의 경우 | 구조화된 채팅(검은 터미널 대신 메신저처럼 말풍선으로 주고받는 채팅 화면)의 업데이트된 버전에서 한 차례(turn(내 메시지 하나에 에이전트가 일하고 답하는 한 차례))가 성공하면 시스템 알림이나 소리 대신 그 탭과 워크트리에 읽지 않음 표시만 붙습니다. 실패하거나 취소된 차례는 읽지 않음 표시를 붙이지 않습니다. |
| Per-machine(기기별) | Settings → Notifications → Machines에서 이 컴퓨터에 알림을 띄울 기기(이 컴퓨터, SSH 대상, 페어링된 Orca 서버)를 고릅니다. 페어링된 서버의 스위치는 그 서버를 거쳐 닿는 작업까지 포함합니다. 끈 기기는 “제외 목록”으로 저장되므로 나중에 추가한 기기는 기본으로 알림이 옵니다. 이 스위치는 이 컴퓨터의 데스크톱 알림에만 영향을 주며 휴대폰 푸시는 그대로입니다. |
| Custom sounds(사용자 소리) | 종류별로 데스크톱 알림 소리를 고릅니다 — 디스크의 아무 오디오 파일이나 Orca 내장 소리. 메일·Slack 소리와 구분하고 싶을 때 유용합니다. 지원 형식: MP3, WAV, OGG, M4A, AAC, FLAC. 한 파일이 전달되는 모든 데스크톱 알림에 적용됩니다. 사용자 소리를 쓰면 같은 화면에서 재생 음량도 정할 수 있습니다. |
7. 설정(Settings) 전체 지도
설정 화면은 19개나 되지만, 처음에 손댈 일은 거의 이 세 곳뿐입니다. 나머지는 아래 “🔧 개발자용 참고” 상자에 모두 접어 두었습니다. 어떤 설정이든 Cmd+,(macOS)를 누르고 키워드를 입력하면 검색할 수 있습니다.
초보자 필수 3개
General(일반) — 앱 전체에 걸친 기본 동작. 초보자가 볼 것: Updates(업데이트 확인·설치), UI zoom(화면 글자 크기 배율), Default new-worktree name(새 워크트리 기본 이름).
General 항목 전체
| 항목 | 설명 |
|---|---|
| Orca CLI | 함께 들어 있는 명령줄 도구를 셸과 에이전트가 쓸 수 있게 등록합니다. |
| Updates | 업데이트 확인·설치. Check for Updates의 보조 키 클릭: Shift+클릭 = 최신 RC 포함 / Cmd+클릭(macOS)·Ctrl+클릭(Windows·Linux) = 최신 perf 태그 사전 출시판 / Option+클릭(macOS만) = 호환성 검사를 통과한 로컬 macOS 빌드 선택. 실패 시 “Could Not Use Local Build”와 Choose Another Build. |
| Open in menu | 워크트리의 “Open in”(다른 앱으로 열기) 메뉴에 나올 앱을 고릅니다. VS Code / Insiders는 SSH 워크트리를 Remote SSH로 열 수 있고, 다른 편집기는 로컬 경로로만 엽니다. |
| UI zoom | 설치본별 화면 배율. |
| Default new-worktree name | 새 워크트리 기본 이름: 사용자 접두어 또는 해양 생물 이름. |
| Editor Word Wrap | 파일 편집기의 기본 줄 바꿈(기본 켜짐). 파일 탭의 ⋯ 메뉴나 Alt+Z로 전환. Diff Word Wrap과는 별개입니다. |
| Reuse a preview tab when browsing files | 기본 켜짐. 파일을 한 번 클릭하면 현재 미리보기 탭을 바꿔치기합니다. 끄면 한 번 클릭한 파일마다 새 탭이 열립니다. |
| Collapse Unchanged Regions | 단일 파일 diff에서 바뀌지 않은 긴 구간을 접고 주변 몇 줄만 보여 줍니다. 필요하면 펼칠 수 있고, “View all changes”(전체 변경 보기)는 자기만의 접힘 배치를 따로 유지합니다. |
Agents(에이전트) — 가장 항목이 많은 화면입니다. 초보자가 볼 것: Installed agents(내 컴퓨터에서 찾은 에이전트 켜고 끄기), 새 워크트리에 미리 선택될 기본 에이전트, Agent permissions(에이전트가 일할 때 매번 나에게 허락을 받을지 — Manual은 매번 승인, Auto는 일상적인 동작만 스스로 승인, Yolo는 묻지 않음), Account lists(쓰는 AI 계정 목록).
Agents 항목 전체
| 항목 | 설명 |
|---|---|
| Installed agents | 감지된 CLI 목록. 켜고 끌 수 있으며, 끄면 실행 메뉴에 원하는 CLI만 보입니다. |
| Per-agent launch defaults | 에이전트별 실행 파일 경로·이름 지정, 기본 Command·Arguments(와 환경 변수) 편집. 구조화된 네이티브 채팅도 같은 명령·인자를 씁니다. 이 실행 설정은 워크트리가 돌아가는 호스트에서 편집되므로, 원격·SSH 워크트리는 그 기기의 설정을 씁니다. |
| Agent permissions | 새 터미널·구조화 채팅 세션의 권한 모드: Manual(매번 승인), Auto(일상적 동작은 에이전트가 스스로 승인 — Claude, Claude Agent Teams, Codex 지원), Yolo(묻지 않음). Auto를 고르면 지원하지 않는 에이전트용으로 Other agents에서 Manual 또는 Yolo를 정합니다. 기존 채팅은 현재 모드를 유지하고, 사용자 지정 실행 인자를 쓰는 에이전트는 그 인자를 프리셋으로 바꾸기 전까지 그대로입니다. |
| Trust the folder when Orca starts an agent | 기본 켜짐. Orca가 실행하는 에이전트(오케스트레이션 작업자, 자동화, 휴대폰에서 시작한 에이전트 포함)가 “이 폴더를 신뢰하나요?” 질문을 건너뜁니다. 끄면 각 에이전트 자신의 신뢰 질문이 그대로 나옵니다. |
| Share Codex history across accounts | 기본 켜짐. Orca가 관리하는 계정의 기록이 시스템 기본 계정으로 돌아갔을 때 ~/.codex에도 보입니다. 끄면 새 공유만 멈추고 기존 기록은 지우지 않습니다. 오래된 SSH·WSL 호스트는 업데이트해야 이 설정이 나타납니다. |
| Run each Codex terminal on its own server | 기본 켜짐. Codex 탭의 상태 표시와 탭 닫기가 정확하게 동작하도록 합니다. 끄면 Codex의 공용 서버와 그 에이전트 개요 화면을 씁니다. 새 터미널부터 적용. 직접 시작한 Codex가 서버를 공유하면 Warn when a Codex tab shares a server 알림이 뜹니다. |
| Account lists | Claude, Codex, OpenCode, Devin, Antigravity, GLM Coding Plan 계정 목록. Linux에서 암호화하지 못한 저장 자격 증명은 경고로 표시됩니다. Claude 계정마다 설정 폴더가 따로 있으며, 기본 브라우저가 이미 다른 Claude 이메일로 로그인돼 있으면 계정 추가 시 Copy sign-in link(로그인 링크 복사)를 제안합니다. Antigravity 계정 줄은 채팅 런타임 설치 상태를 보여 주고 그 호스트에 설치·제거할 수 있습니다. |
| OpenCode Go session cookie | Go 요청 한도를 보려면 __Host-console_session을 포함한 opencode.ai의 전체 Cookie 헤더를 붙여 넣습니다. 인증 쿠키 하나만으로는 부족합니다. |
| Startup hooks | 에이전트별 시작 훅(시작할 때 자동으로 실행할 동작). |
| Agent status hooks | Orca에 working / waiting / done 상태를 표시. 앱을 재시작하지 않아도 바로 적용됩니다(Windows WSL 훅 중계 포함). CLI: orca agent hooks on|off|status. |
| Keep computer awake | On(계속 깨어 있음), Agent(에이전트가 일하는 동안만), Off. 데스크톱 상태 표시줄의 Caffeinate(커피 아이콘)도 같은 조작입니다. 페어링된 웹 클라이언트에서는 숨겨집니다. |
| Skill freshness | Agents 화면과 스킬 카드는 전체 상태를 보여 주지만, 사이드바는 조치가 필요한 스킬(Update available, Needs attention / review)에만 배지를 답니다. 정상·로딩 중·선택 사항 미설치는 조용합니다. 대화상자의 Update로 전역 스킬을 백그라운드에서(터미널 없이) 갱신하고, 진행 상황은 상태 표시줄에 나옵니다. 대화상자를 닫아도 작업은 취소되지 않습니다. |
Notifications(알림) — 자세한 내용은 위 “6. 알림” 절.
- Agent-finished(에이전트 완료): 시스템 알림, 소리, 칩(워크트리 옆 작은 표시) 각각 켜고 끄기
- 종류별 사용자 지정 데스크톱 알림 소리
- Machines: 이 컴퓨터에 알림을 띄울 기기(이 컴퓨터, SSH 대상, 페어링된 Orca 서버). 페어링된 서버 스위치는 그 서버를 거친 작업까지 포함하고, 새로 추가한 기기는 알림이 옵니다.
- PR check failures(PR 검사 실패)
- Update available(업데이트 있음)
나머지 설정 탭 16개 전체
이 가이드의 다른 장에서 해당 기능을 자세히 다룹니다.
Appearance(모양) — 테마·글꼴·상태 표시줄·언어.
| 항목 | 설명 |
|---|---|
| Theme, accent color, density | 테마, 강조색, 화면 밀도. 설치한 플러그인이 앱·터미널 테마를 테마 선택기에 추가할 수 있고, 앱 테마가 터미널 색까지 함께 제공하기도 합니다. |
| Font family | UI 글꼴. 편집기 글꼴은 선택 사항으로, 비워 두면 터미널 글꼴을 따르고 값을 넣으면 파일 편집기와 diff에만 적용됩니다. |
| Editor minimap | 편집기 오른쪽 축소 지도 켜기/끄기. |
| Status bar toggles | 상태 표시줄 항목 켜기/끄기. 여기에 Resource Manager(CPU·메모리·세션, 데몬 조작, 워크트리 디스크 검사)가 있습니다. 프로젝트가 페어링된 Orca 서버에 있으면 그 서버의 프로세스를 서버 이름 아래에 보여 줍니다. |
| Usage percentages | 상태 표시줄 목록(roster)에 AI 제공자 한도를 “사용한 %” 또는 “남은 %”로 표시. 목록은 이제 기본이 짧은 Compact 보기이며(이미 고른 적이 있으면 유지), 같은 선택기에서 Detailed도 고를 수 있습니다. |
| App Icon | Dock과 창 전환기에 보이는 아이콘: Classic, Watercolor, Blue 중 선택. |
| Language | 인터페이스 언어: System(OS를 따름), English, 中文(简体), 繁體中文, 한국어, 日本語, Español, Deutsch, Русский, Türkçe. 설정 검색은 각 언어의 “언어”라는 단어(语言 / 語言 / 언어 / 言語 / Idioma)로도 찾아 주므로, 화면이 아직 영어여도 “언어”로 검색할 수 있습니다. |
Chat(채팅) — 기본 실행 화면을 Chat(채팅 UI)으로 할지 CLI(터미널)로 할지와 에이전트별 예외를 정합니다(Agents 화면에서도 가능). 새로 설치하면 기본은 Terminal이고, 기존 실행 설정은 유지됩니다.
| 항목 | 설명 |
|---|---|
| Behavior | 에이전트가 일하는 동안 후속 메시지를 대기열에 쌓을지, 사용량 한도에 걸린 채팅이 한도가 풀리면 자동으로 이어갈지 정합니다. 새 세션의 권한 기본값은 Agents 화면에서 정하며, 이미 있는 채팅은 자기 모드를 유지합니다. |
| Agents | 지원 에이전트마다 Chat 또는 CLI 선택. 이 데스크톱에서 시작하는 모든 경우(CLI, 오케스트레이션, 휴대폰에서 중계된 실행 포함)에 적용됩니다. Antigravity의 채팅 런타임이 없으면 그 줄에 Install이 보이고, Remove는 실행 중인 채팅을 멈추고 런타임을 지우되 채팅 기록은 남깁니다. |
| Appearance | 채팅 글꼴(미리보기와 설치된 글꼴 추천 포함), 본문 크기·코드 크기(px), 너비, 대비. Match terminal interface를 켜면 채팅 전체가 터미널의 글꼴·색을 쓰고, 나중에 터미널 테마를 바꿔도 따라갑니다. 켜져 있는 동안 글꼴·크기 조절은 비활성화됩니다. Reset chat appearance로 기본값 복원. |
| Inline visuals | 에이전트가 답변 안에 차트·다이어그램·목업을 보여 주도록 허용. 새로 시작하는 채팅에 적용됩니다. |
| Chat naming | 새 채팅은 기본적으로 자기 에이전트와 계정으로 이름을 만듭니다. Advanced에서 이름 짓기용 에이전트를 따로 고를 수 있고, 예전에 저장한 이름 짓기 명령·인자도 계속 동작합니다. |
Git — 브랜치 기준점과 GitHub 사용량.
| 항목 | 설명 |
|---|---|
| Default base ref resolver | 기본 base ref(새 워크트리의 출발점)를 정하는 방식. |
| Commit signing | 커밋 서명 옵션. |
| Editor for external git tools | 외부 git 도구가 쓸 편집기. |
| Auto-Rename Branch From Work | Orca가 만든 생물 이름 브랜치를, 에이전트가 일을 시작한 뒤 작업 내용에 맞게 이름을 바꿉니다. |
| GitHub API Budget | 로컬 gh CLI 기준으로 남은 REST(core)·Search·GraphQL 할당량. PR 검사나 Tasks가 갱신을 멈췄을 때 유용합니다. 숫자는 괜찮은데 GitHub가 실제 호출을 막는다면 아래 “GitHub 오류” 절을 보세요. |
Terminal(터미널)
| 항목 | 설명 |
|---|---|
| Font, theme, cursor style, padding | 글꼴, 테마, 커서 모양, 여백. |
| Ghostty import | Ghostty 터미널 설정 가져오기. |
| Warp theme import | Import themes from Warp(OS별 Warp 테마 폴더를 자동으로 찾음) 또는 Import from YAML(Warp 형식 테마 파일이 든 아무 폴더)로 Warp YAML 테마를 가져옵니다. |
| JIS Yen (¥) to Backslash (\) | macOS 일본어 키보드에서 ¥ 키를 백슬래시로. |
| Default shell | 새 로컬 터미널 탭의 기본 셸. 비우면 시스템 기본값. Windows에서는 가능한 경우 PowerShell, Command Prompt, WSL도 고를 수 있습니다. |
| Shell arguments | Unix 사용자 지정 기본 셸의 인자(Default shell → Advanced). -l(기본, 로그인 셸) 또는 Custom args를 골라 한 줄에 하나씩 입력. 빈 목록이면 인자를 넘기지 않습니다. |
| Running terminal limit | 컴퓨터별 동시 실행 터미널 한도(Advanced). 기본은 시스템 터미널 한도의 절반(최대 4096), 시스템 한도를 못 읽으면 256. 바꿔도 이미 열린 터미널은 닫히지 않습니다. 업데이트 후에는 새 터미널을 열어야 새 터미널 호스트를 씁니다. 오래된 원격 서버는 업데이트해야 한도를 바꿀 수 있습니다. |
| Allow TUI Clipboard Writes (OSC 52) | 기본 켜짐. Zellij, tmux, Neovim, fzf, Grok 같은 터미널 화면 프로그램이 PTY(가상 터미널)를 통해 — SSH 너머에서도 — 시스템 클립보드에 쓸 수 있게 합니다. 예전처럼 막아 두고 싶으면 끕니다. |
Quick Commands(빠른 명령)
- 저장해 둔 터미널 명령과 에이전트 프롬프트 프리셋. 범위는 전체(Global) 또는 프로젝트별. 줄마다 명령 본문 복사 버튼이 있습니다.
- 범위 필터로 목록을 검토·편집합니다. 같은 목록이 모바일 앱과 동기화됩니다.
- 원격·다중 호스트 환경에서는 명령을 소유한 Orca 호스트별로 묶어 보여 줍니다(Saved on). 호스트 소유는 Global/Project 범위, 그리고 명령이 실행되는 곳과는 별개입니다.
Browser(브라우저) — 워크트리별 내장 브라우저.
| 항목 | 설명 |
|---|---|
| Profiles | 브라우저 프로필(로그인 상태 등을 분리 보관). |
| Default Zoom | 새로 여는 브라우저 탭의 확대 수준. 탭마다 Cmd+휠(macOS)로 바꾼 값은 따로 기억됩니다. |
| Design Mode defaults | 디자인 모드 기본값. |
| Devtools opt-in | 개발자 도구 사용 선택. |
| Remote server workspaces | 페어링된 런타임의 새 브라우저 페이지를 This device(이 데스크톱에서 그림) 또는 Server (streamed)(서버에서 그려 스트리밍)로. 트래픽은 항상 원격 서버를 거치며, 새 페이지에만 적용됩니다. |
| Browse through SSH workspace hosts | 브라우저 트래픽과 DNS를 각 워크트리의 SSH 호스트를 통해 보냅니다. 끄면 이 기기에서 직접 접속합니다. |
| Link Routing | 터미널·마크다운·편집기의 http(s) 링크를 Orca 브라우저로 열지 시스템 브라우저로 열지. 하위 옵션 Hold Shift…를 쓰면 한 번의 클릭에 한해 반대로 동작합니다(⇧⌘-클릭 / Shift+Ctrl+클릭). |
| Terminal URL clicks | 터미널 URL을 그냥 클릭했을 때 동작 메뉴를 열지, 바로 열지, 보조 키가 필요한지. 가운데 클릭 동작은 따로 설정합니다. |
| Show terminal link actions | 기본 켜짐. 터미널 링크를 그냥 클릭하면 작은 동작 팝오버가 열립니다. 끄면 ⌘-클릭 / Ctrl-클릭해야 열립니다. |
| Default Search Engine | 주소창이나 새 탭 검색창에 URL이 아닌 글을 입력했을 때 쓸 검색 엔진. |
Artifacts(공유 파일) — HTML/Markdown을 공개 링크로 공유.
| 항목 | 설명 |
|---|---|
| Orca account | 공유 파일을 게시·관리하려면 로그인(Orca Relay와 같은 계정 계열). |
| Allow publishing public artifact links | 기본 꺼짐. 기기 전체에 걸린 관문입니다. 켜면 나·에이전트·이 기기의 orca CLI가 최대 10 MiB의 HTML/Markdown을 올리고 공개 보기 링크를 만들 수 있습니다. 꺼도 이미 만든 링크는 지워지지 않습니다. |
| Show Artifacts / sidebar shortcut | Artifacts 목록을 열어 계정 소유 링크를 검색·미리보기·복사·삭제. |
| Ask Before Deleting Artifacts | 공개 링크를 끊기 전에 확인을 받는 선택 옵션. |
| 공유 방법 | 열려 있는 로컬 HTML 페이지나 마크다운 편집기에서 Share as artifact, 또는 orca artifacts … 명령. |
Integrations(외부 서비스 연동)
| 항목 | 설명 |
|---|---|
| GitHub OAuth | GitHub 로그인 연동. |
| Linear API token | Linear(이슈 관리 서비스) 토큰. |
| Jira | Cloud(이메일 + API 토큰) 또는 자체 설치 Server/Data Center(PAT 또는 사용자 이름/비밀번호). |
| Bitbucket Cloud | Email & API token(기본) 또는 Access token으로 연결. Orca가 저장 전에 자격 증명을 확인합니다. ORCA_BITBUCKET_* 환경 변수가 있으면 그것이 우선이며 Connect / Disconnect 버튼이 숨겨집니다. 저장한 자격 증명은 이 기기에만 남으므로, 원격 Orca 서버에서는 서버에 환경 변수를 설정하세요. |
| MiniMax | MiniMax 세션 쿠키(platform.minimax.io/console/usage에서)를 붙여 넣어 MiniMax CLI의 로컬 사용량·한도 추적을 켭니다. 선택 사항인 group ID와 usage models 칸은 쿠키에서 고른 기본값을 덮어씁니다. |
| MCP servers | MCP 서버 설정. 저장소의 MCP 설정은 그것을 고른 호스트에 남습니다. |
Voice(음성 받아쓰기)
| 항목 | 설명 |
|---|---|
| Enable Voice Dictation | 마이크 권한이 필요합니다(macOS는 개인정보 보호 및 보안 설정이 열릴 수 있음). |
| Microphone | 받아쓰기에 쓸 입력 장치. 기본은 시스템 마이크이고, 헤드셋처럼 특정 장치를 고를 수 있습니다. 고른 마이크가 빠지거나 없으면 시스템 기본으로 돌아가고 방해하지 않는 안내를 띄웁니다. |
| Dictation mode | Toggle(단축키로 시작/정지) 또는 Hold(단축키를 누르고 있는 동안 말하기). |
| Speech Model | 기기 안에서 도는 모델을 내려받아 쓰거나, API 키를 붙여 넣고 OpenAI 클라우드 모델을 씁니다(아래 표). |
| Listening… 표시 | 듣는 동안 Listening… 알약 모양 표시에 Stop 버튼이 나옵니다. Toggle 모드에서는 툴팁에 받아쓰기 단축키도 보입니다. |
| 음성 모델 | 특징 |
|---|---|
| Parakeet TDT v3 (권장) | 여러 유럽 언어, 오프라인 |
| Parakeet TDT v2 | 영어, 더 빠름 |
| Zipformer 계열 | 중국어+영어 이중 언어 스트리밍, 영어/중국어 스트리밍, Zipformer Streaming KO(한국어) |
| Paraformer Bilingual | 중국어 방언 + 영어 |
| Parakeet TDT-CTC JA | 일본어 |
| SenseVoice | 중국어/영어/일본어/한국어/광둥어, 언어 자동 감지 |
| Whisper Tiny | 90개 이상 언어, 정확도 낮음 |
| GPT-4o mini / GPT-4o Transcribe | 클라우드. 같은 화면에 OpenAI 키 필요 |
SSH
- SSH 워크트리, 대상 호스트, 암호문(passphrase), 기본 신원 파일(identity file), 여러 호스트 일괄 관리. 여러 호스트를 골라 한 번에 Test 또는 Remove할 수 있고, OpenSSH 설정 목록에서 지운 호스트는 Restore removed hosts를 누르기 전까지 지워진 채로 남습니다.
- Advanced: 프록시 / 점프 호스트, Reuse SSH connection for faster setup(시스템 OpenSSH 다중화로 빠른 연결, 기본 켜짐), 호스트별 Allow this host's orca CLI to control Orca(그 호스트의 orca CLI가 Orca를 조작하도록 허용).
- Managed servers: Orca가 빈 SSH 호스트에 자체 서버를 설치·실행하고 최신으로 유지합니다. 버전과 터미널을 보고 Update, Roll back(되돌리기), Recover(복구), Stop… / Forget…(중지/잊기)를 할 수 있습니다. 모든 SSH 호스트는 이 관리 서버 위에서 돌며, 예전의 Runtime 선택기는 없어졌습니다. 관리 서버가 돌 수 없는 호스트는 이유를 보여 주고 연결하지 않습니다.
- Kerberos 호스트: OpenSSH 설정의
GSSAPIAuthentication이 시스템 OpenSSH 인증을 결정합니다.
Remote Orca Servers(원격 Orca 서버)
- 원격 Orca 런타임과 페어링·연결하는 서버 목록. Add server로 접속 링크 붙여 넣기, SSH 호스트에 설치, Cloud VM 설정 중 하나를 고릅니다. 줄마다 상태가 보이고 덜 쓰는 동작은 ⋯ 메뉴에 있습니다.
- 이 데스크톱 앱을 서버로 알리고(advertise), 취소 가능한 접속 링크를 만듭니다.
- 페어링된 모바일에 보일 이 데스크톱의 Machine name. 비우면 감지된 컴퓨터 이름을 씁니다.
- Advanced: 서버를 거치는 프로젝트·터미널·제공자 확인에 쓸 기본 런타임 선택.
Shortcuts(단축키) — 전체 키맵이 있고 모든 단축키를 다시 지정할 수 있습니다.
| 동작 | macOS | Windows / Linux | 비고 |
|---|---|---|---|
| Close all editor tabs(편집기 탭 모두 닫기) | Cmd+Option+W | Ctrl+Alt+W | |
| 다음/이전 탭(모든 종류) | Cmd+Shift+] / [ | Ctrl+Shift+] / [ | 새 설치 기본값 |
| 같은 종류 다음/이전 탭 | Cmd+Option+] / [ | (Ctrl 계열) | 새 설치 기본값 |
| 직전에 쓴 탭 | Ctrl+Tab | 새 설치 기본값 | |
| Add Review Note(검토 메모 추가) | Cmd+Shift+A | Ctrl+Shift+A | 변경 가능 |
| Delete workspace(워크트리 삭제) | Cmd+Shift+Backspace | Ctrl+Shift+Backspace | 지울 사이드바 워크트리 위에 마우스를 올려 두고 누름. 그래도 확인을 묻습니다. |
| Toggle Sleeping Workspaces | 지정 안 됨 | 사이드바의 잠든 워크트리 필터를 바로 켜고 끄고 싶으면 지정 | |
| Toggle Child Workspaces | 지정 안 됨 | 상위 워크트리의 하위(children) 보이기/숨기기 — “N children” 칩 클릭과 같음. 마우스 아래 워크트리, 없으면 활성 워크트리 대상 | |
| Toggle Workspace Board | 지정 안 됨 | Workspace Board 열기/닫기. 기존 workspace.openBoard 지정도 계속 동작 | |
| Send Review Notes to Agent | 지정 안 됨 | 지정하면 마우스 없이 활성 워크트리의 diff 메모 보내기 메뉴를 엶 | |
기존 설치본은 직접 바꾼 단축키를 ~/.orca/keybindings.json에 그대로 유지합니다.
Repository(저장소별)
| 항목 | 설명 |
|---|---|
| Base ref and hooks | 저장소별 base ref와 훅. |
| Auto-run commands | 워크트리를 만들 때 자동으로 실행할 명령. |
| Repo icons | 사이드바 저장소 아이콘: 아이콘, 검색 가능한 전체 이모지, 업로드한 이미지, 웹사이트 파비콘, GitHub 아바타 중 선택 후 프리셋 또는 직접 입력한 hex 배지 색. |
| Source Control AI overrides | 커밋 메시지, PR 내용, 브랜치 이름을 만드는 AI 설정을 저장소별로 덮어쓰기. |
| Worktree Shared Paths | git이 무시하는(gitignored) 경로를 기본 체크아웃에서 새 워크트리마다 만들어 줍니다(macOS는 가능하면 APFS 복제 복사, 아니면 심볼릭 링크). 저장소에 커밋된 orca.yaml의 worktree.sharedDirectories 및 .worktreeinclude와 함께 쓰입니다. |
Floating Workspace(떠 있는 워크트리) — 특정 저장소 워크트리에 묶이지 않은 터미널·브라우저·마크다운 탭을 위한 전역 공간.
| 항목 | 설명 |
|---|---|
| Enable Floating Workspace | 기능 켜기. |
| Terminal Directory | 새 floating 터미널 탭의 시작 폴더(~ = 홈). |
| Toggle Button Location | 전환 버튼이 나타날 위치. 키보드 단축키는 버튼 위치와 상관없이 동작합니다. |
Plugins(플러그인)
- Settings → Plugins, 상태 표시줄 버튼, 또는 텍스트 입력칸 밖에서 Cmd+Shift+X / Ctrl+Shift+X로 엽니다. 카탈로그를 둘러보고, 분류나 설치 상태로 거르고, 설치한 플러그인을 켜고 끕니다.
- 플러그인은 테마, 아이콘 테마, 구문 강조, 사용자 지정 편집기 등 여러 기능을 추가합니다. git 마켓플레이스 소스를 추가하고 설치된 버전을 관리할 수도 있습니다.
- 플러그인 시스템은 기본 켜짐. 설치(
orca://plugins링크 포함)하면 검토 화면이 열립니다.
코드를 실행하는 플러그인은 설치 전에 동의를 받으며, 승인하면 내 컴퓨터 전체에 접근할 수 있습니다. 믿을 수 있는 플러그인만 설치하세요. 플러그인 작업자는 이 컴퓨터에서 돌고, SSH 워크트리 동작은 여전히 Orca를 거칩니다.
Experimental(실험 기능) 안정화 전 — 동작이 바뀔 수 있음
| 항목 | 설명 |
|---|---|
| Activity Page | Slack 같은 워크트리 피드로 에이전트 사건을 보여 줌. |
| Compact 워크트리 cards | 레이아웃이 실험 단계인 동안 사이드바 카드의 중복된 둘째 줄을 숨김. |
| Agent hibernation | 쉬고 있는 백그라운드 에이전트를 일시정지하고 다시 열면 자동 재개. |
| Agent Dashboard | Needs You / Working / Done(선택적으로 Idle) 칸반 보드. 검색과 프로젝트·워크트리·PR 필터, 창 안 또는 별도 창으로 열기. “Show idle agents”는 여기가 아니라 대시보드 보드 설정에 있습니다. |
| Browser extensions | 재시작 후 로컬 브라우저 프로필에서 Chrome 웹 스토어 확장 사용. |
| Cloud VM | 저장소가 소유하는 필요 시 환경(클라우드 샌드박스, VM, 로컬 Docker)의 설정 조작과 워크트리 Run on 대상을 표시. 설정 안내와 레시피 설치가 이 토글 아래에 있습니다(위 “실행 방식 ④”). |
8. 개인정보와 텔레메트리
텔레메트리(telemetry)(프로그램이 사용 통계를 개발사로 보내는 것)는 정식 배포된(packaged) Orca 빌드가 보내는 익명 사용 통계입니다. 핵심만 먼저 보면 다음과 같습니다. 끄고 싶다면 앱 설정에서 스위치 하나만 끄면 됩니다.
내 기기에 저장된 무작위 ID로만 구분합니다. 계정, 이메일, IP 주소, 사용자 이름은 수집하지 않습니다.
파일 내용, 프롬프트, 에이전트 출력, 터미널 출력, 저장소 이름, 브랜치 이름, URL, 경로, 커밋 메시지를 절대 보내지 않습니다.
Settings → Privacy에서 “Share anonymous usage data”(익명 사용 데이터 공유)를 끄면 됩니다. 개발자용 방법(환경 변수)도 있습니다 — 아래 “끄는 법” 탭.
모든 사건에 함께 붙는 정보: Orca 버전, 운영체제(darwin / win32 / linux 등), CPU 구조, 대략적인 OS 릴리스 문자열, 배포 채널(stable 또는 rc), 익명 로컬 ID. 호스트 이름·사용자 이름·IP는 없습니다.
| 분류 | 기록하는 것 | 기록하지 않는 것 |
|---|---|---|
| Lifecycle(생애 주기) | 앱이 열린 시점 — 일·주·월간 활성 사용자 추정용 | |
| Repos and workspaces | 저장소 추가·워크트리 생성 시점과 방법(폴더 선택 vs 클론 URL, 명령 팔레트 vs 끌어놓기 등) | 저장소 이름, URL, 경로, 브랜치 이름, 자유 입력 글 |
| Agents | 에이전트 시작 시점, 종류(claude-code, codex, gemini 등 고정 목록), 어디서 실행했는지 | 프롬프트, 모델 세부, 에이전트 출력 |
| Agent errors | 대략적인 오류 분류와 관련 에이전트 종류 | 오류 원문, 스택 트레이스(오류가 프로그램 어디서 났는지 줄줄이 적은 기록)(사건별 세부는 내 기기의 로컬 진단 파일에만 남고, 내가 직접 진단 묶음을 공유할 때만 전달) |
| Settings | 허용 목록에 있는 소수의 기능 플래그·UX 설정을 바꾼 시점, 어떤 설정이 바뀌었는지, 참/거짓형인지 선택형인지 | 자유 입력 설정의 실제 값 |
| Privacy controls | 텔레메트리를 켜거나 끈 시점 — 동의 화면이 제대로 동작하는지 집계로 확인하기 위해 |
- 파일 경로, 저장소 이름, 브랜치 이름, URL, 커밋 메시지, 현재 작업 폴더
- 에이전트 프롬프트, 응답, 터미널 내용
- 오류 원문이나 스택 프레임 (사건별 오류 맥락은 로컬 진단 파일에만 있고, 직접 진단 묶음을 공유할 때만 전달)
- 사용자 계정 정보 (Orca에는 계정 시스템이 없음)
- IP 주소, 정밀한 위치 — 요청에서 얻는 지리 정보는 국가뿐
- 익명 ID에 연결된 공급사 쪽 사용자 프로필
초보자는 앱 설정에서 끄기만 하면 됩니다. Settings → Privacy에서 “Share anonymous usage data”(익명 사용 데이터 공유)를 끕니다. 즉시 적용되고 계속 유지됩니다.
환경 변수로 끄기
방법은 모두 세 가지이며 하나만 해도 충분하고 함께 써도 됩니다. 나머지 두 가지는 환경 변수(프로그램을 실행할 때 컴퓨터가 함께 건네주는 “설정 쪽지”. 터미널이나 시스템 설정에서 정함)를 쓰는 방법입니다.
- 앱에서Settings → Privacy에서 “Share anonymous usage data”를 끕니다.
DO_NOT_TRACK=1업계 공통 환경 변수. 그 실행 동안 전송을 막습니다. 변수를 지우면 다음 실행 때 저장된 설정으로 돌아갑니다.ORCA_TELEMETRY_DISABLED=1Orca 전용 차단 스위치. 동작은 DO_NOT_TRACK과 같습니다.
이 두 환경 변수 중 하나가 설정돼 있으면 앱 설정과 상관없이 항상 꺼집니다.
| 공급사 | PostHog Cloud, 미국 리전(미국에 있는 데이터 센터) |
|---|---|
| 보관 기간 | PostHog Cloud 요금제의 기본값(그들 요금 페이지 기준). Orca가 따로 정한 보관 기간은 없음 |
| 접근 권한 | 소수의 Orca 관리자만 프로젝트 멤버 |
9. 문제 해결과 자주 묻는 질문
문제가 생겼을 때 돌아와서 보는 절입니다. 아래 표에서 증상을 찾아 한 줄 해결책을 먼저 보고, 자세한 방법은 “🔧 개발자용 참고”를 펼치세요.
| 증상 | 한 줄 해결책 |
|---|---|
| 에이전트가 시작되지 않아요 | Orca 밖에서 그 에이전트가 실행되는지 먼저 확인하고, 탭의 Restart를 누릅니다. |
| Codex가 “path must be shorter than SUN_LEN” | Orca를 v1.4.212 이상으로 업데이트합니다. |
| 어떤 프로필 사본을 쓸지 물어봐요 | 보통 Use SQLite (Recommended)를 고릅니다. |
| diff 화면이 이상하거나 멈춰 있어요 | diff 도구 막대의 새로고침 아이콘을 누릅니다. |
| 워크트리 만들기가 실패해요 | 서버의 최신 내용을 받아 오거나(git fetch origin) 다른 이름을 씁니다. |
| Orca CLI가 “command not found” | Settings → General → Orca CLI에서 등록합니다. |
| SSH는 되는데 원격 터미널이 안 돼요 | 설정의 SSH 호스트·관리 서버 화면에서 이유를 확인합니다. |
| SSH로 “Download Folder”가 안 돼요 | 폴더 전송(SFTP)이 막힌 것 — 파일 하나씩 받거나 터미널로 받습니다. |
| “Open in VS Code”가 비활성 | SSH 워크트리에서, VS Code로 지정해 엽니다. |
| Kerberos 로그인 실패 | Kerberos 로그인 티켓과 SSH 설정을 확인합니다. |
| browser_no_tab 오류 | 그 워크트리에 브라우저 탭을 먼저 엽니다. |
| 느리거나 메모리를 많이 써요 | 안 쓰는 워크트리와 브라우저 탭을 닫습니다. |
| GitHub PR 패널·검사 오류 | 아래 “10. GitHub 오류 해결”을 봅니다. |
증상별 자세한 해결 방법
에이전트가 시작되지 않아요
- Orca 밖의 일반 터미널에서 그 에이전트 CLI를 실행해 봅니다. 거기서도 실패하면 CLI 설치와 로그인을 확인하세요. Orca에서만 실패하면 아래를 봅니다.
- 그 CLI가 Orca가 보는 PATH(컴퓨터가 명령 프로그램을 찾아보는 폴더 목록)에 있는지 Settings → Agents에서 확인합니다.
- 탭의 Restart 칩을 눌러 봅니다.
Codex가 “path must be shorter than SUN_LEN”이라고 해요
Orca를 v1.4.212 이상으로 업데이트하세요. Codex 0.157 이상은 Orca가 관리하는 계정 홈에서 백그라운드 데몬의 소켓 경로가 너무 길면 이 오류가 날 수 있습니다. 이제 Orca가 해당 홈을 자동으로 조정하므로 계정을 옮기거나 시스템 ~/.codex/config.toml을 고칠 필요가 없습니다.
Orca가 어떤 프로필 사본을 쓸지 물어봐요
프로필의 JSON 사본과 SQLite 사본이 둘 다 읽히는데 내용이 다르면, 각각 마지막으로 저장된 시각을 보여 줍니다. Use SQLite (Recommended) 또는 Use JSON을 고르면 그 사본을 유지하고 Orca가 적용 후 재시작합니다. 사본을 먼저 살펴봐야 하면 Quit을 고르세요. 다른 프로필 복구 오류는 별도의 명령 안내가 나올 수 있습니다.
diff 화면이 이상하거나 멈춰 있어요
- diff 도구 막대의 새로고침 아이콘을 누르면 Orca가 워크트리를 다시 읽습니다.
- 외부에서 한 git 작업(rebase, reset)이 새로고침 사이에 끼어들 수 있습니다.
워크트리 만들기가 실패해요
- start-from ref를 아직 가져오지(fetch) 않았을 수 있습니다. 저장소에서 터미널을 열고
git fetch origin을 실행하세요. - 대상 폴더에 이미 그 브랜치의 워크트리가 있을 수 있습니다. 지우거나 새 브랜치 이름을 고르세요.
Orca CLI가 “command not found”라고 해요
Settings → General → Orca CLI에서 CLI를 등록하세요. macOS에서는 ~/.local/bin에 실행 연결 파일(shim)을 설치하므로, 그 폴더가 셸의 PATH에 있어야 합니다. Windows에서는 orca가 설치 프로그램이 PATH에 추가하는 네이티브 프로그램입니다.
SSH는 연결되는데 원격 터미널이 안 돼요
- Orca가 호스트에 자체 관리 서버를 설치하므로 Node 버전 불일치나 빌드 도구 부족으로는 더 이상 연결이 막히지 않습니다. Settings → SSH Hosts에서 그 호스트가 어떤 서버를 쓰는지 보고, Settings → Managed servers에서 update / roll back / recover 할 수 있습니다.
- 관리 서버가 돌 수 없는 호스트는 더 이상 예전 SSH 런타임으로 대체되지 않습니다. Settings → SSH Hosts가 이유를 설명하고 연결은 그 이유와 함께 실패합니다. 그 호스트에 계속 연결하려면 이전 버전 Orca를 쓰세요.
- v1.4.224에서 넘어온 터미널은 입출력은 되지만
orcaCLI가 없습니다. orca 명령이 필요하면 같은 호스트에 새 터미널을 여세요.
SSH로 파일은 되는데 “Download Folder”가 안 돼요
폴더 내려받기에는 재귀 SFTP 전송이 필요합니다. 시스템 SSH만 쓰는 연결에서도 파일 하나 내려받기는 될 수 있습니다. 대안으로 터미널에서 tar/scp를 쓰세요.
“Open in VS Code”가 비활성이거나 Local only라고 나와요
- 원격 Orca 서버 런타임이 아니라 SSH 워크트리를 쓰세요.
- Open-in 명령을 Cursor나 인자가 여러 개인 셸 명령이 아니라 VS Code / Insiders로 지정하세요.
- 호스트를 지웠다면 SSH 대상을 새로고침하세요.
Kerberos 로그인이 실패해요
klist에 그 호스트 영역(realm)의 유효한 티켓이 보이는지 확인합니다.- OpenSSH 설정의 해당 Host에
GSSAPIAuthentication yes가 있는지 확인한 뒤, Settings → SSH에서 대상을 다시 가져오거나 다시 테스트합니다.
브라우저가 browser_no_tab이라고 해요
현재 워크트리에 열린 탭이 없다는 뜻입니다. orca tab create --url ...로 열거나, 브라우저 창을 직접 열어 이동하세요.
느리거나 메모리를 많이 써요
- 지금 쓰지 않는 워크트리는 닫으세요. 워크트리마다 파일 감시자(file watcher)가 계속 살아 있습니다.
- 브라우저 탭이 많은 분할 레이아웃이 RAM을 가장 많이 씁니다. 필요 없는 브라우저는 닫으세요.
GitHub PR 패널 / 검사 / Tasks 오류
요청 한도, 잘못된 gh 인증, 부족한 권한 범위, 저장소 접근 문제는 모두 Source Control과 PR Checks 패널에 나타납니다. 전체 표는 다음 절 “GitHub 오류”를 보세요. 터미널에서는 gh가 되는데 Orca가 GitHub CLI가 없다고 한다면, PATH에 있는 gh 실행기 하나가 멈춰 있을 가능성이 큽니다. Orca는 멈춘 실행기를 지나쳐 버전 확인을 통과하는 사본을 찾아 쓰며, CLI가 없다고 보고하지 않습니다.
gh auth status -h github.com gh api user gh api rate_limit --jq '.resources.core'
Help → Open Logs로 Orca 로그 폴더를 엽니다. 버그를 신고할 때 첨부하세요.
- Help → Send Feedback(앱 안) — 스크린샷을 붙여 넣거나 끌어 놓거나 이미지 파일을 고르면, 보내기 전에 미리보기가 보입니다. 재현이 어려운 버그는 로그도 첨부하세요.
- GitHub Issues — 버그·기능 요청
- Discord — 실시간 도움
10. GitHub 오류 해결
GitHub(코드를 인터넷에 올려 두고 함께 작업하는 서비스)와 연결해 PR을 쓰다가 문제가 생겼을 때 보는 절입니다.
한 줄 요약: PR 상태·검사·이슈가 갱신되지 않으면 원인은 거의 항상 GitHub 로그인(인증), 권한, 요청 한도이지 Orca 고장이 아닙니다. 가장 흔한 것은 요청 한도 — 한 계정이 한 시간에 GitHub에 물어볼 수 있는 횟수를 여러 도구가 나눠 쓰다가 다 써 버리는 경우이며, 기다리면 풀립니다.
GitHub 오류 분류표·명령·대처법 전체
Orca는 내 컴퓨터(또는 원격 Orca 호스트)의 GitHub CLI(gh)를 통해 GitHub와 대화합니다. PR 상태, 검사(checks), 이슈, Tasks가 갱신되지 않으면 원인은 거의 항상 GitHub 인증, 권한, API 요청 한도이지 PR 패널 자체의 고장이 아닙니다.
빠른 분류표
| 보이는 메시지 | 가능성 높은 원인 | 먼저 해 볼 것 |
|---|---|---|
| “GitHub is rate-limiting requests” / “rate limit exceeded (core)” | 내 사용자의 GitHub REST(core) 할당량 소진 | 재설정까지 기다리기, 추가 gh/에이전트/Orca 사용 중단, Settings → Git → GitHub API Budget 확인 |
| “GitHub authentication is unavailable” / gh 인증 요구 | gh 미로그인, 만료된 토큰, 잘못된 GITHUB_TOKEN | gh auth status 후 gh auth login |
| “GitHub did not allow access” / HTTP 403(한도 아님) | 권한 범위(scope) 부족 또는 저장소 접근 불가 | repo(필요하면 조직 SSO 포함)로 재인증, 브라우저에서 PR이 열리는지 확인 |
| “repository is unavailable” / HTTP 404 | 잘못된 remote, 접근 권한 없는 비공개 저장소, 이름 바뀐 저장소 | git remote -v와 브라우저 접근 확인 |
| “GitHub is unreachable” / 시간 초과 | 네트워크, 프록시, VPN, GitHub 장애 | githubstatus.com 확인, VPN 끄고 재시도 |
| “GitHub CLI is unavailable” | Orca가 쓰는 PATH에 gh 없음 | gh 설치 후 Orca 재시작 |
요청 한도(rate limit) — 가장 흔함
GitHub는 로그인한 사용자마다 한 시간짜리 공유 예산을 줍니다. 그 계정을 쓰는 모든 도구가 같은 예산을 나눠 씁니다: Orca, 터미널의 gh, gh를 부르는 Claude/Codex/Grok 에이전트, CI 스크립트, 브라우저 확장, 다른 앱.
| 버킷(예산 종류) | 담당하는 것 | 보통 한도(로그인 시) |
|---|---|---|
| REST (core) | 대부분의 PR/이슈/API 호출(gh pr view, 검사 메타데이터, 여러 REST 엔드포인트) | 5,000 / 시간 |
| GraphQL | Project/Tasks와 일부 풍부한 PR 조회 | 5,000 포인트 / 시간 |
| Search | 검색 기반 목록 | 30 / 분 |
주 버킷이 바닥나면 GitHub는 “API rate limit exceeded” 같은 메시지와 함께 HTTP 403을 돌려줍니다. Orca는 이를 “rate-limited”로 분류하고, 가능하면 마지막으로 알던 PR 상태를 유지하며, 짧은 시간 동안 gh 호출을 더 띄우지 않아 한 번의 한도 초과가 연쇄 실패로 번지지 않게 합니다.
Settings → Git → GitHub API Budget은 GitHub의 특수 rate_limit 엔드포인트를 읽습니다. 이 조회는 한도 계산에서 빠져 있어서, 같은 사용자의 실제 REST 호출이 이미 remaining: 0인데도 남은 양이 있다고 보여 줄 때가 있습니다. 서로 다를 때는 이 순서로 믿으세요.
- PR / Checks 패널의 오류(실제 요청이 실패한 것)
- 터미널에서 한 실제 CLI 확인(아래)
- 설정의 예산 숫자(유용하지만 조회 전용)
또 GitHub API Budget을 Accounts의 Claude / Codex / Grok 사용량과 헷갈리지 마세요. 그것들은 AI 제공자 한도이지 GitHub REST 할당량이 아닙니다.
터미널에서 한도 확인하기
# 조회(할당량을 쓰지 않음; 실제보다 건강해 보일 수 있음)
gh api rate_limit --jq '.resources | {core, graphql, search}'
# 실제 REST 호출 — PR 갱신이 의존하는 것
gh api user -i 2>&1 | head -40
gh api user가 “API rate limit exceeded”와 X-Ratelimit-Remaining: 0으로 403을 돌려주면, 그 계정은 X-Ratelimit-Reset(Unix 초 단위 시각)까지 REST가 막힌 상태입니다.
- Orca 창이나 electron-dev 빌드를 여러 개 동시에 열어 둠(각자 PR/Tasks를 갱신할 수 있음)
- gh를 자동으로 돌리는 에이전트(PR/이슈 배정, 검사 폴링, 대량 GraphQL)
- PR 패널 갱신과 함께 무거운 Tasks / 여러 저장소 동시 처리
- 같은 GitHub 사용자 토큰을 쓰는 다른 앱
- 오류나
X-Ratelimit-Reset에 나온 시간당 재설정까지 기다립니다. - 동시에 도는 GitHub 클라이언트를 줄입니다 — 여분의 Orca를 끄고 대량 gh 자동화를 멈춥니다.
- 한도에 걸린 동안 PR 패널 새로고침을 연타하지 마세요. Orca가 이미 물러나 있습니다.
- 스크립트는 GraphQL을 묶어서 쓰고, 개인 계정으로 큰 집합을 PR 하나씩 REST로 반복 조회하지 마세요.
- 재설정 후에도 PR 갱신이 실패하면 인증을 다시 확인합니다(아래).
인증 문제
Orca는 그 호스트에서 gh가 쓰는 인증을 그대로 물려받습니다.
gh auth status -h github.com
gh api user --jq '{login, id}'
정상: 로그인됨, 토큰 유효, gh api user가 내 login을 돌려줌.
셸 프로필(~/.bash_profile, ~/.zshrc 등)에 export GITHUB_TOKEN=$(gh auth token)처럼 내보내 두면, gh는 키체인보다 이 값을 우선합니다. 오래되거나 잘못된 환경 변수 토큰은 헷갈리는 인증·한도 동작을 만듭니다. 지우고 다시 로그인하세요.
unset GITHUB_TOKEN GH_TOKEN gh auth logout -h github.com gh auth login -h github.com
gh auth status가 토큰을 유효하지 않다고 보여 줄 수 있습니다. gh auth login(또는 gh auth refresh)을 실행하고 Orca를 재시작해 새 자격 증명을 읽게 하세요.
조직의 비공개 저장소는 토큰에 SSO 승인이 필요할 수 있습니다. GitHub 토큰 설정에서 조직의 SSO 승인 링크를 열고 다시 시도하세요.
GitHub 인증은 호스트마다 따로입니다. 노트북에서 로그인해도 원격 기기의 gh는 로그인되지 않습니다. 그 호스트에 SSH로 들어가 gh auth login을 하거나, 그 환경의 원격 서버 GitHub 예산 화면을 쓰세요.
권한과 저장소 오류
| 증상 | 의미 |
|---|---|
| “rate limit” 없는 HTTP 403 | 토큰 권한 범위가 부족하거나 그 자원을 볼 수 없음 |
| HTTP 404 / “could not resolve to a Repository” | 저장소가 없거나, 이름이 바뀌었거나, 이 토큰으로는 보이지 않음 |
| “resource not accessible by integration” | 앱/토큰 종류가 그 동작을 할 수 없음 |
gh api user와 같은 사용자로 로그인한 브라우저에서 PR/저장소가 열리는지 확인합니다.repo(그리고 그 기능을 쓰면read:org/project)를 포함한 classic 권한 범위로 재인증합니다.- GitHub Enterprise라면 그 호스트 이름으로 gh 인증이 됐는지 확인합니다(
gh auth login --hostname …).
시간 초과, “could not resolve host”, “GitHub is unreachable”은 연결 문제입니다.
- GitHub Status 확인
- VPN / 회사 프록시 없이 시도
- 원격 호스트라면 api.github.com으로 나가는 HTTPS가 되는지 확인
- gh 설치
- 일반 터미널에서
which gh가 되는지 확인 - Orca를 완전히 종료 후 다시 열기(PATH를 맞추기 위해)
- Windows는 Orca가 실행되는 환경(WSL인지 네이티브인지)과 같은 곳에 설치
GitHub가 실패할 때 Orca의 동작
| 상황 | Orca의 대응 |
|---|---|
| 요청 한도 / 장애 | PR·Checks 패널이 화면을 비우지 않고, 마지막으로 알던 상태 + 짧은 배너를 보여 줍니다. |
| 확실한 인증 / 권한 실패 | 로그인이나 접근 권한을 고치라는 명확한 빈 화면 안내나 배너가 나옵니다. |
| Circuit breaker(회로 차단기) | 주 버킷 한도 403을 받은 뒤, 그 버킷(core, search, graphql)에 대해 잠시 새 gh 실행을 거절합니다. 앱이 계속 반응하도록, 그리고 구멍을 더 깊이 파지 않도록 하기 위해서입니다. |
Orca에서 GitHub API Budget 보기
- Settings → Git → GitHub API Budget: GitHub 조회 기준 REST / Search / GraphQL 남은 양
- 한도가 풀릴 때까지 기다린 뒤 새로고침
- 원격 Orca 서버에서는 서버가 소유한 gh 신원에 대해 원격 고급(advanced) 예산 화면을 쓰세요. 로컬 설정은 데스크톱 클라이언트 것만 보여 줍니다.
- Orca가 쓰는 같은 기기·사용자에서
gh pr view나gh api user로 한 번 재현합니다. - Help → Open Logs로 로그를 모읍니다.
- 분류된 오류 문구(비밀값 제외), 가린(redacted)
gh auth status출력, 터미널 gh도 똑같이 실패하는지를 적어 GitHub Issues에 올립니다.
- Orca는 작업마다 워크트리·에이전트 터미널·브라우저 탭을 따로 주는 ADE(에이전트용 개발 환경)입니다. AI 에이전트의 구독은 직접 준비합니다.
- 설치는 다운로드 → 더블클릭 → 설치. macOS·Windows·Linux를 지원합니다.
- 실행 위치는 로컬 · SSH · 원격 Orca 서버 · Cloud VM(실험) 네 가지지만, 초보자는 화면과 일하는 곳이 같은 “로컬”만 알면 됩니다.
- 첫 세션 전에 에이전트 1개 설치·로그인과 git 저장소 폴더를 준비합니다. 흐름은 저장소 추가 → 워크트리 → 에이전트 → 창 분할 → 변경 검토 → 내보내기입니다.
- 같은 부탁을 에이전트 셋에게 시키고, 결과 화면·바뀐 줄 수·검사 통과로 승자를 고릅니다. 셋이 일치하면 아마 정답, 갈리면 어려운 지점이라는 신호입니다.
- Agents 피드는 자리 비운 뒤의 따라잡기 화면이고, 에이전트가 끝나면 시스템 알림·소리·칩·벨·Dock 배지로 알려 줍니다.
- 설정은 Cmd+,(macOS)로 열어 검색하며, 처음엔 General·Agents·Notifications만 보면 됩니다.
- 텔레메트리는 익명이고 내용·경로를 보내지 않으며, Settings → Privacy에서 끕니다.
출처: onorca.dev/docs (What is Orca?), /docs/install, /docs/first-session, /docs/ways-to-run, /docs/recipes/parallel-agents, /docs/activity, /docs/notifications, /docs/settings, /docs/telemetry, /docs/troubleshooting, /docs/github-errors
Orca의 핵심 모델 — 워크트리·세션·화면 배치·복원·빠른 이동
Orca는 "작업 하나 = 폴더 하나(워크트리)"라는 생각 위에 세워져 있습니다. 이 장에서는 그 바탕이 되는 git 워크트리부터, 에이전트 세션의 상태 표시, 탭과 화면 분할, 앱을 껐다 켜도 그대로 돌아오는 세션 복원, 그리고 키보드로 순식간에 이동하는 검색창까지 Orca의 뼈대를 차례로 살펴봅니다.
- 브랜치·체크아웃·워크트리가 무엇이고, 왜 Orca가 "작업마다 폴더를 따로" 쓰는지
- 워크트리의 일생(만들기 → 작업 → 검토 → 내보내기 → 정리)과 생성 대화상자의 모든 옵션
- gitignore된 파일을 새 워크트리에 채워 넣는 세 가지 방법(Shared Paths ·
orca.yaml·.worktreeinclude) - 사이드바 정리·필터·다중 선택, 정리 도구와 보존 브랜치, 여러 저장소 묶음
- 에이전트 상태 표시, 에이전트 대시보드, 실행 기본값(권한 생략 플래그)과 Restart 칩
- 탭·분할 화면, 세션 복원(데몬), Cmd-P · Cmd-J(macOS) · + 검색창
- 먼저 알아 둘 것 — "작업마다 폴더를 따로" 쓰는 이유. 이 장의 바탕입니다.
- 에이전트 세션과 상태 표시 — 사이드바의 돌아가는 원·주황 ?·초록 점이 무슨 뜻인지.
- 실행 기본값 — 에이전트가 나에게 허락을 묻는지, 묻지 않는지.
- 세션 복원 — 앱을 꺼도 에이전트가 계속 일하는 이유.
먼저 알아 둘 것 — 브랜치·체크아웃·워크트리
Orca의 모든 것은 git(파일이 바뀐 기록을 저장하고 되돌리거나 합칠 수 있게 해 주는 버전 관리 도구)의 워크트리라는 기능 위에 있습니다. git을 처음 들어도 괜찮도록 세 단어부터 풀어 보겠습니다.
저장소(repo)
프로젝트 파일과 그 변경 기록 전체를 담은 상자입니다. 보통 컴퓨터의 폴더 하나로 보입니다.
브랜치(branch)
기록의 "갈래"입니다. main이라는 큰 줄기에서 feature/login 같은 가지를 뻗어, 원본을 건드리지 않고 따로 고쳐 볼 수 있습니다.
체크아웃(checkout)
어떤 브랜치의 파일들을 실제 폴더에 "꺼내 놓는" 일입니다. 폴더 안 파일은 지금 체크아웃된 브랜치의 모습입니다.
워크트리(worktree)
같은 저장소를 폴더 여러 개에 동시에 체크아웃하는 git 기능입니다. 폴더마다 다른 브랜치가 꺼내져 있습니다.
Orca는 워크트리 중심(worktree-native)으로 설계되었습니다. 한 체크아웃에서 브랜치를 바꾸고 stash(하던 변경을 잠시 치워 두기)하는 대신, 모든 기능 개발이나 버그 수정마다 git worktree로 저장소의 디스크 사본을 따로 만듭니다. 이것이 여러 에이전트를 병렬로 돌려도 안전한 이유입니다 — 에이전트끼리 서로의 파일을 건드리지 않습니다.
워크트리 모델 — 기준점·출발점·삭제
이 절에는 ref라는 말이 자주 나옵니다. ref(기록의 한 지점을 가리키는 이름표)는 "main", "feature/login"처럼 사람이 읽을 수 있는 이름을 기록 위의 한 점에 붙여 둔 것입니다. origin(내 컴퓨터가 아닌, 팀이 함께 쓰는 서버 쪽 저장소)이 앞에 붙으면 "서버에 있는 것"이라는 뜻입니다.
origin/main)가 있고, 워크트리는 출발점(start-from ref)에서 갈라져 자기 브랜치를 가집니다.| 요소 | 뜻 |
|---|---|
| 기준 브랜치 (base ref) | 저장소마다 하나. 보통 origin/main(서버에 있는 원본 줄기)입니다. |
| 출발점 (start-from ref) | 워크트리마다 하나. 새 브랜치가 어디서 갈라져 나올지 정합니다. |
| 워크트리 자신의 것 | 자기만의 브랜치, 디스크 위 파일, 자기 에이전트 터미널을 가집니다. |
보통은 출발점 = 기준 브랜치입니다(가장 빠른 기본 경로). 검토 중인 다른 작업(PR) 위에 이어서 쌓을 때만 출발점을 다른 브랜치로 고릅니다.
삭제할 때 일어나는 일
- 워크트리를 삭제하면 폴더와 브랜치를 함께 지웁니다(확인 창이 먼저 뜹니다).
- 체크아웃 제거는 git이 직접 처리하므로, 지우는 동안에도 채팅이나 파일 작업이 멈추지 않습니다.
- git이 체크아웃 제거를 끝내지 못하면 워크트리가 목록에 그대로 남아 다시 시도할 수 있습니다. 실패 종류가 허용하면 Force Delete(강제 삭제)를 제안합니다.
- 합쳐지지 않은 커밋이 있을지 몰라 git이 로컬 브랜치를 남겨 두면, Orca가 검토 단계를 제안할 수 있습니다 — 아래 보존 브랜치 참고.
Force Delete 버튼의 화살표 메뉴
Force Delete는 버튼과 화살표 메뉴가 붙은 분할 버튼입니다. 화살표 메뉴의 Always force delete(항상 강제 삭제)를 고르면 앞으로의 모든 삭제에 이 선택을 기억합니다.
워크트리의 일생 — 기능 하나가 태어나서 정리되기까지
① Create — 만들기
작업 이름을 정하고, 출발점(start-from)을 고르고, 원하면 GitHub · Linear · Jira · GitLab 항목을 연결합니다.
② Work — 작업
에이전트 터미널, 편집기 탭, 브라우저 탭, 터미널 창이 모두 이 워크트리 범위 안에서 열립니다.
③ Review — 검토
출발점과 비교한 diff(변경점) 보기, Annotate AI Diff(AI가 만든 변경에 메모 달기), Attribution(누가 어떤 줄을 썼는지)으로 확인합니다.
④ Ship — 내보내기
커밋(commit, 변경 저장), 푸시(push, 서버로 올리기), PR(Pull Request — 내 변경을 main에 합쳐 달라는 요청) 열기, 자동 검사(checks) 기다리기까지 모두 Orca 안에서 합니다.
⑤ Archive or delete — 보관 또는 삭제
클릭 한 번으로 워크트리와 브랜치를 함께 지웁니다.
워크트리 만들기 — 백그라운드 생성과 출발점
생성은 뒤에서 조용히 진행됩니다
- Create Worktree 대화상자를 제출하면 창이 즉시 닫히고,
git fetch(서버에서 최신 기록 받기)와git worktree add(새 폴더 만들기)는 뒤에서 계속됩니다. - 새 워크트리는 사이드바에 진행 줄과 함께 나타나고, 그 워크트리 탭에는 체크아웃이 끝날 때까지 실시간 설정 상태가 보입니다. 끝나면 고른 시작 화면이 열립니다.
- 에이전트를 고르면 그 에이전트가 첫 탭으로 실행되고, Blank Terminal(빈 터미널)을 고르면 평범한 셸이 열립니다.
- 생성 중에도 다른 워크트리로 옮겨 가거나, 진행을 지켜보거나, 탭 안 패널에서 취소할 수 있습니다.
- 큰 저장소에서도 빠르며, 뒤에서 생성이 끝나도 지금 보고 있는 워크트리에서 억지로 끌려가지 않습니다.
- 실패하면 패널에 오류와 Retry(다시 시도) 버튼이 뜹니다.
출발점 고르기 — Branch from
New Workspace(새 워크스페이스 — 워크스페이스는 워크트리와 같은 것) 작성 창의 Branch from(어디서 갈라질지) 컨트롤로 출발점을 정합니다.
기준 브랜치(base ref)
가장 빠른 기본 경로입니다. 보통은 이것을 고릅니다.
다른 로컬 브랜치
내 컴퓨터에 있는 다른 브랜치. 검토 중인 PR 위에 작업을 "쌓아 올릴" 때 유용합니다.
특정 커밋 SHA
SHA(커밋마다 붙는 긴 고유 번호)로 기록의 한 지점을 콕 집어 그곳에서 출발합니다.
기존 원격 브랜치
Orca가 받아와(fetch) 체크아웃해 줍니다.
생성 대화상자 — Project · Run on · 에이전트 · 연결 · 이름
- Name — 작업 이름. 여기에 GitHub·Jira 같은 이슈 주소를 붙여 연결할 수도 있습니다. 이모지도 넣을 수 있습니다.
- Agent — 일할 에이전트. Set as default로 다음부터 기본값으로 정할 수 있습니다.
- Project · Run on — 글자를 쳐서 고르는 목록. 프로젝트가 없으면 맨 아래 Add a new project로 추가합니다.
- Advanced — 브랜치 이름을 직접 정하거나 부모 워크트리를 고를 때만 엽니다.
각 칸의 세부 동작 (원격 호스트, 연결, 이모지, 브랜치 이름 규칙)
Project와 Run on(어디서 실행할지)은 입력하면 바로 걸러지는 콤보 상자입니다.
- 글자를 쳐서 목록을 거르고, Enter로 지금 강조 표시된 줄을 확정합니다.
- Project 목록 맨 아래에는 늘 Add a new project(새 프로젝트 추가)가 고정되어 있어, 프로젝트가 하나도 없어도 막다른 길이 되지 않습니다.
- Run on은 준비된 호스트와 레시피, 그리고 그 컴퓨터에 아직 프로젝트 설정이 필요한 호스트까지 보여 줍니다.
- 설정이 필요한 호스트에서는 생성 창을 떠나지 않고 Set project location(프로젝트 위치 지정)을 골라, 기존 체크아웃/폴더를 찾아 고르거나 그 호스트에 Git 저장소를 복제(clone)할 수 있습니다. 준비되면 Orca가 그 위치를 자동 선택하므로 계속 만들면 됩니다.
- 연결이 끊긴 SSH(암호화된 통로로 다른 컴퓨터에 접속하는 방법)/원격 호스트는 실행 대상으로 고르지 않고도 Connect(연결)만 할 수 있습니다.
- Add host(호스트 추가)는 SSH나 Remote Orca Server 대상을 위해 항상 고정되어 있습니다. 자세한 실행 방식은 "Ways to run Orca" 문서를 참고하세요.
- Agent 선택기(접힌 상태든 펼친 상태든)에서 Set as default로 고른 에이전트를 기본값으로 정할 수 있습니다. Blank Terminal도 기본값이 될 수 있습니다.
- 이름 칸에서 GitHub PR, Linear 이슈, GitLab MR, Jira 이슈를 연결합니다. Jira는 URL을 붙여 넣거나 Jira 모드에서 검색합니다.
- 연결된 이슈는 워크트리 카드에 표시됩니다(Jira 항목 목록 문서 참고). 나중에 Edit Worktree Details에서 리뷰·작업을 더 붙일 수 있습니다.
- 워크트리 이름 칸에 Slack식 단축 코드(
:rocket:)를 치면 제안 팝업에서 이모지를 고를 수 있습니다. - 같은 선택기가 사이드바에서 더블클릭으로 이름 바꿀 때, Edit Worktree Details에서, Worktree Jump Palette(Cmd-J, macOS)에서도 동작합니다.
- 화면에 보이는 이름은 이모지를 그대로 유지하지만, git 브랜치 이름을 만들 때는 알려진 이모지를 읽을 수 있는 코드로 바꿉니다(예: 🚀 →
rocket). - Jump Palette 검색은 이모지 이름 워크트리를 이 코드 조각으로 찾아 줍니다.
- 기본적으로 브랜치 이름은 입력한 워크트리 이름에서, 또는 연결된 GitHub PR · Linear/Jira 이슈 · GitLab MR에서 만들어집니다.
- 직접 정하려면 Advanced(고급) 펼침 영역을 열고 Branch name 칸(예시 글씨
feature/my-branch)에 입력합니다. - 직접 입력한 워크트리 이름은 Auto-Rename Branch From Work(작업 내용으로 브랜치 자동 이름 변경)가 켜져 있어도 브랜치에 그대로 쓰입니다. 자동 변경은 Orca가 만든 이름만 바꿉니다.
- Linear 이슈에서 만들면, Linear가 제공하는 그 이슈의 브랜치 이름(Linear 화면에서 제안하는 것과 같은 이름)을 씁니다. 이슈 제목을 그대로 줄여 이름으로 만드는 방식이 아닙니다.
- Branch name 칸은 직접 입력한 이름이나 base 브랜치로 만들 때만 보입니다. 추적 중인 작업 항목에 묶이면 브랜치는 그 항목에서 정해지고(연결된 GitHub PR은 제출 순간 브랜치를 다시 확인), 입력해도 무시될 칸이라 아예 숨깁니다.
- 같은 펼침 영역에서 같은 저장소의 활성 워크트리를 Parent workspace(부모 워크트리)로 고를 수 있습니다. 이건 Orca 사이드바에서 안쪽으로 묶어 보여 주기만 할 뿐, git 기록이나 브랜치는 바꾸지 않습니다. 보관된 워크트리나 순환(서로가 서로의 부모)이 생기는 선택은 제외됩니다.
새 워크트리에 빠진 파일 채우기 — 공유 경로
⏭ 처음엔 건너뛰어도 됩니다 — 새 워크트리에서 "파일이 없다"는 오류가 날 때 돌아와 읽으세요.
새 워크트리는 깨끗한 체크아웃입니다. 기록에 저장되는 파일만 꺼내지므로, gitignore된(.gitignore 목록에 적혀 git이 기록하지 않는) 파일은 따라오지 않습니다. 대표적인 세 가지가 빠집니다.
- 의존성(프로그램이 돌아가는 데 필요한 남이 만든 부품 묶음, 예:
node_modules) — 크고, 언제든 다시 받을 수 있습니다. - 캐시(빠르게 하려고 미리 만들어 둔 임시 결과물, 예:
.cache) — 역시 크고, 다시 만들 수 있습니다. - 로컬 비밀값(비밀번호·접속 열쇠를 적은 개인 설정 파일, 예:
.env) — 작고, 다시 만들기 번거롭습니다.
설정하는 곳은 세 군데입니다 — 나만 쓰는 Settings → Repository(설정 → 저장소)의 Shared Paths, 팀이 함께 쓰는 orca.yaml 파일(공유), 그리고 .worktreeinclude 파일(복사). 정확한 적는 법은 아래 접힌 상자에 있습니다.
세 방법의 설정 위치·조건·예시 파일
어디서: 저장소별로 Settings → Repository(설정 → 저장소). 사용자 개인 설정입니다.
동작: 적은 경로를 주 체크아웃에서 새 워크트리마다 만들어 넣습니다. macOS에서는 가능하면 APFS 복제 복사(clone-copy: 디스크 공간을 거의 쓰지 않는 사본), 안 되면 심볼릭 링크(실제 파일 대신 원본 위치를 가리키는 바로가기)를 씁니다.
어디서: 저장소 루트의 orca.yaml 안 worktree.sharedDirectories. 저장소에 커밋되어 팀이 함께 씁니다.
동작: gitignore된 폴더를 같은 방식으로 공유합니다(복사가 아니라 링크/공유). node_modules나 .cache처럼 크고 다시 만들 수 있는 폴더에 씁니다.
조건: 항목은 주 체크아웃에 폴더로 존재하고 gitignore되어 있어야 합니다. git이 추적하는 경로나 없는 경로는 건너뜁니다.
# orca.yaml (repo root)
worktree:
sharedDirectories:
- node_modules
- .cache어디서: 저장소 루트의 .worktreeinclude 파일.
동작: gitignore된 파일·폴더를 새 워크트리마다 복사합니다(링크가 아님). 그래서 워크트리마다 자기 사본을 따로 가집니다. 흔한 예: .env, .vscode/ 아래 로컬 설정.
- 빈 줄과
#주석을 쓸 수 있습니다. - 지금은 글자 그대로의 경로만 지원합니다. 와일드카드(glob, 예:
*.env)와 부정(!)은 경고와 함께 건너뜁니다. - 추적 중이거나, 없거나, gitignore되지 않은 경로는 복사하지 않습니다.
# .worktreeinclude (repo root)
.env
.env.local
.vscode/settings.jsonorca.yaml의 공유 폴더는 사용자별 Worktree Shared Paths 목록에 더해질 뿐 대체하지 않습니다. 이미 공유·링크된 경로는 .worktreeinclude로 다시 복사하지 않습니다.사이드바 — 워크트리를 정리하고 찾기
기본으로 사이드바는 프로젝트별로 워크트리를 묶습니다. 맨 위 줄이 프로젝트(git 저장소 하나 또는 관련 묶음)이고, 펼치면 작업 중인 워크트리가 나옵니다.
- 머리 부분에 전역 검색과 별개인 자체 필터 입력이 있어 사이드바 안에서 목록을 좁힐 수 있습니다.
- 맨 위 Search 버튼은 Worktree Jump Palette(Cmd-J, macOS)를 엽니다 — 키보드를 잘 안 쓰는 사람을 위한 클릭 버전입니다.
- 상태 표시줄에 에이전트 활동이 보이고, 읽지 않은 워크트리는 배지 대신 굵은 글씨로 표시됩니다.
- 왼쪽 사이드바를 열어 두었는지 재시작 후에도 기억하며, 다른 클라이언트에서 원격 워크트리를 드러내도 내 사이드바 묶음이 펼쳐지지 않습니다.
카드 다루기 — 자주 쓰는 것
| 하고 싶은 일 | 방법 |
|---|---|
| 오래 걸리는 작업을 위에 고정 | 워크트리를 프로젝트 맨 위에 pin(고정) |
| 보관 · 잠재우기 · 삭제 | 워크트리 우클릭 → archive / sleep / delete |
| 여러 개 선택 | Cmd(Linux/Windows는 Ctrl)+클릭으로 하나씩 추가, Shift+클릭으로 연속 범위. 선택된 것 중 하나를 우클릭하면 모두에 적용 |
| 이름 바로 바꾸기 | 제목을 더블클릭. 카드의 다른 곳을 더블클릭하면 전체 편집 창이 열림 |
목록을 좁히는 필터(잠든 것·자동으로 만든 것 숨기기 등)와 부모 아래 묶이는 자식 워크트리, 그 밖의 카드 조작은 아래 접힌 상자에 있습니다.
필터 메뉴 · 그 밖의 카드 조작 · 자식 워크트리
필터 메뉴
머리의 필터 메뉴에는 Show 영역(하위 메뉴 Hosts and projects: 호스트·프로젝트 범위)과, 그 아래 "숨기기" 토글들이 있습니다.
| 숨기기 항목 | 설명 |
|---|---|
| Sleeping workspaces | 잠든(활성 패널이 닫힌) 워크트리. 단, 프로젝트의 진입점/메인 워크트리는 이 필터에서도 보여 프로젝트 줄이 사라지지 않습니다. |
| Except default branch | Hide sleeping이 켜져 있을 때만 보이는 하위 옵션. 기본 브랜치 워크트리는 잠든 것 숨기기에서 제외합니다. |
| Default branch workspaces | 메인 체크아웃 줄. |
| Automation-created workspaces | 자동화가 만든 워크트리. |
| CLI-created workspaces | orca worktree create로 만든 것. 카드에 마우스를 올리면 Orca CLI 출처 정보가 보입니다. |
| Other-client workspaces | 공유 Remote Orca Server에 다른 연결 기기가 만든 워크트리가 있을 때 나타납니다. 켜면 이 기기에서 만든 것만 보입니다. 빈 Cmd-J(macOS) 최근 목록과 숫자 단축키도 같은 필터를 따르지만, 검색어를 치면 숨은 줄도 찾아집니다. |
| Detached HEAD workspaces | Detached HEAD(브랜치 이름표 없이 특정 저장 시점 하나에 그대로 서 있는 상태) — 브랜치가 아니라 특정 커밋 위에 있는 체크아웃. |
필터 버튼에 켜진 필터 개수가 표시되고, Clear는 켜진 필터만 초기화합니다. 이 필터로만 숨겨진 워크트리는 텍스트 검색이나 Jump Palette에 검색어를 치면 여전히 찾을 수 있습니다(Jump Palette에는 Tab으로 여는 자체 호스트/프로젝트 필터도 있습니다).
그 밖의 카드 조작
| 하고 싶은 일 | 방법 |
|---|---|
| 키보드로 삭제 시작 | 워크트리나 폴더 워크스페이스에 마우스를 올리고 macOS Cmd-Shift-Backspace, Windows/Linux Ctrl-Shift-Backspace (확인 창은 그대로 뜹니다) |
| 저장소 줄 순서 바꾸기 | 드래그. 줄 위/아래로 끌면 순서 변경, 안쪽으로 넣는 영역은 넓고 안정적. Esc로 취소 |
| 이름 복사 | 워크트리 하나 우클릭 → Copy Worktree Name. Orca가 워크트리 지정에 쓰는 정식 이름을 복사(사용자 이름 → 브랜치 → 폴더 순으로 대체)하므로 폴더 워크스페이스나 이름을 지운 경우에도 동작 |
| 연결된 작업 여러 개 | Edit Worktree Details → Linked work. GitHub·GitLab·Linear·Jira URL을 붙이거나 연결된 서비스를 검색. Reviews(PR/MR)와 Issues & tasks로 나뉘고 개수가 보이며 카드에 쌓여 표시. 링크는 그 워크트리의 저장소 것이어야 함 |
| 끊긴 SSH 다시 연결 | 호스트 연결이 끊긴 SSH 워크트리는 카드 제목 줄에 재연결 컨트롤이 나올 수 있음(SSH worktrees 문서) |
직접 바꾼 이름은 워크트리 브랜치가 바뀌어도 유지됩니다. 사용자 이름을 지우면 다시 브랜치에서 자동으로 이름을 따옵니다. Orca가 만든 이름은 계속 브랜치를 따라갑니다.
자식 워크트리(중첩)
- 오케스트레이션이나 부모를 지정한
worktree create로 생긴 자식이 있으면, 부모 아래 N children 칩이 보입니다. 클릭하면 자식을 보이거나 숨깁니다. - 키보드로 같은 일을 하려면 Settings → Shortcuts에서 Toggle Child Workspaces에 키를 지정합니다. 마우스 아래 워크트리(없으면 활성 워크트리)에 칩과 똑같이 작동합니다.
- 우클릭 메뉴에 Sleep with Descendants (N)와 Delete with Descendants…가 생길 수 있습니다.
- Sleep with descendants: 선택한 워크트리와 같은 프로젝트·저장소·호스트 안의 검증된 모든 자식의 활성 패널을 닫습니다. 살아 있는 터미널이나 브라우저 탭이 있는 것만 대상입니다.
- Delete with descendants: 원래 있던 연쇄 삭제를 명시적으로 보여 주고 백그라운드에서 실행하므로 확인 창이 Orca의 나머지를 막지 않습니다.
- 오래된 계보 링크, 순환, 호스트나 저장소 경계를 넘는 자식은 제외됩니다.
정리 도구와 보존 브랜치
⏭ 처음엔 건너뛰어도 됩니다 — 워크트리가 많이 쌓여 한꺼번에 지울 때 읽으세요.
Resource Manager → Clean up workspaces
여러 워크트리를 지우기 전에 전체를 훑어보고 싶을 때 씁니다. 목록에는 로컬 워크트리, 메인 워크트리, 폴더 워크스페이스, 연결이 끊긴 SSH 호스트의 워크트리가 포함됩니다.
- 폴더 워크스페이스와 프로젝트 그룹은 내부 ID 대신 저장된 표시 이름(예: Documentation → Release notes)으로 보이며, 재시작 후 세션을 복구해도 마찬가지입니다.
- 검색·필터·정렬로 각 워크트리의 상태, 최근 활동, 크기, Git 상태, 연결된 리뷰를 확인한 뒤 지울 것을 고릅니다.
보존 브랜치 (Preserved branches)
사이드바 다중 선택이나 Resource Manager 정리로 일괄 삭제해도 디스크 폴더는 지워집니다. 그런데 git이 "합쳐지지 않은 커밋이 있을 수 있다"며 로컬 브랜치 삭제를 거부하면, Orca는 그 브랜치를 남기고 Review N Branches 같은 알림(화면 구석에 잠깐 뜨는 메시지)을 띄웁니다. 열면 남은 브랜치 목록이 나와 일부만 강제 삭제할 수 있습니다. 선택하지 않은 브랜치는 저장소에 남고, 워크트리 폴더는 복원되지 않습니다.
여러 저장소 묶음과 폴더 워크스페이스
⏭ 처음엔 건너뛰어도 됩니다 — 저장소 여러 개를 한 번에 다룰 때만 필요합니다.
Git 저장소 여러 개가 든 상위 폴더를 추가하면, 고른 저장소를 따로따로 가져오거나 하나의 프로젝트 그룹으로 묶을 수 있습니다.
- 각 프로젝트 그룹에는 폴더 워크스페이스 흐름이 있습니다. 상위 폴더 수준에 있는 워크트리 비슷한 항목으로, 작업 출처(GitHub/GitLab/Linear/Jira)를 아래 저장소 중 하나에 묶어 둡니다. 그래서 사이드바에서 형제들과 함께 묶여 있어도 기능별 작업 화면이 올바른 저장소에 붙어 있습니다.
- 만드는 법: 사이드바의 그룹 머리 줄에 마우스를 올리고 +(툴팁 "Create workspace for group")를 누릅니다. Create Folder Workspace 창에서 작업 출처가 될 프로젝트를 고르고, 이름을 짓고, 원하면 이슈나 PR을 연결해 제출합니다. 그룹 아래 일반 워크트리 옆에 나타납니다.
- 프로젝트 그룹을 지울 때 포함된 프로젝트(저장소 등록)까지 함께 제거하는 체크박스가 있어, 더는 안 쓰는 묶음을 확인 한 번으로 정리할 수 있습니다.
평범한 git 명령도 그대로
Orca가 만든 워크트리는 특별한 것이 아니라 진짜 git 워크트리입니다. 그래서 개발자가 터미널에서 git 명령을 직접 쳐도 문제없고, Orca는 다음에 화면을 새로 고칠 때 그 변화를 알아채 사이드바와 화면에 반영합니다. git 명령을 몰라도 Orca 화면만으로 쓸 수 있으니, 이 절은 "섞어 써도 괜찮다"는 것만 알면 됩니다.
직접 만든 워크트리는 처음엔 "외부" 것으로 숨겨질 수 있고, 사이드바의 hidden worktrees 카드에서 보이게 할 수 있습니다. 세부 설정은 아래에 접어 두었습니다.
직접 만든(외부) 워크트리 다루기와 출처별 설정
- Orca 워크트리는 모두 진짜 git 워크트리입니다. 터미널을 열어
git status,git rebase,git cherry-pick(뒤의 둘은 기록을 옮기거나 골라 담는 개발자용 명령) 등 무엇이든 쓸 수 있고, Orca는 다음 화면 갱신 때 변경을 알아챕니다. - 직접
git worktree add로 만든 워크트리는 Orca에 보이게 하기 전까지 외부 것으로 남습니다. 저장소가 이를 숨기면 사이드바에 hidden worktrees 카드가 나옵니다. 클릭해 Non-Orca worktrees를 열고 원하는 것에 Show를 고르세요. - Settings → General → Workspace에서 외부 워크트리 출처(Claude Code 워크트리, GSD 워크트리, 기타 위치, 직접 추가한 절대 경로 위치)의 전역 기본값을 정합니다. 이 기본값은 그 호스트의 현재·미래 워크트리에 적용되며, 새로 추가한 전역 사용자 루트는 숨김으로 시작합니다.
- 프로젝트의 Non-Orca worktrees 창에서는 출처별로 그 프로젝트만 따로 설정하거나 전역 설정으로 되돌리고, 숨은 워크트리를 검색해 하나씩 되살릴 수 있습니다.
- CLI에서
git worktree remove를 해도 Orca가 다음에 그 저장소를 새로 고칠 때 알아채고 자기 상태를 정리합니다.
에이전트 세션과 상태 표시
에이전트 세션이란 워크트리 하나 안의 터미널 하나에서 도는 CLI 에이전트 하나입니다. CLI(마우스 대신 글자 명령으로 쓰는 프로그램) 에이전트는 Claude Code·Codex처럼 터미널 창 안에서 일하는 AI 도우미를 말합니다. Orca는 그 일생을 추적해서, 탭마다 들어가 보지 않아도 어떤 세션이 일하고 어떤 세션이 쉬는지 알려 줍니다. 모든 워크트리 카드 안에 상태 기호가 바로 보입니다.
| 기호 | 뜻 |
|---|---|
| Spinner(돌아가는 원) | 작업 중 |
| ? 주황 물음표 | 나를 기다림(권한 요청 / 입력 필요). 사이드바 "Needs You" 개수도 같은 기호 |
| 초록 체크(대시보드) 또는 초록 점(사이드바) | 완료 / 조용히 활성 |
| 빨간 점 | 막힘, 중단됨, 실패 |
| 회색 점 | 쉬는 중(idle) — 끝난 뒤 오래 조용한 상태 |
| 표시 없음 | 평범한 셸 — Orca가 아는 에이전트 CLI가 아님 |
Orca는 이 상태를 어떻게 알까요? 에이전트가 일하는 동안 "나 지금 일해요", "끝났어요" 하고 신호를 보내기 때문입니다. Claude Code, Codex 등 여러 에이전트가 이 신호를 내보냅니다.
신호의 정체와 정확한 감지 규칙
- 상태는 터미널의 OSC 제목 신호(프로그램이 터미널 창 제목을 바꾸며 보내는 신호)와 에이전트 훅(hook — 에이전트가 정해진 순간마다 바깥에 알려 주는 연결 지점)으로 감지합니다.
- 작업 중에는 OSC 제목이 바뀌며 상태가 갱신되고, 터미널 출력은 검색·복사가 되며 Ghostty 테마로 꾸며집니다.
- 정확한 감지 규칙은 Orca CLI의
terminal wait --for tui-idle명령 설명을 보세요.
세션의 일생
콤보 상자에서 에이전트를 고르면 Orca가 CLI를 띄웁니다.
에이전트가 보내는 신호로 상태 기호가 바뀝니다. 터미널 출력은 검색·복사가 됩니다.
Orca가 "작업 중 → 조용해짐"으로 바뀌는 순간을 감지해 agent-finished(에이전트 끝남) 알림을 보냅니다. 그대로 오래 두면 회색 "쉬는 중"으로 보입니다.
에이전트 프로그램이 끝나면 탭에 Restart 칩이 나타납니다.
Restart 칩
에이전트가 끝나면(정상 종료든 충돌이든) 탭에 Restart 칩이 뜹니다. 한 번 누르면 같은 에이전트를 같은 작업 폴더에서 다시 살립니다.
Codex 계정 유지
Codex의 Restart 칩은 현재 계정도 유지합니다(Hot-swap Codex accounts 문서 참고).
에이전트 대시보드 실험 기능
Settings → Experimental → Agent Dashboard(설정 → 실험 기능)를 켜면 왼쪽 사이드바에 Agent Dashboard 항목이 생깁니다. 모든 워크트리의 에이전트를 칸반(열마다 카드를 놓는 게시판) 형태로 보여 줍니다.
? Needs You
Working
Done
Idle (기본 숨김)
네 개의 열
- Needs You — 권한이나 질문에 답을 기다림
- Working — 실행 중
- Done — 끝났지만 아직 검토하고 싶을 수 있는 세션
- Idle — 약 30분 동안 완료를 알리지 않은 조용한 에이전트. 보드에서 기본 숨김입니다. 보이려면 보드 설정(톱니바퀴)에서 Show idle agents를 켭니다 — 전역 Experimental 설정이 아니라 창 안/팝아웃 화면의 톱니바퀴입니다. 창 안과 팝아웃은 서로 동기화됩니다.
카드를 누르면 그 에이전트의 터미널이 바로 열립니다. 카드에 무엇이 표시되는지, 검색·필터와 별도 창으로 여는 법은 아래에 접어 두었습니다.
카드 구성 · 검색·필터·열기 방식
- 머리: 에이전트 아이콘, 세션 대화 이름(직접 바꾼 이름 → 생성된 제목 → AI Vault/에이전트 세션 제목 → 없으면 워크트리 이름), 상태 기호
- 미리보기: 가능하면 마지막 사용자/에이전트 메시지, 없으면 작업 요약
- 바닥: 프로젝트 아이콘, 워크트리 이름(머리에 세션 이름이 이미 있을 때), 경과 시간, 캐시된 리뷰 상태(있으면). 워크트리 상태는 툴바 필터에만 있고 카드에는 워크트리별 상태 점이 더는 없습니다.
- Needs You 카드는 주황빛(대기 중인 질문 요약 표시 가능), Done 카드는 초록빛, 나머지는 중립 — 색이 있으면 "여기 보세요"라는 뜻입니다.
- 카드를 클릭하면 그 에이전트의 실시간 터미널이 열리거나 앞으로 옵니다. 연결된 Remote Orca Server의 에이전트도 되며, 미리보기는 그것을 돌리는 호스트에서 가져옵니다.
- SSH 워크트리와 연결된 Remote Orca Server 카드에는 호스트 배지가 붙습니다. 마우스를 올리거나 초점을 주면 저장된 호스트 이름(예: SSH host · openclaw, Remote Orca host · Build Mac)이 보입니다. 로컬 워크트리에는 없습니다.
- 중첩된 Codex/Claude 하위 에이전트(subagent)는 부모 줄 아래 펼칠 수 있는 자식으로 나올 수 있습니다.
- Open as: 사이드바 옆 창 안 보드(In-window) 또는 별도 창(Pop-out)
- Search: 워크트리·프로젝트·에이전트 이름. 검색어나 필터가 있으면 결과 개수가 보임
- Filter: Project, Workspace status(워크트리 상태), PR / MR status(Open, Draft, Merged, Closed, No review) 다중 선택
- 하나씩 지울 수 있는 필터 칩과 Clear all filters
- Settings → Shortcuts에서 Toggle Agent Dashboard에 단축키를 지정할 수 있습니다. 기본 키는 없고, 터미널·편집기·브라우저 탭에 초점이 있어도 동작합니다.
실험 보드를 꺼 두어도 워크트리 카드에는 같은 기호로 에이전트 줄이 인라인 표시됩니다.
실행 기본값 — 에이전트가 허락을 묻는가
에이전트는 파일을 고치거나 명령을 실행하기 전에 "이거 해도 될까요?" 하고 사람에게 물을 수 있습니다. Orca는 기본으로 묻지 않게 해서 에이전트를 띄웁니다. 매번 허락 창이 떠서 흐름이 끊기지 않게 하려는 것이고, 그래도 되는 이유로 워크트리 자체가 안전 울타리라는 점을 듭니다 — 에이전트는 자기 작업 폴더에서 일하고, 그 결과(변경점)는 합치기 전에 사람이 골라 담거나 버릴 수 있습니다.
"묻지 않게"는 에이전트를 켤 때 권한 생략 플래그(프로그램을 켤 때 뒤에 붙이는 옵션 글자. 여기서는 "확인 절차를 건너뛰어라"라는 뜻)를 미리 붙여 두는 방식으로 이루어집니다. 이 기본값은 Settings → Agents(설정 → 에이전트)의 Agent permissions(에이전트 권한)에서 바꿀 수 있습니다 — 플래그가 붙은 지금 상태가 Yolo(묻지 않음)이고, Manual(매번 묻기)로 바꾸면 허락 창이 돌아옵니다. 그 사이의 Auto는 지원하는 에이전트(Claude, Claude Agent Teams, Codex)가 일상적인 동작만 스스로 승인하는 모드입니다.
에이전트별 기본 플래그와 실행 인자 직접 고치기
| 에이전트 | 기본으로 붙는 플래그 |
|---|---|
| Claude | --dangerously-skip-permissions |
| Codex | --dangerously-bypass-approvals-and-sandbox |
| Gemini (Cursor · Crush · Kimi · Rovo Dev · Hermes · GitHub Copilot · Command Code도 같음) | --yolo |
| 그 밖의 에이전트 | 선택기의 각 에이전트에 해당하는 같은 성격의 플래그 |
- 에이전트 하나만 바꾸려면 Settings → Agents에서 그 에이전트 줄을 펼치고 launch arguments(실행 인자)를 고칩니다. Orca가 이 변경을 기억해 이후 실행마다 적용하고, 옆의 Reset 버튼은 원래 플래그로 되돌립니다.
- Agent permissions에서 Manual·Auto·Yolo를 고르면 새 터미널 세션과 구조화된 채팅 세션에 적용됩니다. 이미 열려 있는 채팅은 자기 모드를 유지합니다.
- Auto를 고르면 Auto를 지원하지 않는 에이전트에 쓸 Manual 또는 Yolo를 Other agents에서 따로 정합니다.
- 실행 인자를 직접 고쳐 둔 에이전트는 전체 권한 설정을 바꿔도 그대로 둡니다(직접 넣은 명령이 지워지지 않도록). 그 인자를 미리 준비된 값(preset)으로 바꿔야 전체 설정을 따릅니다.
탭·창·분할 레이아웃
Orca의 창 시스템은 여러 에이전트가 일하는 모습을 맥락을 잃지 않고 지켜보도록 만들어졌습니다. 탭은 탭 그룹(창, pane)에 모이고, 창은 쪼개져 레이아웃이 됩니다.
탭 하나에는 한 가지가 담깁니다: 터미널, 편집기 버퍼, 브라우저, diff, PR.
- 그룹 안에서 탭을 위아래로 끌어 순서를 바꿉니다.
- 다른 그룹 위로 끌면 그쪽으로 옮겨집니다.
- 터미널·편집기·브라우저 탭 우클릭 → Copy Tab ID: 그 탭을 가리키는 고정 참조(예:
orcaTabId: abc123)를 복사합니다. 에이전트에게 "정확히 이 탭"을 알려 줄 때 편합니다. 비활성·고정 탭에서도 되고, 탭 이름을 바꾸거나 활성화하거나 닫지 않습니다. - 활성 워크트리의 편집기 파일 탭을 모두 닫기: macOS Cmd+Option+W, Windows/Linux Ctrl+Alt+W.
- 활성 탭 색 막대가 어느 창에 초점이 있는지 알려 줍니다.
- 탭 어디든 마우스를 올리면 전체 제목과 그 아래 아이콘·프로그램 줄이 나옵니다. 옆 탭으로 옮기면 짧은 미끄럼 효과와 함께 바로 그 카드가 보여, 잘린 제목도 쉽게 알아볼 수 있습니다.
탭을 창의 가장자리로 끌어다 놓으면 분할됩니다.
- 오른쪽 가장자리 — 좌/우로 나눔(horizontal split)
- 아래쪽 가장자리 — 위/아래로 나눔(vertical split)
- 분할은 중첩됩니다. 어떤 탭 종류든(에이전트 터미널, diff, 브라우저, 편집기, PR 보기) 한 창 트리 안에 함께 있을 수 있습니다.
- 터미널 탭은 탭 안에서도 나눌 수 있습니다. 터미널 탭 메뉴의 Split terminal right / Split terminal down, 또는 활성 터미널 창 머리의 분할 버튼(오른쪽 분할)을 씁니다.
- 고정된 경계(Pinned boundaries): 경계선은 놓은 자리에 머뭅니다. 창 크기를 바꿔도 레이아웃이 뒤섞이지 않고, 경계 위치는 워크트리별로 저장됩니다.
새로 설치했을 때의 기본 단축키입니다.
| 동작 | macOS | Linux / Windows |
|---|---|---|
| 다음 / 이전 탭 (모든 종류) | Cmd+Shift+] / Cmd+Shift+[ | Ctrl+Shift+] / Ctrl+Shift+[ |
| 다음 / 이전 탭 (같은 종류) | Cmd+Option+] / Cmd+Option+[ | Ctrl+Alt+] / Ctrl+Alt+[ |
| 직전에 쓴 탭 | Ctrl+Tab | Ctrl+Tab |
Settings → Shortcuts에서 바꿀 수 있습니다. 기존 설치는 사용자 지정 값을 ~/.orca/keybindings.json에 유지합니다.
워크트리마다 자기 탭 레이아웃을 가집니다. 워크트리를 바꾸면 창 트리 전체가 통째로 바뀌고, 브라우저 탭·터미널·diff가 두고 간 모습 그대로 다시 나타납니다.
세션 복원 — 껐다 켜도 그대로
Orca를 닫았다가 다시 열면 작업 공간 전체가 되살아납니다. 어떤 브랜치에서 어떤 에이전트를 돌리고 있었는지 기억하는 건 사용자가 아니라 Orca의 일입니다.
비결은 데몬(화면 없이 뒤에서 계속 도는 프로그램)입니다. 데몬을 앱을 꺼도 뒤에서 터미널을 붙잡고 있는 관리인이라고 생각하면 됩니다. 에이전트가 일하는 터미널은 앱 창이 아니라 이 관리인이 쥐고 있어서, 창을 닫아도 일이 멈추지 않습니다. 다만 관리인도 컴퓨터 안에 사는 프로그램이라, 컴퓨터 자체가 꺼지면 함께 꺼집니다.
복원되는 것
- 열린 워크트리 — 사이드바에 열려 있던 모든 워크트리
- 탭과 분할 — 워크트리별 창 배치(중첩 분할 포함)와 초점이 있던 탭
- 실행 중인 에이전트 — 데몬(관리인)이 터미널을 쥐고 있으므로 앱 창을 닫아도 Claude Code·Codex 등이 작업 도중 죽지 않습니다. 다음 실행 때 새로 띄우지 않고 살아 있던 그 에이전트에 그대로 다시 연결합니다.
- 터미널 스크롤백(위로 굴려 다시 볼 수 있는 지난 출력) — 각 터미널의 출력 기록. Orca가 닫혀 있던 동안 나온 출력도 포함
- 초점 워크트리와 탭 — 닫을 때 보던 화면으로 열림
복원되지 않는 것
- 데몬은 컴퓨터와 운명을 같이합니다. 재부팅, OS 업데이트, 커널 패닉(운영체제가 심각한 오류로 갑자기 멈추는 일), 강제 전원 끄기처럼 기계 전체가 꺼지면 실행 중인 에이전트는 모두 끝납니다. 다음 실행 때 워크트리·탭·분할·마지막 스크롤백은 돌아오지만 에이전트 프로세스는 없습니다. 아무 탭에서 에이전트를 다시 실행해 이어 가세요.
- Orca가 닫혀 있는 동안 데몬이 충돌해도 그 데몬이 붙잡던 세션은 같은 결과가 됩니다. 레이아웃과 스크롤백은 여전히 복원됩니다.
개발자용 용어 — PTY와 warm-reattach
데몬이 쥐고 있는 것은 각 에이전트의 PTY(가상 터미널 — 프로그램이 터미널 화면과 주고받는 통로)입니다. 다음 실행 때 살아 있던 프로세스에 그대로 다시 붙는 동작을 warm-reattach라고 부릅니다.
언제 복원이 일어나나 — 상황별로 보기
데몬 살아남음 → 에이전트 계속 실행. Cmd-Q(macOS)는 평소의 종료 방법이며, 에이전트는 뒤에서 계속 일합니다.
데몬 살아남음. 업데이트 설치를 위해 Orca가 다시 켜져도 에이전트는 영향받지 않습니다.
데몬 살아남음. Orca 자체가 충돌해도 데몬이 세션을 살려 두고, 다음 실행 때 다시 붙습니다.
데몬 죽음 → 에이전트 사라짐, 레이아웃은 복원. 노트북 재시작, OS 업데이트, 커널 패닉, 강제 전원 끄기. 워크트리·탭·분할·마지막으로 저장된 스크롤백은 돌아옵니다.
빠른 이동 — Cmd-P · + 검색창 · Cmd-J
⏭ 처음엔 아래 표만 보고 건너뛰어도 됩니다 — 탭 안의 세부 동작은 워크트리가 많아졌을 때 읽으세요.
워크트리가 몇 개를 넘으면 "어디로 가지?"가 병목이 됩니다. Orca는 키보드 중심 이동 도구를 제공합니다. 이 절의 Cmd 단축키는 원문에 macOS 키로만 나옵니다. 단축키는 모두 Settings → Shortcuts에서 바꿀 수 있습니다.
검색창이 세 개라 헷갈리기 쉽습니다. 무엇을 찾느냐로 고르면 됩니다.
| 검색창 | 무엇을 찾나 | 언제 쓰나 |
|---|---|---|
| Cmd-P(macOS) Quick Open | 지금 워크트리 안의 파일 | "그 파일 어디 있더라?" — 파일 이름 조각으로 바로 열 때 |
| 탭 줄의 + | 열린 탭·파일·웹 주소·에이전트, 그리고 웹 검색 | 새 탭을 열면서 무엇을 띄울지 한 칸에서 정할 때 |
| Cmd-J(macOS) Jump Palette | 모든 워크트리와 모든 탭 | 다른 작업(워크트리)으로 건너가거나, 나를 기다리는 에이전트를 찾을 때 |
- 현재 워크트리 안의 파일 검색입니다. 조각을 입력하면 최근 사용 + 일치 점수로 순위를 매기고, 고른 파일을 새 편집기 탭에 엽니다.
- 여러 단어 검색어는 경로의 여러 부분에 걸쳐 맞춰지고, 위치(줄 등)를 가리키는 결과는 파일을 그 위치에서 엽니다.
- 도중에 버린 검색은 취소되어 오래된 결과가 목록에 끼어들지 않습니다.
- 결과 줄은 파일 이름이 앞에 오고, 공간이 좁으면 상위 폴더 경로를 줄입니다(마우스를 올리면 전체 경로).
- gitignore된 파일도 결과에 나옵니다. 추적 파일 결과 다음 두 번째 단계로 나오므로, 자주 여는 빌드 결과물이나 env 파일에 닿으면서도 목록 위쪽을 어지럽히지 않습니다.
- 탭 줄의 +는 열린 탭·파일·URL·에이전트를 한 칸에서 찾습니다(예시 글씨: Search open tabs, files, URLs, agents…).
- 파일 줄은 Quick Open처럼 파일 이름이 앞에 옵니다. 이미 열린 편집기 탭과 맞으면 중복 파일 결과 대신 그 탭을 우선해 두 번째 사본을 열지 않습니다.
- 이 워크트리의 브라우저 방문 기록도 검색합니다. 일치 정도와 최근 방문 순으로 URL·페이지 제목 제안이 나옵니다.
- 경로나 URL 대신 검색어를 치면 워크트리 브라우저에서 Default Search Engine(기본 검색 엔진)으로 엽니다. 한 단어면 파일 결과가 먼저, 여러 단어 문장이면 검색 줄이 위로 올라갑니다.
- 검색어 앞에
?를 붙이면 파일·탭 맞추기를 건너뛰고 바로 검색합니다.
모든 워크트리와 모든 탭을 한 번에 검색해 이동합니다. 빈 입력칸의 예시 글씨는 repo/worktree — 어느 쪽 반쪽만 쳐도 걸러집니다. 입력을 시작하면 사이드바 필터로 숨겨진 것도 포함해 보관되지 않은 모든 워크트리를 찾습니다. :rocket: 같은 이모지 코드도 이름 짓기와 같은 제안 팝업을 씁니다.
Tab을 누르면 호스트·프로젝트 필터 메뉴가 열립니다. 고른 것은 하나씩 지울 수 있는 칩으로 보이고, 팔레트를 닫으면 필터가 지워져 다음엔 전체 범위로 열립니다.
Jump Palette는 아무것도 입력하지 않으면 최근 에이전트 세션(나를 기다리는 것부터)을 보여 주고, 입력을 시작하면 모든 워크트리와 탭을 찾습니다. 결과가 어떤 순서로 나오는지는 아래에 접어 두었습니다.
Jump Palette 결과 구성과 순서 규칙
- 활동 순으로 최근 에이전트/터미널 세션을 최대 6개: 나를 기다림 → 완료 → 쉬는 중 순서.
- 지금 보고 있는 쉬는 탭은 빼서 목록이 "할 일" 위주로 유지됩니다. 단, 현재 탭이라도 작업 중·나를 기다림·읽지 않은 활동이 있으면 나옵니다.
- 탭 줄과 같은 실시간 배지(돌아가는 원, 물음표, 종, 체크)를 씁니다.
- 더 있으면 See more로 전체 목록을 펼칩니다. 숫자 단축키 macOS Cmd-1~Cmd-6, Windows/Linux Ctrl-1~Ctrl-6로 첫 줄들에 바로 갑니다.
- 팔레트를 여는 순간 구성과 순서가 고정되어 커서 아래에서 줄이 뒤섞이지 않습니다.
빈 검색어의 다음 구역. 마지막으로 초점을 준 순서이며, 훑어보기 좋게 개수가 제한됩니다.
사이드바 구역 이름으로 바로 이동할 수 있습니다.
캐시된 GitHub PR 제목·번호(#123), GitLab MR 제목·번호(!123)로도 워크트리를 찾습니다 — 그 리뷰 정보가 이미 받아져 있을 때.
- 현재 워크트리 것이 먼저, 그다음 전체.
- 탭 제목·내용에 맞는 것이 워크트리·브랜치·저장소 이름에만 맞는 것보다 앞섭니다. 비슷하면 최근에 쓴 탭이 앞.
- 터미널·브라우저·시뮬레이터 줄은 저장소와 워크트리를 작은 위치 칩으로 합쳐 보여 주고, 긴 보조 경로는 앞쪽을 줄여 파일 이름과 맞은 끝부분이 보이게 합니다.
- 마지막 활성 시점(얼마 전인지)을 아는 경우 표시합니다.
terminal,simulator같은 종류 별칭으로도 찾을 수 있지만 줄 이름에는 붙지 않습니다.
- 검색어가 탭과 워크트리 둘 다에 맞으면 각 구역 미리보기를 번갈아 보여 줘 한쪽이 묻히지 않게 합니다.
- 구역에 더 있으면 N more 줄의 See more로 20개씩 더 펼칩니다. 검색어를 바꾸면 펼친 구역이 초기화됩니다.
- 한 구역만 나오는 결과는 상한이 있는 전체 목록을 보여 줍니다.
- Enter로 이동, 워크트리에서 Shift-Enter는 현재 창을 바꾸지 않고 새 분할로 엽니다.
- 검색어가 기존 워크트리와 맞지 않으면 그 글자를 이름으로 하는 Create worktree 줄을 제안합니다. 실제 결과가 있으면 그것이 먼저 선택되어 있어 Enter는 여전히 이동합니다.
실전 — 워크트리 10개를 오가기
워크트리 10개는 버거운 양입니다. Jump Palette + Restart 칩 + 에이전트 상태 기호가 바로 이 규모를 위해 만들어졌습니다. 아래는 10개를 띄워 둔 사이드바를 흉내 낸 것입니다 — 어디부터 가야 할지 기호만 보고 정할 수 있습니다.
| 기호 | 할 일 |
|---|---|
| ? 주황 ? | 나를 기다림 — 가장 먼저 갑니다 |
| 돌아가는 원 | 일하는 중 — 그냥 둡니다 |
| 초록 점 | 끝났거나 조용히 활성 — 결과를 검토합니다 |
| 빨간 점 | 막힘·실패 — 필요하면 Restart 칩으로 다시 띄웁니다 |
| 회색 점 | 끝난 뒤 오래 조용함(쉬는 중) — 필요할 때 살펴봅니다 |
기호의 뜻은 상태 표시 표와 같습니다.
- Cmd-J(macOS)로 팔레트 열기작업 이름 조각을 입력합니다. Enter는 이동, Shift-Enter는 화면을 나눠 열기. 목록이 크면 Tab으로 호스트·프로젝트를 거릅니다.
- 사이드바 훑기입력이 필요한 워크트리(주황 ?)부터 먼저 갑니다.
- Restart 칩으로 되살리기각 워크트리에서 끝난 에이전트를 다시 띄웁니다. 노트북이 잠든 뒤 한꺼번에 재개할 때 좋습니다.
- 종 알림 비우기계속 남아 있는 종(🔔) 아이콘으로 "agent finished"(에이전트 끝남) 알림을 하나씩 처리합니다. 알림을 클릭하면 그 워크트리로 이동합니다.
- 워크트리 = 같은 저장소를 작업마다 다른 폴더에 꺼내 둔 것. 에이전트끼리 파일을 밟지 않아 병렬 작업이 안전합니다.
- 일생: 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 키).
출처: onorca.dev/docs/model/worktrees · onorca.dev/docs/model/agents-sessions · onorca.dev/docs/model/tabs-panes-splits · onorca.dev/docs/model/session-restore · onorca.dev/docs/model/quick-open · onorca.dev/docs/recipes/jump-worktrees
에이전트와 터미널 — 지원 에이전트, 채팅 UI, 기록, 사용량
Orca의 심장은 “코딩 에이전트를 터미널에서 돌리는 일”입니다. 이 장에서는 코딩 에이전트와 터미널이 무엇인지부터 시작해, Orca가 어떤 에이전트를 지원하고, 그 에이전트와 대화하는 두 가지 화면(터미널·채팅), 지난 대화 다시 열기, 쉬는 에이전트 재우기, 사용량 확인, 그리고 터미널의 모든 기능을 차례로 살펴봅니다.
- 코딩 에이전트·터미널·CLI가 무엇이고, Orca가 둘을 어떻게 이어 주는지
- Orca가 기본으로 지원하는 40여 개 에이전트와 통합 수준의 차이, 권한(Yolo/Manual) 기본값
- Claude Code·Codex·Cursor CLI·GLM-5.2 각각의 설정과 특이사항, 계정 바꿔 끼우기(hot-swap)
- 네이티브 채팅 UI(Chat UI)의 작성창·대기열·되감기·모델 선택 등 세부 기능
- 에이전트 세션 기록(Agent Session History), 휴면(hibernation), 훅·메모리, 사용량·한도 추적
- 터미널: 링크 동작, 검색, 테마, 기본 셸, 단축키, 플로팅 터미널, Quick Commands
- 코딩 에이전트와 터미널, 먼저 쉽게 알기 — 이 장 전체의 바탕입니다.
- 권한 기본값 — 에이전트가 왜 “물어보지 않고” 일하는지, 그래도 괜찮은 이유.
- 네이티브 채팅 UI — 글자 화면 대신 메신저 같은 화면으로 에이전트와 대화하기.
- 에이전트 세션 기록 — 어제 하던 대화를 그대로 이어 가기.
- 지원 에이전트 한눈에 보기 — 어떤 에이전트로 시작할지 고르기.
에이전트별 특이사항, 계정 바꿔 끼우기, 사용량 공급자별 방식, 터미널 세부 설정은 필요할 때 찾아 읽으면 됩니다. 🔧 표시가 붙은 접힌 상자는 개발자용 참고라 처음엔 건너뛰어도 됩니다.
코딩 에이전트와 터미널, 먼저 쉽게 알기
터미널(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의 구조화된 채팅 화면으로 대화할 수 있습니다.
사용량
상태 표시줄에 사용량·한도까지 남은 정도를 보여 줍니다.
세션 기록 · 재개
지난 대화를 목록에서 찾아 그대로 이어갈 수 있습니다.
전체 목록 펼치기 — 기본 선택기의 에이전트 41개 (검색·필터)
기본 선택기에 들어 있는 에이전트 전체입니다. 이름으로 검색하거나 기능별로 걸러 볼 수 있습니다. 표에 나오는 낯선 이름 풀이:
- 감독 작업자(supervised workers): 에이전트가 거느리는 작업자를 Orca가 함께 관리·표시해 준다는 뜻입니다.
- 백그라운드 도우미를 행으로 표시: 에이전트가 뒤에서 돌리는 보조 작업이 목록에 한 줄씩 보인다는 뜻입니다.
- 작업 공간 신뢰(workspace trust): Qoder CLI 행에 붙은 지원 항목 이름입니다. 원문에는 이름만 나옵니다.
dsh-tui프로필: DeepSeek Harness를 실행할 때 Orca가 쓰는 실행 설정(profile)의 이름입니다.tui는 터미널 안 글자 화면(TUI)을 뜻합니다.acli,traecli,qwen: 각각 Rovo Dev, Trae, Qwen Code를 찾거나 실행할 때 쓰는 실행 파일 이름입니다.
| 에이전트 | Orca에서 되는 것 (Notes) | 만든 곳 |
|---|---|---|
| Claude Code | 깊은 통합 사용량 계정 전환(hot-swap), 훅, 계정별 폴더 | Anthropic |
| Claude Agent Teams | 기본은 꺼져 있음. Settings → Agents에서 켜면 orca claude-teams로 실행되고, 팀원(teammate)마다 Orca의 네이티브 패널이 하나씩 생깁니다 | Anthropic |
| Codex | 깊은 통합 사용량 계정 전환(hot-swap) | OpenAI |
| Muse Code | 깊은 통합 훅 상태, 사용량 세션 기록 | Meta |
| Grok | 자동 설정, 네이티브 채팅(구조화) | xAI |
| GitHub Copilot CLI | 자동 설정 | GitHub |
| OpenCode | 자동 설정, 상태, 계정 프로필, 네이티브 채팅(구조화). OpenCode 2 베타도 지원 | OpenCode |
| Pi | 자동 설정, 훅 상태, 네이티브 채팅(구조화). 백그라운드 도우미를 행으로 표시 | Pi |
| ZCode | 자동 설정, 훅 상태, 세션 재개, 사용량, 감독 작업자. 터미널 UI가 있는 zcode 빌드를 설치해야 함 | ZCode |
| DeepSeek Harness | 자동 설정, 훅 상태, 질문(questions), 세션 재개. dsh-tui 프로필로 실행 | DeepSeek |
| OMP | 자동 설정, 훅 상태, 네이티브 채팅(구조화). 백그라운드 도우미를 행으로 표시 | OMP |
| Prime Agent | 자동 설정, 훅 상태, 세션 기록 | Prime Intellect |
| Gemini | 자동 설정 | |
| Antigravity | 자동 설정, 훅 상태, 계정. 로컬 감독 작업자. IDE·2.0에서 하던 대화를 새 CLI 대화로 이어갈 수 있음 | |
| Ante | 자동 설정, 상태 | Ante |
| Aider | 자동 설정 | Aider |
| Goose | 자동 설정 | Block |
| Amp | 자동 설정 | Amp |
| Kilocode | 자동 설정 | Kilo |
| Kiro | 자동 설정, 상태, 세션 기록 | Kiro |
| Charm Crush | 자동 설정 | Charm |
| Auggie | 자동 설정 | Augment |
| Autohand | 자동 설정 | Autohand |
| Cline | 자동 설정 | Cline |
| CodeBuddy | 자동 설정, 훅 상태, 세션 기록. 설치: npm install -g @tencent-ai/codebuddy-code | CodeBuddy |
| Codebuff | 자동 설정 | Codebuff |
| Freebuff | 자동 설정, 상태 | Freebuff |
| Command Code | 자동 설정, 상태 | Command Code |
| Continue | 자동 설정 | Continue |
| Cursor CLI | 깊은 통합 | Cursor |
| Devin | 자동 설정, 계정 프로필 | Devin |
| Droid (Factory) | 자동 설정, 훅 상태 | Factory |
| Kimi | 자동 설정 | Moonshot |
| Mistral Vibe | 자동 설정 | Mistral |
| MiniMax | 자동 설정, 사용량 추적, 한도(rate-limit) 추적 | MiniMax |
| Qoder CLI | 자동 설정, 훅 상태, 작업 공간 신뢰(workspace trust), 세션 재개, 감독 작업자. Qoder CLI CN 포함 | Qoder |
| Qwen Code | 설치된 qwen 실행 파일로 자동 설정, 감독 작업자 | Qwen |
| Rovo Dev | 자동 설정. acli를 통해 감지 | Atlassian |
| Hermes | 자동 설정 | Nous |
| OpenClaw | 자동 설정 | OpenClaw |
| Trae | traecli(TRAE CN CLI)로 자동 설정 | Trae |
권한 기본값 — 왜 “확인 없이” 실행할까
코딩 에이전트는 보통 명령을 실행하기 전에 “이거 실행해도 될까요?”라고 매번 묻습니다. 예를 들어 파일을 지우거나 고치기 전에 “이 파일 지워도 될까요? [예/아니오]” 같은 확인 창을 띄우는 식입니다. Orca는 새로 실행하는 에이전트에 이 확인을 건너뛰는 옵션(flag(프로그램을 실행할 때 명령 뒤에 붙이는 켜기/끄기 스위치. 예: --yolo))을 미리 붙여 둡니다. 이런 “확인 없이 실행” 상태를 흔히 Yolo라고 부릅니다.
무엇이 위험할까
확인을 건너뛰면 에이전트가 파일을 고치거나 지우는 셸 명령도 여러분에게 묻지 않고 바로 실행합니다. 잘못된 명령이 있어도 중간에 막을 기회가 없습니다.
그래도 괜찮다고 보는 이유
에이전트는 원본이 아니라 자기 전용 워크트리(버려도 되는 작업용 복사본)에서 일합니다. 결과는 원본에 합치기(병합) 전에 사람이 보고 마음에 드는 것만 골라 담거나 통째로 버릴 수 있습니다.
main은 보통 기본 갈래), 체리픽(cherry-pick)(변경 중 마음에 드는 것만 골라 가져오기), 병합(merge)(작업 결과를 원본 갈래에 합치기).
에이전트별로 미리 붙는 옵션 이름
| 에이전트 | 미리 채워지는 옵션 |
|---|---|
| Claude | --dangerously-skip-permissions |
| Codex | --dangerously-bypass-approvals-and-sandbox |
| Gemini · Cursor · Crush · Kimi · Rovo Dev · Hermes · GitHub Copilot · Command Code | --yolo |
| 그 밖의 에이전트 | 같은 역할을 하는 옵션이 있으면 그것 |
권한 모드 바꾸기
- 전체 전환: Settings → Agents → Agent Permissions따로 손대지 않은(uncustomized) 터미널 에이전트 실행을 Yolo(확인 없이)와 Manual(매번 확인) 사이에서 한 번에 바꿉니다.
- Claude·Codex 새 세션의 기본값같은 곳에서 새 Claude·Codex의 터미널 세션과 구조화 채팅 세션 기본값도 정합니다. 이미 열린 채팅은 자기 모드를 그대로 유지합니다.
- 한 에이전트만 다시 묻게 하기Settings에서 그 에이전트의 기본 인수(arguments)나 환경 변수(environment)(프로그램이 시작할 때 읽어 가는 이름=값 설정)를 직접 고칩니다.
직접 고친 에이전트 설정은 전체 전환 스위치가 건드리지 않습니다. 구조화 채팅에서는 Manual · Auto · Yolo 세 가지 중 고를 수 있습니다(뒤의 네이티브 채팅 참고).
직접 고친 설정이 보호되는 규칙
어떤 에이전트의 실행 인수나 환경 변수를 이미 직접 바꿔 두었다면, 전체 전환 스위치가 그 명령을 지우지 않도록 Orca는 그 에이전트를 그대로 둡니다. 비어 있지 않은 사용자 값은 “명시적 덮어쓰기”로 취급되어, 이후 권한 모드 일괄 변경(migration)에서도 빠집니다.
에이전트별 특이사항
깊게 통합된 에이전트 셋과, 다른 회사 모델(GLM-5.2)을 끼워 쓰는 방법을 탭으로 나눠 봅니다. 탭마다 설치 → 로그인 → 실행 세 단계만 알면 충분하고, 버전별 예외나 설정 파일 내용은 접힌 참고 상자에 모아 두었습니다.
Claude Code — Anthropic의 에이전트 CLI
Orca가 정식으로 지원하는(first-class) 터미널 에이전트입니다. 어느 계정인지 알아보고 시작하고, 사용량을 보여 주고, 계정을 한 번 클릭으로 바꿔 끼울 수 있습니다.
흐름: 설치 → 한 번 로그인 → Orca에서 고르기. Anthropic 안내대로 설치하고, 아무 터미널에서 한 번 로그인하면 Orca가 내 사용자 폴더(~ 표시가 뜻하는 곳 — macOS라면 /Users/내이름 같은 내 개인 폴더) 안의 Claude 설정을 알아서 읽습니다. 추가 설정은 필요 없습니다. 그다음 워크트리에서 터미널을 열고 에이전트 선택 상자에서 Claude Code를 고르면, 탭에 “작업 중 / 입력 대기 / 완료” 상태 점이 뜹니다.
Claude Code 세부 — 설치 명령, 상태 훅, 사용량, 계정 전환, 서브에이전트
설치 명령: npm i -g @anthropic-ai/claude-code 또는 Anthropic 문서를 따릅니다. 로그인 후 Orca는 ~/.claude를 자동으로 읽습니다.
실행: Orca는 워크트리를 작업 폴더로 삼아 실행하고, 상태 줄 훅(status-line hook)을 함께 넣습니다. 이 훅이 내보내는 OSC 제목 이벤트(터미널 프로그램이 터미널에게 보내는 특수 신호. 여기선 창 제목을 바꾸는 신호)로 Orca가 상태 점(state dots)을 그립니다.
사용량·한도: 로컬 ~/.claude 사용량 상태를 읽어 현재 사용량과 한도에 얼마나 가까운지를 상태 표시줄에 보여 줍니다(사용량 절).
계정 hot-swap: 여러 Claude 계정을 한 번 클릭으로 바꿉니다(Codex와 같은 흐름). Claude 세션이 돌고 있어도 바꿀 수 있는데, 전환이 진행되는 동안에는 인증 갱신이 서로 겹치지 않도록 막아 둡니다. 바꿔도 공유 MCP 서버(에이전트에 도구를 붙여 주는 외부 서버, Model Context Protocol) 로그인은 유지되어 다시 인증할 필요가 없습니다.
서브에이전트와 팀: 백그라운드 서브에이전트와 Agent Teams 팀원이 워크트리 에이전트 목록과 Agent Dashboard에서 리드 에이전트 아래 펼칠 수 있는 하위 행으로 보입니다. 하위 행을 고르면 리드 터미널에 그 대화 기록이 보이고, 부모를 고르면 돌아옵니다. 지금 보이는 기록에는 눈(👁) 표시가 붙습니다. Claude 상태 훅이 있으면 기본으로 켜져 있으며, 리드 터미널을 그대로 보고 싶으면 Settings → Agents → Claude subagent navigation에서 끕니다. 설정을 바꾼 뒤에는 새 Claude 세션을 시작해야 적용됩니다.
훅·메모리: 저장소별 훅과 메모리 파일을 지원하며 훅·메모리 절에서 다룹니다.
Codex — OpenAI의 에이전트 CLI
Orca에서 가장 깊이 통합된 에이전트 중 하나입니다. 사용량을 보거나, 계정을 바꾸거나, 다시 실행해도 어느 계정으로 돌던 것인지가 그대로 이어집니다.
흐름: 설치 → 로그인 → Orca에서 고르기. OpenAI 안내대로 설치하고 아무 터미널에서 로그인하면, Orca가 내 사용자 폴더(~ — 내 개인 폴더) 안의 Codex 로그인 정보를 읽어 계정을 알아봅니다. 선택 상자에서 Codex를 고르면 지금 고른 계정으로 실행되고, Codex가 끝나면 재시작 칩(다시 실행 버튼)이 같은 계정으로 다시 실행해 줍니다.
Codex 세부 — 로그인 폴더·작업 폴더, System default·추가 계정, 0.157 이상 버전 예외, 탭별 서버
Orca는 ~/.codex에서 계정과 자격 증명을 읽고, 실행할 때 워크트리를 작업 폴더(cwd)로 삼아 지금 고른 계정으로 인증을 보냅니다.
System default와 추가 계정
System default는 실제 ~/.codex 로그인(Orca 밖에서 그냥 codex를 쳤을 때 쓰는 그 홈)입니다. Orca가 관리하는 추가 계정은 Orca 계정 데이터 아래 각자의 홈을 가져 자격 증명과 기록(rollouts)이 섞이지 않습니다. 새 Codex 실행은 활성 계정을 따르고, 이미 돌고 있는 세션은 재시작할 때까지 시작할 때의 홈을 유지합니다.
Codex 0.157 이상
- Orca 관리 계정의 홈 경로가 너무 길어 Codex 백그라운드 데몬 소켓에 못 쓰면, Orca가 그 홈에서 데몬을 꺼서 Codex가 시작되게 합니다. 선택기로 실행하든 Orca 터미널에
codex를 직접 치든 같습니다. 계정 데이터는 그대로이고 시스템~/.codex/config.toml은 바꾸지 않습니다. - 그런 홈에서는
codex agents와 데몬 기반 resume/continuation을 쓸 수 없습니다. 그래도path must be shorter than SUN_LEN오류가 나면 Troubleshooting 문서를 보세요.
Codex 터미널마다 자기 서버
0.157 이상에서는 Orca 터미널의 Codex 탭마다 자기 백그라운드 서버를 기본으로 돌립니다. 탭마다 상태가 정확해지고, 한 탭을 닫아도 다른 탭이 끊기지 않습니다. 새로 연 터미널부터 적용되며, 업데이트 때 이미 열려 있던 터미널은 다시 열 때까지 예전 방식입니다.
- 대가: 탭별 서버에서는 Codex의 공유 서버 기능(백그라운드 실행,
codex agents, Codex 데스크톱 앱이나 IDE에서 연 세션)이 Orca에서 시작한 세션을 보지 못합니다. - 공유 서버로 바꾸려면: 새 터미널을 열기 전에 Settings → Agents → Run each Codex terminal on its own server를 끄거나,
ORCA_CODEX_ISOLATE=0을 설정합니다(예: 셸 시작 파일에export ORCA_CODEX_ISOLATE=0). 그러면 Codex의 agents 개요를 다시 쓸 수 있습니다.
직접 시작한 Codex가 공유 서버에 붙으면 그 탭 위쪽에 안내가 뜹니다. Fix를 누르면 공유가 꺼지고, 업데이트 전에 연 탭이라면 대신 새 터미널을 열자고 제안합니다.
Codex 세부 — Task 서브에이전트, 넘겨주기, 재시작 칩, 사용량
- Task 서브에이전트: Codex가 만든 Task 서브에이전트가 워크트리 에이전트 목록과 Agent Dashboard에서 부모 아래 하위 행으로 보입니다. 꺾쇠(chevron)를 펼쳐 보고, 하위 행을 누르면 부모 터미널로 초점이 갑니다(서브에이전트는 따로 패널을 갖지 않음).
- Hand Off to Another Agent: 에이전트 터미널 머리글이나 우클릭 메뉴에서 고르면, 같은 또는 다른 CLI로 새 세션을 시작하고 이전 대화 기록이나 수집된 맥락에서 만든 분량이 제한된 인계 프롬프트를 넣어 줍니다. 원래 세션은 그대로이며,
codex resume과는 다릅니다. - 재시작 칩(restart chip): Codex가 끝나면 이 칩이 같은 계정으로 다시 실행합니다. 중간에 계정을 바꿨고 새 계정으로 재시작하고 싶다면 계정 전환기를 먼저 쓰고 재시작하세요.
- 사용량: 활성 계정의 로컬 Codex 사용량을 상태 표시줄에 보여 줍니다.
Windows(WSL)에서의 Codex
- Windows의 Codex도 macOS·Linux처럼 실제
~/.codex홈을 씁니다. 업데이트 후 처음 Codex 터미널이 뜰 때 한 번 안내가 나옵니다: Codex가 폴더 신뢰나 명령 승인을 다시 물을 수 있고, Orca 안에서만 추가했던 MCP 서버는 다시 추가해야 합니다. 이미 열려 있던 Codex 터미널은 다시 열 때까지 이전 홈으로 돕니다. - Windows에서는 호스트 설치본이나 WSL 배포판(distro)(WSL은 Windows 안에서 리눅스를 돌리는 기능, 배포판은 설치된 리눅스 종류) 중 어디의 Codex를 쓸지 고를 수 있습니다. 계정 전환기에서 WSL Codex 계정을 추가하면, Orca가 배포판 안에 격리된 홈(
~/.local/share/orca/codex-accounts/<id>/home)을 만들고, 인증을 읽을 수 있게 호스트에서\\wsl.localhost\<distro>\...경로로 연결하며, 실행·hot-swap·한도 조회를 그 배포판을 거쳐 보냅니다. - 대상 배포판에 Codex가 없으면 Add account 창이 어느 배포판에 실행 파일이 없는지 알려 주는 메시지와 함께 실패합니다.
Cursor CLI — Cursor의 명령줄 에이전트
선택 상자에서 실행, 상태 점 표시, 끝났을 때 재시작 칩까지 정식으로 지원합니다.
흐름: 설치 → 한 번 로그인 → Orca에서 고르기. Cursor 안내대로 Cursor CLI를 설치하고 한 번 로그인하면 Orca가 설치된 프로그램을 스스로 찾아냅니다. 선택 상자에서 Cursor를 고르면 그 워크트리 안에서 실행되고 탭에 상태 점이 뜹니다.
Cursor CLI 세부 — 감지 방식, 상태 신호
Orca는 PATH(셸이 실행 파일을 찾아보는 폴더 목록)에서 CLI를 찾아냅니다. Cursor의 TUI가 상태 점에 필요한 신호(OSC 상태 이벤트(터미널 프로그램이 터미널에게 보내는 특수 신호))를 보내 줍니다.
모델 선택: Cursor 자체 설정을 따릅니다. Orca는 덮어쓰지 않으니 CLI 안에서 설정하세요.
사용량: 기존 Cursor 로그인으로 플랜 사용량을 상태 표시줄과 Settings → Accounts → Cursor에 보여 줍니다.
GLM-5.2를 Orca에서 쓰기
GLM-5.2는 따로 “에이전트”가 있는 게 아니라, 이미 쓰는 에이전트의 두뇌(모델)만 바꿔 끼우는 방식입니다. 이때 바깥 껍데기 프로그램을 하네스(harness)(모델을 감싸 파일 읽기·명령 실행을 맡는 에이전트 프로그램. 예: Claude Code, OpenCode)라고 부릅니다. Claude Code, OpenCode, Cline, Kilo Code, Roo Code, Droid, OpenClaw 등에 GLM-5.2를 설정한 뒤 Orca 선택기에서 그 에이전트를 실행하면 됩니다. Orca는 워크트리·터미널 패널·브라우저 탭·리뷰 흐름·세션 관리를 주고, 모델 접근은 Z.ai CodePlan 구독과 에이전트 설정이 맡습니다.
설정 방법은 하네스마다 다릅니다: Claude Code는 설정 파일에 모델 이름 몇 줄을 넣고, OpenCode 등 OpenAI 호환 하네스는 설정 화면에서 주소·키·모델 이름을 입력하고, OpenClaw는 설정 파일에 모델을 직접 추가합니다. 자세한 값은 아래 접힌 상자에 있습니다.
① Claude Code에 GLM-5.2 설정 (settings.json)
~/.claude/settings.json열기Claude Code는 여기서 모델 덮어쓰기를 읽습니다.- 아래
env블록 추가·수정 - Orca의 Claude Code 세션 재시작새 환경 변수를 불러오기 위해서입니다.
/status실행Claude Code 안에서 활성 모델을 확인합니다.
{
"env": {
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]"
}
}
[1m]접미사는 GLM-5.2의 100만 토큰 문맥(context) 버전을 뜻합니다. 이때CLAUDE_CODE_AUTO_COMPACT_WINDOW를1000000으로 두어 Claude Code의 압축(compaction) 창 크기를 맞춥니다.- Claude Code가
[1m]모델이 없다고 하면 Claude Code를 업데이트한 뒤 다시 시도합니다. - 코딩 작업에는 Z.ai가
/effort로 effort를 max로 두길 권합니다. Claude Code의 낮은 effort 설정은 GLM-5.2의 high로,xhigh·max·ultracode는 GLM-5.2의 max로 연결됩니다.
② OpenAI 호환 하네스 (OpenCode, Cline, Kilo Code, Roo Code, Droid)
OpenCode, Cline, Kilo Code, Roo Code, Droid처럼 OpenAI 호환 공급자를 지원하는 하네스:
- 하네스 설정 열기Orca 안이든 밖이든 상관없습니다.
- 공급자 선택OpenAI 호환(OpenAI-compatible) 공급자, 또는 Z.ai 공급자 항목이 있으면 그것을 고릅니다.
- Base URL
https://api.z.ai/api/coding/paas/v4 - Z.ai API 키 입력
- 사용자 지정 모델 이름
glm-5.2 - 문맥 창 크기입력란이 있으면
1000000. - 이미지 지원 끄기그 하네스가 이 공급자 경로의 이미지 지원을 명시하지 않는 한 끕니다.
저장한 뒤 Orca 에이전트 선택기에서 실행하면, Orca가 같은 설정의 CLI를 선택한 워크트리에서 돌립니다.
③ OpenClaw에 GLM-5.2 추가 (openclaw.json)
OpenClaw가 공급자 모델 목록에서 GLM-5.2를 바로 고르지 못하면 ~/.openclaw/openclaw.json에 직접 추가합니다.
① models.providers.zai.models에 glm-5.2 추가
{
"id": "glm-5.2",
"name": "GLM-5.2",
"reasoning": true,
"input": ["text"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 1000000,
"maxTokens": 131072
}
② 기본 주 모델 지정
{ "model": { "primary": "zai/glm-5.2", "fallbacks": ["zai/glm-4.7"] } }
③ agents.defaults.models에 모델 추가
{ "models": { "zai/glm-5.2": { "alias": "GLM" }, "zai/glm-4.7": {} } }
④ 게이트웨이 재시작 — openclaw gateway restart
⑤ 확인 — Orca에서 OpenClaw를 실행하거나 Orca 터미널에서 openclaw tui를 실행해 GLM-5.2가 활성인지 봅니다.
계정 바꿔 끼우기 (Hot-swap Codex · Claude 계정)
AI는 쓴 양을 토큰(AI 사용량을 세는 단위. 글자 조각 하나하나를 셉니다)으로 세고, 계정마다 쓸 수 있는 양에 한도가 있습니다. 그래서 넉넉히 쓰려고 Codex 계정을 여러 개 쓰는 경우가 흔합니다. Orca에서는 다시 로그인하지도, 설정 파일을 고치지도 않고 한 번 클릭으로 활성 계정을 바꿉니다. Claude Code 계정도 데이터 폴더만 ~/.claude로 다를 뿐 똑같이 동작합니다.
원리는 간단합니다. Orca는 “지금 쓸 계정”을 가리키는 표시, 즉 자격 증명 포인터(여러 로그인 정보 중 지금 쓸 계정을 가리키는 화살표 같은 표시)만 옮깁니다. 로그인 정보 자체는 건드리지 않으므로 다시 로그인할 필요가 없습니다.
1단계 · 각 계정에 한 번씩 로그인
터미널에서 각 Codex 계정으로 적어도 한 번 로그인해, 인증 정보가 ~/.codex 아래에 남게 합니다.
2단계 · Settings → Agents → Codex Accounts
Orca가 감지한 계정을 사용량·현재 한도와 함께 모두 보여 줍니다.
3단계 · 친근한 이름 붙이기
각 계정에 “personal”, “work” 같은 이름(label)을 붙입니다.
4단계 · 상태 표시줄의 Codex 칩 클릭
계정 전환기가 열립니다. 계정을 고르면 그 뒤에 실행하는 새 Codex 세션이 그 계정을 씁니다. 이미 돌고 있는 세션은 재시작할 때까지 원래 계정을 씁니다.
System default 행은 Orca 밖 터미널에서 그냥 codex를 쳤을 때 쓰는 원래 로그인입니다.
System default 행과, 설정을 고쳤는데 무시되는 것 같을 때
System default 행
~/.codex에 있는 현재 호스트의 Codex 로그인입니다. Orca에서 추가한 관리 계정은 이 로그인을 다시 쓰지 않고 격리된 홈에서 돕니다. Orca 밖 터미널의 codex와 똑같이 실행하고 싶으면 System default를 고르세요.
설정을 고쳤는데 무시되는 것 같을 때
관리 계정에서는 Orca가 실제 ~/.codex/config.toml의 설정을 활성 실행 홈으로 복사(mirror)합니다. 원본이 없거나, 비었거나(예: 클라우드 동기화가 아직 내려받는 중), 읽을 수 없으면 Accounts에 경고가 뜨고, Codex는 마지막으로 성공한 설정을 계속 씁니다. 배너에 적힌 경로의 파일을 고친 뒤 다시 실행하거나 계정을 다시 고르세요.
- 전환은 즉시입니다 — 활성 자격 증명 포인터만 바꾸고, 다시 인증하지 않습니다.
- 이미 실행 중인 Codex 프로세스는 재시작할 때까지 현재 계정을 유지합니다.
- 상태 표시줄 사용량은 현재 활성 계정을 따라갑니다.
- 재시작 칩은 재시작하는 그 순간의 활성 계정을 씁니다.
네이티브 채팅 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를 씁니다.
Chat/CLI 선택의 세부 규칙
- 구조화 구현이 없는 에이전트와 WSL·SSH 세션은 터미널 기반 Chat UI를 씁니다.
- 기존 사용자는 원래 실행 설정을, 기존 대화는 원래 화면을 유지합니다.
- 에이전트별 선택은 데스크톱에서 시작하는 모든 경우(CLI, 오케스트레이션, 휴대폰에서 중계된 실행 포함)에 적용됩니다.
- 탭 우클릭 메뉴나 Agent Session History에서 지원되는 대화를 채팅↔터미널로 옮길 수 있습니다.
- 어디서 되나: 내 컴퓨터(macOS·Linux·Windows)와, 짝지은 Orca Server가 맡은 워크트리.
- 모양: Settings → Chat UI에서 글꼴·크기·폭·대비를 정하고, Match terminal interface로 터미널과 같은 모양을 쓸 수 있습니다.
- Inline visuals: 켜면 에이전트가 답변 안에 차트·다이어그램·목업을 그립니다.
- 권한 모드: Manual · Auto · Yolo 중 고릅니다(권한 기본값의 그림 참고).
- Orca가 재시작돼 끊긴 채팅은 다시 연결될 때 이어서 하자고 제안합니다.
구조화 채팅 세부 — 셸 환경 변수, 실행 명령, Codex Ask, Antigravity, 끊긴 채팅
- 어디서 되나: 로컬 macOS·Linux·네이티브 Windows의 자격 있는 세션, 그리고 짝지은(paired) Orca Server가 소유한 워크트리. WSL·SSH는 터미널 기반 Chat UI를 계속 쓰고, 구조화 구현이 없는 에이전트는 터미널에 머뭅니다. 기존 터미널 세션은 터미널 세션으로 남습니다.
- Use your shell environment: 새로 열거나 재개하는 구조화 채팅에 넘길 환경 변수(프로그램이 시작할 때 읽어 가는 이름=값 설정)를 정합니다. 기본으로 켜져 있어 로그인 셸의 export 값을 받습니다. 끄면 PATH(실행 파일을 찾는 폴더 목록), 로캘(언어·지역 설정),
SSH_AUTH_SOCK(SSH 로그인 열쇠를 찾는 위치) 같은 기본 셸 변수에 더해 고른 변수 이름만 허용합니다. 터미널 기반 채팅은 계속 터미널 셸을 씁니다. - 실행 명령: 구조화 채팅은 Settings → Agents에 저장된 그 에이전트의 Command·Arguments로 실행됩니다.
- 모양: Settings → Chat UI에서 채팅 글꼴, 글자 크기, 코드 크기, 폭, 대비를 정합니다. Match terminal interface를 켜면 터미널의 글꼴·색(이후 테마 변경 포함)을 따라갑니다.
- Inline visuals: 같은 화면 설정에서 켜면 에이전트가 답변 안에 차트·다이어그램·목업을 그릴 수 있습니다(데스크톱·휴대폰). 넓게 보려면 그림을 따로 탭으로 열 수 있고, Mermaid 다이어그램은 다크 모드에서 채팅 테마를 따릅니다.
- 권한 모드: Settings → Agents에서 새 Claude·Codex 터미널·구조화 채팅 세션의 기본값을 Manual · Auto · Yolo 중 고릅니다. Auto는 지원 에이전트가 일상적인 동작을 스스로 승인하게 합니다. Auto를 지원하지 않는 에이전트는 Other agents에서 Manual 또는 Yolo를 고릅니다. 기본값을 바꾸거나 모델을 바꿔도 기존 채팅은 자기 모드를 유지합니다.
- Codex Ask 모드: Codex가 편집을 요청할 때까지 워크트리 접근을 읽기 전용으로 둡니다. 요청을 승인하면 편집이 진행됩니다. 필요하면 처음부터 Approve for me나 Full access로 시작하세요. 권한 선택은 다음 턴부터 적용되고, 이미 돌고 있는 작업은 시작할 때의 권한을 유지합니다.
- Antigravity 채팅: 자체 채팅 서버를 씁니다. 채팅을 돌릴 호스트에 서버가 없으면 Providers 행이나 채팅의 설치 카드에서 Install을 누른 뒤, 그 서버의 Google 로그인으로 로그인합니다. 실행 환경(runtime)은 Install을 누른 뒤에만 내려받습니다. 설치된 Providers 행의 Remove로 지우면 그 호스트의 Antigravity 채팅이 멈추지만 기록은 남습니다.
- 재시작으로 끊긴 채팅: 다시 연결될 때 이어서 하자고 제안합니다. 창을 닫았다가 상태 표시줄의 chats to resume 항목에서 나중에 열 수 있고, 이을 채팅이 없으면 항목이 사라집니다. 직접 닫은 채팅 탭은 오른쪽에 다시 나타나지 않습니다.
보내기 · 멈추기 · 첨부
메시지를 보내거나 진행 중인 턴을 멈춥니다. 호스트(에이전트가 실제로 돌아가는 컴퓨터 — 내 컴퓨터나 짝지은 서버)가 지원하면 파일·이미지를 첨부합니다. 파일 트리나 바탕화면에서 작성창(또는 채팅 화면 아무 곳)으로 끌어다 놓으면 에이전트가 읽을 수 있는 경로로 추가됩니다. 첨부 파일은 파일 이름 알약(pill)으로 보입니다.
이미지 붙여넣기 (Codex)
업데이트된 로컬 Codex 채팅에서는 앱 메뉴나 클립보드로 이미지를 붙여넣습니다. 보내기 전 지울 수 있는 썸네일로 보이고, 눌러서 크게 볼 수 있습니다.
끊겨도 남는 초안
보내지 않은 글과 첨부는 호스트가 복원할 수 있으면 연결이 끊겼다 이어져도 남습니다. 같은 세션이 재연결되는 동안 이미 끝난 대화 기록도 화면에서 지워지지 않습니다(데스크톱·모바일 공통).
@ 파일 고르기
초안에 @를 치면 워크트리 파일을 골라 경로로 넣습니다. 모바일 Chat UI에도 같은 팝오버가 뜹니다.
찾기 · 인용 · 이전 프롬프트
Cmd+F(macOS) / Ctrl+F(Windows·Linux)로 채팅 내 검색. 답변 일부를 선택하고 Add to chat으로 작성창에 인용. 빈 초안에서 ↑/↓로 보냈던 모든 프롬프트를 불러옵니다.
숫자 키로 답하기
에이전트가 번호 선택지가 있는 질문을 하면 숫자 키로 답하고, 다음 질문으로 넘어갑니다.
분할 · 이동
패널 동작으로 Chat UI를 나누거나 다른 패널로 옮겨도 같은 세션이 유지됩니다.
diff 카드 · 링크
에이전트의 파일 수정은 인라인 diff 카드로 보입니다. 대화 속 파일 경로·링크를 누르면 Orca에서 열립니다.
복사
답변 속 코드 상자(펜스 코드 블록(답변 안에 테두리로 따로 묶여 보이는 코드 부분))와 셸 명령은 문법 강조되고 블록마다 Copy code 버튼이 있어 코드만 복사합니다. 데스크톱에서 보낸 메시지에 마우스를 올리면 타임스탬프 옆 버튼으로 복사합니다.
대기열(Queue)과 끼어들기(Steer)
대기열 세부 — 편집, 기본 동작 뒤집기, 모바일
- 대기 메시지는 에이전트가 질문하는 중에도 그 자리에서 편집할 수 있고, 이미지·스킬·@파일을 포함한 전체 작성창으로 고칩니다. 카드는 끌어서 순서를 바꿉니다. 모바일 작성창 위에도 같은 카드가 보입니다.
- Cmd+Enter / Ctrl+Enter는 진행 중인 턴에 바로 보냅니다. 기본 동작을 뒤집으려면 Settings → Chat UI → Behavior → Queue follow-ups를 끕니다.
- 모바일에서는 Send를 길게 눌러 Queue/Steer를 고르고, 짧게 누르면 호스트 설정을 따릅니다. 대기열을 모르는 예전 클라이언트·호스트는 바로 보냅니다.
멈추기 · 전송 상태 · 되감기
| Stop | 진행 중인 턴을 끝냅니다. |
|---|---|
| Sending… | 보내는 중. 상대(호스트)가 받았다고 확인할 때까지 이렇게 보입니다. |
| Not sent | 보내지 못했음. 이유가 함께 나오고 Retry로 다시 보냅니다. |
| 미확인(unconfirmed) | 보냈는지 확실치 않을 때, 같은 메시지가 두 번 가는 것을 막으려고 “미확인”으로 둡니다. |
| Rewind to here | 대화를 그 메시지 시점으로 되돌리고, 그 메시지를 작성창에 돌려놓아 고쳐 다시 보내게 합니다. |
멈추기·전송 상태·되감기 세부
- Stop은 턴을 끝냅니다. Claude는 백그라운드 명령과 서브에이전트까지 포함한 프로세스를 끝냅니다. Codex가 멈춤 요청을 거부하거나 답하지 않으면 Orca가 끝냅니다.
- “보내지 않았다”고 표시된 메시지는 Retry를 누르기 전까지 보내지지 않고, Steer로 넣은 메시지는 다시 보내지 않습니다.
- 나가는 메시지는 호스트가 확인할 때까지 Sending…, 실패하면 이유와 함께 Not sent로 표시됩니다. Orca가 충돌하거나 종료되어 끊긴 답변은 설명 하나와 함께 끝난 턴으로 보입니다. Orca가 끊어야 했던 답변은 이유를 밝히고 Continue를 제안하는데, 먼저 에이전트에게 마지막 단계가 끝났는지 확인하게 합니다.
- 보내는 도중 Orca나 에이전트가 재시작되면, Orca는 공급자 쪽 대화 기록을 확인해 봅니다. 메시지가 도착한 것이 확인되면 전송 완료로, 도착하지 않은 것이 확인되면 Retry를 엽니다. 어느 쪽인지 알 수 없으면 같은 메시지가 두 번 가지 않도록 미확인(unconfirmed)으로 둡니다.
- Rewind to here: 보낸 메시지의 마우스 오버 줄에 있는 되돌리기 동작으로, 대화를 그 시점으로 되돌리고 그 메시지를 작성창에 돌려놓아 고쳐 다시 보낼 수 있습니다. 에이전트가 쉬고 있고 기다리는 것이 없어야 하며, Codex는 턴 전체를 되돌립니다.
긴 대화는 생각·도구 호출 묶음이 한 줄로 접히고, 가장자리 메시지 레일로 원하는 턴에 뛸 수 있어 읽기 쉽습니다.
읽기 쉬운 대화 기록 — 도구 행, 접기, 메시지 레일, 이전 기록 불러오기
- 업데이트된 구조화 Codex 채팅에서는 실행 중인 도구 호출이 실시간 진행을 보여 주고, 끝나면 펼쳐서 명령·결과를 볼 수 있는 작은 행으로 접힙니다.
- 도구 행은 MCP·웹 검색 작업을 포함해 실제로 한 일을 이름으로 보여 주고(내부 동작 이름 대신), 세션의 다른 작업은 두고 그 행의 작업만 멈출 수 있습니다.
- 긴 보낸 메시지는 토글 뒤로 접히고, 답변 사이의 생각·도구 호출 묶음은 펼칠 수 있는 한 행으로 접힙니다.
- 긴 대화에서는 가장자리에 메시지 레일(message rail)이 생겨 사용자 프롬프트마다 표시가 하나씩 붙습니다. 올려 보거나 초점을 주면 미리 보고, 고르면 그 턴으로 뜁니다. 아주 긴 기록은 표본을 뽑아 레일이 짧게 유지됩니다.
- 위로 스크롤하면 맨 위에 닿기 전에 이전 기록을 미리 불러옵니다. 한 페이지가 실패하면 그 자리의 재시도 버튼을 누릅니다.
/ 명령과 스킬
/를 치면 명령과 스킬(에이전트가 불러 쓰도록 저장해 둔 작업 지침 묶음) 목록이 열립니다.
/clear
같은 패널에서 새 대화를 시작합니다. 이전 대화는 기록에 남습니다.
/compact
에이전트에게 지금까지의 대화 분량(문맥(에이전트가 한 번에 기억하며 참고하는 대화·파일 내용))을 줄여 달라고 해 계속 작업하게 합니다.
모델·옵션 알약
작성창 아래 알약에서 모델과 생각 수준(effort(에이전트가 답하기 전에 얼마나 깊이 생각할지 정하는 단계)) 등을 고릅니다.
새 채팅은 가능하면 첫 메시지로 이름이 지어지고, 탭 동작에서 이름을 바꿀 수 있습니다.
슬래시 명령과 스킬 세부
- 초안 맨 앞이나 공백 뒤에서 /를 치면 슬래시 명령과 발견된 스킬이 묶인 목록 하나가 열립니다. 에이전트가 기대하는 표기를 넣어 줍니다(Claude는
/skill, Codex는$skill). $는 더 이상 별도 선택기를 열지 않습니다. - 문장 중간에서 명령을 고르면 주변 초안을 보내지 않고 그 명령 글자만 완성합니다. 목록은 에이전트별로 다르며 모바일 Chat UI와 공유됩니다. 데스크톱에서 Claude 명령 행은 설치된 CLI가 알려 주는 설명과 인수 힌트를 씁니다.
- 선택기에서 고른 스킬은 초안에 알약으로 남고, 직접 치거나 붙여넣은 스킬 이름은 일반 글자로 남습니다.
- 에이전트 고유 명령은 거부하지 않고 그대로 넘깁니다: Claude
/init,/review,/help, Codex/goal <objective>. Orca는 자기 대화 명령인/clear,/compact는 직접 처리합니다. /clear: 같은 패널에서 새 대화를 시작하고 이전 대화는 기록에 남깁니다./compact: 에이전트에게 현재 대화 문맥을 줄여 달라고 해 계속 작업하게 합니다(Claude, Codex, Grok, OpenCode, OMP 지원). 작업 중에 보낸/compact는 거부되지 않고 줄을 섭니다.
모델·옵션 알약 세부 — Claude·Codex·Grok, Fast mode, 문맥 링
- 에이전트가 제공하면 모델과 옵션(생각 수준, Fast mode 등) 알약을 씁니다. 모델이 많으면 Search models… 칸으로 거릅니다.
- Fast mode는 공급자·모델을 아는 토글로, 활성 에이전트가 지원한다고 알릴 때만 보이며 공급자가 지원하는 경로를 그대로 둡니다.
- Claude: 모델 목록은 그 호스트에 설치된 Claude CLI에서 가져옵니다(고정 목록 아님). CLI를 업데이트하면 새 모델이 보입니다.
- Codex: 알약에서 모델을 바로 고르면
/model <id>를 보내고, 그냥/model은 에이전트 선택기를 엽니다. 속도 선택으로 Ultrafast가 있습니다. - Grok: 모델(실행 시
-m, 세션 중/model)과 추론 effort(실행 시--reasoning-effort, 세션 중/effort). 모델 목록은 로그인된 Grok CLI(grok models)에서 조사해 은퇴한 id는 빠집니다. effort 선택지는 모델을 따릅니다: Grok 4.6은 Extra high까지, Grok 4.5는 High까지. - 모델 선택기는 에이전트 시작을 기다리지 않습니다. 프로세스 시작 전에도 그 에이전트의 모델·effort 선택지가 보이고 첫 시작에 적용됩니다. 세션이 살아난 뒤 실행 중 턴에만 영향을 주는 알약은 준비될 때까지 비활성이거나 표시가 붙습니다. 실시간 값은 그 탭의 CLI로 갑니다.
- 문맥 링(ring): 업데이트된 구조화 Claude 채팅에서 모델·effort 옆 링이 문맥 창 사용량을 보여 줍니다. 열면 토큰 수와 메시지·도구·메모리 파일 등이 차지한 공간이 나옵니다. 턴 중에도 갱신되고 채팅을 다시 열어도 남습니다.
- Codex, Pi, OMP는 로그아웃 상태면 보내기 전에 알려 줍니다(Send는 막지 않음). 실패할 턴을 기다리지 말고 로그인을 고치면 됩니다.
채팅 이름 짓기
새 채팅은 가능하면 첫 메시지로 이름이 지어지고, 아니면 Claude Chat / Codex Chat으로 남습니다. 기본은 그 채팅의 에이전트·계정이 이름을 짓고, Settings → Chat UI → Chat naming → Advanced에서 다른 이름 짓기 에이전트를 고를 수 있습니다. 탭 동작에서 이름을 바꿀 수 있고, 정한 이름은 탭을 닫은 뒤에도 Agent Session History, 휴대폰, 다른 창에 그대로 남습니다.
구조화 채팅은 맡긴 일·뒤에서 도는 일을 메인 턴 동안과 그 뒤에도 보이게 합니다.
- 백그라운드 작업 띠: 뒤에서 도는 작업 수와 상태가 작성창 근처에 보입니다.
- 계획 체크리스트: 에이전트가 세운 계획이 체크리스트로 보입니다.
- 끝나면: 바뀐 파일과 추가/삭제 줄 수 요약이 나오고, 백그라운드에서 끝난 채팅에는 안 읽음 표시가 붙습니다.
작업 따라가기 세부 — 하위 작업, 대기 알림, goal, 활동 행
- 백그라운드 작업 띠(strip): 작업이 살아 있는 동안 보입니다. 요약에 에이전트·셸·모니터·워크플로 등 작업 수가 나오고, 펼치면 이름·상태 점·경과 시간이 있는 묶음 행이 나옵니다. Claude·Codex 하위 작업은 각자 끝날 때까지 보이며 펼친 화면에 과제와 결과가 있습니다. 에이전트 하위 작업은 사이드바 세션 아래에도 들여쓴 행으로 보입니다.
- Codex 채팅은 행에서 백그라운드 명령이나 서브에이전트만 멈출 수 있고, Grok 채팅은 뒤에 남겨 둔 명령을 나열·중지할 수 있습니다. Grok도 서브에이전트를 행으로 보여 줍니다.
- Claude 서브에이전트가 권한 확인을 기다리면 하위 행은 waiting, 부모 세션도 blocked가 아닌 waiting으로 보입니다(CLI 표시와 같음).
- 구조화 채팅이 턴 중간에 승인·입력을 기다리면, 다른 대기 에이전트처럼 알림을 띄워 계속 지켜보지 않아도 됩니다.
- Claude
TodoWrite와 Codexupdate_plan은 인라인 체크리스트로 보이고, 최신 계획은 작성창 위 접이식 진행 패널에도 나옵니다. - 활성 Codex goal은 작성창 위에 상태와 함께 보이며 일시정지·재개·지우기·펼치기 버튼이 있습니다.
/goal을 입력하면 다음 초안을 goal로 보냅니다. goal이 설정·일시정지·막힘·완료·중지·삭제될 때 대화에 행이 생기며, 반복되는 집계 갱신은 중복 행을 만들지 않습니다. - 실행 중인 턴은 대화 끝에 활동 행 하나를 가집니다. Thinking은 추론 중이라는 뜻이고, 명령 실행 같은 공급자 활동이 우선 표시됩니다. 끝났거나 중단된 시간은 새로고침·재시작 후에도 남고, Orca가 턴의 끝을 보지 못했으면 추정하지 않고 시간을 생략합니다.
- 턴이 끝나면 머리글에 바뀐 파일과 추가/삭제 줄 수 요약이 나오고, 펼치면 diff 카드가 보입니다. 답한 승인·질문 카드는 고른 답을 보여 주는 영수증처럼 남습니다.
- 끝난 턴은 답변만 남기고 접힙니다. 에이전트가 실패를 알리면 계속 실행 중으로 보이지 않고 턴이 끝납니다.
- 구조화 채팅이 백그라운드에서 성공적으로 끝나면 탭과 워크트리에 안 읽음 표시가 붙습니다. 데스크톱 알림이나 소리는 없습니다(다른 알림 설정은 Notifications & Inbox 문서).
- 에이전트의 질문: 에이전트가 묻는 것은 질문 카드로 보이고, 카드의 Submit으로 답합니다.
- 채팅 ↔ 터미널: 탭을 우클릭해 같은 대화를 채팅 화면과 터미널 화면 사이에서 바꿉니다.
- Hand Off: 다른 에이전트에게 일을 넘깁니다.
- 한도 후 자동 이어가기: 사용 한도에 걸려 멈춘 채팅을, 한도가 풀리면 Orca가 이어 가게 할 수 있습니다.
질문 카드·화면 옮기기·넘겨주기·자동 이어가기 세부
에이전트의 질문
Claude가 AskUserQuestion(또는 비슷한 구조화 권한·질문 카드)을 띄우면, Chat UI는 접힌 도구 호출이 아니라 질문 카드로 대화에 그려 작성창 쪽에서 답하게 합니다. 카드의 Submit으로 확정합니다. 로컬 패널뿐 아니라 짝지은 Remote Orca Server·헤드리스 호스트에서 도는 에이전트도 마찬가지입니다.
채팅 ↔ 터미널 옮기기
- 탭을 우클릭해 지원 세션을 Chat UI와 TUI 사이에서 실시간으로 바꿉니다.
- 탭 우클릭 메뉴나 Agent Session History 행에서 Resume in New Native Chat은 이전 대화를 구조화 채팅으로 열고, Resume in New CLI는 그 대화를 터미널로 갈라(fork) 냅니다. 원래 대화는 그대로입니다.
- 대화가 구조화 채팅용으로 예약되면 그 세션은 터미널 Resume 대신 채팅을 쓰세요.
넘겨주기와 한도 후 자동 이어가기
- 채팅 머리글이나 탭 우클릭 메뉴의 Hand Off로 다른 에이전트에게 일을 넘깁니다.
- Claude·Codex 채팅이 리셋 시각이 알려진 사용 한도에 닿으면, Settings → Chat UI → Behavior → Continue chats automatically when a usage limit resets를 켜서 리셋 후 Orca가 이어가기 메시지를 보내게 할 수 있습니다. 한도 안내의 Don't continue로 그 채팅만 취소합니다.
- 이 설정은 에이전트를 돌리는 호스트에 속합니다. 닫힌 채팅이나 잠든 워크트리는 다시 열거나 깨울 때까지 기다리고, 24시간보다 오래된 리셋은 직접 이어가야 합니다.
제공 범위
Chat UI는 데스크톱에서 지원되는 로컬·원격(짝지은 서버) 에이전트 세션에 제공됩니다. 모바일 동반 앱도 같은 세션에 채팅식 대화 화면을 재사용합니다.
에이전트 세션 기록 (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 같은 개수 옆 검색 상자에 입력하면 세션 제목, 작업 폴더, 브랜치, 모델, 대화 미리보기 글로 거릅니다.
연결된 다른 컴퓨터의 기록까지 검색할 수도 있습니다.
다른 컴퓨터까지 검색
연결된 다른 컴퓨터와 짝지은 Orca Server의 색인된 기록도 찾을 수 있습니다. Settings → Session History에서 원하는 컴퓨터에 Search inside sessions를 켜거나 Enable on all computers를 씁니다. 컴퓨터가 꺼져 있거나 색인 권한이 없으면 안내가 뜹니다. 검색 데이터는 각 컴퓨터에 머물고, 색인에 없는 세션도 로컬 패널에서 둘러볼 수 있습니다. 스크립트·터미널에서는 orca search로 같은 색인을 조회합니다.
| 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로 더 과거까지 찾습니다.
Agents 필터 전체 목록과 규칙
- Agents: 훑을 CLI를 하나씩 켜고 끕니다 — Claude, Codex, Muse Code, Hermes, Pi, OMP, Prime Agent, Cursor, Gemini, Antigravity, Rovo Dev, Copilot, OpenCode, Grok, OpenClaw, Devin, Droid, Kimi, Kiro, CodeBuddy, ZCode, Qoder. 끈 에이전트는 훑지 않습니다. 머리글의 Select all / Clear로 한 번에 바꾸며, Clear는 아무것도 안 고른 상태로 만들어 원하는 CLI 하나만 켜기 좋습니다. 아무것도 고르지 않으면 No agents selected가 보입니다.
세션 행을 누르면 상세가 열립니다: 작업 폴더, 브랜치, 모델, 메시지 수, 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 | 세션의 작업 폴더를 워크트리로 엶 |
Resume이 실행하는 명령 예시
claude --resume <id>, codex resume <id>, muse resume <session-id>, pi --session <session_file>, prime-agent --resume <path>, cursor-agent --resume <id>, acli rovodev run --restore <id>. Codex는 원래 세션이 CODEX_HOME을 썼다면 그것도 다시 export합니다.
--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 기록 |
에이전트 휴면 (Agent hibernation) 실험 기능
워크트리를 수십 개 열어 두면 쉬고 있는 에이전트도 쌓입니다. 쉬고 있어도 하나하나가 대화를 메모리에 붙잡은 채 켜져 있어서, 켜 둔 에이전트가 많을수록 컴퓨터 자원(메모리)을 계속 씁니다. (속을 들여다보면 각각이 모델 세션을 쥐고 있는 살아 있는 PTY(프로그램이 진짜 터미널에 연결된 것처럼 느끼게 해 주는 가상 터미널)입니다.) 휴면은 일을 마치고 충분히 오래 손대지 않은 터미널을 조용히 멈췄다가, 다음에 그 워크트리를 열 때 같은 세션을 이어서 되살립니다.
언제 잠드나 — 핵심 세 가지
① 일이 끝났다
에이전트가 마지막 일을 마치고(done), 여러분의 입력을 기다리고 있지도 않습니다.
② 30분 동안 손대지 않았다
끝난 뒤 키 입력도 새 출력도 없이 정해 둔 시간(기본 30분)이 지났습니다.
③ 지금 보고 있지 않다
그 터미널이 지금 열어 둔 워크트리나 화면에 띄운 워크트리에 있지 않습니다.
실제로는 이 셋 말고도 몇 가지 조건(아래 접힌 전체 목록)이 모두 맞아야 잠들고, 하나라도 어긋나면 계속 돕니다. 한 워크트리에 에이전트 패널이 여러 개면 한 덩어리로 함께 잠들어, 반쯤만 멈춘 워크트리는 생기지 않습니다.
휴면 조건 전체 목록 (모두 참이어야 함)
- 에이전트가 done 상태 — 마지막 턴을 끝냈고 입력을 기다리지 않음
- 터미널이 활성 워크트리에도, 지금 앞에 터미널을 그리고 있는 워크트리에도 없음
- 에이전트가 끝난 뒤 키 입력을 받지 않았음
- 재개 가능한 세션을 가진 에이전트: Claude, Codex, Gemini, Antigravity, OpenCode, Pi, MiMo Code, Droid, Grok, Devin, OMP
- 설정한 대기 시간(기본 30분) 이상 쉬었음
- 모바일 세션이 그 터미널을 조종하고 있지 않음
- 끝나지 않은 오케스트레이션 Dispatch(pending, dispatched, unknown)가 없음 — 실행 환경이 completed, failed, circuit_broken을 확인하면 다시 잘 수 있음
- 패널에 살아 있는 서브에이전트·팀원 명단이 남아 있지 않음(자식이 붙어 있으면 공급자의 “done”만으로는 부족)
대기 시간 조절 (Hibernate after)
- 위치: Agent hibernation 토글 아래
- 기본 30분, 범위 1분 ~ 24시간
- 에이전트가 일을 마친 시각(마지막 done 갱신)부터 시계가 돌고, 키 입력·새 출력·그 탭으로 돌아오기가 시계를 되돌립니다.
- 길게 잡으면 덜 멈추지만 메모리 절약이 줄고, 짧게 잡으면 적극적으로 멈추지만 다시 돌아올 때 재개 비용이 듭니다.
수동 재우기 · 찾기
- 사이드바에서 워크트리를 직접 재울 수 있습니다(중첩 자식이 있으면 Sleep with Descendants). 수동 잠은 끝났거나 중단된 재개 가능 세션 기록을 지우지 않아, 다시 열면 같은 재개 옵션으로 실행됩니다.
- 사이드바 필터 메뉴에서 잠든 워크트리를 보일지 정합니다. 자주 숨긴다면 Settings → Shortcuts에서 Toggle Sleeping Workspaces에 단축키를 지정하세요.
재개와 한계
- 잠든 워크트리를 열면 Agent Session History와 같은 재개 옵션(
claude --resume <id>,codex resume <id>등)으로 다시 실행되어 대화·작업 폴더·공급자 세션이 이어집니다. 누를 것은 없습니다 — 터미널을 앞으로 가져오는 과정에서 자동으로 일어납니다. - 처음 열 때 기록해 둔 실행 명령·인수·개인 환경 변수를 다시 씁니다.
- 기록이 지워졌거나 공급자가 세션 ID를 바꾸는 등으로 재개할 수 없으면, 새 프롬프트로 열리고 이전 기록은 세션 기록에 남습니다.
- 목록의 재개 가능 에이전트만 잠듭니다. Cursor CLI, Hermes, Copilot, Trae 등 재개할 수 없는 터미널은 계속 돕니다.
에이전트 훅과 메모리
CLAUDE.md, AGENTS.md)은 에이전트가 매번 시작할 때 읽는 “이 프로젝트 사용 설명서”입니다.Orca는 Claude Code와 Codex가 이미 쓰는 훅·메모리 규칙을 그대로 읽고 따릅니다. 그중 Orca 안에서 다룰 만한 것은 설정 화면, 파일 탐색기, 탭의 상태 점처럼 눈에 보이는 곳에 꺼내 줍니다.
저장소별 훅
각 저장소의 .claude/, .codex/ 설정을 읽습니다. 이미 있는 훅은 Orca가 그 저장소의 워크트리에서 에이전트를 실행할 때 그대로 돕니다.
워크트리 준비 훅
새 워크트리를 만든 직후 자동으로 돌 명령을 정해 둡니다. 새 작업 폴더에서 매번 손으로 하던 준비 작업을 대신 해 주는 것입니다. 예: pnpm install(프로젝트에 필요한 부품(라이브러리)을 내려받아 설치), direnv allow(그 폴더 전용 설정값을 쓰도록 허락), .env 복원 스크립트(비밀번호·키 같은 설정을 담은 파일을 다시 가져다 놓기). Settings → Repository → Hooks에서 정합니다.
메모리 파일
Claude의 CLAUDE.md, Codex의 AGENTS.md(저장소 루트 또는 하위 폴더)는 에이전트의 것이라 Orca가 손대지 않습니다. 파일 탐색기에 다른 파일처럼 보여 바로 편집할 수 있습니다.
에이전트 상태 훅 (Agent status hooks)
Settings → Agents → Agent status hooks는 작업 중(working)·대기(waiting)·완료(done)를 화면에 알려 주는 Orca 관리 훅을 다룹니다. 탭과 사이드바의 상태 점이 바로 이 훅 덕분에 뜹니다. 끄면 관리 훅을 지우고, 다시 켜면 Orca를 재시작하지 않고 복구합니다.
상태 훅 내부 동작 — CLI 명령, Codex 승인, endpoint 파일
- 끄면 관리 훅을 지우고 다시 설치하지 않습니다. 다시 켜면 Orca를 재시작하지 않고 복구합니다(Windows의 WSL 훅 중계도 같은 스위치를 따름).
- CLI로는
orca agent hooks status|on|off --json. - Codex 훅은 바뀐 것이 있을 때만
~/.codex에 써서, Codex가 매번 승인을 다시 묻지 않습니다.
{userData}/agent-hooks/endpoint.env, Windows에선 endpoint.cmd에 저장되고 훅이 불릴 때마다 다시 읽힙니다.Orca CLI는 에이전트가 스스로 갱신할 수 있는 워크트리 상태(주석) 필드도 제공합니다(Worktree checkpoints 문서).
사용량과 한도 추적 (Usage & rate-limit tracking)
AI 모델은 보통 “5시간에 얼마, 일주일에 얼마”처럼 쓸 수 있는 양(rate limit, 사용 한도(정해진 시간 동안 쓸 수 있는 AI 사용량의 상한))이 정해져 있습니다. Orca는 Claude Code, Codex, Muse Code, Gemini, Antigravity, OpenCode, Kimi Code, MiniMax, Cursor, ZCode, GLM Coding Plan의 사용량을 상태 표시줄에 보여 줘, 에이전트가 멈추기 전에 한도에 얼마나 가까운지 알게 합니다.
↑ 화면 흉내(숫자는 예시). 가장 빠듯한 한도가 맨 위로 정렬되고, 80%를 넘으면 경고 칩이 뜹니다.
무엇이 보이나
- 활성 계정 플랜 대비 현재 사용량
- 5시간·하루·일주일·Claude Fable 주간 창의 리셋까지 남은 시간(해당될 때)
- 한도의 80%를 넘으면 경고 칩
- 공급자가 알려 주면 크레딧 잔액 — Claude usage credits, OpenCode Zen 잔액, Codex credits. 잔액을 주지 않는 공급자는 0이 아니라 “사용 불가”로 표시
여러 계정
상태 표시줄은 항상 활성 계정을 반영합니다. 다른 계정은 계정 전환기에서 각자의 사용량과 함께 보입니다.
Usage 팝오버(사용량 명단)
- 상태 표시줄의 사용량 부분을 누르면 열립니다. 추적되는 모든 공급자를 (아이콘 · 이름 · 플랜 · 가장 빠른 리셋 · 창별 막대) 형태로, 가장 빠듯한 한도부터 보여 줍니다. 머리글의 새로고침으로 로컬 사용량을 다시 읽습니다.
- Detailed: 모든 창의 막대·이름표·퍼센트 / Compact: 공급자마다 가장 빠듯한 창만
- Settings → Appearance에서 % used(쓴 비율)와 % remaining(남은 비율) 중 고릅니다.
- 숫자가 없는 행은 Loading usage…, not signed in, Usage unavailable, No usage data, 또는 공급자별 오류를 보여 줍니다.
- Claude·Codex 행에서 계정 전환으로 들어갈 수 있고, Manage accounts는 Settings를 엽니다.
좁은 창에서 상태 표시줄이 줄어드는 방식
상태 표시줄을 한 줄로 유지하려고 작은 막대와 이름표를 숨기고 공급자마다 퍼센트 하나만 보입니다. 그래도 좁으면 일부 공급자 칩이 +N 칩으로 묶이고, 누르면 Usage 팝오버에서 전부 봅니다. 80% 이상인 공급자는 가장 늦게 묶입니다. 잔액이 있으면 그 공급자 한도 옆에 보이고, 좁은 Compact 칸에서는 플랜 상한에 닿은 공급자의 쓸 수 있는 잔액이 드러납니다.
숫자는 가능하면 내 컴퓨터에 있는 에이전트 상태를 읽어 가져옵니다. 공급자에 따라 Settings → Accounts에서 따로 계정 연결이 필요할 수 있습니다.
공급자별로 숫자를 가져오는 방법 (OpenCode Go 쿠키, Cursor, GLM 키 등)
| 공급자 | 방법과 주의 |
|---|---|
| 공통 | 가능하면 로컬 에이전트 상태를 읽습니다. 공급자에 따라 Settings에서 따로 계정 설정이 필요할 수 있습니다. |
| Muse Code | 로컬 세션 로그로 토큰을 직접 셉니다. 가격 추정은 없습니다. |
| OpenCode Go | 콘솔 API에서 가져오며, Settings → Accounts에 __Host-console_session을 포함한 opencode.ai의 전체 Cookie 헤더가 필요합니다. 인증 쿠키만으로는 작업 공간은 찾아도 Go 사용량은 못 가져옵니다. |
| Cursor | 컴퓨터의 기존 Cursor 로그인을 읽어 월간 사용량을 상태 표시줄, Usage 팝오버, Settings → Accounts → Cursor에 보여 줍니다. 로그인시켜 주지는 않으니 저장된 세션이 만료되면 cursor-agent login을 실행하세요. 요청이 거부되면 로그인 만료가 아니라 사용량 실패로 표시됩니다. |
| Antigravity | Antigravity 자체 CLI에서 모델 그룹 풀까지 포함한 할당량을 읽습니다. 로그인된 Gemini CLI가 필요 없고, 확인해도 할당량이 줄지 않습니다. |
| ZCode | 디스크 기록에서 읽는 세션 기록과 함께 Coding Plan 할당량이 보입니다. |
| GLM Coding Plan | Settings → Accounts → GLM Coding Plan에서 플랜 사이트(Z.AI 또는 Zhipu BigModel)를 고르고 플랜 API 키를 저장해 직접 연결합니다. ZCode CLI 로그인이 필요 없고, 저장한 키가 ZCode CLI 로그인보다 우선합니다. 명단에 다른 공급자처럼 나옵니다. |
모바일
동반 앱에서 호스트의 Accounts 화면을 열면 같은 전환기·사용량이 보입니다. Codex가 한도 리셋 크레딧을 얻었으면 그 화면에서 하나를 쓸 수 있습니다(Mobile companion 문서).
예상 비용 (Stats)
Stats 화면은 모델별 예상 비용을 보여 줄 수 있습니다. 실제 청구 금액이 아니니 정확한 지출은 공급자 콘솔을 보세요.
예상 비용 계산 방식
Stats 분석은 알려진 모델 계열(Claude Opus 5.5, Fable 5.1, Codex GPT-5.6, GPT-6 Astra·Sol·Luna 등)의 예상 비용을 보여 줄 수 있습니다. 공급자의 실제 청구가 아니라 로컬 가격표로 계산합니다. • inferred pricing은 Orca가 모델을 추정한 값, Codex의 • excludes unpriced models는 가격 없는 모델을 뺀 값이며 Overview도 부분 합계임을 표시합니다. 정확한 지출은 공급자 콘솔을 보세요.
터미널 — 기본기와 에이전트용 추가 기능
Orca의 터미널은 널리 쓰이는 코드 편집기 VS Code와 같은 터미널 부품에, AI 에이전트 작업에 맞춘 기능을 더한 것입니다. 다른 터미널 앱에서 쓰던 색·글꼴을 가져올 수도 있습니다.
터미널 부품과 Ghostty
VS Code가 쓰는 xterm.js 기반 터미널입니다. 첫 실행 때 Ghostty 테마·글꼴·커서를 가져올 수 있는 Ghostty 스타일 터미널이기도 합니다.
패널과 탭
- 터미널은 그냥 탭입니다(탭·패널·분할 레이아웃 장 참고). 터미널 패널을 나누면 셸 두 개가 나란히 생깁니다. 탭에 패널이 하나뿐이어도 닫기 버튼이 있습니다.
- 에이전트 터미널 탭에는 에이전트 정체와 실시간 상태가 보입니다: 작업 중(working), 입력 대기(waiting for input), 완료(completed), 완료됐지만 안 읽음(completed-but-unread).
탭 제목과 패널 되살리기 규칙
- Claude·Codex는 Orca가 패널을 세션과 연결할 수 있으면 탭 제목에 AI Vault 대화 이름(사용자 제목·스레드 이름)이 보입니다. 직접 바꾼 이름이 항상 우선합니다.
- 백그라운드로 보낸 터미널은 돌아올 때 중복 탭을 열지 않고 자기 탭에 다시 붙습니다. 종료 직전에 닫은 패널은 다시 켤 때 되살아나지 않고, 패널을 끌어 따로 탭으로 빼도 두 탭에 동시에 보이지 않습니다.
긴 에이전트 실행 명령 전달 방식 (macOS·Linux)
에이전트 실행 명령
macOS·Linux에서 길거나 여러 줄인 에이전트 실행 명령이 잘리거나 한 줄씩 따로 실행되지 않고 통째로 전달되며, 시작 명령은 진짜 Enter로 제출됩니다. 업데이트 후 연 터미널부터 적용되고, 이미 열린 터미널은 다시 열 때까지 예전 방식입니다.
- 찾기: Cmd+F / Ctrl+F로 위로 지나간 출력 안에서 글자를 찾고, Esc로 닫습니다.
- 링크: 터미널 속 링크를 그냥 누르면 바로 열리지 않고 “어디서 열지” 고르는 작은 메뉴(팝오버)가 뜹니다. 내 컴퓨터에서 띄운 웹 페이지 주소(예: localhost(‘이 컴퓨터 자신’을 가리키는 주소)로 시작하는 주소)는 Orca 안 브라우저로도 열 수 있습니다. Cmd/Ctrl-클릭은 바로 엽니다.
- 우클릭 메뉴: 최근 출력 복사(Copy Context), 세션 번호 복사(Copy Session ID), 꼬인 키 입력 풀기(Reset Terminal).
- 끌어다 놓기: 파일을 터미널에 놓으면 그 파일 경로가 입력됩니다.
찾기·링크 동작·복사·초기화 세부
찾기 (Search)
Cmd+F / Ctrl+F로 스크롤백(지나간 출력) 안에서 찾습니다. 찾기 막대는 현재 일치 위치와 전체 개수를 보여 주고, 대소문자·정규식·일치 이동을 지원합니다. Cmd+F / Ctrl+F를 다시 누르면 검색어에 초점을 주고 전체 선택하며, Esc로 닫습니다. 초점·닫기 동작은 편집기 검색 막대와 같습니다.
링크 동작 (Link actions)
- 터미널 링크(HTTP/OSC 8 URL, 파일 경로, 워크트리, 터미널, 작업 핸들)를 그냥 클릭하면 바로 이동하지 않고 작은 동작 팝오버가 열립니다.
- 로컬 웹 링크와, 자격 있는 SSH 워크트리나 기능이 확인된 짝지은 런타임의 링크는 Orca Browser와 System Browser를 고를 수 있고, 예전 런타임은 시스템 브라우저만 됩니다.
- 웹 링크에는 Copy link도 있어 숨은 OSC 8 목적지를 포함한 실제 URL을 팝오버를 닫지 않고 복사합니다(파일·워크트리 목적지는 그대로).
- Cmd-클릭(macOS) / Ctrl-클릭(Windows·Linux)은 여전히 바로 열고, Shift+Cmd / Shift+Ctrl-클릭은 대체 경로로 엽니다.
- Settings → Browser → Terminal URL clicks에서 URL을 그냥 클릭했을 때 동작 메뉴 열기 / 바로 열기 / 수정키 기다리기 중 고르고, 가운데 버튼 클릭 동작은 따로 정합니다.
- 미리 볼 수 있는 HTML 파일 링크는 로컬·SSH·짝지은 런타임 워크트리에서 Orca 안에 열리고, 원격 파일 행에는 Download & open with default app도 있습니다. 같은 파일이 형제 워크트리 탭에 이미 열려 있으면 중복으로 열지 않고 그 탭을 활성화합니다(HTML viewers 문서).
- 팝오버는 Settings → Browser → Show terminal link actions에서 끌 수 있고, 끄면 링크를 열 때 수정키+클릭이 필요합니다.
복사·초기화·끌어다 놓기
- Copy Context(터미널 우클릭): 그 패널의 최근 기록을 분량 제한 있게 복사합니다. Orca fork를 시작하지 않고 에이전트 출력을 다른 도구에 붙여 넣을 때 씁니다.
- Copy Session ID(터미널 탭 우클릭): 스크립트·지원 요청·다른 도구용 세션 식별자를 복사합니다.
- Reset Terminal(터미널 우클릭): 죽은 프로그램이 키보드·마우스 모드를 꼬아 놓았을 때, 셸을 재시작하지 않고 호스트와 패널의 남은 입력 모드를 지웁니다. Shift+Enter나 수정키가 앱에 안 닿을 때 유용합니다. Orca는 프로그램이 죽었다고 “짐작”만으로 모드를 끄지 않으므로, 살아 있는 프로그램은 Ctrl+C 뒤에도 키보드 모드를 유지합니다. SSH 터미널도 로컬처럼 정리합니다.
- 파일·스크린샷 끌어다 놓기: 파일을 터미널에 놓으면 프롬프트에 경로가 붙습니다. macOS 스크린샷 썸네일은 로컬 Claude Code 터미널이나 새 워크트리 작성창에 놓을 수 있고, Orca가 임시 이미지의 읽을 수 있는 사본을 에이전트에 줘서 실제로 열 수 있게 합니다. 건너뛴 파일이 있으면 이유를 알려 줍니다.
- TUI 클립보드(OSC 52): Zellij, tmux, Neovim, fzf, Grok 같은 TUI는 OS 클립보드 대신 OSC 52로 복사합니다. Orca는 기본으로 이를 허용해 SSH에서도 로컬처럼 복사됩니다. 스위치: Settings → Terminal → Allow TUI Clipboard Writes (OSC 52).
Settings → Terminal에서 색 테마와 글자 대비를 고릅니다. 다른 터미널 앱(Ghostty, Warp)을 쓰던 사람은 그 앱의 색 테마를 가져올 수 있습니다.
테마·색 대비·Ghostty·Warp 가져오기 세부
- 테마: Settings → Terminal에서 색 테마를 고릅니다. 인기 테마 묶음이 들어 있고 무엇이든 고쳐 쓸 수 있습니다. Ghostty 색을 가져왔더라도 Orca에서 테마를 고르면 그 테마 색이 적용되며, Ghostty 설정을 지울 필요는 없습니다.
- 색 대비: Settings → Terminal → Rendering → Color Contrast에서 Automatic(Orca가 글자를 읽기 좋게 유지), Off(테마의 흐린 색·Powerline 색 그대로), Custom(대비 목표 1~21 지정).
- Ghostty 가져오기: Ghostty 사용자라면 첫 실행 때 테마·글꼴·커서 설정을 가져올 수 있고, 나중에 Settings → Terminal → Import from Ghostty로 다시 실행합니다.
- Warp 테마 가져오기: Settings → Terminal의 테마 선택기에서 Import themes from Warp를 누르면 OS별 Warp 테마 폴더(macOS
~/.warp/themes, Linux$XDG_DATA_HOME/warp-terminal/themes, Windows%APPDATA%\warp\Warp\data\themes)를 훑어 가져올 YAML 테마를 고르게 합니다. 옆의 Import from YAML은 같은 선택기를 아무 폴더의 Warp 형식.yaml/.yml파일로 향하게 합니다. 가져온 테마는 기본 테마와 함께 목록에 나옵니다.
새 터미널 탭이 어떤 셸로 열릴지 Settings → Terminal에서 고릅니다. 비워 두면 컴퓨터의 기본값을 씁니다. Windows에서는 PowerShell, Command Prompt, WSL 중에서 고를 수 있습니다.
기본 셸 세부 — 셸 인수, 시작 파일을 읽는 순서, WSL
Settings → Terminal에서 새 로컬 터미널 탭의 기본 셸을 고릅니다. 비워 두면 시스템 기본값입니다. Windows에서는 PowerShell, Command Prompt, WSL을 고를 수 있고, WSL은 wsl.exe --status가 성공하면 자동으로 나옵니다. 이 설정은 새 로컬 패널에만 적용되고 기존 패널·SSH 셸은 그대로입니다. 탭 막대의 + 드롭다운 하위 메뉴로 기본값을 바꾸지 않고 다른 셸 탭을 한 번만 열 수 있습니다.
Unix 사용자 지정 기본 셸은 Advanced → Shell arguments에서 인수를 정합니다. 기본 -l(로그인 셸)을 두거나, Custom args로 한 줄에 인수 하나씩 넣습니다(예: --rcfile과 그 경로를 따로 두 줄). 목록을 비우면 인수 없이 실행합니다.
$SHELL)을 로그인 셸(-l)로 엽니다.- bash는
~/.bashrc를 스스로 읽지 않습니다. PATH나 버전 관리자(nvm, asdf, mise) 설정이~/.bashrc에 있다면, bash가 읽는 로그인 파일에서~/.bashrc를 불러오세요(대부분 배포판의 기본~/.profile이 이미 그렇게 합니다). - Orca의 bash 통합 래퍼(wrapper)를 쓸 때는
-l대신--rcfile로 bash를 시작하고, 래퍼가 같은 로그인 파일을 읽되~/.bashrc를 따로 읽지는 않습니다. - 사용자 지정 셸에서는 입력한 인수가 일반 로컬 패널의 기본
-l을 대신합니다. 빈 목록이면 인수가 없으므로, 래퍼 없는 대화형 bash는 로그인 파일 대신~/.bashrc를 읽습니다. - 터미널 데몬을 쓸 수 없을 때는 Orca의 bash·zsh 통합이 사용자 인수를 무시하고 로그인 시작을 유지할 수 있습니다. 에이전트 실행, 시작 명령, 한 번만 고른 셸은 이 인수 설정을 쓰지 않습니다.
- WSL 파일 시스템(
\\wsl.localhost\...)의 저장소는wsl.exe -d <distro>로 실행합니다. WSL에서 연 Windows 경로 저장소는 작업 폴더를/mnt/<drive>/...로 바꾸고 로그인 bash로 들어갑니다. 관리되는 WSL 터미널에는 Orca CLI가 자동으로 제공됩니다.
원문에 macOS 키만 나온 항목은 “(macOS)”로 표시했습니다.
| 단축키 | 동작 |
|---|---|
| Cmd+T (macOS) | 현재 워크트리에 새 터미널 탭 |
| Cmd+Alt+T (macOS) | 기본 에이전트로 새 에이전트 탭. Linux·Windows에서는 기본으로 비어 있으니 Settings → Shortcuts에서 “New agent tab”을 검색해 지정. 지원 에이전트마다 따로 “New agent tab” 동작이 있어 특정 CLI를 바로 띄우는 단축키를 걸 수 있음 |
| Cmd+W (macOS) | 현재 탭 닫기 |
| Cmd+\ (macOS) | 오른쪽으로 분할 |
| Cmd+Shift+\ (macOS) | 아래로 분할 |
| Cmd+F / Ctrl+F | 지나간 출력에서 찾기 |
| Cmd+Option+A(macOS) / Ctrl+Alt+A(Windows·Linux) | 플로팅 터미널 토글(아래 참고) |
Shift+Enter 같은 조합키도 다른 터미널 앱과 똑같이 에이전트에 전달됩니다.
네이티브 키 입력 (kitty 키보드 프로토콜, JIS 키보드)
네이티브 키 입력
Orca는 kitty 키보드 프로토콜(조합키 입력을 정확히 전달하는 터미널 규약)을 알리므로, 터미널 앱이 진짜 Shift+Enter, Ctrl+Enter 같은 수정키 입력을 받습니다. Ghostty, WezTerm, 원래 터미널과 똑같이 동작합니다. macOS에서는 기본 Auto 모드로 ABC 키보드의 Option/Alt 단축키가 터미널 앱에 닿습니다.
macOS 일본어 JIS 키보드라면 Settings → Terminal → JIS Yen (¥) to Backslash (\)를 켜서 ¥ 키가 터미널에서 백슬래시를 보내게 할 수 있습니다.
플로팅 터미널과 Quick Commands
플로팅 터미널 (Floating terminal)
어느 워크트리·탭에 있든 단축키 한 번이면 화면 위에 떠오르는 공용 터미널 창입니다. 새로 설치하면 기본으로 켜져 있습니다.
- Cmd+Option+A(macOS) / Ctrl+Alt+A(Linux·Windows)로 토글합니다. 이미 열려 있으면 초점을 주고, 이미 초점이 있으면 닫습니다.
- 창 가장자리의 떠 있는 버튼을 누르거나, Settings → Terminal → Floating terminal에서 그 버튼을 상태 표시줄로 옮깁니다.
- 같은 설정에서 시작 작업 폴더를 정합니다(기본
~). - 자기 탭을 따로 가집니다.
플로팅 터미널과 오케스트레이션
오케스트레이션(여러 에이전트에게 일을 나눠 맡기고 진행을 관리하는 기능) 설정도 지원해, 워크트리 패널을 차지하지 않고 백그라운드 실행을 시작할 수 있습니다.
Quick Commands — 자주 쓰는 명령 저장
자주 쓰는 글을 저장해 두고 버튼 한 번으로 다시 쓰는 기능입니다. 예를 들어 “이 변경 사항을 리뷰해 줘” 같은 부탁 문장을 Claude·Codex처럼 실행할 때 프롬프트(지시문)를 받는 에이전트용 재사용 프롬프트로 저장해 두면 매번 다시 쓸 필요가 없습니다. 개발자라면 npm run dev, pnpm test, 프로젝트 준비 스크립트처럼 자주 실행하는 터미널 명령도 저장합니다.
- 만들기Settings → Quick Commands 또는 탭 막대의 Add command 버튼에서 만듭니다. 각 명령은 이름(label), 명령 글(command text), 범위(scope)를 가집니다. 범위는 어디서나 보이는 Global, 특정 저장소 워크트리에서만 보이는 Project.
- 실행하기워크트리 탭 막대의 Quick Commands 분할 버튼은 새 터미널 탭을 열어 실행하고, 터미널 우클릭 메뉴는 현재 터미널에 명령을 끼워 넣습니다.
- 복사하기명령 행(Settings 목록, 탭 막대 메뉴, 모바일 Quick Commands)의 복사 버튼으로 명령 본문을 클립보드에 넣습니다.
↑ 화면 흉내(이름은 예시). 누르면 새 터미널 탭에서 그 명령이 실행됩니다.
원격 서버와 함께 쓸 때
짝지은 Remote Orca Server(또는 다른 실행 호스트)와 일하면, 선택기가 로컬과 원격 묶음을 호스트 이름표(예: Local Mac, Orca Server)와 함께 나란히 보여 줍니다. Saved on은 명령이 저장된 곳이고, 실행은 여전히 명령을 부른 터미널·워크트리에서 일어납니다 — 그래서 클라이언트에 저장된 명령도 원격 워크트리 안에서 돌릴 수 있습니다. 여러 호스트 Quick Commands를 알리지 않는 예전 서버는 로컬 목록만 보입니다.
- 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로 자주 쓰는 명령·부탁 문장을 저장합니다.
출처: onorca.dev/docs/agents/supported · onorca.dev/docs/agents/claude-code · onorca.dev/docs/agents/codex · onorca.dev/docs/agents/codex-hot-swap · onorca.dev/docs/agents/cursor-cli · onorca.dev/docs/agents/glm-agent · onorca.dev/docs/agents/native-chat · onorca.dev/docs/agents/session-history · onorca.dev/docs/agents/hibernation · onorca.dev/docs/agents/hooks-memory · onorca.dev/docs/agents/usage-tracking · onorca.dev/docs/terminal
워크트리별 내장 브라우저와 디자인 모드
Orca에는 워크트리마다 따로 쓰는 진짜 Chromium 브라우저가 들어 있습니다. 사람은 이 브라우저로 만든 화면을 확인하고, 에이전트는 글자 명령(CLI)으로 같은 브라우저를 조작합니다. 디자인 모드를 켜면 화면의 요소를 클릭하는 것만으로 “이걸 고쳐 줘”를 에이전트에게 전할 수 있습니다.
- 내장 브라우저의 조작법과 단축키, 워크트리별로 탭이 나뉘는 방식
- 쿠키 가져오기, Google 로그인 주의점, 브라우저 프로필(Profiles)로 신원 분리하기
- 작업 폴더가 다른 컴퓨터에 있을 때: 화면은 내 PC에서 그리고, 인터넷 통신은 그 컴퓨터를 거쳐 가는 구조
- 링크를 어느 브라우저로 열지 정하기, Chrome 확장, 다운로드, 아티팩트 공유, 휴대폰 화면 크기 흉내
- 디자인 모드: 요소 클릭 → 에이전트 채팅 → 수정 → 화면 자동 새로 고침의 순환, 그리고 UI 버그 고치기 레시피
- 에이전트가 화면 요소에 번호표를 붙이고 그 번호로 누르는 원리
- 워크트리마다 하나씩 있는 브라우저 — 이 브라우저가 무엇인지
- 화면 구성과 조작법 — 평소 브라우저와 같은 점·다른 점
- 디자인 모드(Design Mode) — 화면을 클릭해 에이전트에게 “여기 고쳐 줘”라고 맡기는 법
- 레시피: 디자인 모드로 UI 버그 고치기 — 위 기능을 실제로 쓰는 순서
원격 컴퓨터에서 작업하지 않는다면 「원격 워크트리」 절은 건너뛰어도 됩니다. 「🔧 개발자용 참고」로 접힌 부분(명령 목록·오류 이름 등)도 처음엔 펼치지 않아도 됩니다.
워크트리마다 하나씩 있는 브라우저
이 브라우저는 흉내만 낸 미리보기 창이 아니라 진짜 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 미리보기와 브라우저 탭의 전환, 페이지에 포커스가 있을 때의 단축키 동작은 아래 접힌 상자에 있습니다.
새 창 규칙·미리보기 전환·포커스
- 링크와 스크립트가 연 새 창(
window.open)은 Chrome과 같은 규칙을 따릅니다. Chrome이라면 새 탭으로 열렸을 링크나, 페이지의 스크립트(웹 페이지 안에서 돌아가는 작은 프로그램)가 연 탭은 Orca의 새 탭으로 열리고, 그 탭은 원래 탭의 브라우저 프로필을 그대로 씁니다. 이름이 붙은 팝업이나 OAuth(“Google로 로그인”처럼 다른 서비스 계정으로 로그인하는 방식) 팝업은 별도 창으로 열릴 수도 있습니다. - HTML 미리보기는 주소창에 문서 경로를 보여 줍니다. 여기에 웹 주소를 입력하면 그 자리에서 브라우저 탭으로 바뀌고, 반대로 브라우저 탭에 워크트리 안 HTML 파일 경로를 입력하면 다시 미리보기로 바뀝니다. 사이에 다른 방문 기록이 없으면 뒤로 버튼으로 이 전환도 되돌릴 수 있습니다.
- 페이지에 포커스가 있어도 Orca 단축키, 분할 화면 포커스 이동, 마우스의 뒤로/앞으로 버튼은 그대로 작동합니다.
워크트리별 분리(Worktree scoping)
탭은 워크트리별로 걸러져 보입니다. 다른 워크트리로 옮기면 그 워크트리의 브라우저 탭과 스크롤 위치까지 복원됩니다. 탭은 세션(로그인 상태 등)을 유지하며, 쿠키는 버튼 한 번으로 Chrome이나 Edge에서 가져올 수 있습니다(다음 절 참고).
쿠키 가져오기와 Google 로그인
- 어디서: Chrome, Edge, Vivaldi에서, 또는 쿠키 파일에서 가져올 수 있습니다.
- 어떻게: Settings(설정)나 브라우저 툴바에서 원하는 프로필(아래 「브라우저 프로필」 절 — 쿠키를 따로 보관하는 신원 묶음)로 가져옵니다.
- 무엇이 바뀌나: 가져온 파일에 들어 있는 도메인(사이트 주소. 예: example.com)의 쿠키만 교체합니다. 같은 프로필에 있던 관계없는 사이트의 로그인은 그대로 남습니다.
USB 보안 키로 로그인하는 사이트에서 키에 계정이 여러 개 있으면, Orca가 계정을 고르는 창을 띄워 줍니다.
USB 보안 키 패스키 세부
원격 워크트리에서 화면 그리기
회사 서버 등 원격 컴퓨터에서 작업하지 않으면 이 절은 건너뛰세요.
왜 필요할까? 작업 폴더가 내 PC가 아니라 다른 컴퓨터(예: 회사 서버)에 있을 때가 있습니다. Orca에서는 이런 작업 공간을 Workspace(워크스페이스 — 워크트리와 같은 것)라고도 부르는데, 이 장에서는 “원격 워크트리”라고 하겠습니다. 이럴 때도 브라우저를 쓸 수 있고, 연결 방식은 두 가지입니다.
- Remote Orca Server(Orca 원격 서버)와 짝지은(paired) 원격 워크트리 — 다른 컴퓨터에 Orca 서버를 띄워 내 Orca와 짝지은 경우
- SSH(다른 컴퓨터에 안전하게 접속해 명령을 실행하는 방법) 원격 워크트리
짝지은 원격 서버에서는 기본적으로 화면은 내 PC에서 그리고, 웹사이트와 주고받는 인터넷 통신은 원격 컴퓨터를 거쳐 나갑니다. 그래서 키보드 입력·글자 선택·팝업은 내 PC에서 자연스럽게 동작하면서도, 웹사이트 입장에서는 원격 컴퓨터에서 접속한 것으로 보입니다. 브라우저 툴바의 호스트 표시(통신이 어느 컴퓨터를 거쳐 가는지 보여 주는 표시)로 확인할 수 있습니다.
“인터넷 통신”에 들어가는 것
원격 호스트를 거쳐 나가는 통신은 HTTP(S)(웹 페이지 요청), WebSocket(실시간 연결), DNS(주소를 찾는 일), 루프백(자기 자신 컴퓨터를 가리키는 주소. 예: localhost, 127.0.0.1) 통신입니다. 입력·선택·팝업은 이 기기에서 처리되면서도 페이지의 네트워크 신원(어디서 접속했는지)은 바뀌지 않습니다.
Settings → Browser → Remote server workspaces(설정 → 브라우저 → 원격 서버 워크트리)에서 This device(이 기기)를 고르면 위 그림처럼 동작합니다(기본값). 입력·선택·팝업이 이 기기에서 자연스럽게 처리됩니다.
다만 이렇게 내 PC에서 그리는 페이지는 내 PC가 켜져 있어야 합니다. 에이전트가 이 페이지를 조작하는데 PC가 꺼지거나 잠들거나 연결이 끊기면 오류가 납니다.
오류 이름
이렇게 그려지는 페이지를 “client-hosted” 페이지라고 합니다. 짝지은 데스크톱이 꺼져 있거나 잠들었거나 연결이 끊기면 browser_host_unavailable 오류가 납니다.
같은 설정에서 Server (streamed)(서버, 스트리밍)를 고르면 페이지가 원격 서버에서 실행되고 화면만 내 PC로 전송됩니다. 내 PC가 연결되어 있지 않아도 돌아가므로, 오래 걸리거나 사람이 지켜보지 않는 자동화에 더 알맞습니다.
SSH 원격 워크트리에서는 Browse through SSH workspace hosts(SSH로 접속한 컴퓨터를 거쳐 탐색) 설정이 브라우저의 인터넷 통신(주소 찾기 포함)을 SSH로 접속한 컴퓨터로 보낼지, 이 기기에서 직접 보낼지를 정합니다.
내 PC에서 그리는 원격 페이지에서 받은 다운로드는 원격 컴퓨터에 저장되고, 업로드할 파일도 먼저 그 컴퓨터에 옮겨 놓은 뒤 페이지에 전달됩니다.
링크 라우팅(Link routing) — 링크를 어느 브라우저로 열까
터미널(글자로 명령을 입력하는 창), 마크다운 문서, 편집기에서 http(s) 링크를 눌렀을 때 Orca의 워크트리별 브라우저로 열지, 운영체제의 기본 브라우저(system browser)로 열지를 Settings → Browser → Link Routing(설정 → 브라우저 → 링크 라우팅)에서 정합니다.
그 아래 Hold Shift… 토글을 켜면, 보조키를 누른 채 클릭할 때 이번 한 번만 반대쪽 브라우저로 엽니다. 보조키는 macOS에서 ⇧⌘+클릭, Windows/Linux에서 Shift+Ctrl+클릭입니다.
| 클릭 방법 | 열리는 곳 |
|---|---|
| 그냥 클릭 | Orca 내장 브라우저 |
| 보조키+클릭 | 이번 한 번만 시스템 브라우저 |
| 클릭 방법 | 열리는 곳 |
|---|---|
| 그냥 클릭 | 시스템 브라우저(그대로) |
| 보조키+클릭 (Hold Shift… 토글을 켰을 때) | 이번 한 번만 Orca 내장 브라우저 |
원격 워크트리의 터미널 링크도 대개 같은 선택을 쓸 수 있지만, 오래된 버전과 연결된 경우에는 시스템 브라우저로만 열립니다.
원격 터미널 링크의 조건
이 기능을 지원하는지 확인된(capability-verified) 짝지은 런타임(원격 컴퓨터에서 돌아가며 내 Orca와 짝지어진 Orca 실행 프로그램)이나 조건에 맞는 SSH 원격 워크트리는 그 터미널 링크에도 같은 Orca/시스템 브라우저 선택을 제공합니다. 오래된 런타임에서 온 링크는 시스템 브라우저로만 열립니다. 자세한 내용은 Terminal → Link actions 문서를 보세요.
Chrome 확장 실험 기능
Chrome 확장(브라우저에 기능을 덧붙이는 작은 추가 프로그램. 예: 광고 차단기)을 Orca 브라우저에도 설치할 수 있습니다. 아직 실험 기능이라 먼저 켜야 합니다.
- 실험 기능 켜기Settings → Experimental → Browser extensions(설정 → 실험 기능 → 브라우저 확장)를 켜고 Orca를 다시 시작합니다.
- 웹 스토어 열기Orca 브라우저 탭에서 Chrome Web Store를 엽니다.
- 설치확장 페이지에서 Add to Orca(Orca에 추가)를 누릅니다.
다운로드
브라우저에서 받는 파일은 진행 중이거나 막 끝난 동안 툴바 아래 다운로드 선반(shelf)에 표시됩니다. 각 줄에서 할 수 있는 일은 다음과 같습니다.
취소
진행 중인 다운로드 중단
열기
받은 파일 열기
폴더에서 보기
파일이 있는 폴더 열기
닫기(dismiss)
선반에서 그 줄 치우기
원격 페이지에서 받은 파일이 어디에 저장되는지는 위 「원격 워크트리」 절의 SSH 탭을 참고하세요.
아티팩트로 공유(Share as artifact)
워크트리 브라우저로 연 내 컴퓨터의 HTML 파일(웹 페이지 파일)은 툴바의 Share as artifact(아티팩트로 공유)를 눌러, 로그인한 Orca 계정으로 누구나 볼 수 있는 공개 링크를 만들 수 있습니다. 공유 기능을 처음 쓸 때의 사용 동의(opt-in) 절차와, 공유한 것을 관리하는 화면은 마크다운 문서 공유와 같습니다.
- 파일 하나당 10 MiB(약 10MB)까지만 공유됩니다.
- 같은 폴더의 사진 파일 등, HTML이 따로 불러 쓰는 파일은 함께 올라가지 않습니다. 모든 것이 한 파일에 들어 있는 HTML을 공유하세요.
상대 경로·절대 주소와 관련 문서
HTML이 상대 경로(./img/a.png 같은)로 부르는 파일은 업로드되지 않습니다. 모든 것이 한 파일에 들어 있는(self-contained) HTML을 쓰거나 절대 주소(https://…)로 자원을 불러오세요. 관련 설정과 명령은 Settings → Artifacts와 CLI reference → Artifacts 문서에 있습니다.
뷰포트 크기 흉내(Viewport-size emulation)
브라우저 탭에 원하는 뷰포트(웹 페이지가 보이는 화면 영역) 크기를 지정하면, 칸 크기는 그대로 둔 채 휴대폰·태블릿 같은 다른 화면에서 페이지가 어떻게 보이는지 시험할 수 있습니다(반응형 레이아웃(화면 크기에 따라 배치가 바뀌는 웹 디자인) 확인). 흉내 내는 동안 페이지는 진짜 휴대폰 화면인 줄 압니다 — 그래서 실제 휴대폰에서처럼 배치가 바뀝니다.
어떻게 속이나
Orca는 내부적으로 Chrome DevTools Protocol의 기기 흉내(device emulation)를 쓰기 때문에, 페이지도 window.innerWidth와 미디어 쿼리(@media 규칙)에서 흉내 낸 크기를 그대로 받습니다.
에이전트에게 맡길 때도 같은 흉내를 명령으로 켤 수 있습니다.
에이전트용 명령
orca set device --name "iPhone 15" 또는 orca viewport --width 390 --height 844 --scale 3 --mobile을 씁니다. 이렇게 해야 터치 입력과 pointer: coarse까지 함께 흉내 냅니다. 새로 고침, goto, 링크 클릭 등 페이지를 다시 불러올 때마다 초기화되므로 이동 후에는 다시 실행해야 합니다.브라우저 프로필(Browser-use profiles)
프로필은 브라우저를 특정 신원으로 돌리는 기능입니다. 로그인한 사용자, 특정 쿠키 묶음(cookie jar — 출입증 지갑), 직접 정한 user-agent(UA)(브라우저가 사이트에 “나는 어떤 브라우저입니다”라고 알리는 자기소개 문구)를 프로필마다 따로 가질 수 있습니다. 에이전트가 로그인해야 할 때, 특정 로그인 상태에서만 나는 버그를 다시 일으켜 볼 때, 여러 사용자를 흉내 낼 때 쓸모가 있습니다.
프로필 만들기
Settings → Browser → Profiles(설정 → 브라우저 → 프로필)를 엽니다.
Add profile(프로필 추가)을 누르고 이름을 붙입니다.
쿠키, user-agent, 뷰포트 크기를 미리 넣어 둘 수 있습니다.
Orca 기본 UA는 Chrome처럼 보이게 다듬은 자기소개입니다. 일부 Google 로그인처럼 이 값을 거부하는 사이트용으로는, 꾸미지 않고 Electron(Orca를 만든 바탕 기술) 원래의 UA를 쓰는 프로필을 만듭니다. 기본 프로필은 Cloudflare(많은 웹사이트가 쓰는 보안 서비스)를 쓰는 사이트에서도 잘 열리도록 Chrome처럼 다듬은 UA를 계속 씁니다.
명령으로 만들기
스크립트로 브라우저를 준비할 때는 CLI로도 만들 수 있습니다: orca tab profile create --no-ua-spoof
프로필 쓰기와 분리
브라우저 툴바에서 프로필을 고르면, 다른 것으로 바꿀 때까지 그 칸의 모든 탭이 그 프로필을 씁니다. 에이전트가 내리는 브라우저 명령도 현재 활성 프로필을 그대로 이어받습니다.
디자인 모드(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), 잘라 낸 이미지를 받습니다. 사람 검토자라도 받고 싶어 할 바로 그 정보입니다.
에이전트가 브라우저를 조작하는 원리
에이전트는 마우스를 쓰지 않습니다. 대신 먼저 페이지를 훑어 누를 수 있는 요소마다 번호표(@e1, @e2 …)를 붙이고, “@e3 눌러”처럼 그 번호로 누르거나 글자를 입력합니다. 사람이 보는 것과 같은 브라우저, 같은 탭이라서, 에이전트가 무엇을 하는지 화면에서 그대로 지켜볼 수 있습니다.
@e1 같은 이름표, ref)를 보고 “3번을 눌러”처럼 조작합니다.명령·규칙·오류 복구 (에이전트용 세부)
내장 브라우저는 에이전트가 Orca CLI(글자로 명령을 입력해 프로그램을 다루는 방식)로 조작합니다(orca snapshot, orca click, orca fill 등). 기본 요령은 “페이지 하나를 고정하고, 한 번 스냅숏을 찍고, 그다음 행동한다”입니다. 스냅숏은 위 그림의 “화면을 훑어 번호표 받기”에 해당합니다.
@e1 같은 이름표(ref)를 붙이고, 에이전트는 그 이름표로 클릭·입력합니다.orca tab current --json
orca goto --page <browserPageId> --url https://example.com --json
orca snapshot --page <browserPageId> --interactive
orca click --page <browserPageId> --element @e3 --json
| 방법 | 무엇을 주나 |
|---|---|
snapshot --interactive | 컨트롤과 링크만 ref와 함께. 전체 트리의 절반 이하인 경우가 많음. 단, 오류·상태 메시지 같은 페이지 글은 빠짐 |
--delta | 저렴한 두 번째 보기(예: 아무 행동 없이 wait 한 뒤). 지난 --delta 이후 바뀐 것만 — “no change”이거나 어느 줄을 무엇으로 바꿀지. 페이지마다 기준(baseline) 하나: 이동, 큰 변화, 다른 옵션의 --delta 호출이면 전체 트리를 다시 주고 기준을 교체 |
--full | 전체 트리를 받고 기준을 새로 시작 |
--selector <css> · --depth <n> · --compact · --urls | 한 영역만 / 깊이 제한 / 빈 구조 생략 / 링크 주소 추가 |
exec --command "read" 또는 옵션 없는 snapshot | 페이지 글 읽기(마크다운으로, 또는 글이 포함된 전체 트리) |
screenshot / full-screenshot | 보이는 화면 / 페이지 전체 PNG를 저장하고 경로 출력. 데스크톱 브라우저에서는 픽셀이 CSS 픽셀이라 그 x/y를 orca mouse에 그대로 쓸 수 있음. --annotate는 컨트롤마다 ref 라벨, --if-changed는 지난번과 같으면 저장 안 함 |
click, fill, type, keypress, select, check, hover, scroll, goto, back, reload, mouse 등 행동 명령은 페이지가 잠시 안정되기를 기다린 뒤 result.effects로 결과를 알려 줍니다.
url/title(바뀌었을 때),newTabs(새 탭과 그browserPageId), 막히거나 열린popups, 시작된downloads,consoleErrorspage:"unchanged", 또는 추가·교체된 스냅숏 줄과 ref(full: true면 새 페이지 전체)loading: true: 아직 이동 중 →wait --load load후snapshot.page가 없으면 읽지 못한 것 →snapshot.settled: false: 읽을 때 아직 바뀌는 중- JavaScript 대화상자를 연 행동은
browser_dialog_opened로 실패합니다.
다시 스냅숏할 때: page.truncated가 true일 때, wait 뒤, 탭 전환 뒤, browser_stale_ref가 났을 때, 결과에 effects가 없을 때(오래된 Orca 또는 서버 호스팅 페이지)만.
fill과 type의 차이: fill은 입력칸의 값 전체를 한 번에 넣습니다(길이 무관). type은 포커스된 요소에 실제 키를 누르듯 입력하므로 minlength/maxlength, 키 처리기, Enter·Tab이 사람이 칠 때처럼 동작합니다. 먼저 orca focus로 포커스를 주고, 페이지가 키 입력에 반응할 때 type을 씁니다. 서버 호스팅 페이지의 특수 입력칸에서 둘 다 안 되면 orca focus 후 orca inserttext --text "..."를 시도합니다.
자주 쓰는 명령 전체 목록
orca goto|back|reload --page <id> [--url <url>] --json
orca snapshot --page <id> --interactive [--delta]
orca snapshot --page <id> --selector main --depth 4
orca screenshot --page <id> [--annotate]
orca full-screenshot --page <id>
orca pdf --page <id> --json
orca click|check|hover|focus --page <id> --element <ref> --json
orca fill --page <id> --element <ref> --value <text> --json
orca type --page <id> --input <text> --json
orca select --page <id> --element <ref> --value <value> --json
orca scroll --page <id> --direction down --amount 1000 --json
orca keypress --page <id> --key Enter --json
orca upload --page <id> --element <ref> --files <paths> --json
orca wait --page <id> --text|--url|--selector|--load ... --json
orca eval --page <id> --expression <js> --json
orca dialog accept [--text <answer>] | dialog dismiss --page <id> --json
orca set device --page <id> --name "iPhone 15" --json
orca viewport --page <id> --width 390 --height 844 --scale 3 --mobile --json
orca tab list | tab create --url <url> [--split right] --json
orca tab switch|close --index <n> --json
orca cookie get | capture start | console --limit 50 | network --limit 50 --page <id> --json
orca exec --page <id> --command "read" | "get text @e3" --json
- ref(
@e1등)는snapshot이 붙이며, 한 탭 안에서만 유효하고 페이지 이동이나 탭 전환으로 무효가 됩니다. - 한 페이지에 작용하는 명령에는 항상
--page <browserPageId>를 붙입니다. ID는orca tab current --json의result.tab.browserPageId나orca tab create --json의result.browserPageId에서 얻어 작업 내내 씁니다.tab list,tab current,tab create,open-url은--page를 받지 않고,tab switch/tab close는--index나--page중 하나만(둘 다 주면--page우선).tab current는 고정한 탭이 아니라 지금 라우팅된 탭을 보여 줍니다. 사용자가 특정 탭을 말하면tab list --json에서 URL·제목으로 찾습니다. --page가 없으면 워크트리의 현재 탭으로 갑니다. 에이전트가 최근 약 20초 안에 명령을 냈다면 사용자가 다른 탭을 골라도 에이전트 탭이 유지되고, 그 뒤에는 사용자가 고른 탭으로 넘어갑니다.tab switch후에는 새 페이지의 ID를 씁니다.- 페이지가 연 팝업 창(로그인·결제 등)은
tab list에openerBrowserPageId가 붙은popup-<n>으로 나옵니다. 클릭이 아무 일도 안 한 것 같으면tab list를 보고--page popup-<n>으로 조작합니다. 닫히면 원래 페이지에서 계속합니다. - 브라우저 명령은 기본적으로 현재 워크트리 대상입니다.
--page는 다른 워크트리 페이지에도 닿지만--worktree <selector>를 함께 주면 그 범위로 제한됩니다.--worktree all은 의도할 때만. tab list는 탭 막대의 모든 탭을 보여 줍니다. 재시작 뒤 사용자가 열지 않은 탭은loaded: false이고,tab switch나--page명령을 쓰면 사용자 화면을 바꾸지 않고 뒤에서 로드됩니다.tab create --split <right|left|down|up>는 탭 대신 호출한 터미널 옆 새 칸에 열고, 포커스는 터미널에 남습니다.- 탭은
orca tab list/create/close/switch로, 기기 흉내는orca set device/orca viewport --mobile로, 업로드는orca upload로 —exec --command "..."로 하지 않습니다(UI 상태 동기화·터치 입력 때문). 목록에 없는 기능만orca exec --command "<agent-browser 명령>"(예:"is visible @e3")로 하며,help명령은 없습니다. upload는 파일 입력칸 또는 파일 선택 창을 여는 버튼을 받습니다(다른 도메인 iframe 포함). 서버 호스팅 페이지에서는 파일 입력칸의 ref를 줍니다.- 비동기 변화 뒤에는 고정 시간 대기 대신
wait --text/--url/--selector/--load를 씁니다.--load networkidle은 폴링·웹소켓·스트리밍이 있으면 끝나지 않으니 피합니다. - client-hosted 페이지는 데스크톱이 온라인이어야 하므로, 길거나 무인 자동화에는 서버 호스팅 페이지가 낫습니다.
| 오류 | 뜻과 대처 |
|---|---|
browser_no_tab | 탭이 없음 → orca tab create --url <url> --json |
browser_stale_ref | ref가 낡음 → 같은 페이지에서 snapshot 후 새 ref로 재시도 |
browser_element_not_interactable | 그 요소에 그 명령을 쓸 수 없음(입력칸 아님, 비활성, 읽기 전용, <select> 아님, 파일 선택 창 안 열림 등 — 메시지에 이유) → 재스냅숏 후 맞는 ref. 직접 만든 드롭다운은 클릭 후 옵션 클릭 |
browser_tab_not_found | 전환·닫기 전에 orca tab list --json |
browser_dialog_open / browser_dialog_opened | alert·confirm·prompt가 열림(오류에 내용 인용) → 다른 명령 전에 dialog accept(prompt면 --text, 없으면 기본값) 또는 dialog dismiss. 연 명령이 이미 효과를 냈을 수 있으니 반복 전에 확인 |
browser_host_unavailable | 페이지를 그리는 데스크톱이 오프라인 → 다시 켜거나, 데스크톱 세션보다 오래가야 하면 서버 배치로 페이지를 다시 만듦 |
- 워크트리마다 진짜 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(저장 지점 만들기).
- 에이전트는 마우스 대신 화면 요소에 번호표를 붙이고, 그 번호표를 보고 누르거나 입력합니다. 같은 브라우저·같은 탭이라 하는 일을 화면에서 지켜볼 수 있습니다.
출처: onorca.dev/docs/browser/overview · onorca.dev/docs/browser/design-mode · onorca.dev/docs/browser/profiles · onorca.dev/docs/recipes/design-mode-fix · 보조: Orca CLI 내장 브라우저 명령 안내(로컬)
파일 편집과 보기 — 에디터, 마크다운, 뷰어, 파일 탐색기
Orca 안에서 파일을 직접 고치고, 문서를 보기 좋게 다듬고, PDF·이미지·영상·표·노트북을 열어 보고, 파일을 찾아 에이전트에게 건네는 방법을 다룹니다.
- 코드 에디터(Monaco)의 자동 저장, 다른 쪽이 파일을 바꿨을 때의 처리, 단축키, 화면 설정
- 마크다운 문서 에디터의 슬래시 메뉴·콜아웃·표·목차·리뷰 노트·공유 링크
- HTML·Mermaid·PDF·이미지·오디오/비디오·CSV·Jupyter 노트북 뷰어
- 파일 탐색기의 정렬·git 상태 색·오른쪽 클릭 메뉴, 바깥에서 파일을 끌어다 놓는 법
- 한눈에 보는 편집 영역 — 파일을 열면 어떤 화면이 뜨는지
- 코드 에디터(Monaco)와 자동 저장 — 저장 버튼이 없는 이유
- 마크다운 문서 에디터(리치 에디터) — 문서를 워드처럼 고치기
- 파일 탐색기와 git 상태 색 — 왼쪽 파일 목록 읽는 법
HTML 미리보기, Jupyter 노트북, 그리고 🔧 표시가 붙은 접힌 상자는 필요할 때 펼쳐 보면 됩니다.
한눈에 보는 편집 영역
Orca의 각 워크트리(에이전트마다 따로 꺼내 주는 프로젝트 폴더의 작업용 복사본)에는 왼쪽에 파일 탐색기, 가운데에 파일을 여는 탭이 있습니다. 파일을 열면 종류에 맞는 화면이 자동으로 열립니다. 코드는 Monaco 에디터, 마크다운 문서는 리치 에디터, PDF·이미지·영상·표·노트북은 전용 뷰어로 열립니다.
코드 에디터(Monaco)와 자동 저장
Orca의 코드 에디터는 Monaco입니다. VS Code(널리 쓰이는 코드 편집 프로그램)가 쓰는 바로 그 편집기라서 VS Code를 써 본 사람은 거의 같은 감각으로 쓸 수 있고, 여기에 Orca만의 몇 가지 조정이 더해졌습니다.
자동 저장과 "디스크에서 바뀜" 배너
무엇인가 — 파일은 저절로 저장됩니다. 다른 곳을 클릭해 에디터에서 벗어날 때, 그리고 잠깐 타이핑을 멈추고 있을 때 저장됩니다. 그래서 다른 편집기에서 흔히 보는 "아직 저장 안 됨" 표시 점이 없습니다. 평소에는 저장 안 된 변경이 생기지 않기 때문입니다.
왜 검사가 필요한가 — Orca에서는 사람과 에이전트가 같은 파일을 만질 수 있습니다. 그래서 Orca는 저장하기 직전에 "이 탭이 마지막으로 파일을 읽거나 저장한 뒤에 디스크의 파일이 바뀌었나?"를 확인합니다.
파일을 고치고 다른 탭이나 터미널을 클릭하면(또는 잠시 손을 멈추면) 자동 저장됩니다.
탭이 마지막으로 읽거나 쓴 뒤 디스크의 파일이 바뀌었습니다. 다음 저장 직전 Orca가 이를 알아챕니다.
배너가 뜨고 자동 저장이 멈춥니다. 내가 친 내용은 탭 안에 그대로 남아 있어 사라지지 않습니다.
- compare(비교) — 디스크 쪽 내용과 내 편집을 비교합니다.
- reload(다시 불러오기) — 디스크 쪽 내용으로 탭을 새로 고칩니다.
- keep your edits(내 편집 유지) — 탭의 내용을 그대로 둡니다.
- overwrite(덮어쓰기) — 디스크 쪽 내용을 내 편집으로 바꿉니다. 내가 직접 골라야만 일어납니다.
SSH로 접속한 원격 컴퓨터의 파일을 열 때만 해당하는 내용(같은 경로의 파일이라도 컴퓨터마다 편집 내용을 따로 보관)은 아래 접힌 상자에 있습니다.
호스트별 편집 내용 분리 (SSH 원격 작업)
컴퓨터(호스트)마다 편집 내용을 따로 보관
Orca는 내 컴퓨터(로컬)뿐 아니라 SSH(다른 컴퓨터에 안전하게 접속해 그곳 파일을 쓰는 방법)로 접속한 원격 컴퓨터의 파일도 엽니다. 이때 경로가 똑같은 파일이라도 컴퓨터(호스트)가 다르면 에디터 내용과 Undo(실행 취소) 기록을 따로 보관합니다. 그래서 원격의 /app/main.ts를 열었을 때 로컬 /app/main.ts의 실행 취소 기록이 섞여 나오는 일이 없습니다. 반대로 같은 로컬 파일을 탭 두 개로 열면 두 탭은 하나의 편집 내용 묶음을 함께 씁니다.
단축키와 변경 보기(Changes view)
멀티 커서·찾기·정의로 이동
| 단축키 (원문에는 macOS 키만 나옴) | 하는 일 |
|---|---|
| Cmd+D (macOS) | 지금 선택한 단어의 다음 같은 단어를 추가로 선택합니다. 여러 번 누르면 커서가 여러 개가 되어 한꺼번에 고칠 수 있습니다(멀티 커서). |
| Cmd+F (macOS) | 지금 파일 안에서 찾기. 글자를 선택한 상태로 누르면 그 글자가 검색창에 미리 채워집니다. |
| Cmd+Shift+F (macOS) | 워크트리 전체에서 찾기. |
| Cmd+클릭 (macOS) | 정의로 이동(go to definition). 예를 들어 코드에 쓰인 어떤 기능의 이름을 Cmd+클릭하면, 그 기능을 처음 만들어 둔(정의한) 곳으로 바로 이동합니다. 그 언어용 확장 기능이 지원하는 경우에만 동작합니다. |
Changes view mode — 탭 안에서 바로 "무엇이 바뀌었나" 보기
어느 에디터 탭에서든 Changes view mode(변경 보기 모드)를 켜면, 커서 위치는 그대로 둔 채 그 파일이 "마지막 커밋과 지금 파일"을 비교하는 화면으로 바뀝니다. 커밋은 git(파일의 변경 이력을 기록하는 도구)에 남긴 기록입니다(마지막 커밋을 원문 용어로 HEAD라고 함). 빨간 줄은 지운 줄, 초록 줄은 더한 줄입니다. 한 번 더 켜고 끄면 일반 파일 화면으로 돌아옵니다.
- n / p — 다음 / 이전 변경 덩어리(hunk)로 이동
- s — 그 변경을 stage(다음 커밋에 넣을 목록에 올려 두기)
- 단축키는 diff 뷰어(두 버전의 차이를 보여 주는 화면, 6장)와 같습니다.
원문 표현
원문: "an in-tab HEAD-vs-working-tree diff". HEAD는 마지막 커밋 상태, working tree(작업 트리)는 아직 커밋하지 않은 변경까지 포함한 지금 디스크의 상태입니다.
화면 설정 — 줄 바꿈·미니맵·글꼴·언어 지원
파일 에디터는 긴 줄을 기본으로 접어서(Word Wrap) 화면 폭 안에 보여 줍니다. 끄고 켜는 방법은 세 가지입니다.
- 탭 메뉴에디터 탭의 ⋯ 메뉴에서 Word Wrap 토글
- 단축키Alt+Z (VS Code와 같음). Settings → Shortcuts(설정 → 단축키)에서 다른 키로 바꿀 수 있습니다.
- 기본값 설정Settings → General → Editor Word Wrap(설정 → 일반 → 에디터 줄 바꿈)
미니맵은 에디터 오른쪽에 파일 전체를 아주 작게 줄여 보여 주는 세로 띠입니다(VS Code 스타일). 기본으로 꺼져 있고, Settings → Appearance(설정 → 모양)에서 켤 수 있습니다.
기본적으로 에디터와 변경 비교(diff) 화면은 터미널과 같은 글꼴을 씁니다.
- Settings → Appearance → Editor Font Family(에디터 글꼴)를 비워 두면 터미널 글꼴을 계속 따라갑니다.
- 글꼴을 지정하면 에디터에만 그 글꼴이 적용됩니다. 메뉴·버튼 같은 화면 글꼴은 따로 유지됩니다.
문법 색칠(코드의 종류별로 글자색을 달리 칠해 읽기 쉽게 하는 기능)은 Monaco가 기본으로 지원하는 언어 전부에 더해 몇 가지 언어를 추가로 지원합니다(목록은 아래 접힌 상자).
Orca는 IDE(모든 기능이 다 든 개발 도구)보다 에디터를 지향하므로, 코드 검사 도구(타입 검사기·린터)는 터미널 창에서 실행합니다.
추가 지원 언어 목록·Nim·Typst 색칠 방식
.qmdR Markdown .Rmd셸 시작 파일 .bashrc · .zshrc 등NimTypstNim과 Typst는 Orca가 공통으로 쓰는 TextMate 문법 계층(shared TextMate grammar layer)으로 색칠합니다. 이 방식 덕분에 아주 긴 한 줄이 있어도 창이 멈추지 않습니다.
마크다운 문서 에디터(리치 에디터)
마크다운(#를 붙이면 제목, -를 붙이면 목록이 되는 식으로, 간단한 기호로 서식을 다는 글 문서 형식. 확장자 .md) 파일은 기본으로 리치 에디터로 열립니다. 기호 대신 완성된 모양(제목은 큰 글씨, 목록은 점)을 보면서 바로 고치는 방식이라 워드 프로그램과 비슷합니다. 슬래시 메뉴, 도구 모음, 이미지·코드 미리보기, 내부 링크 자동완성을 갖추고 있습니다.
- Cmd+Shift+M (macOS) — 기호가 그대로 보이는 원문(raw) 에디터와 리치 에디터를 언제든 오갑니다.
- 운영체제의 "다음으로 열기" — Orca는 macOS·Windows·Linux에서 마크다운 파일의 Open With(다음으로 열기) 목록에 자신을 등록합니다. 원래 쓰던 기본 편집기를 바꾸지는 않습니다. 리치 에디터로 열고 싶을 때 그 메뉴에서 Orca를 고르면 됩니다.
- 600 KB보다 큰 파일은 타이핑이 느려지지 않도록 원문(raw) 에디터로 먼저 열립니다. 안내 배너에서 Open anyway(그래도 열기)를 누르면 리치 에디터로 열리며, 이 선택은 그 탭을 닫을 때까지 유지됩니다.
- 리치 에디터가 망가뜨리지 않고 지킬 수 없는 마크다운 문법을 쓴 파일은 원문 에디터에 머뭅니다.
마크다운 쓰기 도구 — 슬래시 메뉴·콜아웃·링크·검색
슬래시 메뉴와 토글
빈 줄에서 /를 치면 슬래시 메뉴가 열립니다. 넣을 수 있는 것: 제목, 목록, 코드 블록, 콜아웃, 이미지, mermaid 다이어그램, 토글(눌러서 접었다 펴는 블록).
/toggle-text— 접었다 펼 수 있는 메모./toggle-h1…/toggle-h5— 접힌 상태의 요약 줄이 제목(1~5단계)처럼 보이게 합니다.- 토글 안에 토글을 넣어도 그 자리에서 바로 고칠 수 있습니다.
- 토글은 표준
<details>/<summary>형식으로 저장됩니다. 그래서 Orca 밖에서 미리보기해도 똑같이 접힙니다.
콜아웃 — 색깔 있는 알림 상자
인용문(>로 시작하는 줄)의 첫 줄에 아래 다섯 표시 중 하나를 쓰면, 표시 글자가 그대로 보이는 평범한 인용 대신 아이콘과 제목이 달린 색 상자로 그려집니다(GitHub 방식). 미리보기를 포함해 Orca가 마크다운을 읽기 전용으로 보여 주는 모든 곳에 적용됩니다.
> [!NOTE]
> 참고할 내용
> [!TIP]
> [!IMPORTANT]
> [!WARNING]
> [!CAUTION]
내부 링크와 문서 안 검색
위키식 링크 — [[를 치면 워크트리 안의 파일 경로가 자동완성되고, 고르면 지금 문서 기준의 상대 경로 링크가 들어갑니다.
보이는 글자로 검색 — 에디터 안 마크다운 검색은 기호가 아니라 화면에 보이는 글자를 찾습니다.
| 검색어 | 찾아 주는 제목 (원문에 쓴 방식이 달라도) |
|---|---|
| Install | # Install 로 쓴 제목, <h1>Install</h1> 로 쓴 제목 모두 |
마크다운 검토·정리 도구 — 리뷰 노트·프런트 매터·표·목차
리뷰 노트(주석) 달기
리치 에디터에서 문서를 검토할 때, 화면에 보이는 글자를 선택하고 바로 메모를 달 수 있습니다. 원문(raw) 화면으로 돌아갈 필요가 없습니다. Orca는 메모를 선택한 원문 위치에 묶어 두므로, 문서를 계속 고쳐도 메모가 제자리에 보입니다.
Add Review Note(리뷰 노트 추가) 단축키: Cmd+Shift+A / Ctrl+Shift+A (기본값, Settings → Shortcuts에서 변경 가능).
프런트 매터
프런트 매터(문서 맨 위 --- 사이에 적는 제목·날짜·태그 같은 정보 묶음. 블로그 글 등에서 많이 씀)는 YAML·TOML(이런 정보를 적는 설정 형식의 이름) 어느 쪽이든 리치 에디터와 미리보기에 기본으로 보입니다.
title: 11월 소식지
date: 2026-11-04
---
- 본문만 보고 싶으면 에디터의 More actions (…) 메뉴 → Hide front matter(프런트 매터 숨기기).
- 같은 메뉴의 Show front matter로 다시 보입니다.
- 이 설정은 파일마다 따로입니다. 한 문서에서 숨겨도 다른 문서는 그대로입니다.
표 편집
| 키 | 동작 |
|---|---|
| Tab / Shift+Tab | 다음 / 이전 칸. 마지막 칸에서 Tab을 누르면 새 행이 추가됩니다. |
| Enter | 아래 칸으로 이동. 마지막 행이면 행을 추가합니다. |
| 완전히 빈 행에서 Backspace | 그 행을 지웁니다(표에 남은 마지막 행이면 표 전체를 지웁니다). |
| 행에 다른 내용이 있는데 빈 칸에서 Backspace | 이전 칸으로 이동합니다. |
- Shift+Tab은 목록 항목이나 코드 블록에서 선택한 줄의 들여쓰기를 줄이는 데도 씁니다.
- 커서가 표 안에 있으면 도구 모음에 행·열 추가/삭제 버튼이 나타납니다.
- 표 칸을 오른쪽 클릭하면 같은 명령이 메뉴에 나옵니다. Table 하위 메뉴는 표 칸을 오른쪽 클릭했을 때만 나타납니다.
목차(Table of Contents)
긴 문서에서는 에디터 머리줄의 Table of Contents 버튼(나무 모양 아이콘)을 누르면 에디터 왼쪽에 제목 목록이 붙어 열립니다. 제목을 누르면 그 위치로 이동하고, 접기/펼치기로 깊이 들어간 부분도 읽기 쉽게 정리됩니다. 리치 모드와 미리보기 모드에서 쓸 수 있습니다.
← 왼쪽 목차에서 누른 제목으로 본문이 이동합니다.
아티팩트로 공유 — 공개 보기 링크 만들기
에디터 머리줄의 Share as artifact(아티팩트로 공유)는 열린 마크다운 파일을, 로그인한 Orca 계정을 통해 누구나 볼 수 있는 공개 보기 링크로 게시합니다.
- 먼저 허용 설정Settings → Artifacts → Allow publishing public artifact links(공개 아티팩트 링크 게시 허용)를 켭니다. 기본은 꺼짐입니다.
- 게시파일 크기는 10 MiB(약 10MB)까지 지원합니다.
- 다시 게시(Republish)Orca가 파일과 링크의 연결을 아직 기억하면 같은 링크의 내용이 바뀝니다.
- 관리·삭제사이드바 Artifacts 페이지에서 링크를 관리하거나 지웁니다.
에이전트·스크립트에서 공유하기
orca artifacts share|update|list|delete 명령으로 같은 일을 할 수 있습니다(CLI 참고 → Artifacts).
파일 종류별 뷰어 고르기
Orca에는 프로젝트 폴더에 흔히 있는 형식을 위한 뷰어(파일을 열어 보는 전용 화면)가 들어 있습니다. 확장자(파일 이름 끝의 .pdf 같은 부분)에 따라 아래처럼 열립니다.
HTML 미리보기
무엇인가 — .html(웹 페이지 파일)을 Open in Orca Browser(Orca 브라우저에서 열기) 또는 Open Preview to the Side(옆에 미리보기 열기)로 열면, 웹 페이지 모양 그대로 볼 수 있습니다. 내 컴퓨터, SSH로 접속한 컴퓨터, 페어링된 런타임(paired runtime)(내 Orca와 짝지어 연결해 둔 다른 컴퓨터의 Orca 서버. 4장 「원격 워크트리」 참고)에 있는 파일 모두 됩니다.
어떻게 안전하게 보여 주나 — Orca는 문서를 내 컴퓨터의 샌드박스(바깥과 격리된 안전한 상자. 그 안의 페이지가 내 컴퓨터 파일을 마음대로 못 건드림) 브라우저 탭으로 그립니다. 파일과 그 파일이 쓰는 이미지 같은 자료는 Workspace(워크스페이스 — 워크트리와 같은 것)의 파일 연결(Orca가 그 워크트리 폴더의 파일을 읽어 오는 통로)을 통해서만 읽습니다. 그래서 원격 서버의 디자인 문서도 선명하게 보이면서, 내 컴퓨터의 다른 파일은 드러나지 않습니다.
- 폴더 권한 — 미리보기가 다른 폴더를 더 읽어야 하면 먼저 묻고, 승인한 폴더만 그 탭에 허용합니다.
- 외부 링크 — 바깥 웹 주소(HTTP(S)) 링크는 확인을 받은 뒤 일반 Orca 브라우저 탭에서 열립니다.
- 다운로드 — 문서 미리보기 안에서는 다운로드가 꺼져 있습니다.
웹 글꼴·미리보기 옵션·주소창·페어링 런타임
- 웹 글꼴 — 내가 허락한 제공자(예: Google Fonts 링크)에서 글꼴을 요청하는 페이지는 대체 글꼴 대신 그 글꼴로 그려집니다.
- Preview options(미리보기 옵션) — 디스크에서 다시 불러오기, 원본 파일 열기, 전체 경로 또는 워크트리 기준 상대 경로 복사.
- 문서 칩 = 주소창 — 미리보기의 문서 칩을 고쳐 웹 URL을 넣으면 그 탭이 일반 브라우저 탭이 됩니다. 반대로 브라우저 탭에서 워크트리의 HTML 경로를 넣으면 다시 미리보기가 됩니다. 사이에 다른 페이지 기록이 없으면 뒤로(Back)로 둘 사이를 오갈 수 있습니다.
- 페어링 런타임 — HTML 파일이 워크트리 안에 있어야 합니다. 아주 오래된 페어링 서버는 이미지 같은 바이너리 자료 없이 문서를 그릴 수 있으니, 원격 이미지가 안 보이면 서버를 업데이트하세요.
Mermaid · PDF · 이미지 · 오디오/비디오
Mermaid(글자로 적으면 순서도·관계도를 그려 주는 다이어그램 언어) 다이어그램은 마크다운 미리보기 안에서 그 자리에 바로 그려집니다. 따로 떨어진 .mmd 파일은 이동(pan)·확대(zoom)가 되는 전용 뷰어로 열립니다.
스크롤, 확대, 글자 선택이 됩니다. 프로젝트 폴더에 함께 넣어 둔 설계 문서를 볼 때 유용합니다.
- 확대 — 트랙패드 핀치, Ctrl+스크롤, 또는 Cmd/Ctrl + = / - / 0. 마우스 커서 아래 지점을 기준으로 확대됩니다.
- 확대 비율 기억 — 탭을 바꿔도, Orca를 다시 켜도 유지됩니다.
- 읽던 위치 기억 — 다른 탭에 갔다 돌아오면(같은 세션 안에서 닫았다 다시 열어도) 페이지와 페이지 중간 위치까지 복원됩니다. 단, 위치는 Orca를 켜 둔 동안만 기억하며 다시 시작하면 지워집니다.
지원 형식: .png .jpg .svg .webp .gif.
Image-diff 모드(이미지 비교)는 같은 이미지 파일의 두 버전을 나란히 놓고 비교합니다.
오디오·비디오 파일은 Orca 안에서 재생·정지 같은 기본 조작 버튼으로 재생됩니다.
.mp3.wav.ogg.m4a.aac.flac.mp4.mov.webm.mkv.avi- 스트리밍 — 데스크톱 앱은 로컬·SSH·페어링 서버의 파일을 조금씩 받아 가며 재생하므로, 큰 영상도 파일 전체를 받기 전에 재생이 시작됩니다.
- Open in Default App(기본 앱으로 열기) — 로컬 파일은 운영체제 기본 플레이어로 열 수 있습니다.
- 재생할 수 없는 파일 — Orca가 읽을 수 없는 파일은 빈 화면 대신 재생 오류로 표시됩니다.
CSV · TSV 표
.csv·.tsv(쉼표나 탭으로 칸을 나눈 표 데이터 파일. 엑셀에서 내보내기 할 때 자주 생김) 파일은 엑셀처럼 그 자리에서 고칠 수 있는 표로 열립니다.
| id | name | site |
|---|---|---|
| 1 | Kim▏ | https://… |
| 2 | Lee | — |
- 칸을 클릭해 고치고, 범위를 선택해 복사/붙여넣기.
- 행·열 메뉴로 행·열 추가/삭제, Columns(열) 메뉴로 열 순서 바꾸기.
- 정렬·필터는 보기만 바꿀 뿐 파일 안의 행 순서는 바꾸지 않습니다.
- 칸 전체가 웹 주소(http(s))면 클릭해서 열립니다.
- 조절한 열 너비는 보기를 바꾸거나 앱을 다시 켜도 기억됩니다.
- 파일의 숨은 형식은 그대로 — 엑셀처럼 칸을 고쳐도, 파일이 원래 갖고 있던 저장 형식(눈에 안 보이는 표시 문자, 줄 끝 방식, 따옴표 방식 등)은 바뀌지 않습니다. 기준은 언제나 파일 자체입니다.
- 구분자 — 칸을 나누는 문자(쉼표·세미콜론·탭)를 자동으로 알아냅니다. Delimiter(구분자) 선택기로 Auto / Comma / Semicolon / Tab을 직접 고를 수 있습니다(세미콜론으로 나뉜 내보내기 파일에 유용).
- 원문 보기 — 도구 모음에서 글자 그대로의 원문(raw) 보기로 바꿀 수 있습니다.
보존되는 형식·큰 파일 처리 방식
- 편집해도 파일의 BOM(파일 맨 앞의 보이지 않는 인코딩 표시), record endings(줄 끝 문자), quoting(따옴표 방식), 마지막 줄바꿈이 그대로 보존됩니다. "The file stays the source of truth" — 파일 자체가 기준입니다.
- 1 MiB 이상 파일은 읽기 전용 paged preview(나눠 보여 주는 미리보기)로 열립니다. Orca가 파일에 색인을 만든 뒤 화면에 보이는 행·열만 그려서, 파일 전체를 메모리에 올리지 않고도 빠르게 보여 줍니다.
- 테스트용 데이터(fixture), 내보낸 자료 등 프로젝트에 든 표 데이터를 다룰 때 유용합니다.
Jupyter 노트북
Jupyter 노트북(설명 글과 실행할 수 있는 코드 칸(셀)을 한 문서에 섞어 둔 파일, 확장자 .ipynb)을 열면 설명 글, 코드 셀, 저장된 실행 결과가 그려진 상태로 보입니다. 코드 셀은 클릭해서 고치고, 설명(마크다운) 셀은 더블클릭하거나 Enter로 고칩니다. 고친 내용은 노트북 파일에 저장됩니다.
내 컴퓨터에 있는 Python(데이터 분석에 많이 쓰는 프로그래밍 언어) 노트북은 Orca 안에서 셀을 실행할 수도 있습니다. 실행은 커널(셀을 실제로 실행하는 엔진)이 맡습니다.
노트북 코드를 실행하기 전에 Orca의 신뢰 확인 창에 동의해야 합니다. 신뢰하기 전까지 Orca는 이 워크트리의 Python을 시작하지 않습니다.
머리줄의 커널 선택기가 가까이 있는 Python 환경을 추천해 줍니다. 필요한 구성 요소가 없으면 Orca가 설치를 제안합니다. 세부 사항은 아래 🔧 상자를 보세요.
Shift+Enter는 실행 후 다음 셀로, Cmd/Ctrl+Enter는 실행 후 그 셀에 머뭅니다. 그래프·결과·오류·실행 번호가 셀과 함께 표시됩니다.
첫 실행부터 탭을 닫을 때까지 그 노트북용 커널이 살아 있어 셀 사이에 값이 유지됩니다. 머리줄의 Run All(모두 실행), Interrupt(중단), Restart(재시작), Clear All Outputs(결과 모두 지우기)를 씁니다.
커널 선택·필요 패키지·파일 형식
- 커널 선택기는 가까운
.venv또는.conda환경을 추천합니다. 다른 Python을 고르거나 찾아볼 수 있고, Orca는 그 노트북에 대한 선택을 기억합니다. - Python에
ipykernel과jupyter_client가 있어야 합니다.ipykernel이 없으면 Orca가 설치를 제안합니다. - 선택한 Python이 패키지 설치를 막으면 Create .venv로 워크트리 전용 환경을 만드세요. 설정 대화상자에 진행 상황과 오류가 보입니다.
- 편집 내용은 nbformat(노트북 파일 형식)을 지키며 저장됩니다.
파일 탐색기
파일 탐색기는 각 워크트리 왼쪽에 있으며 디스크의 파일을 실시간으로 따라갑니다. 만들기·이름 바꾸기·삭제·이동이 모두 실제 파일에 그대로 적용되고, 에이전트처럼 바깥에서 생긴 변경도 바로 나타납니다. 정렬은 폴더 먼저, 그다음 파일이며, 이름 속 숫자를 수로 이해하는 순서(9, 99, 100)입니다.
정렬이 적용되는 곳·큰 원격 폴더·sparse checkout
- 정렬 — 같은 순서(natural, numeric-aware)가 SSH, 원격 런타임, Source Control 트리, 폴더 선택 창, 모바일 파일 트리에도 적용됩니다.
- 큰 원격 폴더 — 업데이트된 SSH·페어링 서버에서는 스크롤하면 항목을 더 불러옵니다. 큰 폴더가 다 안 보이면 호스트 서버를 업데이트하세요.
- sparse checkout(저장소의 일부 폴더만 골라 꺼내는 git 기능) — 워크트리가 이것을 쓰면 탐색기가 꺼낸 폴더만 보여 줘, 저장소 전체 대신 실제 작업 폴더에 바로 닿습니다.
바깥에서 끌어다 놓기
파일을 놓으면 지금 활성화된 워크트리가 아니라, 마우스 커서가 가리키는 바로 그곳에 떨어집니다. 파일 트리, 프로젝트 사이드바, 에디터, 탭 줄, 또는 커서 아래에 있는 특정 터미널 창.
파일 트리에 놓기
Finder/Explorer에서 끌어 온 파일이 그 폴더로 복사됩니다.
마크다운 에디터에 놓기
이미지를 놓으면 커서 위치에 이미지가 들어갑니다.
에이전트 터미널에 놓기
파일들의 경로가 입력줄에 붙여넣어집니다.
SSH 워크트리
여기서도 됩니다. Orca가 놓기를 마치기 전에 파일을 원격 컴퓨터로 올려 두므로, 에이전트는 원격 디스크의 실제 경로로 파일을 봅니다.
git 상태 색 — 파일 이름 색이 다른 이유
탐색기의 파일 이름은 git(파일의 변경 이력을 기록하는 도구)이 보는 상태에 따라 색이 다릅니다. 색만 봐도 "새로 만든 파일인지, 고친 파일인지"를 알 수 있습니다.
그림의 색은 설명을 위한 예시입니다.
| 상태 | 뜻 · 왜 생기나 |
|---|---|
| untracked | 새로 만들어서 git이 아직 기록해 본 적 없는 파일. 에이전트나 내가 새 파일을 만들면 생깁니다. |
| modified | 기록된 적 있는 파일을 그 뒤에 고친 상태. |
| staged | 고친 내용을 다음 커밋(변경을 하나의 저장 지점으로 기록하는 일)에 넣기로 표시해 둔 상태. 오른쪽 클릭 → stage 등으로 생깁니다. |
| ignored | 프로젝트가 "git이 신경 쓰지 않을 파일"로 정해 둔 것. 임시 파일처럼 기록할 필요 없는 파일이 해당합니다. |
오른쪽 클릭 메뉴 — 버리기·올리기·경로 복사·내려받기·찾기
탐색기에서 파일이나 폴더를 오른쪽 클릭하면 자주 쓰는 동작이 모여 있습니다.
메뉴의 순서·모양은 설명을 위한 예시입니다.
| 메뉴 | 설명 |
|---|---|
| discard | 그 파일에서 고친 내용을 버립니다. 버린다는 것은 고친 내용이 없어진다는 뜻이니, 버려도 되는지 확인하고 누르세요. |
| stage | 다음 커밋 목록에 올리기 |
| rename | 이름 바꾸기 |
| Copy Path | 전체 경로(파일의 위치 주소) 복사 |
| Copy Relative Path | 워크트리 기준 상대 경로 복사. 기본 단축키 Cmd+Option+Shift+C / Ctrl+Alt+Shift+C (변경 가능) |
| Copy | 파일 한 개를 골랐을 때, 파일 자체를 운영체제 클립보드에 올려 다른 앱에 붙여넣을 수 있게 합니다. |
SSH 워크트리에서 Copy
SSH 워크트리에서는 Orca가 원격 파일을 먼저 내 컴퓨터에 임시로 받아 둔 뒤, 그 파일을 클립보드에 넣습니다. 원격 폴더는 Copy 대상에서 제외됩니다.
원격 파일 내려받기
데스크톱 앱에서 원격 파일을 오른쪽 클릭 → Download(내려받기), 원격 폴더는 → Download Folder(폴더 내려받기 — 연결이 폴더 통째 전송을 지원할 때). 운영체제의 저장 위치 선택 창이 열립니다.
| 어디서 | Download 메뉴 |
|---|---|
| 데스크톱 앱 + 원격(SSH 등) 파일 | 있음 (폴더는 연결이 지원할 때 Download Folder) |
| 웹 버전 Orca | 쓸 수 없음 |
| 로컬 워크트리 | 보이지 않음 (이미 내 컴퓨터에 있으니까요) |
Finder / File Explorer에서 보기
탐색기의 파일, Source Control(변경 목록)의 바뀐 파일, 터미널 안의 파일 경로 링크를 오른쪽 클릭하고 Reveal in Finder(macOS) 또는 Reveal in File Explorer(Windows)를 고르면, 운영체제의 파일 창에서 그 파일이 있는 폴더가 열립니다.
폴더 안에서 찾기
| 방법 | 결과 |
|---|---|
| 폴더를 오른쪽 클릭 → Find in Folder(폴더에서 찾기) | 그 폴더 안만 찾도록 범위가 정해진 검색 화면이 열립니다. |
| 탐색기에서 폴더를 선택하고 Cmd+Shift+F(macOS) / Ctrl+Shift+F(Windows·Linux) |
탐색기의 이름 필터는 파일이 아주 많은 워크트리에서도 처음 목록에 없던 파일까지 찾아 줍니다.
아주 큰 워크트리에서의 이름 필터
아주 큰 워크트리가 목록 한도(listing cap)에 닿아도, 탐색기 이름 필터는 로컬 전체 파일 목록을 검색하므로 처음 목록에 없던 파일도 찾을 수 있습니다. 이때는 타이핑하는 동안 아주 잠깐 기다렸다가 검색하고(debounce), 작은 워크트리는 치는 즉시 걸러 줍니다.
- 코드는 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=올린 뒤 경로.
출처: onorca.dev/docs/editing/monaco · onorca.dev/docs/editing/markdown · onorca.dev/docs/editing/viewers · onorca.dev/docs/editing/file-explorer
리뷰와 배포 — diff 보기부터 PR·이슈 연동까지
에이전트가 코드를 고쳤다면 이제 사람이 꼼꼼히 확인하고, 저장(커밋)하고, 서버로 올리고(푸시), 동료에게 검토를 부탁(PR)할 차례입니다. 이 장은 그 과정을 Orca 안에서 한 번에 끝내는 방법과, GitHub·GitLab·Bitbucket·Jira·Linear 같은 바깥 서비스와 연결하는 방법을 다룹니다.
- diff·스테이징·커밋·푸시·PR·CI가 각각 무엇이고, 변경 사항이 어떤 길을 따라 이동하는지
- Diff viewer(차이 보기 화면)의 기능·범위 설정·줄바꿈·파일 트리·단축키
- Annotate AI Diff로 줄마다 코멘트를 달고 한 번에 묶어 에이전트에게 돌려보내는 리뷰 순환
- Attribution(작성자 표시)으로 사람이 쓴 줄과 AI가 쓴 줄을 구분하는 법
- Orca 안에서 커밋·푸시·강제 푸시·Amend·PR 만들기, 그리고 AI 액션 레시피 설정
- GitHub·GitLab·Bitbucket 등의 리뷰 연동(자동 병합, 스택 PR, 이슈, Actions, Projects)
- Jira·Linear 이슈를 워크트리와 연결하는 법, AI diff를 줄 단위로 리뷰하는 레시피
순서대로 보세요.
- 먼저 알아 둘 말: diff · 스테이징 · 커밋 · 푸시 · PR · CI — 봉투·사물함 비유와 용어표
- Diff viewer — AI가 만든 코드를 제대로 읽는 화면
- Annotate AI Diff — 코멘트를 모아 한 번에 돌려보내기
- 커밋 · 푸시 · PR 만들기 — Orca를 떠나지 않고 (첫 두 탭)
- 레시피: AI diff를 줄 단위로 리뷰하기 — 코드를 몰라도 따라 할 수 있는 확인법 포함
GitHub 세부 기능·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 파일이면 눈 모양 아이콘을 눌러 옆 화면에서 웹페이지 모습으로 미리 봅니다.
눈 아이콘이 나오는 조건
View all/합친 diff에서, 작업 폴더에 아직 남아 있는 HTML 부분에는 항상 보이는 “파일 열기” 버튼 옆에 Open Preview to the Side(눈 모양 아이콘, 옆에 미리보기 열기)가 나타납니다. 누르면 작업 폴더의 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에서는 왼쪽 파일 트리를 접었다 펴고 너비를 바꿀 수 있습니다.
줄바꿈 켜는 곳 · 파일 트리 조작 상세
- diff editor 머리글의 ⋯ actions 메뉴에서 Word Wrap을 토글하거나,
- Settings → General → Diff Word Wrap(설정 → 일반 → diff 줄바꿈)에서 전체 기본값을 정합니다.
파일 트리
합친 diff는 hunk 옆에 접었다 펼 수 있는 파일 트리를 보여 줄 수 있습니다.
- 트리의 크기 조절 손잡이를 끌거나, 손잡이에 포커스를 두고 화살표 키로 너비를 바꿉니다. Shift를 같이 누르면 한 번에 더 많이 움직입니다.
- 정한 너비는 앱을 껐다 켜도 기억됩니다.
- 트리 숨기기/보이기는 합친 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를 다시 누를 때 다음 묶음에 포함됩니다.
Attribution — 이 줄은 사람이 썼나, AI가 썼나
무엇인가. Orca는 에이전트가 건드리는 것을 본 모든 줄에 “출처(provenance)”를 기록합니다. 그래서 diff를 읽을 때 어떤 줄은 사람이, 어떤 줄은 AI가 썼는지 한눈에 알 수 있습니다.
왜 중요한가
- PR 중에서 어느 부분을 더 꼼꼼히 봐야 하는지 알 수 있습니다.
- 보안·규정 준수 감사에서 AI가 쓴 코드와 사람이 쓴 코드를 나눠 볼 수 있습니다.
- 방금 내 손으로 쓴 코드는 다시 읽지 않아도 되니 리뷰가 빨라집니다.
커밋 · 푸시 · 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 버튼이 담긴 안내가 나옵니다.
Create PR 때 AI 초안 · 실패 요약 · OMP 상세
- 이미 푸시된 브랜치에서 Create PR을 누르면, 자리표시 제목과 빈 본문을 보내는 대신 설정된 생성 에이전트가 제목과 설명 초안을 먼저 쓴 뒤 제출합니다. 내가 고른 Draft 선택은 에이전트가 다른 값을 돌려줘도 그대로 유지됩니다.
- Create PR 과정에서 Orca가 후속 커밋을 해야 하는데 그 커밋이 실패하면(hook 거부, 커밋할 수 없는 작업 폴더 상태 등), 대화상자가 hook 출력과 다음 단계 버튼을 담은 상세 실패 요약을 보여 줍니다. 아무 설명 없이 패널로 튕겨 내지 않습니다. 요약에서 Fix with AI로 에이전트에게 맡기거나, 직접 해결하고 다시 실행하세요.
- 리뷰 만들기 대화상자의 Generate pull request details with AI(AI로 PR 내용 생성)는 브랜치 diff와 커밋을 바탕으로 제목·설명·초안 여부를 써 줍니다. 생성된 글은 짧고 쉬운(ELI5) “문제/해결” 단락과, 연결된 이슈 안내(GitHub 이슈가 붙어 있으면
Fixes와Refs중 무엇을 쓸지)를 목표로 합니다. Orca는 내가 고른 base 브랜치를 유지하고, 빈 설명은 거부하며, 빈 본문이 나가지 않도록 분명한 오류를 보여 줘 다시 시도할 수 있게 합니다. 만들기 전에 각 칸을 꼭 검토하세요. - OMP(Orca가 지원하는 에이전트 프로그램 중 하나)가 선택된 액션 에이전트라면 Source Control AI가 이 생성 동작들을 OMP로 실행할 수 있습니다.
Amend(마지막 커밋 고치기)는 명시적으로만 합니다: Commit → Amend. 이미 푸시된 커밋은 사용자가 확인하지 않으면 Orca가 amend하지 않습니다.
Source Control 패널
사이드바의 Source Control(소스 관리) 패널은 지금 보고 있는 화면을 떠나지 않고 같은 동작을 할 수 있게 해 줍니다. 파일을 스테이징하거나 변경을 버리고(discard), 커밋 메시지를 쓰고, Commit · Push · Pull · Sync를 한 번 클릭으로 실행합니다.
- Push(푸시) — 내 서랍의 봉투를 학교 사물함(원격)으로 갖다 넣기.
- Pull(풀) — 사물함에 있는 봉투(다른 사람이나 다른 컴퓨터가 넣은 것)를 내 서랍으로 가져오기.
- Sync(싱크) — 가져오기와 올리기를 함께 하기. 양쪽에 다 새 봉투가 있을 때 씁니다.
- upstream — 내 서랍과 짝으로 정해진 사물함 칸. 처음 Push할 때 정해집니다.
→ main+128 −34
맨 위 줄에는 지금 브랜치와 합칠 대상(branch → base)이, 그 옆 작은 칩에는 늘어난/줄어든 줄 수가 보입니다.
Source Control 패널 세부 동작 (경로 표시 · Stage all · 칩 · 복사)
- 경로에 한글 같은 비ASCII 문자가 있어도 UTF-8로 제대로 표시됩니다.
- Stage all은 바뀐 파일 목록이 화면에서 잘려(개수 제한) 보이더라도 모든 변경을 스테이징합니다. 호스트가 전체 경로를 직접 찾아내기 때문입니다.
- 브랜치 정보 줄(맨 위): 현재 브랜치(또는 detached HEAD — 브랜치가 아닌 특정 커밋에 서 있는 상태)를 위에, 비교 base를 아래에(branch → base) 쌓아 보여 줍니다. 그래서 Create PR이나 원격 동작 중에도 어느 브랜치에 있는지 가려지지 않습니다.
- 쓸 수 있는 merge base가 있으면 작은 칩이 그 분기점 대비 추가/삭제된 줄 수 합계를 보여 줍니다. 스테이징/비스테이징을 따로 더한 값이 아니라 범위 diff 하나로 계산합니다.
- 칩에 마우스를 올리면, 호스트가 나눈 값을 제공할 때 Code breakdown이 보입니다: Source(소스), Tests(테스트), Generated(자동 생성, 0이 아닐 때만). 내용 분석이 아니라 경로 기준 추정입니다.
- 긴 브랜치 이름은 칩을 가리지 않도록 잘려 보입니다.
- 바뀐 파일을 우클릭하면 Copy Path / Copy Relative Path(워크트리 루트 기준 상대 경로)를 쓸 수 있습니다.
패널 맨 아래 주 버튼은 상태에 따라 바뀌어서, 다음에 할 일이 항상 클릭 한 번 거리에 있습니다.
충돌이 났을 때
병합 충돌(두 쪽이 같은 줄을 다르게 고쳐서 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가 움직이는 버튼들이 어떤 지시문으로 어떤 에이전트를 부를지 바꾸는 설정입니다. 기본값 그대로 써도 되므로 처음에는 건너뛰어도 됩니다.
Action recipes 상세 — 편집 위치 · 템플릿 변수 · 저장소별 덮어쓰기
Generate with AI, Generate pull request details with AI, Fix with AI, Resolve with AI는 모두 Source Control AI 액션입니다. 각각 액션 레시피가 뒤에 붙어 있어서, 버튼을 누를 때 어떤 에이전트를, 어떤 CLI 인자로, 어떤 프롬프트 템플릿으로 실행할지 정합니다.
- 편집 위치: Settings → Git & Source Control → Action recipes. 전역 기본값으로 하거나 현재 저장소에만 적용할 수 있습니다.
- Model(모델)과 Effort(노력 수준)는 전용 칸에서 고릅니다. 예전에 Arguments(인자)에 저장해 둔 모델·effort 플래그는 자동으로 이 칸들로 옮겨집니다.
| 쓰는 곳 | 템플릿 변수 |
|---|---|
| 커밋 메시지 | {basePrompt} {branch} {stagedFiles} {stagedPatch} {linkedIssue} |
| PR 내용(위 변수에 더해) | {baseBranch} {currentTitle} {currentBody} {commitSummary} {changedFiles} {patch} |
Fixes #{linkedIssue}라고 쓰면 연결이 없을 때 Fixes #가 되어 버립니다. “연결된 이슈가 있으면 Fixes 줄을 넣어라”처럼 지시하는 문장으로 쓰는 편이 좋습니다.어떤 저장소가 한 액션에 자기만의 레시피를 갖고 있으면, 전역 기본값을 저장해도 그 저장소 레시피는 바뀌지 않습니다. 설정 화면에 Repository overrides(저장소별 덮어쓰기) 안내가 나타나 어떤 저장소가 무엇(에이전트, CLI 인자, 명령 템플릿)을 다르게 쓰는지 알려 주고, Review 링크로 그 저장소 설정으로 바로 가서 덮어쓰기를 수정하거나 지울 수 있습니다.
호스팅 리뷰 · 이슈 · Actions (GitHub · GitLab · Bitbucket 외)
GitHub(코드를 올려 두고 함께 검토하는 웹사이트)·GitLab·Bitbucket 같은 서비스에서 하는 코드 검토를 호스팅 리뷰라고 합니다. Orca에서는 이것이 워크트리에 기본으로 딸린 기능입니다. 워크트리를 그 PR/MR과 연결하고, 리뷰 상태를 화면 안에 보여 주며, 앱을 떠나지 않고 이슈(할 일·버그 신고 카드)를 정리(triage — 우선순위 매기고 나누기)할 수 있게 합니다.
PR 하나의 일생
- 만들기워크트리를 푸시한 뒤 Source Control에서 PR을 만듭니다(처음엔 초안으로 둘 수 있음).
- 검토·체크동료의 코멘트와 자동 검사 결과가 Orca의 PR 화면·Checks 패널에 모입니다. 거기서 바로 답글을 달 수 있습니다.
- 병합조건이 맞으면 병합합니다. GitHub에서는 “조건이 충족되면 알아서 합치기(자동 병합)”도 켤 수 있습니다.
제공자(provider) 연결하기
제공자(코드를 맡아 두고 PR·이슈를 주고받는 서비스 — GitHub·GitLab 같은 곳)는 저장소마다 다릅니다. 저장소가 쓰는 서비스를 Settings → Integrations(설정 → 연동)에서 연결합니다.
GitHub는 Orca가 가장 많은 기능을 지원하는 서비스입니다(특히 Actions와 이슈). 자동 병합, 스택 PR, 반응(이모지), Fix broken checks, Projects 보기 등은 GitHub 전용입니다.
GitLab의 MR과 이슈도 같은 워크트리 리뷰 흐름을 씁니다.
SSH 워크트리에서 GitLab 쓰기 (GITLAB_HOST)
Workspace(워크스페이스 — 워크트리와 같은 것)가 SSH(원격 서버에 접속하는 방법)로 원격 서버에 있으면, GitLab MR·이슈 동작이 그 서버에 설정된 환경 변수(프로그램이 읽어 가는 컴퓨터 쪽 설정값) GITLAB_HOST를 거치므로, 쓰기 요청이 올바른 GitLab 서버로 갑니다.
같은 설정 화면에서 앱 안에서 연결합니다. Connect with Email & API token(이메일과 API 토큰(비밀번호 대신 쓰는 출입증 문자열)) 또는 Access token(액세스 토큰) 중 하나로 연결하며, Orca가 저장 전에 자격 증명을 확인합니다. Source Control에서 PR을 만들 수 있고, 초안 PR이 없어서 작성 화면에 Draft 토글이 없습니다.
관리자용: 환경 변수가 우선
환경 변수(프로그램이 읽어 가는 컴퓨터 쪽 설정값) ORCA_BITBUCKET_*가 있으면 화면에서 저장한 자격 증명보다 그것이 우선합니다.
Azure DevOps와 Gitea(GitHub와 같은 종류의 코드 저장·검토 서비스)의 PR도 GitHub·GitLab·Bitbucket과 나란히 워크트리 사이드바와 Checks 패널에 나타납니다. 워크트리 생성 흐름은 푸시 전에 이들에서도 원격 충돌을 확인합니다.
리뷰(PR/MR) 다루기
PR을 만들고, 상태를 보고, 코멘트에 답하고, 브라우저로 열고, 초안을 “검토 준비 완료”로 바꾸는 일을 모두 Orca 사이드바·PR 화면에서 합니다.
리뷰 다루기 세부 기능 13가지
- 워크트리가 푸시되면 Source Control 패널에서 호스팅 리뷰를 엽니다. 만들기 전에 base 브랜치·제목·설명·초안 여부를 확인하세요.
- 리뷰를 만들거나 여는 동안에도 Source Control의 브랜치 정보 줄에 현재 브랜치가 계속 보입니다. Create PR 동작이 브랜치 라벨을 대신 차지하지 않습니다.
- 연결된 리뷰는 사이드바에 상태(열림 · 병합됨 · 닫힘)와 함께 표시됩니다.
- 연결된 PR/MR의 URL을 알면 브랜치 정보 줄에 작은 Open review page in browser(브라우저에서 리뷰 페이지 열기) 링크가 생깁니다. 내부 PR 화면을 거치지 않고 GitHub·GitLab·Bitbucket·Azure DevOps·Gitea의 리뷰 페이지로 바로 갑니다.
- 연결된 리뷰나 이슈의 더보기(overflow) 메뉴에서 Open in Orca browser를 고르면, 터미널이나 작업 화면을 떠나지 않고 현재 워크트리의 브라우저 탭에서 엽니다.
- GitHub PR은 사이드바의 PR 동작 메뉴에서 리뷰 링크 복사, 닫기, (상태 변경을 확인한 뒤) 다시 열기를 할 수 있습니다.
- 초안 상태의 GitHub PR과 GitLab MR은 사이드바 동작에서 Mark ready for review(검토 준비 완료로 표시) 또는 Close를 할 수 있습니다. GitLab에서는 이 동작이 Draft/WIP 상태를 없앱니다. 초안인 동안에는 병합과 자동 병합을 쓸 수 없습니다.
- 연결된 GitLab MR은 Checks 사이드바의 리뷰 링크 메뉴에서 Unlink MR(연결 해제) 또는 Link another MR(다른 MR 연결)을 할 수 있습니다.
- GitHub의 체크·리뷰·코멘트는 PR 탭 안에서 열립니다. GitLab MR과 이슈도 같은 리뷰 화면에서 열립니다.
- GitLab 파이프라인의 경우 Checks 패널에 최상위 작업뿐 아니라 bridge·child 파이프라인 작업도 나옵니다. 작업을 펼치면 가능할 때 그 작업의 trace(로그)를 불러옵니다(GitHub 체크 상세가 열리는 곳과 같은 자리). 실패한 작업이 “상세 없음”으로 막히지 않습니다.
- Checks 패널에서는 리뷰 스레드의 첫 코멘트뿐 아니라 아무 코멘트에나 답할 수 있습니다.
- GitHub PR 대화 코멘트와 줄 단위 리뷰 스레드 코멘트에는 GitHub의 반응 8가지(👍 👎 😄 😕 ❤️ 🎉 🚀 👀)를 고르는 선택기가 있습니다. 이미 있는 반응 칩은 눌러서 켜고 끕니다. GitLab 코멘트는 바뀌지 않았습니다.
- 묶어 보여 주는 PR 코멘트 구역은 최신순이라 새 답글이 달린 스레드가 위로 올라옵니다. Timeline 탭은 그대로 오래된 순입니다.
- GitHub PR에 실패한 체크가 있으면 PR 화면의 Fix broken checks(깨진 체크 고치기)로 실패한 체크 이름과 링크를 에이전트에게 넘깁니다.
자동 병합 (Auto-merge)
열려 있는 GitHub PR에서 PR 화면의 병합 버튼은 Enable auto-merge(자동 병합 켜기)를 제공합니다. 요구 조건(체크 통과, 필수 리뷰 승인)이 충족되면 GitHub가 알아서 브랜치를 병합합니다. 같은 버튼으로 끌 수도 있습니다.
자동 병합 방식 · merge queue · 버튼이 숨는 경우
- 병합 방식은 저장소 기본값을 따르며 Squash and merge(커밋을 하나로 합쳐 병합), Create merge commit(병합 커밋 만들기), Rebase and merge(커밋들을 base 위로 옮겨 병합) 중 하나입니다. 저장소가 막아 둔 방식은 보이지 않습니다.
- 같은 버튼의 Disable auto-merge로 대기 중인 자동 병합을 취소합니다.
- base 브랜치가 GitHub의 merge queue(병합 대기열)를 쓰면 같은 버튼이 Merge when ready로 바뀌고, PR을 대기열에 넣습니다.
- GitHub가 초안·닫힘·충돌·불안정(unstable)으로 보고한 PR, 그리고 자동 병합을 허용하지 않는 저장소에서는 자동 병합 버튼이 숨겨지고 수동 병합만 보입니다.
스택 PR (Stacked pull requests)
스택 PR은 PR 위에 PR을 쌓는 방식입니다. 큰 작업을 작은 PR 여러 개로 나누고, 각 PR이 바로 아래 PR을 base로 삼습니다.
GitHub 전용 기능입니다. PR을 만들 때 “#N 위에 쌓기”를 고르면 스택이 되고, 병합 버튼은 지금 PR과 그 아래 PR들을 한꺼번에 합칩니다. 하나라도 합칠 수 없으면 아무것도 합치지 않습니다.
스택 PR 세부 동작 (작성 화면 라벨 · Stack 지도 · 병합 라벨)
- GitHub PR을 만들 때 고른 base에 이미 열린 PR이 있으면 작성 화면이 Stack this PR above #N을 제안합니다. 체크하면 GitHub Stack을 새로 만들거나(또는 부모의 기존 스택을 늘리고), 제출 버튼 라벨이 Create PR in stack(또는 Create draft PR in stack / Push & Create PR in stack)으로 바뀝니다. 작은 미리보기가 부모 PR과 새 브랜치를 보여 줍니다.
- 이 옵션은 GitHub 전용이고, 실행 중인 호스트가 스택 생성을 지원할 때만 나타납니다. GitLab MR과 Bitbucket PR은 하나씩만 만듭니다.
- GitHub가 PR을 스택의 일부로 등록하면, PR 사이드바에 접을 수 있는 Stack #N 지도가 나옵니다: 스택 안 내 위치, 스택 크기, 스택 base 브랜치. 펼치면 순서대로 늘어선 층과 상태(open, draft, checks pending/failed, review needed, conflicts, merged, closed)가 보입니다. 층을 클릭하면 그 PR을 Orca에서 엽니다.
- 스택을 아는 병합은 단일 PR 병합 라벨 대신 Merge through #N · M PRs(merge queue를 쓰면 Queue through #N · M PRs)를 보여 줍니다. 현재 PR과 그 아래 모든 PR을 다룹니다. 스택 정보가 완전하면 확인 창에 포함된 번호들이 나열됩니다.
- GitHub에 스택으로 등록되지 않은 평범한 의존 PR 사슬은 일반 단일 PR 병합을 그대로 씁니다. GitLab MR은 바뀐 것이 없습니다.
이슈 (Issues)
이슈 패널(화면 옆에서 밀려 나오는 패널. 원문 이름 issue drawer)에서 GitHub와 GitLab 이슈를 둘러보고, 거르고, 편집합니다. 이슈에서 바로 워크트리를 만들면 이슈와 작업이 서로 연결됩니다.
이슈에서 워크트리 만들기 · Activity · GitLab 이슈 목록
- GitHub 이슈나 PR에서 워크트리를 만들면 조용히 백그라운드에서 만드는 대신 대화형 워크트리 작성 화면(composer)이 열립니다. 그래서 issue-command 자동화, SSH 대상, 폴더 워크트리가 다른 생성 경로와 똑같이 동작합니다. 작성 화면은 작업 이름을 미리 채우고 이슈를 연결해, 리뷰가 그 작업에 계속 붙어 있게 합니다.
- GitHub 이슈의 상세 창에는 Activity 구역이 있어 코멘트와 타임라인 이벤트(담당자 지정, 멘션, 교차 참조, 상태 변경, 프로젝트 칼럼 이동)를 섞어 시간순으로 보여 줍니다.
- 워크트리 사이드바의 연결된 이슈 메뉴에서 이슈 패널을 열지 않고 이슈 링크를 복사할 수 있습니다.
- GitLab 저장소에서는 이슈 패널이 선택한 프로젝트의 열린 이슈를 보여 주고, 나에게 배정된 이슈만 남길 수 있습니다.
Actions (CI)
실패한 GitHub Actions 체크는 워크트리에 빨간 칩으로 표시됩니다. 클릭하면 실패한 작업의 로그를 화면 안에서 바로 봅니다.
Tasks — GitHub Projects 보기
사이드바의 Tasks(작업) 항목에서 GitHub Projects(GitHub의 작업 보드) 전체 보기를 씁니다. 여러 저장소에 걸친 프로젝트 카드를 보고, 출처 저장소로 거르고, 초안 PR 상태를 보고, 아무 카드에서나 워크트리를 만들 수 있습니다. Board(보드) 보기는 칸반(포스트잇을 칸별로 옮기는 보드)으로 그려져 카드를 끌어 옮길 수 있고, 놓으면 카드의 상태(status) 필드가 프로젝트에 다시 기록됩니다. 표(table)와 그 밖의 보기는 목록 형태를 유지합니다.
gh auth(GitHub CLI 로그인), 권한, 네트워크 문제일 수 있습니다 — 문서의 “Troubleshooting GitHub errors” 항목을 참고하세요.Jira 연동 — Jira 이슈 패널
무엇인가. Jira(이슈 = 할 일·버그 카드를 관리하는 서비스) Cloud 또는 자체 설치(Server/Data Center — 회사 서버에 직접 설치한 Jira) Jira의 이슈를 Orca 안에서 둘러보고, 고치고, 워크트리와 연결합니다. Linear나 GitHub 항목을 연결하는 방식과 똑같습니다. Jira는 작업 패널(화면 옆에서 밀려 나오는 패널. 원문 이름 task drawer)에서 GitHub·Linear 옆에 자리합니다.
Jira 사이트 연결하기
- Tasks에서 Jira 고르기사이드바 Tasks를 열고 출처 선택기에서 Jira를 고릅니다. 자격 증명을 저장하기 전에도 Jira는 기본으로 GitHub·Linear 옆에 있습니다.
- Connect Jira누르면 Connect Jira site 대화상자가 뜹니다.
- Cloud 또는 Self-hosted 선택아래 탭에서 각각 넣을 값을 확인하세요. 대부분은 주소 + 이메일 + 토큰(비밀번호 대신 쓰는 출입증 문자열)입니다.
- ConnectOrca가 자격 증명을 확인하고 사이트를 불러옵니다.
| Jira Cloud site URL | 예: https://example.atlassian.net |
|---|---|
| Atlassian email | Atlassian 계정의 이메일 주소 |
| Atlassian API token | 비밀번호 대신 쓰는 출입증 문자열. id.atlassian.com → Security → API tokens에서 만듭니다. |
| Jira base URL | Server/DC의 기본 주소. Jira가 /가 아닌 하위 경로에 있다면 그 경로까지 넣습니다. |
|---|---|
| Auth method (로그인 방식) | Personal access token — Bearer PAT(개인 액세스 토큰(나 한 사람용 출입증 문자열)). 최신 Server/DC에서 권장. Username and password — PAT가 없는 오래된 버전용 Basic 인증(아이디·비밀번호를 그대로 보내는 가장 기본적인 로그인 방식). |
- Atlassian 사이트를 여러 개 연결할 수 있습니다. 사이트가 연결되면 Tasks 머리글에 사이트 선택기가 생기고, All sites를 고르면 여러 사이트 이슈를 합쳐 봅니다.
- Jira를 전혀 안 쓴다면 Settings → Tasks에서 출처 선택기에서 숨길 수 있습니다.
Jira 쓰기
GitHub·Linear·Jira 이슈가 한 목록에 모이고, 이슈를 열어 상태·담당자를 고치거나 코멘트를 달고, 이슈에서 바로 워크트리를 만들 수 있습니다. 검색창에는 평범한 단어를 넣어도 됩니다.
Jira 쓰기 세부 기능 (JQL 검색 · 새 이슈 대화상자 · URL 붙여 넣기 · 출처 기억)
- 각 출처를 켜면 작업 패널이 GitHub·Linear·Jira 이슈를 하나의 목록으로 보여 줍니다.
- 검색창은 JQL(Jira 전용 검색 문법. 예: project = ABC AND status = Done)만이 아니라 평범한 단어도 받습니다. JQL 연산자가 없으면 이슈 본문을 검색하고(단어 일부도 일치),
ABC-1처럼 이슈 키 모양이면 그 이슈를 먼저 찾은 뒤 없으면 본문 검색으로 넘어갑니다. JQL처럼 보이는 검색을 Jira가 400 오류로 거부하면 Orca는 본문 검색 결과를 대신 보여 주고, Jira가 밝힌 이유는 Details 안에 둡니다. - 이슈를 열면 옆 패널에서 전체 설명·코멘트·메타데이터를 봅니다. 상태(가능한 전환(transition)으로), 우선순위, 담당자, 사용자 정의 필드를 그 자리에서 고칩니다.
- 패널의 코멘트 작성란에서 코멘트를 추가합니다.
- New Jira issue 대화상자는 실수로 닫아도(Esc, Cancel, 바깥 클릭, 닫기) 제목과 설명을 기억합니다. 같은 앱 세션에서 다시 열면 글이 돌아오고, 생성에 성공하면 지워지며, 앱을 다시 시작하면 남지 않습니다. 이슈 유형 등 다른 선택기는 평소처럼 열 때의 기본값을 씁니다.
- 같은 대화상자에서 담당자를 미리 정할 수 있습니다: Automatic(프로젝트 기본값), me(나), 또는 배정 가능한 사용자 검색. 이 선택기는 Jira 생성 화면이 담당자를 받을 때만 나타나며, 고른 프로젝트와 사이트 범위로 제한됩니다.
- Jira 이슈에서 워크트리를 만들면 작업 이름이 미리 채워지고 워크트리가 이슈와 연결되어, 리뷰와 이슈가 함께 묶입니다.
- Create workspace(워크트리 만들기) 대화상자의 이름 칸에 Jira 이슈 URL(
https://…/browse/ABC-123)을 붙여 넣거나, 칸을 Jira search로 바꿔 글자로 이슈를 고를 수도 있습니다. Orca가 워크트리 이름을 채우고 이슈를 연결하며, 워크트리 카드에 키와 요약, View on Jira를 보여 줍니다. 붙여 넣기는 여러 사이트를 고려합니다. URL 주소와 맞는 연결 사이트가 둘 이상이면 어느 사이트인지 묻고, 하나도 없으면 연결되지 않은 사이트라고 알려 줍니다. - Orca는 저장소마다 마지막으로 쓴 작업 출처를 기억해서, Jira 중심 저장소는 다음에 열 때 Jira가 기본입니다.
Linear 연동 — Linear 이슈 패널
Linear(이슈·프로젝트 관리 서비스)는 작업 패널(화면 옆에서 밀려 나오는 패널)에서 GitHub 같은 호스팅 리뷰 서비스 옆에 있습니다. GitHub 이슈처럼 Linear 이슈를 둘러보고, 만들고, 고치고, 워크트리와 연결합니다.
설정
- Settings → Integrations → Linear설정의 연동 화면에서 Linear를 엽니다.
- API 토큰 붙여 넣기Linear의 Settings → API에서 만든 개인 API 토큰(비밀번호 대신 쓰는 출입증 문자열)을 붙여 넣습니다.
- 팀 고르기보고 싶은 팀(들)을 고릅니다.
Linear 쓰기
한 목록
작업 패널이 GitHub와 Linear 이슈를 하나로 합쳐 보여 줍니다.
이슈 → 워크트리
이슈에서 워크트리를 만들면 이름과 브랜치 이름이 미리 채워지고 이슈가 연결됩니다.
그 자리에서 고치기
상태·담당자·우선순위·라벨·추정치를 Orca 안에서 바꿉니다.
그림도 에이전트에게
이슈 속 이미지가 에이전트 프롬프트에 함께 들어갑니다.
Linear 쓰기 세부 기능 (Has Workspace · 이슈 다시 연결 · 대화상자 기억 · 화면 배치 저장)
- 작업 패널이 GitHub와 Linear 이슈를 하나로 합쳐 보여 줍니다.
- Linear 작업 보기의 Has Workspace 모드는 이미 로컬 워크트리나 폴더 워크트리에 연결된 이슈만 보여 줍니다. 워크트리가 붙은 줄을 누르면 그 워크트리가 열리고, 두 번째 작업본이 필요하면 같은 이슈에서 새로 시작할 수도 있습니다.
- Linear 이슈에서 워크트리를 만들면(GitHub 항목과 같은 경로로) 대화형 워크트리 작성 화면이 열려 issue-command 자동화·SSH·폴더 워크트리가 적용됩니다. Orca가 이름을 미리 채우고 이슈 ID를 붙입니다. Linear가 이슈의 브랜치 이름을 제공하면 제목을 줄인 이름 대신 그것을 워크트리 브랜치로 씁니다(Linear가 제안하는 것과 같은 이름). 이슈 상세 메뉴에서 Copy suggested branch name(제안 브랜치 이름 복사)도 할 수 있습니다.
- 만든 뒤에는 워크트리 카드의 Edit Worktree Details를 열고 Issue 칸에서 Linear 칩을 쓰거나 Linear URL을 붙여 넣어, 워크트리를 다시 만들지 않고 이슈를 연결·변경합니다. GitHub와 Linear는 이 한 칸을 함께 쓰므로, 새 링크를 저장하면 이전 제공자의 링크가 대체됩니다.
- 이슈 상세 보기에서 상태, 담당자, 우선순위, 라벨, 추정치(estimate)를 고칩니다. 우선순위는 Linear 고유 아이콘으로 표시되어 Linear 화면과 똑같아 보입니다.
- Linear 이슈에서 에이전트를 실행하면, 이슈 설명·코멘트·하위 이슈에 들어 있는 이미지와 미디어가 프롬프트 맥락에 함께 들어갑니다. 시안이나 버그 재현 화면을 직접 캡처해 붙일 필요가 없습니다. 이슈 설명 속 비공개 Linear 이미지도 깨진 그림 대신 패널에 제대로 뜹니다.
- New Linear issue와 New Linear project는 실수로 닫아도(Esc, Cancel, 바깥 클릭, 닫기) 제목·설명(프로젝트는 이름·요약·brief까지)을 기억합니다. 같은 앱 세션에서 다시 열면 돌아오고, 생성에 성공하면 지워지며, 앱 재시작 후에는 남지 않습니다. 팀/프로젝트 선택기는 열 때의 기본값을 씁니다.
- 긴 목록은 Load more(더 불러오기)로 나눠 불러옵니다.
- 화면 배치 선택은 재시작 후에도 유지됩니다: 목록/보드, 묶기(group-by), 정렬(order-by), 보이는 칼럼, 속성 필터. 속성 필터는 Linear 워크스페이스(Linear 쪽 팀 공간)별로 저장되어, Linear 워크스페이스를 바꿔도 다른 곳의 필터가 섞이지 않습니다.
- Orca는 저장소마다 마지막으로 쓴 작업 출처(GitHub, Linear, Jira)를 기억합니다.
에이전트와 CLI
에이전트도 명령으로 Linear 이슈를 읽고 쓸 수 있습니다.
orca linear 명령 · 스킬 · 플래그
에이전트는 orca linear 명령(과 orca-linear 스킬)으로 Linear를 읽고 쓸 수 있습니다. 여기에는 MCP 호환 생성/수정과 목록 필터(save-issue, list-issues, relation add/remove)와 이슈 맥락 플래그(--activity, --full)가 포함됩니다. 자세한 것은 CLI 레퍼런스의 Linear 항목을 보세요.
레시피: 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·후속 코멘트 → 깨끗해지면 커밋. 코드를 모르면 바뀐 범위 확인 · “쉬운 말로 설명해 줘” 코멘트 · 결과 화면 확인으로 대신합니다.
출처: onorca.dev/docs/review/diff-viewer · onorca.dev/docs/review/annotate-ai-diff · onorca.dev/docs/review/attribution · onorca.dev/docs/review/commit-push · onorca.dev/docs/review/github · onorca.dev/docs/review/jira · onorca.dev/docs/review/linear · onorca.dev/docs/recipes/review-ai-diff
Orca CLI와 자동화 — 명령, 예약 작업, 오케스트레이션, Computer Use, 스킬
마우스로 하던 Orca 조작을 글자 명령으로 할 수 있게 해 주는 orca 명령줄 도구를 배웁니다. 사람이 스크립트로 쓸 수도 있고, AI 에이전트가 직접 Orca를 움직이는 데도 씁니다.
- CLI(명령줄)가 무엇이고, “에이전트가 Orca를 조작한다”는 말이 무슨 뜻인지
orca명령 설치·확인 방법과 선택자(selector)·호스트 지정법- 분야별 명령 레퍼런스 — 런타임, 저장소, 워크트리, 터미널, 파일, 브라우저, 에뮬레이터, Linear, 아티팩트 등
- 예약 자동화(
orca automations)로 정해진 시간에 프롬프트 실행하기 - 오케스트레이션 — Run·Task·Dispatch·Message·Decision gate로 여러 에이전트를 감독하며 일 나누기
- Computer Use — 에이전트가 데스크톱 앱을 접근성 트리로 조작하기
- 스킬 레지스트리와 MCP, 그리고 진행 상황을 남기는 워크트리 체크포인트
- CLI란 무엇이고, 왜 에이전트가 Orca를 조작하나 — “런타임”이 무엇인지, 명령 한 줄을 어떻게 읽는지(해부도 그림).
- 설치·등록과 동작 확인 — 설정에서 켜고
orca status --json으로 확인하는 두 단계. - 오케스트레이션 — 여러 에이전트를 감독하며 일 나누기 — 비유와 포함 관계 그림으로 보는 큰 그림. 명령은 주로 에이전트가 칩니다.
- 워크트리 체크포인트 — 진행 상황 남기기 — 에이전트가 진행 상황을 카드에 남기는 방법.
건너뛰어도 되는 곳: 명령 레퍼런스는 에이전트·스크립트가 찾아보는 사전입니다. 🔧 표시가 붙은 접힌 상자도 처음엔 열지 않아도 됩니다.
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 스킬(에이전트용 사용 설명서)을 설치할 수 있습니다. 스킬은 뒤의 스킬 레지스트리에서 다룹니다.
PATH 우선순위와 스킬 설치 명령
PATH(터미널이 명령어 프로그램을 찾는 폴더 목록. 앞에 있는 폴더가 먼저 쓰입니다) — 셸 시작 파일(.zshrc 등)이 예전에 따로 설치한 전역 orca를 PATH에 넣더라도, Orca는 자기 터미널 안에서는 자신의 orca를 항상 맨 앞에 둡니다. 그래서 스크립트와 에이전트는 지금 실행 중인 앱과 버전이 맞는 CLI를 부르게 됩니다.
npx skills add https://github.com/stablyai/orca --skill orca-cli
# 설정 화면이 없는 헤드리스 환경:
orca skills install --skill orca-cli
선택자(selector)와 호스트 고르기
< >— 바꿔 넣는 칸입니다.<repoId>는 글자 그대로 치는 게 아니라, 그 자리에 실제 저장소 ID를 넣으라는 뜻입니다(꺾쇠는 지웁니다).#— 그 뒤는 설명 메모입니다. 실행되지 않습니다.\— 줄 끝의 역슬래시는 “다음 줄로 이어짐”입니다. 긴 명령을 보기 좋게 여러 줄로 나눈 것일 뿐, 한 줄짜리 명령입니다.a|b— 옵션 설명 속 세로 막대는 “a 또는 b 중 하나”입니다.
대부분의 명령은 긴 ID 대신 선택자(selector — “어떤 워크트리·저장소를 말하는지”를 짧게 가리키는 표현)를 받습니다. 사람에게 “그 파일” 대신 “3층 회의실 왼쪽 책상의 파란 파일”이라고 정확히 짚어 주는 것과 같습니다.
| 선택자 | 뜻 | 예 |
|---|---|---|
id:<repoId> | ID로 지정 | orca repo show --repo id:<repoId> --json |
active / current | 지금 셸의 현재 폴더나 터미널이 속한, Orca가 관리하는 워크트리 | orca worktree show --worktree active --json |
path:/abs/path | 절대 경로로 지정 | orca worktree show --worktree path:/abs/path/to/worktree --json |
branch:이름 | 브랜치 이름으로 지정 | orca worktree show --worktree branch:feature-name --json |
issue:번호 | 연결된 이슈 번호로 지정 | orca worktree show --worktree issue:123 --json |
name:이름 | Workspace(워크스페이스 — 워크트리와 같은 것) 이름으로 지정(References 예시에 등장) | --worktree name:api |
active·current는 “지금 내가 서 있는 곳”을 기준으로 합니다. 대상 워크트리 밖에서 실행될 수도 있는 스크립트라면 id:·path: 같은 명시적 선택자를 쓰세요.
원격 런타임에서의 선택자
원격 런타임(다른 컴퓨터에서 켜져 있는 Orca)이라면 내 컴퓨터의 현재 폴더가 원격 호스트에 없을 수 있으므로 id:<repoId>::<absolute-worktree-path>나 path:<absolute-server-path>처럼 서버 쪽 전체 선택자를 쓰는 게 좋습니다.
어느 컴퓨터에서 실행할지(호스트) 고르기
호스트(명령이 실제로 실행되는 컴퓨터)는 내 컴퓨터일 수도, 다른 컴퓨터일 수도 있습니다. orca host list --json은 지금 Orca가 대상으로 삼을 수 있는 모든 컴퓨터와 각각의 선택자를 보여 줍니다. 결과에는 이 컴퓨터, 등록된 SSH(다른 컴퓨터에 안전하게 원격 접속하는 방법) 대상, 짝지어진(paired) Remote Orca Server가 포함됩니다.
호스트 지정 표와 이름 찾기 규칙
| 지정 방법 | 대상 |
|---|---|
--host local | 이 컴퓨터 |
--host ssh:<target-id> | SSH 대상 |
--environment <server-name> | 짝지어진 Remote Orca Server |
SSH 라벨과 서버 이름이 하나뿐이면 이름으로도 찾아집니다. 이름이 겹치면 host list의 ID를 쓰세요. 컴퓨터 이름을 엉뚱한 옵션에 넣으면 Orca가 빈 결과 대신 “이 컴퓨터는 이 옵션으로 지정하세요”라고 알려 줍니다.
명령 레퍼런스 — 분야별
여기는 에이전트·스크립트가 정확한 명령을 찾아보는 사전입니다. 처음 읽는다면 아래 지도와 탭마다 맨 위 한 문장(“이걸로 할 수 있는 일”)만 훑고 다음 절로 넘어가세요. 명령 목록은 탭 안의 🔧 접힌 상자에 있습니다. 모든 명령 끝의 --json은 “기계가 읽을 결과로 달라”는 뜻입니다.
이걸로 할 수 있는 일 — Orca를 켜고(open), 연결을 확인하고(status), 화면 없는 컴퓨터에서 Orca를 서버로 계속 돌려 둘(serve) 수 있습니다.
런타임·serve 명령 목록
orca open --json
orca status --json
orca serve --port 6768 --pairing-address 100.64.1.20 --json
orca serve --supervise --json
orca serve service install --port 6768 --dry-run
orca serve service status --json
orca serve service uninstall --json
orca serve restore resume --json
| 명령 | 하는 일 |
|---|---|
orca open | Orca를 엽니다. |
orca status | CLI가 런타임에 닿는지 확인합니다. |
orca serve | 데스크톱 창을 열지 않고 런타임 서버를 앞단(foreground)에서 띄웁니다. Remote Orca Server나 화면 없는(headless) 환경용이며 Ctrl-C로 멈춥니다. --port로 포트, --pairing-address로 짝짓기 주소를 정합니다. |
orca serve --supervise | 서비스 관리자용. 서버가 멈춰도 종료하지 않고 점점 늘어나는 간격으로 스스로 재시작하고, 앱 업데이트가 교체되는 동안 기다리며, 반복 실패하면 포기합니다. |
orca serve service install | 이 프로필용으로 orca serve --supervise --no-pairing을 실행하는 사용자 단위 서비스(macOS LaunchAgent, Linux systemd user unit)를 씁니다. --dry-run은 실제로 쓰지 않고 보여만 줍니다. |
orca serve service status | 서비스가 실행 중인지 알려 줍니다. |
orca serve service uninstall | 서비스를 멈추고 제거합니다. |
orca serve restore resume | 터미널 자동 복원에 걸린 일시정지를 풀고, 옛 클라이언트가 요청한 복원 목록을 보여 줍니다. |
이 serve·service·supervisor 명령들은 아직 Windows에서는 쓸 수 없고, service와 supervisor 명령은 그 컴퓨터에 Orca 앱이 설치돼 있어야 합니다. 자세한 건 Remote Orca Servers → orca serve as a service 문서를 보세요.
이걸로 할 수 있는 일 — Orca에 저장소(프로젝트 폴더)를 추가·확인하고, 지난 에이전트 대화 기록에서 “rate limit” 같은 낱말을 검색할 수 있습니다.
저장소·세션 검색 명령 목록
저장소(Repos)
orca repo list --json
orca repo add --path /abs/path/to/repo --json
orca repo show --repo id:<repoId> --json
orca repo set-base-ref --repo id:<repoId> --ref origin/main --json
orca repo search-refs --repo id:<repoId> --query main --limit 10 --json
list 목록, add 추가, show 상세, set-base-ref 기준 ref 지정, search-refs 브랜치·ref 검색입니다.
워크트리를 많이 만들기 전에 set-base-ref로 저장소의 기준 ref(브랜치나 커밋을 가리키는 이름. 예: origin/main)를 정해 두세요. 그래야 새 작업이 기본적으로 올바른 지점에서 갈라져 나옵니다.
세션 검색(Session search)
색인된 에이전트 대화 기록을 셸에서 검색합니다.
orca search --query "rate limit" --scope conversation --limit 20 --json
orca search --query "migration" --agent codex --since 30d --sort recent --json
orca search --index-status --json
| 옵션 | 뜻 |
|---|---|
--scope conversation|all | 대화 일치만, 또는 색인된 모든 텍스트 |
--fresh | 검색 전에 색인을 새로 고침 |
--limit, --cursor | 개수 제한, 다음 페이지 |
--agent, --path, --since, --sort | 에이전트·경로·기간·정렬로 좁히기 |
--index-status | 검색 없이 색인 상태만 보고 |
연결된 컴퓨터와 짝지어진 서버가 접근을 허락했다면, 그 호스트의 세션도 결과에 포함될 수 있습니다.
이걸로 할 수 있는 일 — 예: “fix-login이라는 워크트리를 만들고 Codex에게 ‘로그인 테스트를 조사해 줘’라고 바로 시켜라” — 이런 일을 한 줄로 시킬 수 있습니다.
워크트리 명령과 옵션 목록
orca worktree list --repo id:<repoId> --json
orca worktree ps --json
orca worktree current --json
orca worktree show --worktree active --json
orca worktree create --repo id:<repoId> --name fix-login --json
orca worktree create --name child-task --agent codex --prompt "Investigate the flaky login test" --json
orca worktree set --worktree active --comment "reproduced failure; testing token refresh fix" --json
orca worktree set --worktree active --workspace-status in-review --unread --json
orca worktree rm --worktree id:<worktreeId> --force --json
| 명령·옵션 | 뜻 |
|---|---|
list / ps / current / show | 저장소의 워크트리 목록 / 실행 현황 / 지금 워크트리 / 상세 |
create --name | 새 워크트리. --name은 워크트리 이름 |
--branch <branch> | 설정된 브랜치 접두어 없이 Git 브랜치 이름을 직접 지정. 이름이 겹치면 Orca가 숫자 꼬리를 붙일 수 있음 |
--parent-worktree active / --no-parent | Orca 관리 워크트리 안에서 create하면 관계를 추론할 수 있을 때 새 워크트리를 자식으로 기록합니다. 명시하려면 --parent-worktree active, 독립 작업이면 --no-parent |
--agent | 첫 터미널에서 선택한 에이전트를 실행 |
--prompt | 그 에이전트에게 첫 작업을 바로 보냄(터미널에서 도는 에이전트 포함) |
--setup run|skip|inherit | 저장소 setup 훅을 실행 / 건너뜀 / 저장소 정책을 따름 |
set --comment | 워크트리 메모(체크포인트) 기록 — 체크포인트 참고 |
set --workspace-status | 카드 상태 변경 |
set --unread / --read | 사이드바 워크트리에 “안 읽음” 점을 켬(에이전트가 끝났을 때 보이는 그 점) / 끔 |
rm --force | 워크트리 삭제 |
에이전트 시작 옵션 예
orca worktree create --name review-api --agent claude --setup run --json
orca worktree create --name quick-check --agent codex --prompt "Summarize the diff" --setup skip --json
orca worktree create --name hidden-setup --setup inherit --json
이슈·리뷰 연결
orca worktree create --repo id:<repoId> --name my-task --issue 123 --json
orca worktree create --repo id:<repoId> --name review-task --pr 123 --json
orca worktree create --repo id:<repoId> --name gitlab-task --gitlab-issue 42 --gitlab-mr 77 --json
orca worktree set --worktree active --gitlab-issue '#42' --gitlab-mr '!77' --json
orca worktree set --worktree active --pr null --gitlab-mr null --json
--pr: GitHub PR(Pull Request. 내 변경을 합쳐 달라고 요청하는 것) 번호.--issue: 이슈 번호.--gitlab-issue: 번호 또는#42.--gitlab-mr: 번호 또는!77(MR = GitLab의 Merge Request). HTTP(S) URL도 받으며 자체 호스팅·중첩 그룹도 됩니다. 단 URL의 호스트·프로젝트가 워크트리에 저장된 GitLab 출처나 저장소 원격과 일치해야 합니다.- 옵션을 빼면 그 링크는 그대로 둡니다.
set에서 글자 그대로null을 주면 그 링크만 지웁니다(create는null을 거부). - 제공자마다 필드가 따로라서 GitLab 링크를 바꿔도 GitHub·Linear 링크는 보존됩니다.
이걸로 할 수 있는 일 — 이미 있는 워크트리에서 에이전트를 하나 더 띄우거나, 워크트리에 PR·Linear 이슈 링크를 여러 개 붙여 두고 나중에 이슈 번호로 그 작업과 담당 에이전트를 찾을 수 있습니다.
에이전트 실행·References 명령 목록
기존 워크트리에서 에이전트 실행
orca agent launch --agent codex --json
orca agent launch --agent codex --model gpt-6-astra --effort high --prompt "Write the design doc" --json
orca agent launch --agent claude --worktree path:/projects/myapp --focus --json
- 새 에이전트 탭을 여는 것과 같은 방식으로 시작합니다. Chat UI 설정이 켜져 있고 에이전트·호스트가 지원하면 구조화된 채팅으로, 아니면 터미널로 열립니다. 결과의
outcome.kind가 어느 쪽이 열렸는지와 이유를 알려 줍니다. --worktree기본값은 현재 폴더를 포함한 워크트리/폴더 워크스페이스입니다. 완전히 새 체크아웃이 필요하면orca worktree create --agent를 쓰세요.--model과--effort(--model필요)는 두 화면 모두에 적용됩니다.- 탭은 포커스를 빼앗지 않고 열립니다. 보이게 하려면
--focus. - 응답을 못 받았다면 에이전트를 하나 더 띄우지 말고, 같은 호스트·같은 폴더에서 같은 명령에
--retry-launch <operationId>를 붙여 다시 실행하세요.
References — 워크트리에 리뷰·이슈 여러 개 연결
orca reference list --worktree name:api --json
orca reference add https://github.com/acme/api/pull/5123 https://linear.app/acme/issue/STA-1234 --worktree name:api --json
orca reference remove https://github.com/acme/api/pull/5123 --worktree name:api --json
orca reference remove --key '<key-from-list>' --worktree name:api --json
orca worktree create --name fix --reference https://github.com/acme/api/pull/5123 --reference https://linear.app/acme/issue/STA-1234 --json
orca reference find STA-1234 --json
- 저장소 밖의 출처도 연결할 수 있습니다. 쓰기는 전체 URL을 받고,
remove --key는 URL이 없는 옛 링크도 처리합니다. - 중복 추가·없는 것 삭제는 아무 일도 안 하며(no-op), 관련 없는 링크는 보존됩니다.
--pr·--gitlab-issue·--linear-issue같은 이슈 연결 옵션과--reference는 한 명령에 같이 쓸 수 없습니다.find는 전체 URL이나STA-1234같은 고유 키를 받습니다(숫자만은 거부). 저장된 메타데이터만 읽고(외부 요청·대화 검색 없음) 일치하는 워크트리와 연관 에이전트(연결 상태, 터미널·메일함 주소 포함)를 돌려줍니다. 대화 내용 검색은orca search.
찾은 에이전트에게는 명시적 주소로 메시지를 보냅니다.
orca terminal send --terminal '<terminal-from-find>' --text 'Status?' --enter
orca orchestration send --to '<mailbox-from-find>' --subject 'Status?' --type question
이걸로 할 수 있는 일 — 에이전트가 돌고 있는 터미널 화면을 읽고, “continue”를 입력해 주고, 일이 끝날 때까지 기다릴 수 있습니다.
터미널 명령 목록
orca terminal list --worktree active --json
orca terminal show --terminal <handle> --json
orca terminal read --terminal <handle> --json
orca terminal read --terminal <handle> --screen --json
orca terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json
orca terminal send --terminal <handle> --text "continue" --enter --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
orca terminal create --worktree active --title "tests" --command "npm test" --json
orca terminal split --terminal <handle> --direction horizontal --command "npm run dev" --json
orca terminal rename --terminal <handle> --title "runner" --json
orca terminal switch --terminal <handle> --json
orca terminal close --terminal <handle> --json
| 명령 | 하는 일 |
|---|---|
list / show | 터미널 목록 / 상세 |
read | 출력 읽기. 기본은 이스케이프 문자를 뺀 누적 출력 스트림이라, 줄을 다시 그리는 프로그램은 조각이 겹쳐 보일 수 있습니다. 지금 그려진 화면이 필요하면 --screen(응답의 source가 stream / screen / screen-unavailable 중 무엇인지 알려 줌). 화면 읽기는 넘길 기록이 없으므로 --screen과 --cursor는 함께 못 씁니다. |
read --cursor | 긴 출력은 한 번 읽을 때 받은 nextCursor를 저장했다가 다음에 넘겨 새 출력만 받습니다. |
send --text … --enter | 글자 입력 후 Enter |
wait --for tui-idle --timeout-ms | 에이전트 화면이 조용해질(일을 멈출) 때까지 대기 |
create / split | 새 터미널 / 화면 나누기(--direction horizontal|vertical), --command로 실행할 명령 |
rename / switch / close | 이름 바꾸기 / 전환 / 닫기 |
--terminal을 빼면 현재 워크트리의 활성 터미널이 대상입니다.- 터미널이 무엇을 기다리는지 모를 때는 보내기 전에 먼저 읽으세요.
핸들(터미널을 가리키는 짧은 이름)은 그 런타임에서만 유효합니다. Orca가 재시작됐거나 “오래된 핸들”이라는 오류가 나면 orca terminal list --json으로 다시 받으세요.
terminal list는 확인 가능할 때 각 터미널의 executionHostId와, 결과 수준의 hostScope(포함·제외된 호스트 ID)를 줍니다. 호스트 정보나 범위가 없으면 “로컬”이 아니라 “확인 불가”로 취급하세요. 터미널이 목록에 없다는 것은 그 실행 호스트가 hostScope.hostIds에 있을 때만 “종료됐다”는 증거가 됩니다.
그냥 터미널에 프롬프트를 보내지 말고 오케스트레이션을 쓰세요.
이걸로 할 수 있는 일 — 바뀐 파일이나 그 변경 내용(diff)을 Orca 화면의 탭으로 열어 줍니다.
파일 명령 목록
orca file open src/App.tsx --worktree active --json
orca file diff src/App.tsx --staged --worktree active --json
orca file open-changed --mode both --worktree active --json
- 경로는 선택한 워크트리 기준 상대 경로입니다. 셸의 현재 폴더가 대상 워크트리 안이 아니면
--worktree <selector>를 쓰세요. diff --staged: staged(git add로 커밋 대기열에 올린 상태)된 변경의 diff를 엽니다.open-changed: git status를 읽어 바뀐 파일을edit,diff,both모드로 엽니다.- 이 명령들은 화면을 바꾸지 않고 탭으로만 엽니다(지금 보고 있는 워크트리여도). 탭을 보이게 하려면
--focus— 에이전트는 사용자가 그 파일을 보고 싶다고 했을 때만 붙이세요.
이걸로 할 수 있는 일 — 사람이 웹 화면을 확인하듯, Orca 안의 내장 브라우저에서 주소로 이동하고, 입력칸을 채우고, 버튼을 누르고, 스크린샷을 찍을 수 있습니다.
브라우저 명령 목록
Orca 안에 있는 내장 브라우저 탭(선택한 워크트리의 것)을 조작합니다. Chrome·Safari나 Orca 데스크톱 UI 자체는 조작하지 않습니다.
orca goto --url http://localhost:3000 --worktree active --json
orca snapshot --worktree active --json # @e1, @e3 같은 ref를 돌려줌
orca click --element @e3 --worktree active --json
orca fill --element @e1 --value "user@example.com" --worktree active --json
orca wait --text "Welcome" --worktree active --json
orca screenshot --worktree active --json
snapshot → 행동 → 다시 snapshot 순환으로 씁니다. @e3 같은 ref는 snapshot에서 나옵니다. 페이지 이동, 탭 전환, 페이지를 바꾸는 클릭 뒤, 그리고 “오래된 ref” 오류가 나면 다시 snapshot하세요.
탭·기록(capture) 명령
orca tab list --worktree active --json
orca tab create --url http://localhost:3000 --worktree active --json
orca tab switch --index 1 --worktree active --json
orca capture start --worktree active --json
orca console --limit 50 --worktree active --json
orca network --limit 50 --worktree active --json
orca full-screenshot --worktree active --json
orca pdf --worktree active --json
console은 콘솔 로그, network는 네트워크 요청, full-screenshot은 페이지 전체 캡처, pdf는 PDF 저장입니다. 아직 전용 Orca 명령이 없는 브라우저 동작만 orca exec --command "<agent-browser command>" --json으로 실행하세요.
기기 흉내(반응형 확인)
orca set device --name "iPhone 12" --worktree active --json
orca screenshot --worktree active --json
브라우저 프로필
프로필은 탭의 세션 상태(쿠키, 로컬 저장소, 로그인한 신원)를 서로 분리해, 스크립트나 에이전트가 다른 계정으로 테스트할 수 있게 합니다. orca tab profile list --json으로 시작해 필요에 따라 create, set, clone, use-default를 씁니다.
이걸로 할 수 있는 일 — Orca 밖의 데스크톱 앱을 누르거나, iOS 시뮬레이터(컴퓨터 속 가상 아이폰)를 탭·회전할 수 있습니다.
Computer use·에뮬레이터 명령 목록
데스크톱 Computer use (요약)
orca computer permissions --json
orca computer list-apps --json
orca computer get-app-state --app com.apple.Safari --json
orca computer click --app com.apple.Safari --element-index 12 --json
orca computer paste-text --app com.apple.Safari --text "hello" --json
내장 브라우저 밖의 네이티브 데스크톱 앱용입니다. 전체 흐름과 권한 설정은 Computer Use 절에서 다룹니다.
모바일 에뮬레이터(iOS Simulator)
orca emulator list --worktree active --json
orca emulator attach "<device-name-or-udid>" --worktree active --json
orca emulator tap 0.5 0.7 --worktree active --json
orca emulator type "hello" --worktree active --json
orca emulator gesture '[{"type":"begin","x":0.5,"y":0.8},{"type":"move","x":0.5,"y":0.4},{"type":"end","x":0.5,"y":0.2}]' --worktree active --json
orca emulator button home --worktree active --json
orca emulator rotate landscape_left --worktree active --json
orca emulator exec --command "tap 0.5 0.7" --worktree active --json
orca emulator kill --worktree active --json
orca emulator shutdown --worktree active --json
- Orca의 워크트리 단위 브리지로 iOS Simulator를 조작합니다. Orca 안에서 일하는 에이전트는 날것의
serve-sim·simctl대신 이 명령을 써야 수명주기와 활성 기기 상태가 현재 워크트리에 붙어 있습니다. - 할 수 있는 일: 목록에서 시뮬레이터 연결(
attach), 탭, 글자 입력, 제스처, 하드웨어 버튼(button home), 회전, 종료(kill/shutdown). - 좌표는 화면 크기와 무관하게 0~1로 정규화됩니다(0.5 = 가운데). 한 번 누르기는
tap, 끌기나 여러 단계 터치는gesture. - 특정 시뮬레이터를 겨냥하려면
--device <udid-or-name>또는--emulator <id>, 워크트리를 지정하려면--worktree <selector>.
이걸로 할 수 있는 일 — 에이전트가 Linear(팀 업무 티켓 관리 서비스)의 티켓을 읽고, 상태를 “진행 중”으로 바꾸고, 댓글을 다는 등 티켓을 관리합니다.
Linear 명령 목록
Linear 명령은 에이전트가 orca-linear 스킬을 통해 쓰는 영역입니다(옛 설치 이름 linear-tickets도 동작). --json을 권장하고, 연결된 워크트리에서는 --current로 그 이슈를 가리킵니다. Orca에 연결되지 않은 워크트리 밖에서 돌 수 있는 스크립트는 ENG-123처럼 이슈 ID를 명시하세요.
읽기(Read) 명령
orca linear issue --current --full --json
orca linear issue ENG-123 --comments --children --relations --activity --json
orca linear search "auth bug" --workspace all --json
orca linear list --filter assigned --limit 10 --json
orca linear list-issues --team ENG --state started --assignee me --json
orca linear list-issues --query auth --updated-at -P7D --cursor <cursor> --workspace <id> --json
orca linear team list --json
orca linear team states --team ENG --json
orca linear team labels --team ENG --json
orca linear project list --query launch --json
--full은 댓글·하위 이슈·첨부·관계·활동을 모두 펼칩니다. 각각(--comments, --children, --attachments, --relations, --activity)만 따로 써도 됩니다.
MCP 방식 쓰기(save-issue, relation)
# id/--current를 빼면 새로 만들기(이때 --team, --title 필수)
orca linear save-issue --team ENG --title "Fix auth" --priority high --json
orca linear save-issue ENG-123 --state "In Progress" --assignee me --json
orca linear save-issue --current --project null --due-date null --json
orca linear relation add ENG-1 --related ENG-2 --type blocks --json
orca linear relation remove ENG-1 --related ENG-2 --type related --json
save-issue의 라벨은 전체 라벨 집합을 통째로 교체합니다(Linear MCP save_issue와 같은 의미). 글자 그대로 null은 담당자·추정치·마감일·프로젝트·상위 이슈를 지웁니다.
필드 도우미(여전히 유효)
orca linear status set --current --to "In Progress" --json
orca linear assignee set --current --me --json
orca linear priority set ENG-123 --to high --json
orca linear estimate set --current --to 3 --json
orca linear due-date set --current --to 2026-08-01 --json
orca linear label add --current --label backend --json
orca linear comment add --current --body "Investigating regression" --json
orca linear comment edit <commentId> --body "Investigating the regression" --json
orca linear comment delete <commentId> --json
orca linear attach --current --url https://example.com/repro --title "Repro" --json
orca linear create --title "Flaky login test" --team ENG --priority high --json
comment edit·comment delete는 정확한 Linear 댓글 ID를 대상으로 하며, comment rm은 delete의 별칭입니다. 바꿀 글을 파일이나 표준 입력에서 가져오려면 edit에 --body-file <path|->를 쓰세요.
버전에 맞는 전체 목록은 orca linear --help 또는 orca skills get orca-linear로 확인합니다.
이걸로 할 수 있는 일 — 에이전트용 설명서(스킬)를 설치하고, 원격 컴퓨터에 Claude/Codex 계정을 추가하고, 보고서 HTML·Markdown 파일을 공개 링크로 공유할 수 있습니다.
스킬·계정·아티팩트 명령 목록
Skills (로컬, 런타임 불필요)
orca skills list
orca skills get orca-cli
orca skills get orchestration --full
orca skills install --skill orca-cli --skill orchestration
orca skills install --all --dry-run
orca skills update --all
번들된 가이드 목록, 버전에 맞는 가이드 출력, 스킬 설치·업데이트를 설정 화면 없이 합니다. install/update는 설정 화면이 쓰는 것과 같은 npx skills 명령을 실행하며 Orca 런타임에 연락하지 않습니다. 자세히는 스킬 레지스트리.
Account (호스트 로컬 런타임)
orca account list
orca account add # 기본은 Claude
orca account add --agent codex
Orca가 도는 헤드리스 호스트(orca serve 또는 데스크톱 앱)에서, 원격 클라이언트가 Add account 버튼을 쓸 수 없을 때(원격 런타임 범위에서는 그 버튼이 꺼짐) 관리형 Claude/Codex 계정을 추가합니다. account add는 그 호스트 터미널에서 claude login/codex login을 실행한 뒤 받은 자격 증명을 로컬 런타임에 등록합니다. Codex는 장치 인증 방식이라 브라우저 쪽 로그인은 다른 컴퓨터에서 마쳐도 됩니다. 계정을 소유한 그 컴퓨터에서 실행하세요 — 클라이언트 전용 원격 세션을 통해서가 아니라.
Artifacts — HTML·Markdown 공개 링크
orca artifacts share ./report.html --json
orca artifacts share ./notes.md --json
orca artifacts update ./notes.md --json
orca artifacts unshare ./notes.md --json
orca artifacts list --json
orca artifacts list --cursor <cursor> --json
orca artifacts delete <id> --json
로그인한 Orca 계정으로 게시합니다. 공개 링크 보기는 로그인이 필요 없지만 만들기·목록·수정·삭제는 필요합니다. 사람이 그 기기에서 Settings → Artifacts → Allow publishing public artifact links(공개 아티팩트 링크 게시 허용)를 직접 켜야 하며, 이 관문을 여는 CLI 옵션은 없습니다. 게시를 끈 뒤에도 list·unshare·delete는 쓸 수 있어 링크를 점검·회수할 수 있습니다.
- 받는 파일:
.html,.htm,.md,.markdown. 파일당 최대 10 MiB. share는 편집 토큰을 현재 Orca 프로필에 저장하고 출력하지 않습니다.update/unshare는 처음 공유한 것과 같은 로컬 경로·프로필로 찾습니다.list는 페이지로 나뉩니다(nextCursor→--cursor).delete는list의 ID를 받으며 원본 파일이 없어도 됩니다.- HTML의 상대 경로 자원(이미지 등)은 올라가지 않습니다 — 모든 것이 한 파일에 든 HTML이나 절대 URL 자원을 쓰세요.
- 거부되면
artifact_sharing_disabled로 실패합니다. 재시도하지 말고 설정을 고치세요. - 데스크톱에서는 로컬 HTML/Markdown을 열고 Share as artifact를 누르거나, 사이드바 Artifacts 페이지에서 링크를 관리합니다.
이걸로 할 수 있는 일 — 예약 프롬프트를 만들고, 관리하는 원격 Orca 서버를 업데이트·복구하고, 에이전트 상태 훅을 켜고 끌 수 있습니다.
자동화·환경·훅 명령 목록
예약 프롬프트
orca automations list --json
orca automations create --name "Daily review" --trigger daily --time 09:00 --prompt "Review open changes" --provider claude --repo id:<repoId> --extra-agent-args="--model opus" --disabled --json
orca automations run <automationId> --json
자세히는 예약 자동화 절.
관리형 SSH 서버(Managed servers)
orca environment list --json
orca environment status --environment <selector> --json
orca environment update --environment <selector> --json
orca environment rollback --environment <selector> --json
orca environment recover --environment <selector> --json
orca environment stop --environment <selector> --yes --json
orca environment forget --environment <selector> --yes --json
--environment는 이 컴퓨터가 SSH로 배포한 관리형 Orca 서버를 가리킵니다(Settings → Managed servers와 같은 동작). 상태 확인·업데이트·되돌리기(rollback)·복구가 있고, stop은 서버를 폐기하며, forget은 호스트가 사라진 서버의 연결을 끊습니다. 자세히는 SSH worktrees → Managed Orca server 문서.
원격 런타임 환경
orca environment add --name work-laptop --pairing-code "orca://pair?code=..." --json
orca environment list --json
orca environment rm --environment <selector> --json
에이전트 상태 훅
orca agent hooks status --json
orca agent hooks on --json
orca agent hooks off --json
에이전트 상태 훅의 현재 상태 확인·켜기·끄기입니다.
- 결과를 프로그램이 읽어야 하면
--json을 붙인다(기계가 읽기 쉬운 형식). - 화면에 보이는 글자로 대상을 짐작하지 말고,
id:같은 정확한 선택자(대상을 가리키는 이름표)로 고른다. - 다음에 무엇을 입력할지 분명하지 않으면, 보내기 전에 터미널 화면을 먼저 읽어 본다.
- 진행 상황은 워크트리 카드의 코멘트로 남긴다(체크포인트).
- 누가 무엇을 맡았고 끝났는지 따라가야 하는 여러 에이전트 작업은, 터미널에 그때그때 지시를 넣는 대신 오케스트레이션을 쓴다.
예약 자동화 — 정해진 시간에 프롬프트 실행
무엇인가 — Orca 자동화(automation)는 정해진 일정에 프롬프트를 실행합니다. 왜 필요한가 — 매일 아침 이슈 정리, 매시간 PR 리뷰 같은 반복 일을 사람이 워크트리를 직접 열지 않아도 시작할 수 있습니다. 아래에서 “꺼진 자동화를 만들고 → 살펴보고 → 준비되면 실행”하는 흐름을 따라갑니다.
--trigger 프리셋의 감을 잡기 위한 그림입니다. 정확한 시각은 --time, 시간대는 --timezone으로 정합니다.1단계 — 꺼진 상태로 안전하게 만들기
프롬프트와 대상을 다듬는 동안 실수로 돌지 않도록 --disabled로 시작합니다.
orca automations create \
--name "Weekday triage" \
--trigger weekdays \
--time 09:00 \
--prompt "Triage new issues and summarize blockers" \
--provider codex \
--repo my-repo \
--disabled \
--json
2단계 — 목록과 상세 확인
orca automations list --json
orca automations show <automationId> --json
켜기 전에 이름·프롬프트·대상·일정이 맞는지 살핍니다.
3단계 — 지금 한 번 직접 실행해 보기
orca automations run <automationId> --json
orca automations runs --id <automationId> --json
다음 예약 시간을 기다리지 않고 수동 실행해 프롬프트와 대상이 맞는지 확인하고, runs로 실행 기록을 봅니다. 실행이 워크트리를 열거나 대상에 다시 연결하기 전에 실패했다면 Orca에서 그 실행을 열고 Rerun을 눌러 같은 자동화의 새 수동 실행을 대기열에 넣습니다.
4단계 — 켜기
orca automations edit <automationId> --enabled --json
edit로 이름·프롬프트·provider·대상·일정·켜짐 상태를 바꿀 수 있고, remove는 자동화와 실행 기록까지 지웁니다.
처음에는 위 네 단계(꺼진 채 만들기 → 확인 → 한 번 실행 → 켜기)만 기억하면 됩니다. 옵션마다의 뜻은 아래 접힌 표에 있습니다.
create 옵션 전체 표
| 옵션 | 뜻 |
|---|---|
--name | 자동화 이름 |
--trigger | 일정. 프리셋 hourly·daily·weekdays·weekly, 또는 cron 식(‘분 시 일 월 요일’ 다섯 칸으로 반복 일정을 적는 표기법. 예: 0 18 * * 1-5 = 평일 18시), 또는 RRULE(달력 표준(iCalendar)의 반복 규칙 문자열) 문자열 |
--time | 실행 시각(예: 09:00) |
--timezone <tz> | 런타임 기본값 대신 특정 IANA 시간대(예: Asia/Seoul)를 따름 |
--prompt | 에이전트에게 줄 프롬프트 |
--provider | 실행할 에이전트(예: codex, claude) |
--repo <selector> | 실행마다 저장소에서 작업을 만들거나 고름 |
--workspace <selector> | 이미 있는 워크트리나 폴더 워크스페이스 안에서 실행 |
--project / --host | 특정 프로젝트 호스트 setup에서 실행 |
--project-host-setup <id> | setup ID를 이미 알 때 |
--source-context '<json>' | 작업/provider 데이터를 특정 호스트·계정에 고정(편집 시 null로 지움) |
--precheck | 실행 전 가벼운 셸 검사 |
--reuse-session / --fresh-session | 이전 터미널 이어 쓰기 / 매번 새 터미널 |
--extra-agent-args= | 실행마다 덧붙일 모델·effort 인자 |
--missed-run-grace-minutes | 놓친 실행의 유예 시간(분) |
--disabled / --enabled | 꺼짐 / 켜짐 |
화·목·토처럼 프리셋 이름이 없는 여러 요일 규칙은 “Invalid schedule” 대신 저장된 일정 그대로 표시됩니다.
어디서 실행할지 고르기
실행할 때마다 저장소에서 작업을 만들거나 고릅니다. 위 1단계 예가 이 방식입니다.
orca automations create \
--name "Nightly status" \
--trigger "0 18 * * 1-5" \
--prompt "Summarize today's changes" \
--provider claude \
--workspace active \
--disabled
0 18 * * 1-5 읽는 법: 0분 · 18시 · 매일(*) · 매월(*) · 월~금(1-5) = 평일 오후 6시.
이미 있는 Orca 워크트리 안에서 돌립니다.
대상 생략 시 동작과 에이전트별 프롬프트 입력
이미 있는 Orca 워크트리나 폴더 워크스페이스 안에서 돌립니다. 두 대상 옵션을 모두 빼면 Orca가 가능할 때 현재 셸 폴더가 속한 워크트리를 씁니다.
Orca 서버의 기존 워크트리에서 예약 실행될 때, 시작 후에 프롬프트를 읽는 에이전트(Aider, Goose, Amp 등)에게는 준비되는 대로 Orca가 프롬프트를 입력해 줍니다(놀고 있게 두지 않음). Claude·Codex처럼 명령줄로 프롬프트를 받는 에이전트는 원래 영향이 없었습니다.
특정 프로젝트·호스트(작업이 돌아가는 컴퓨터)를 정해 돌릴 때 씁니다.
--project / --host 예시와 세부 옵션
orca automations create \
--name "Remote triage" \
--trigger daily \
--time 09:00 \
--prompt "Triage open issues" \
--provider claude \
--project <projectId> \
--host <hostId> \
--disabled \
--json
--repo/--workspace만이 아니라 특정 프로젝트 호스트 setup에서 돌려야 할 때 씁니다. setup ID를 알면 --project-host-setup <id>. --source-context '<json>'은 작업·provider 데이터를 호스트/계정에 고정합니다(편집 때 null을 주면 지워짐).
실행 전 검사(precheck)
precheck는 예약 시각에 에이전트를 깨우기 전에 “오늘 할 일이 있나?”를 먼저 확인하는 짧은 셸 명령입니다.
orca automations create \
--name "PR review" \
--trigger hourly \
--precheck "gh pr list --json number -q .[0].number" \
--prompt "Review requested PRs" \
--provider codex \
--repo my-repo \
--disabled \
--json
gh pr list …는 검토 요청된 PR이 있는지 확인하는 명령입니다. 이런 검사 명령은 에이전트에게 만들어 달라고 해도 됩니다.
그 밖의 세부 조정
놓친 실행을 얼마나 늦게까지 따라잡을지(--missed-run-grace-minutes), 지난번 터미널에서 이어서 할지(--reuse-session), 이 자동화만 다른 모델을 쓸지(--extra-agent-args)도 정할 수 있습니다.
놓친 실행 유예·세션 이어 쓰기·실행별 모델과 effort
놓친 실행 유예, 세션 이어 쓰기
orca automations edit <automationId> --missed-run-grace-minutes 30 --json
놓친 실행(missed run)의 유예 시간을 분 단위로 정합니다.
orca automations create \
--name "Inbox digest" \
--trigger hourly \
--prompt "Summarize unread mail" \
--provider codex \
--workspace active \
--reuse-session \
--disabled
기존 워크트리를 대상으로 하는 자동화에 --reuse-session을 붙이면, 다음 실행이 빈 터미널이 아니라 이전의 살아 있는 자동화 터미널에서 이어서 진행됩니다. 다시 매번 새 터미널로 돌리려면 orca automations edit <automationId> --fresh-session --json.
실행별 모델·effort(--extra-agent-args)
orca automations create \
--name "Docs tidy" \
--trigger daily \
--prompt "Tidy the docs" \
--provider claude \
--extra-agent-args="--model opus --add-dir docs" \
--disabled
- 자동화마다 실행 때 추가 에이전트 인자를 줄 수 있어, 호스트 기본값을 바꾸지 않고 이 자동화만 다른 모델·effort를 씁니다. 데스크톱 편집기에서는 Advanced → Extra agent arguments(고급 → 추가 에이전트 인자).
- 새 실행마다 호스트의 그 에이전트 기본 Arguments에서 시작해 추가 인자를 덧붙이며, 추가 인자에 모델·effort가 있으면 기본값의 것을 대체합니다.
- 값이
--로 시작하므로 반드시=로 붙여 씁니다. - 허용되는 것은 모델·effort 옵션과 Claude의
--add-dir뿐이며, 대상 에이전트는 Claude, Codex, CodeBuddy, Cursor, Grok, OMP입니다. 권한·설정·프롬프트·세션 옵션은 거부됩니다. - 매번 새 세션이 필요하므로
--reuse-session과 함께 못 씁니다. 지우려면orca automations edit <automationId> --extra-agent-args=.
데스크톱 Automations 페이지와 여러 호스트
검색: 이름·프로젝트·프롬프트 Filters: Host · Enabled/Paused · Failed/Succeeded/Never ran · Agents
| Name ↕ | Host | Last run ↕ |
|---|---|---|
| Weekday triage | this computer | Succeeded · 2h ago |
| Remote triage | ssh: build-box | Failed · 1d ago |
| Docs tidy | paired server | Never ran |
위는 화면 구성을 설명하기 위한 흉내입니다(값은 예시).
앱의 Automations 페이지에서는 이 컴퓨터와 연결된 다른 컴퓨터의 예약 작업을 한 표로 보고, 검색·필터·정렬할 수 있습니다.
Automations 페이지 세부 동작과 단축키
- 이 컴퓨터와 지원되는 연결된 Orca 호스트의 일정을 한 표로 불러옵니다. Host 열은 자동화가 저장·예약된 곳이며, Filters → Host로 특정 호스트만 보거나 All hosts로 돌아갑니다.
- UI에서 만들 때는 Create on으로 먼저 호스트를 고르고, 그다음 프로젝트를 고릅니다(프로젝트 목록은 그 호스트 것). 더 새 Orca 서버가 필요한 호스트는 사라지지 않고 비활성 상태로 Update server 안내와 함께 보입니다.
- 검색창은 이름·프로젝트·프롬프트 글자로 거릅니다. SSH 호스트에 있는 외부 자동화는 그 호스트가 끊겨 있어도 관리(삭제 포함)할 수 있어, 일정 하나 지우려고 SSH 연결을 할 필요가 없습니다.
- Filters: Host, Enabled/Paused 상태, 마지막 실행 결과(Failed, Succeeded, Never ran), Agents(여러 개 가능, 목록이 길면 하위 메뉴 안에서 검색). 걸린 필터는 표 위에 지울 수 있는 알약으로 보입니다.
- 표에는 호스트, 마지막 실행 결과, 상대 시간이 보입니다. Name(가나다/알파벳순)이나 Last run(기본 최신순) 열을 눌러 정렬합니다.
| 키 | 동작 |
|---|---|
| 검색창에서 ↑/↓ | 보이는 일치 행 사이로 선택 이동(선택 행이 화면에 유지됨). 수정키를 누르거나 글자 조합 중이면 원래 커서 동작 |
| Enter | 선택한 자동화나 실행 열기 |
| 상세에서 ↑/↓ | 실행 기록 이동 |
| ←/→ | Overview ↔ Runs 전환 |
| Esc | 상세에서 목록으로 |
오케스트레이션 — 여러 에이전트를 감독하며 일 나누기 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이 먼저 성공해야 합니다.
은퇴한 옛 명령
orca orchestration run, run-stop, coordinator-start, coordinator-stop은 아무 효과가 없고, orca skills get orchestration --full을 가리키는 복구 안내만 돌려줍니다. 아래 Run + worker-start 흐름을 쓰세요.
핵심 낱말 다섯 가지 — 비유로
Run = 프로젝트 폴더
이번 일 전체를 담는 폴더이자 팀장의 우편함입니다. 폴더가 일을 직접 나눠 주지는 않습니다 — 나눠 주는 건 팀장입니다.
Task = 할 일 카드
카드 한 장에 무엇을 할지, 먼저 끝나야 할 카드, 지금 상태(대기·준비·배정됨·완료·실패·막힘)가 적혀 있습니다.
Dispatch = 1회 배정
카드 한 장을 팀원 한 명(터미널 하나)에게 한 번 맡기는 것. 다시 맡기면 새 Dispatch(시도 2)가 됩니다. “다 했어요” 보고는 지금 맡은 배정으로만 받아 줍니다.
Message = 우편함 편지
“다 했어요”(worker_done), “질문 있어요”(question), “아직 일하는 중이에요”(heartbeat) 같은 편지입니다.
Decision gate = 자물쇠
팀장이 답해야 풀리는 자물쇠. 답이 정해질 때까지 그 카드를 잠가 둡니다.
그래서 워커가 “다 했어요”나 “아직 일하는 중이에요”를 보낼 때는 카드 번호(taskId)와 배정 번호(dispatchId)를 둘 다 적습니다. 예전 시도가 엉뚱하게 지금 카드를 완료 처리하지 못하게 하려는 것입니다.
다섯 낱말의 원래 정의와 Task ID 링크
- Run — 오래 유지되는 이름 공간이자 코디네이터의 집 우편함. 워커를 스케줄하거나 배치하지는 않습니다.
- Task — 사양(spec), 의존 관계, 상태를 가진 작업 항목. 상태: pending, ready, dispatched, completed, failed, blocked.
- Dispatch — 한 터미널에서 Task를 한 번 시도하는 것. worker_done·heartbeat를 받아들일 권한(수명주기 권한)을 가집니다.
- Message — 우편함 편지: status, dispatch, worker_done, escalation, question, heartbeat 등.
- Decision gate — 코디네이터가 소유하는 질문. 해결될 때까지 Task를 막아 둡니다.
완료 권한은 활성 Dispatch 맥락에서 나옵니다. 그래서 워커의 완료·heartbeat 메시지에는 taskId와 dispatchId를 둘 다 넣어야 합니다. 터미널에 찍힌 task_... 같은 Task ID는 클릭할 수 있는 링크로, 누르면 Orca 런타임에 그 Task의 현재 Dispatch를 물어 배정된 터미널로 포커스를 옮깁니다(원격·SSH 런타임에 있는 Task도 됨).
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
새 자식 워크트리·워커별 모델 예시
# 새 자식 워크트리에서:
orca orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run --json
# 워커별 모델/effort (Claude, Codex, Muse, Cursor, Antigravity, OpenCode; --terminal과 같이 못 씀):
orca orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high --json
# Antigravity를 로컬 자식 워크트리의 감독 워커로:
orca orchestration worker-start --task <taskId> --worktree new-child --name research --agent antigravity --setup run --json
새 워크트리에서 --name을 빼면 Orca가 이름을 지어 줍니다.
④ 우편함 확인하며 기다리기(다 읽으면 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)를 냅니다.
Delivery와 출력 채널
한 번의 Delivery(배달 묶음)에 든 메시지를 모두 처리한 뒤 --ack로 표시합니다. 기다리는 동안 CLI는 15초마다 작은 JSON heartbeat 줄을 stderr로 내보내고, 최종 결과는 stdout에 나옵니다.
⑤ 워커가 완료 보고(워커 창에서)
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.
코디네이터 ↔ 워커 메시지 흐름
더 깊은 운영 — 접어 둔 부분
워커마다 다른 모델 고르기, 멈춘 워커 살펴보기·복구, 다른 컴퓨터에서 워커 띄우기(연합), 직접 조립하는 저수준 배정, 여러 에이전트에게 한꺼번에 보내는 그룹 주소는 아래 접힌 상자에 있습니다.
워커 설정·복구·연합 워커·저수준 dispatch·우편함 주소 규칙
워커별 모델·effort와 시작 관련 설정
--model은 Claude, Codex, Muse, Cursor, Antigravity, OpenCode의 제공자 모델 ID를 그대로(opaque) 받습니다. Muse는 설치된 Muse가 받는 ID(예:muse-spark-1.3), Antigravity는agy models가 알려 주는 모델 슬러그를 씁니다.- OpenCode 워커가 요청한 모델은 실행 호스트에서 검증되고 그 워커에만 적용되어, 다른 실행의 기본 모델을 바꾸지 않습니다.
--effort는--model이 있어야 하고, 그 에이전트·모델이 그 수준을 지원할 때만 적용됩니다. 두 옵션 모두--terminal(기존 창 재사용)과 같이 못 씁니다.- Orca 내장 목록보다 새 Codex 모델(예: gpt-6.x)에는 설치된 Codex가 지원하면
max,ultra를 포함한 알려진 전체 effort 어휘를 받습니다. 모르는 effort 이름은 여전히 거부됩니다. - 재정의는 그 실행에만 적용되고, 시작 영수증(receipt)의
launch.requested/launch.effective에 표시됩니다. 연합(federated) 시작은 실행 선호 지원을 알리는 워커 호스트가 필요합니다. - Settings → Agent Orchestration에서 워커 heartbeat를 끄거나 1~60분 간격을 고릅니다(기본 5분). 새로 Dispatch되는 워커에만 적용되고, 기존 워커는 원래 브리프를 유지하며, 옛 호스트는 5분 기본값을 유지합니다.
- Chat UI가 켜져 있으면
worker-start도 새 에이전트 탭처럼, 지원되면 구조화된 채팅으로, 아니면 터미널로 엽니다.--terminal은 여전히 기존 창을 재사용합니다. - Orca는 로컬 Antigravity 자식 워크트리의 신뢰(trust)를 워커 시작 전에 준비합니다. SSH 너머의 Antigravity 감독은 이 신뢰 설정으로 지원되지 않습니다.
살펴보기·복구
orca orchestration worker-show --dispatch <dispatchId> --json
orca orchestration worker-read --dispatch <dispatchId> --limit 50 --json
orca orchestration worker-stop --dispatch <dispatchId> --json
orca orchestration worker-release --dispatch <dispatchId> --json
orca orchestration worker-retain --dispatch <dispatchId> --json
# 재시도 배치는 명시적 — --retry-of는 --on/worktree를 물려받지 않음
orca orchestration worker-start --task <taskId> --retry-of <dispatchId> --worktree current --agent codex --json
- 출력을 다시 읽으려고 끝난 워커 터미널을 열어 두지 마세요 —
worker-release뒤worker-read를 씁니다. release가release_pending이나release_unknown을 돌려줄 때 터미널을 마구 닫지 마세요. 영수증에 적힌 복구 동작을 따르세요.
연합 워커(Federated, 선택)
orca orchestration worker-start \
--task <taskId> \
--on windows \
--worktree new-top-level \
--repo <exact_remote_repo_selector> \
--name remote-worker \
--agent codex \
--setup run \
--json
orca orchestration send --to dispatch:<dispatchId> --subject "Follow-up" --body "…" --json
--on으로 다른 호스트에서 워커를 띄웁니다. 이후 명령은 Dispatch ID로 길을 찾으므로 --on을 반복하지 마세요.
저수준 dispatch(직접 구성)
orca worktree create --name billing-audit --agent codex --json
orca terminal wait --terminal <workerHandle> --for tui-idle --timeout-ms 60000 --json
orca orchestration dispatch --task <taskId> --to <workerHandle> --inject --json
워크트리와 에이전트를 직접 띄우고, 화면이 조용해지길 기다린 뒤, Task를 그 터미널에 주입(--inject)합니다.
메시지 주소와 우편함 규칙
- 기본
check는 연결된 Run의 가장 오래된 미확인(unacked) Delivery를 줍니다(먼저 온 것 먼저, FIFO).--ack할 때까지 같은 것을 다시 줍니다. --peek/--all은 편지를 소비하지 않고 보기만 합니다.
그룹 주소:
@all@idle@claude@codex@opencode@gemini@droid@grok@cursor@worktree:<id>
— 그 밖에 dispatch:<dispatchId>, 코디네이터 핸들, reference find로 찾은 메일함 주소처럼 개별 주소도 씁니다.
그룹 주소는 worker_done·heartbeat에는 절대 쓰지 않습니다. PowerShell에서는 따옴표로 감싸세요: --to "@all".
orca orchestration send --to @all --subject "Heads up" --body "Pausing dispatches for a review." --json
orca orchestration send --to @idle --subject "Anyone free?" --json
orca orchestration send --to @codex --subject "Codex agents only" --json
워커 계약(Worker contract)
일을 배정받은 워커는 팀장과 연락하는 법이 적힌 안내문(preamble)을 함께 받습니다. 약속은 다섯 가지입니다.
- worker_done은 정확히 한 번실패해도 보내고,
--outcome을 붙입니다. - 짧은 --body 요약한 일, 찾은 것, 남은 것.
- task ID와 dispatch ID 둘 다오래된 재시도가 엉뚱한 Dispatch를 완료 처리하지 못하게 합니다.
- heartbeat배정 안내문이 요구하면, 오래 걸리는 작업 중에 “살아 있어요” 신호를 보냅니다.
- 막히는 질문은 ask로자기 터미널 화면에서 사용자에게 묻지 말고
orca orchestration ask로 팀장에게 묻습니다.
ask 명령 예시
orca orchestration ask \
--to <coordinatorHandle> \
--question "Should I update the shared component or only this page?" \
--options "shared,page-only" \
--timeout-ms 600000 \
--json
--json이면 ask는 JSON 객체 하나만 출력하므로, 워커는 jq -r .answer로 답만 꺼낼 수 있습니다.
결정 관문(Decision gates)
ask — 워커 → 코디네이터 질문.
gate — 코디네이터가 Task DAG를 만들어 두고, 결정이 기록될 때까지 특정 Task를 막고 싶을 때.
gate 명령 예시
orca orchestration gate-create \
--task <taskId> \
--question "Merge the shared button change into the task branch?" \
--options '["yes","no"]' \
--json
orca orchestration gate-resolve --id <gateId> --resolution "yes" --json
상태 복구와 초기화(reset)
상태 복구와 초기화
orca orchestration dispatch-show --task <taskId> --json
orca orchestration dispatch-show --task <taskId> --preamble --json
orca orchestration task-list --json
orca orchestration task-update --id <taskId> --status blocked --result '{"reason":"waiting on credentials"}' --json
dispatch-show --preamble은 워커가 받은 머리말까지 보여 줍니다. 초기화는 오케스트레이션 상태를 의도적으로 버릴 때만:
orca orchestration reset --tasks --json
orca orchestration reset --messages --json
orca orchestration reset --all --json
다른 코디네이터가 활동 중일 때는, 그 정리가 의도한 게 아니라면 실행하지 마세요.
어떤 명령을 고를까
| 상황 | 명령 |
|---|---|
| 지켜보고 있는 에이전트에게 가벼운 프롬프트 | orca terminal send |
| 워커가 worker_done을 보고하고, 코디네이터를 통해 질문하고, Task ID로 추적돼야 함 | orca orchestration worker-start (또는 dispatch --inject) |
| Run(프로젝트 폴더)으로 오래 묶어 두고 감독하는 다중 에이전트 작업 | run-create + Task + 워커 (은퇴한 orchestration run 아님) |
명령 옵션은 앱과 함께 바뀝니다. 설치 후 에이전트는 orca skills get orchestration --full을 실행해 버전에 맞는 전체 가이드를 읽어야 합니다.
Computer Use — 데스크톱 앱 조작 Beta
무엇인가 — orca computer는 에이전트가 네이티브 데스크톱 앱(브라우저 안이 아니라 컴퓨터에 직접 설치된 앱)을 살피고 조작하게 합니다: 실행 중 앱 목록, 접근성 트리(화면의 버튼·입력칸 등을 운영체제가 나무 구조로 정리한 목록. 시각장애인용 화면 낭독기도 이걸 씁니다) 읽기, 컨트롤(버튼·체크박스 같은 화면 부품) 클릭, 값 설정, 글자 입력, 스크롤, 스크린샷. 언제 — 터미널이나 내장 브라우저가 아니라 운영체제나 다른 회사 앱을 다뤄야 할 때.
플랫폼별 네이티브 도우미가 함께 들어 있으며, 손쉬운 사용(Accessibility) 권한과 macOS에서는 화면 기록(Screen Recording) 권한이 필요합니다. 명령은 대체로 안정적이지만 옵션 이름은 바뀔 수 있습니다.
처음 설정
orca status --json
orca computer permissions --json
orca computer capabilities --json
permissions가 빠진 권한을 알려 주면 시스템 설정에서 Orca Computer Use에 Accessibility(macOS는 Screen Recording도)를 허용하고, permissions --json을 다시 실행해 확인합니다.
macOS에서는 기본적으로 에이전트가 뒤에서 앱을 다루므로, 그동안 여러분은 마우스·키보드를 계속 쓸 수 있습니다.
macOS 백그라운드 동작과 앞쪽 모드
macOS에서는 기본적으로 백그라운드에서 동작해, 에이전트가 다른 앱을 만지는 동안 여러분은 마우스·키보드를 계속 쓸 수 있습니다. 일부 동작은 그래도 앱이 앞으로 나와야 합니다. 앞쪽(foreground) 모드는 --restore-window이며, Chromium·Electron 앱에서 끌기(drag)는 이 모드가 필요합니다.
snapshot → act → snapshot
orca computer list-apps --json
orca computer get-app-state --app com.spotify.client --json
orca computer click --app com.spotify.client --element-index 42 --json
com.spotify.client는 앱 식별자(bundle ID)입니다. 첫 줄 list-apps 결과에서 찾아 씁니다.
요소 번호(인덱스)는 가장 최근에 읽은 화면 기준입니다. 화면이 바뀌면 다시 읽고 나서 번호를 쓰세요.
요소 인덱스 규칙 전체
- 인덱스는 가장 최근 get-app-state 결과에만 유효하고 번호가 띄엄띄엄일 수 있습니다.
--json출력에서는result.snapshot.treeText에서 트리를 읽습니다.elementCount를 보고 인덱스를 지어내지 마세요.- 화면 이동, 포커스 변경, 스크롤, 앱이 다시 그려진 뒤에는 상태를 새로 읽은 다음 인덱스를 쓰세요.
여러 창, 앱 고르기
orca computer list-windows --app com.microsoft.edgemac --json
orca computer get-app-state --app com.microsoft.edgemac --window-id <id> --json
orca computer click --app com.microsoft.edgemac --window-id <id> --element-index 12 --json
- 목록의 창 id가
none이 아니면 안정적인--window-id를, 아니면--window-index를 씁니다. - 앱은
list-apps가 주는 번들 ID(예:com.microsoft.edgemac)가 가장 좋습니다. 겹치지 않으면 앱 이름(--app Spotify)도 됩니다. 번들 ID와 이름이 모두 겹칠 때만--app pid:<number>.
쓸 수 있는 동작
| 명령 | 하는 일 |
|---|---|
click --element-index <i> | 요소 클릭 의미 기반 |
set-value --element-index <i> --value "text" | 입력칸 값 직접 설정 의미 기반 |
perform-secondary-action --element-index <i> --action <name> | 요소의 보조 동작 실행 의미 기반 |
type-text --text "text" | 키보드로 글자 타이핑 |
press-key --key Return | 키 하나 누르기 |
hotkey --key CmdOrCtrl+A | 단축키 조합(CmdOrCtrl = macOS는 Cmd, Windows·Linux는 Ctrl) |
paste-text --text "text" | 붙여넣기로 입력 |
scroll --element-index <i> --direction down | 스크롤 |
drag --from-x 100 --from-y 100 --to-x 300 --to-y 300 | 좌표로 끌기 |
“의미 기반” 동작은 “7번째 줄 120픽셀 지점”이 아니라 “저장 버튼”처럼 요소 자체를 겨냥하므로 더 안정적입니다. 이쪽을 먼저 쓰세요.
동작 선택 규칙·좌표 대체·민감한 입력과 스크린샷
모든 명령은 --app <app>과 --json을 함께 씁니다. 의미 기반 동작(click, set-value, perform-secondary-action)을 날것의 type-text·press-key보다 우선하세요 — 접근성 요소를 직접 겨냥하므로 키보드 입력이 깨지는 포커스 변화에도 견딥니다.
접근성 겨냥이 실패하면 조심스럽게 좌표로 물러섭니다.
orca computer click --app com.apple.Safari --x 120 --y 340 --json
orca computer drag --app <app> --from-element-index 3 --to-element-index 9 --json
민감한 입력과 스크린샷
printf '%s' "$TEXT" | orca computer set-value \
--app com.apple.Safari --element-index 7 --value-stdin --json
- 비밀번호 같은 비밀값은 표준 입력(stdin)으로 넘겨 셸 기록에 남지 않게 합니다.
type-text·paste-text에는--text-stdin이 같은 역할을 합니다. get-app-state는 접근성 트리와 기본으로 스크린샷도 돌려줍니다.--json이면 이미지는 디스크에 쓰이고 응답에는 경로(screenshot.path)만 들어갑니다.- 픽셀이 필요 없으면
--no-screenshot(더 빠르고 작음). 숨겨지거나 최소화된 창을 찍기 전에 보이게 하려면--restore-window.
에이전트에서 쓰기 — 같은 명령에 안전 지침을 묶은 computer-use 스킬을 에이전트 스킬 폴더에 설치합니다.
npx skills add https://github.com/stablyai/orca --skill computer-use
스킬 레지스트리와 MCP
스킬(에이전트가 특정 일을 할 때 읽는 사용 설명서 묶음, SKILL.md 파일)은 에이전트용 사용 설명서입니다. 에이전트의 스킬 폴더에 넣어 두면, 에이전트가 “아, Orca 일을 할 때는 이렇게 하면 되는구나” 하고 꺼내 읽습니다.
설명서 표지만 설치하고, 본문은 앱에서 꺼내 읽기
핵심은 하나입니다. 에이전트 폴더에는 설명서 표지(짧은 안내문)만 설치되고, 본문은 그때그때 앱에서 최신으로 꺼내 읽습니다. 그래서 앱이 업데이트돼도 설명서와 실제 명령이 어긋나지 않습니다.
표지(stub)에 적힌 내용과 skills get 명령
공개 설치 패키지는 “하이브리드 발견 stub”입니다(바이너리 = 설치된 CLI 실행 파일). npx skills add 뒤에 에이전트가 보는 stub은 다음을 말합니다.
- 이 세션의 CLI 실행 파일을 정한다:
ORCA_CLI_COMMAND→orca-dev→ (Linux)orca-ide→ 그 외orca. - 전체 가이드를 불러온다:
orca skills get <topic>(긴 가이드는--full). --json을 선호하고, 기억에 의존해 옵션을 지어내지 않는다.
orca skills list
orca skills get orca-cli
orca skills get orchestration --full
orca skills get orca-linear --json
자동화에서 결정적인 출력이 필요하면 --json. skills show는 skills get의 별칭입니다.
설치할 수 있는 Orca 스킬
보통은 앱의 Update skills 창으로 충분합니다(아래 「스킬 최신 상태 유지」). 명령으로 직접 설치할 때는 npx(인터넷에서 도구를 받아 바로 실행하는 명령)를 씁니다.
기본 에이전트 설정은 보통 orca-cli, computer-use, orchestration을 설치합니다. 설치 명령 형식은 모두 npx skills add https://github.com/stablyai/orca --skill <이름> --global입니다.
| 스킬 | 용도 |
|---|---|
orca-cli | 워크트리, 터미널, 파일, 자동화, 내장 브라우저 |
orchestration | 다중 에이전트 Run, Task, 감독 워커, 메시지, 관문 |
computer-use | 접근성 트리와 안전한 UI 동작으로 데스크톱 앱 조작 |
orca-linear | orca linear로 Linear 티켓 읽기/쓰기 |
orca-emulator | iOS Simulator 제어 |
orca-emulator-android | adb로 연결된 Android 에뮬레이터/기기 |
orca-per-workspace-env | 워크트리별 환경 레시피(orca.yaml) |
스킬별 추가 안내
| 스킬 | 추가 안내 |
|---|---|
orca-cli | 설치 후 orca skills get orca-cli |
orchestration | 오케스트레이션 상태를 바꾸기 전 항상 orca skills get orchestration --full(옛 run 명령은 은퇴) |
computer-use | 로컬 데스크톱 앱 창을 살피고 다룰 때 |
orca-linear | 티켓 변경 전 orca skills get orca-linear. issue --full, save-issue, list-issues, 관계, 완료 시 attach+comment 흐름, 신뢰할 수 없는 티켓 규칙 포함. 기존 linear-tickets 설치도 동작 |
orca-emulator | Orca 안에서 orca emulator 명령으로 |
orca-emulator-android | 목록/부팅, 탭/스와이프/입력, 하드웨어 버튼, 설치/실행, 권한, 접근성 트리, logcat. 자세히 orca skills get orca-emulator-android |
orca-per-workspace-env | 설정·디버깅할 때. Ways to run Orca 문서 참고 |
스킬 최신 상태 유지
새 버전이 나오면 앱이 update available(업데이트 있음)을 알려 주고, Update skills 창에서 한 번에 업데이트합니다. 가능하면 이 방법을 쓰세요.
앱 업데이터 세부 동작
Orca가 전역 설치본보다 새 스킬 패키지를 내놓으면 앱은:
- update available(업데이트 있음) 알림을 띄우고, 업데이트 도구가 안전하게 다시 쓸 수 없는 곳에 오래된 사본이 있으면 Needs attention을 표시합니다.
- Update skills 창을 엽니다 — 배치 위치와 건너뛴 이유 목록을 보여 주고,
npx --yes skills update <names> --global -y를 화면 없이(내장 터미널 없이) 실행합니다. - 실행은 백그라운드로 이어지며 창을 닫아도 취소되지 않습니다. 상태 표시줄 조각이 진행을 보여 줍니다(실행 중 회전, 성공 시 잠깐 체크, 실패는 조치할 때까지 유지). 클릭하면 창이 다시 열립니다.
- Settings → Agents에서 설치된 스킬의 최신 여부(전역 설치 레일)를 보여 주고, 검토가 필요한 행은 Details를 제공합니다.
가능하면 앱 업데이터를 쓰세요 — 앱이 스캔한 같은 전역 위치를 다시 씁니다. Skipped 행은 자동 업데이트가 안 되는 이유(예: 출처 등록 없음)를 설명하니, 위치를 고친 뒤 다시 확인하세요.
npx skills update orca-cli orchestration computer-use --global
데스크톱 설정 화면도 같은 npx 형식을 보여 줍니다.
설정 화면이 없는 컴퓨터(원격 서버 등)에서는 orca skills install / orca skills update 명령으로 설치·업데이트합니다.
헤드리스 CLI 명령과 옵션
SSH, 컨테이너, CI, orca serve처럼 설정 화면이 없는 호스트에서는 로컬 CLI 래퍼를 씁니다. 같은 npx 명령을 만들어 비대화형 옵션을 붙이며, 실행 중인 Orca 런타임이 필요 없습니다.
orca skills install # 설치 가능한 이름 목록
orca skills install --skill orca-cli --skill orchestration
orca skills install --skill orca-cli --agent claude-code,codex
orca skills install --all --dry-run
orca skills update --all
orca skills update --skill orca-cli --dry-run
- 기본 범위는 전역(
--global), 현재 프로젝트만이면--local. install은 호스트에서 Orca가 감지한 에이전트(그리고 공용.agents/skills폴더)를 대상으로 합니다.--agent <name>[,<name>…]나--agent universal로 바꿀 수 있고, 감지된 에이전트가 없으면--agent가 필수입니다.update는 이미 설치된 스킬만 새로 고칩니다.--dry-run은 만들어진 명령만 출력합니다.--json은 목록 출력이나--dry-run에서만 유효합니다.
스킬 화면에서 관리·공유하기
앱의 Skills 화면에서 스킬을 설치·삭제하고, 내 스킬을 링크 하나로 다른 컴퓨터나 동료에게 비공개로 나눠 줄 수 있습니다. 링크가 있으면 누구나 설치할 수 있으니 비밀번호처럼 다루세요.
Skills 페이지 설치·삭제, 호스트 간 비공개 공유, 발견 위치
Skills 페이지에서 설치·삭제
- 앱 안 설치가 설치할 워크트리를 물으면, 선택기에서 워크트리 이름이나 종류(worktree / folder)로 검색합니다.
- 에이전트 선택기는 Orca가 항상 포함하는 폴더와 추가로 고를 수 있는 에이전트 폴더를 나눠 보여 주므로, 정확한 설치 대상을 확인하고 진행할 수 있습니다.
- 스캔된 스킬 하나를 지우려면 그 동작 메뉴에서 Delete…, 여러 개는 페이지의 More actions → Delete skills…에서 고릅니다. 지울 수 없는 사본은 이유(번들됨, 플러그인 관리, 읽기 전용, 지울 수 있는 스킬 폴더 밖)를 확인 전에 알려 줍니다.
- 이는 공유 링크로 설치한 사본을 관리하는 Manage installs와는 별개입니다.
호스트 간 비공개 스킬 공유
- 게시Skills → Share skills에서 스킬 하나나 묶음(bundle)을 목록에 안 뜨고 회수 가능한 링크 하나로 게시합니다. Orca 계정이 필요합니다. 게시 전 포함 파일·스크립트·실행 파일·다이제스트·선택적 릴리스 노트를 검토하세요. 게시된 버전은 바뀌지 않으므로(immutable) 나중에 로컬을 고쳐도 받는 사람이 설치하는 내용이 몰래 바뀌지 않습니다.
- 받기활성 링크가 있으면 누구나 로그인 없이 살펴보고 설치할 수 있으니 링크를 비밀번호처럼 다루세요. 받는 사람은 정확한 버전을 검토하고, 전부 또는 일부 스킬을 고르고, 이 컴퓨터·짝지어진 Orca 런타임·WSL·SSH 호스트 중 전역 또는 워크트리 범위를 고릅니다. 이미 고친 기존 스킬은 기본값이 Keep local(로컬 유지)입니다.
- 관리Skills → Manage installs에서 Orca가 설치한 사본을 업데이트·되돌리기·제거하고, Settings → Share Skills에서 활성 링크를 복사하거나 회수합니다. 회수하면 앞으로의 접근은 막히지만 이미 설치된 사본은 지워지지 않습니다.
에이전트가 CLI로 게시하려면, 별도로 있고 기본으로 꺼진 Settings → Share Skills → Allow agents and the Orca CLI to publish skill links 권한을 사람이 켜야 합니다.
orca skills installed --json
orca skills share --skill frontend --skill testing --bundle-name "Team Toolkit" --json
skills installed는 로컬 경로를 노출하지 않는 안전한 선택자를 돌려줍니다. skills share는 정확한 발견 ID나 모호하지 않은 이름만 받고, 임의 경로나 --all은 받지 않습니다.
발견 위치와 나만의 스킬
- Orca 스킬 화면은 Claude, Codex, Agent Skills, OMP(
~/.omp/agent/skills)의 설치된 스킬 폴더를 스캔하므로, 거기 둔 스킬은 수동 심볼릭 링크 없이 보입니다. skills/<name>/SKILL.md파일이 있는 저장소는 무엇이든npx skills add로 설치할 수 있습니다. 사내 저장소를 가리키면 에이전트에게 회사 고유의 능력을 줄 수 있습니다.
MCP 서버
MCP(Model Context Protocol — AI 에이전트에게 외부 도구를 연결해 주는 표준 규약) 서버는 호환 에이전트에게 외부 도구를 제공합니다. Settings → Integrations → MCP(설정 → 연동 → MCP)에 서버 주소(엔드포인트)를 등록하면, MCP를 지원하는 에이전트 CLI 안에 그 도구들이 나타납니다.
워크트리 체크포인트 — 진행 상황 남기기
무엇인가 — 모든 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로, 쓰기 전에 먼저 읽습니다.
출처: onorca.dev/docs/cli/overview · onorca.dev/docs/cli/reference · onorca.dev/docs/cli/automations · onorca.dev/docs/cli/orchestration · onorca.dev/docs/cli/computer-use · onorca.dev/docs/cli/skills · onorca.dev/docs/cli/worktree-checkpoints
원격과 모바일 — SSH, 원격 Orca 서버, 폰 앱
노트북이 아닌 다른 컴퓨터(성능 좋은 개발 서버, GPU 장비, 집에 둔 Mac mini)에서 에이전트를 돌리고, 그 모습을 노트북이나 휴대폰으로 지켜보고 조종하는 방법을 다룹니다.
- SSH·원격 서버·페어링·Tailscale이 무엇인지, 둘 중 어떤 방식을 골라야 하는지
- SSH 대상(target)을 추가하고, 호스트 키·암호·다단계 인증·Kerberos·보안키를 다루는 법
- 연결이 끊겨도 에이전트가 살아남는 구조, 재연결·재시작 동작, 포트 포워딩, 원격 파일 내려받기
- Orca가 원격 호스트에 스스로 설치하는 관리형 서버(managed server)
- 원격 Orca 서버: 데스크톱 앱 + Tailscale 설정,
orca serve로 헤드리스 서버 운영, 서비스 등록, 보안 - iOS·Android 모바일 앱의 모든 기능과 페어링, Android APK 설치
다른 컴퓨터(서버)가 없다면 SSH·원격 서버 부분은 건너뛰어도 됩니다. 폰 앱만 보세요.
- 먼저 알아 둘 말: SSH · 원격 서버 · 페어링 — SSH·LAN·Relay·Tailscale이 무엇인지 카드 한 장씩
- 어떤 방식을 고를까 — 비교 그림 하나로 "실제 일은 어느 컴퓨터가 하나"만 보면 됩니다
- 원격 Orca 서버 — 그 안의 「권장: 데스크톱 앱 + Tailscale」 순서대로 누르면 연결됩니다
- 모바일 앱(Orca Mobile) — 폰으로 에이전트 상태를 보고 짧게 답하기
건너뛰어도 되는 곳: 「호스트 키 확인」, 「고급 연결 옵션과 인증」, orca serve·서비스 등록. 「🔧 개발자용 참고」로 접힌 상자는 모두 접어 둔 채 읽어도 됩니다.
먼저 알아 둘 말: 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 베타 기능입니다.
SSH 대상 추가하기
SSH 원격 Workspace(워크스페이스 — 워크트리와 같은 것)에서는 에이전트는 원격 호스트에서 돌고, 편집기와 diff(무엇이 바뀌었는지 전·후를 나란히 보여 주는 화면)는 내 노트북에 그대로 있습니다. 먼저 접속할 호스트를 등록합니다.
Settings → SSH(설정 → SSH)를 열고 Add Target(대상 추가)을 누릅니다. 호스트 입력 양식은 목록 아래가 아니라 모달 창으로 뜹니다. 그래서 등록된 호스트가 아무리 많아도 Host·Advanced·Save 버튼이 항상 손 닿는 곳에 있습니다.
host(주소), user(사용자 이름), port(포트), 그리고 선택 사항인 identity file(키 파일)을 넣습니다. 이 값들은 그 서버를 관리하는 사람(IT 담당자)이 알려 줍니다(일반적인 안내). 모르는 값을 짐작해 넣지 마세요.
gpu-box.exampleUser:
dev · Port: 22Identity file:
~/.ssh/id_ed25519 (선택)Advanced Test Save
같은 창에서 OpenSSH config 선택기(내 컴퓨터에 적어 둔 SSH 접속 목록 파일에서 고르는 창)를 열면 ~/.ssh/config(그 파일이 다른 설정 파일을 불러와 쓰고 있으면 그 파일까지)를 검색해 호스트 하나를 골라 양식을 자동으로 채울 수 있습니다. 이미 Orca에 저장된 호스트에는 In Orca 배지가 붙습니다. 일괄 가져오기(bulk import) 흐름이 제공될 때는 config에서 여러 호스트를 한꺼번에 가져올 수도 있습니다.
키 파일(passphrase는 키 파일을 여는 비밀번호)이 암호로 잠겨 있으면 처음 접속할 때 Orca가 암호를 묻습니다.
Test로 접속이 되는지 확인한 뒤 Save로 저장합니다. 나중에 Edit(편집)도 같은 창을 쓰며, 대상 이름과 user@host:port를 함께 보여 줍니다.
호스트 키 확인 — "이 서버가 진짜 그 서버인가?"
known_hosts 파일입니다.Orca의 내장 SSH 연결은 내 컴퓨터에서 실제로 적용되는 OpenSSH(컴퓨터에 깔린 표준 SSH 프로그램) known_hosts 파일들과, Orca가 예전에 저장해 둔 키를 기준으로 확인합니다.
| 상황 (관련 설정) | Orca의 동작 |
|---|---|
| 전에 접속한 서버이고 지문이 같을 때 | 아무것도 묻지 않고 조용히 접속 |
| 처음 접속하는 서버일 때 (기본 설정) | 받아들이고 기억하며, 지문(fingerprint)을 보여 줌 |
엄격 모드를 켠 경우 (StrictHostKeyChecking yes) | 처음 보는 호스트는 거부 |
확인을 끈 경우 (StrictHostKeyChecking no / off) | 받아들이지만 신뢰 기록은 저장하지 않음 |
| 지문이 바뀌었거나, 폐기된(revoked) 키이거나, 키 종류가 예상과 다를 때 | 비밀번호나 키 암호를 묻기 전에 거부 |
관리자용: 지문 불일치 복구 방법
호스트를 의도적으로 재구축·재설치했다면 먼저 새 지문이 맞는지 확인한 뒤, 오류 메시지에 나온 복구 방법을 따르세요. known_hosts 불일치일 때는 Orca가 알맞은 ssh-keygen -R 명령을 알려 줍니다(필요하면 [host]:port처럼 대괄호로 감싼 호스트와 포트까지 포함).
SSH 대상 사용하기 — 원격 워크트리 레시피
워크트리를 만들 때 위치로 Local 대신 SSH 대상을 고르면 Orca가 다음을 해 줍니다.
- 원격 호스트에 git 워크트리(같은 저장소를 여러 폴더에 펼쳐 각각 다른 작업을 하게 하는 git 기능)를 만듭니다.
- SSH 연결을 통해 에이전트를 원격에서 실행합니다.
- 파일 이벤트를 동기화해, 편집기·diff·브라우저가 여전히 로컬처럼 느껴지게 합니다.
성능 좋은 개발 서버, GPU 호스트, 클라우드 샌드박스 — 어떤 SSH 대상이든 같은 편집기, 같은 diff 화면, 같은 에이전트에 컴퓨팅만 다른 로컬 워크트리처럼 쓸 수 있습니다. 원격 저장소뿐 아니라 그냥 아무 폴더도 열 수 있습니다.
Settings → SSH에 호스트를 추가합니다.
Test로 연결을 확인합니다. 저장소로 작업한다면 호스트에 git이 설치되어 있어야 합니다.
저장소를 Orca에 추가하면서 위치로 SSH 대상을 고릅니다. 또는 파일 선택기에서 원격 폴더를 바로 엽니다.
워크트리를 만들면 Orca가 원격에서 git worktree add를 실행합니다.
에이전트를 띄우면 노트북이 아닌 원격 호스트에서 돕니다.
파일을 그 자리에서 고치면 Orca가 저장 내용을 원격 파일 시스템으로 흘려보냅니다.
diff를 검토하고, 커밋하고, 푸시하는 일은 평소처럼 노트북에서 합니다.
노트북이 잠들거나 Wi‑Fi가 끊겨도 에이전트는 원격에서 계속 돕니다. Orca가 다시 연결해 터미널을 붙여 주므로 잃는 것이 없습니다.
고급 연결 옵션과 인증(암호 · MFA · Kerberos · 보안키)
한 줄 요약: 키 암호는 Orca가 켜져 있는 동안만 기억하고, 인증 코드(OTP·MFA)를 묻는 서버는 Orca가 질문을 화면에 띄워 줍니다. 회사 로그인(Kerberos)이나 USB 보안키처럼 특별한 방식은 Orca가 알아서 컴퓨터에 깔린 표준 SSH 프로그램으로 넘겨 처리합니다.
고급 연결 옵션 · 암호 · 다단계 인증 · Kerberos · FIDO2 보안키
Settings → SSH에서 대상을 편집하고 Advanced Connection(고급 연결)을 펼치면 프록시, 점프 호스트(최종 서버로 가기 전에 거쳐 가는 중간 서버, bastion), SSH 멀티플렉싱 설정을 바꿀 수 있습니다.
- Reuse SSH connection(SSH 연결 재사용) — 기본으로 켜져 있습니다. macOS·Linux에서 OpenSSH 연결 재사용(멀티플렉싱)을 써서, 설정 명령마다 새로 SSH 악수(handshake)를 하지 않아 빨라집니다. 호스트 정책이 멀티플렉스 세션을 거부할 때만 끄세요.
- Reconnect on launch(시작 시 재연결) — 기본은 켜짐. 필요할 때만 쓰는 호스트라면 꺼 두세요. 꺼져 있으면 Orca는 그 세션 동안 사용자가 Connect를 누를 때까지 그 호스트와 관리형 서버에 다시 연결하지 않습니다.
- Allow this host's orca CLI to control Orca — 아래 "SSH 호스트의 orca CLI" 절 참고.
키 암호(passphrase)는 Orca가 켜져 있는 동안만 메모리에 보관됩니다. Orca를 닫으면 지워집니다. SSH 설정에서 더 긴 보관 시간(TTL)을 직접 선택할 수 있습니다.
인증 코드나 일회용 비밀번호(OTP), MFA 확인처럼 "키보드로 답하는(keyboard-interactive)" 질문을 하는 호스트도 내장 연결로 동작합니다. Orca가 질문을 사용자에게 전달하고 답을 다시 보냅니다. 질문이 자동 설정 단계 도중에 나오면, 연결을 실패시키지 않고 사용자가 답할 수 있는 단계로 미뤄 둡니다.
내장 클라이언트와 호스트가 공통으로 쓸 수 있는 SSH 알고리즘이 없으면, Orca는 시스템 ssh로 다시 시도합니다. 시스템 ssh는 그 설치본에 설정된 알고리즘을 쓸 수 있습니다.
회사 SSO 등에서 쓰는 Kerberos/GSSAPI 인증입니다. OpenSSH config에서 호스트에 GSSAPIAuthentication yes가 설정되어 있으면, Orca는 그 대상에 시스템 OpenSSH 연결을 우선 사용합니다(내장 ssh2 클라이언트는 GSSAPI를 지원하지 않음).
- 접속 전에 유효한 Kerberos 티켓을 갖고 있어야 합니다(
kinit또는 회사 SSO). - 수동으로 만든 대상도 시스템 SSH로 설정하면 GSSAPI를 켤 수 있습니다.
- config에서 가져온 호스트는 별도의 "Kerberos 모드" 스위치가 필요 없습니다 — 가져오기/
ssh -G가 그 설정을 그대로 넘겨 줍니다.
USB 보안키처럼 하드웨어에 저장된 OpenSSH 키(ed25519-sk, ecdsa-sk, 에이전트에 올린 보안키 포함)도 내장 ssh2 대신 시스템 OpenSSH를 씁니다. Orca가 키 파일에서 종류를 알아내 OS의 OpenSSH 프로그램에 연결을 넘기므로, 터치·PIN 요청이 평소처럼 뜹니다.
- 일반 Ed25519·ECDSA·RSA 키는 내장 연결을 그대로 씁니다.
- 컴퓨터에 OpenSSH가 없으면 FIDO2 대상은 인증할 수 없습니다. OpenSSH를 설치해 PATH(또는 Windows·macOS·Linux의 일반적인 위치)에 두세요.
연결 상태, 끊김, 재연결
원격 워크트리에는 실시간 SSH 상태를 보여 주는 칩이 붙습니다: ● 연결됨● 재연결 중● 끊김
꼭 알아 둘 것은 두 가지뿐입니다.
- 끊겨도 에이전트는 계속 돕니다 — 노트북이 잠들거나 Wi‑Fi가 끊겨도 에이전트는 원격 컴퓨터에서 하던 일을 이어 갑니다. 연결이 돌아오면 Orca가 자동으로 다시 붙여, 그동안의 화면을 그대로 보여 줍니다. 그러니 "끊김"을 보고 같은 워크트리에 에이전트를 하나 더 띄우지 말고, 먼저 다시 연결해 상태를 확인하세요.
- 카드에서 바로 재연결 — 호스트가 끊기면 해당 워크트리 카드에 Connect/재연결 버튼이 나타나, 터미널 창을 열거나 상태 표시줄을 찾지 않아도 복구할 수 있습니다.
끊김·재연결 세부 (출력 재생 · 앱을 닫았을 때 · 복원되는 것)
- 재연결 때 화면 복원 — Orca가 재연결해 다시 붙이며, 스크롤 출력을 재생하고 전체 화면 앱 창은 렌더링된 화면 그대로 복원합니다(빈 화면이나 깨진 화면이 아님).
- 연결 중에도 사이드바가 비지 않음 — 호스트가 아직 연결 중일 때는 로컬에 저장된 정보로 워크트리 목록을 먼저 보여 주고, 연결이 자리 잡으면 원격의 실제 상태로 갱신합니다.
- 재연결 중 친 키도 보존 — 복원 중인 SSH 터미널에 입력한 키는 버려지지 않습니다.
- "Multiplexer disposed" 같은 오류 — 창이 멈춘 채 재시작을 기다리지 않고 자동으로 복구합니다.
- 에이전트 상태 전달 — working(작업 중)·idle(대기)·blocked(막힘) 상태가 로컬과 똑같이 SSH로 전달되어, 사이드바와 Agents 피드에 원격 에이전트가 실시간으로 보입니다.
앱을 닫아도 원격 세션은 유지
데스크톱 앱을 닫아도 원격 PTY(가상 터미널 — 원격에서 돌아가는 명령 창 하나) 세션은 죽지 않습니다. 세션이 호스트의 관리형 Orca 서버에 있기 때문입니다. 앱을 다시 열고 대상에 연결하면 세션이 원래 탭에 붙은 상태로, 스크롤 기록과 함께 돌아옵니다. 관리형 서버의 구조화된 채팅(Chat UI)은 답변이 진행 중이거나 질문이 기다리는 동안 제공자를 계속 띄워 두므로, 데스크톱 연결이 끊겨도 승인 요청이 그대로 남아 있습니다.
재연결과 재시작 후 복원되는 것
- 열린 파일, 살아 있는 에이전트 탭, 일시정지된 Claude·Codex의 이어하기(resume) 제안이 SSH 재연결과 앱 재시작 후에도 남아, 떠날 때 모습 그대로 돌아옵니다.
- 연결이 끊긴 동안 친 키는 연결이 돌아오면 정확히 한 번, 순서대로 전달됩니다. 창의 스크롤 기록과 크기도 유지됩니다.
- 관리형 서버가 업데이트된 뒤에도 열린 탭이 다시 붙습니다.
- 오래전에 닫은 탭이 빈 껍데기로 되살아나지 않습니다. 마지막 탭까지 닫은 SSH 워크트리를 클릭하면 새 터미널이 열립니다.
- 무언가를 출력하는 셸 시작 파일, 수만 개 항목이 든 폴더, 64비트 ARM 리눅스 서버 때문에 연결이 깨지거나 끊기지 않습니다.
- 두 컴퓨터가 같은 경로를 가지고 있어도 파일·브라우저 탭·링크·드래그 앤 드롭은 원래 속한 컴퓨터에 머뭅니다.
SSH 호스트에서 쓰는 orca CLI
CLI(마우스 대신 터미널에 명령어를 입력해 프로그램을 조종하는 방식)인 orca 명령을 SSH 호스트에서 실행하면, 기본적으로는 그 호스트 자신의 터미널과 오케스트레이션 메시지(에이전트끼리 일을 나누고 보고하는 메시지)에만 닿습니다. 그 호스트의 에이전트는 자기를 보낸 조정자(coordinator)에게 결과를 보고할 수는 있지만, 다른 호스트·데스크톱 제어·계정·설정에는 닿지 못합니다.
- 그 호스트의 에이전트가
orca로 워크트리를 만들고, 터미널을 열고, 작업을 배분하게 하려면 Settings → SSH → 호스트 편집 → Advanced Connection에서 Allow this host's orca CLI to control Orca를 켭니다. - Orca가 호스트에서 지우지 못하는 SSH 워크트리를 삭제할 때는 Remove from Orca를 쓰면 앱에서만 지우고 호스트의 파일은 남겨 둡니다.
예전 버전(v1.4.224)에서 올라온 경우
v1.4.224에서 넘어온 터미널에는 orca가 없습니다. 같은 호스트에서 새 터미널을 열어 실행하세요.
원격 파일 내려받기와 VS Code로 열기
원격 컴퓨터에 있는 파일을 내 노트북으로 가져오거나, 익숙한 편집기 VS Code(마이크로소프트의 무료 코드 편집기)로 원격 폴더를 바로 열 수 있습니다. 둘 다 오른쪽 클릭 메뉴에서 시작합니다.
report.csv → Download 파일 하나 받기📁
results/ → Download Folder 폴더째 받기→ 운영체제 저장 창이 뜨고 노트북으로 복사됨
VS Code Remote SSH
Finder / Explorer (로컬 전용)
→ VS Code가 원격 폴더를 열어 줌
파일·폴더 내려받기
SSH 워크트리의 파일 탐색기에서 오른쪽 클릭합니다.
- 파일 → Download — 운영체제 저장 창이 뜨고 파일이 노트북으로 복사됩니다.
- 폴더 → Download Folder — 고른 폴더로 하위 폴더까지 통째로 내려받습니다(데스크톱 전용).
VS Code Remote-SSH로 열기
- 메뉴에 VS Code 넣기Settings → General → Open in menu에서 VS Code를 목록에 추가합니다(프리셋 또는 사용자 명령).
- 열기SSH 워크트리를 오른쪽 클릭(또는 워크트리 더보기 메뉴) → Open in → VS Code.
Download Folder가 안 보일 때 · VS Code 연결 세부 · 지원되지 않는 편집기
전송은 연결과 같은 SSH 경로로 합니다. Download Folder는 연결이 폴더 재귀 전송을 지원한다고 알릴 때(보통 완전한 SFTP(SSH 위에서 파일을 주고받는 표준 방법))만 보입니다. 시스템 OpenSSH 전송만 쓰는 연결은 파일은 받을 수 있어도 폴더 받기 메뉴는 없을 수 있습니다.
웹 클라이언트에는 Download가 없습니다 — Electron의 저장 창에 의존하기 때문입니다.
설정한 앱이 VS Code 또는 VS Code Insiders(code/code-insiders, 또는 그 실행 파일의 직접 경로)라면, 워크트리 메뉴의 Open in 목록이 원격 경로를 VS Code Remote-SSH에 넘깁니다. Orca가 --remote ssh-remote+<host> <path>로 VS Code를 실행합니다. 메뉴 항목에 Remote SSH 배지가 보일 수 있습니다.
이 원격 경로에는 Cursor, Zed, 복합 셸 명령, 원격 Orca 서버를 활성 런타임으로 쓰는 경우가 지원되지 않습니다(그것들은 Local 전용). Finder/Explorer 항목은 로컬 경로에만 쓰세요.
관리형 Orca 서버(Managed Orca server)
처음 연결할 때 Orca는 호스트에 자기 전용 작은 서버 프로그램을 설치합니다. Orca가 함께 배포하고 최신으로 유지하는, 버전이 고정된(pinned) 런타임입니다. 그래서 호스트에 깔린 Node(Node.js — Orca 서버가 돌아가는 데 필요한 부품) 버전이 틀리거나 빌드 도구가 없어도 연결이 실패하지 않습니다. 켜는 설정은 따로 없습니다 — 항상 이렇게 동작합니다.
서버를 설치하고 그 관리형 서버에 연결합니다.
다음 연결 때 프로젝트·폴더·프로젝트 그룹·열린 편집기 탭을 관리형 서버로 옮깁니다.
예전 SSH 런타임으로 몰래 되돌아가지 않습니다. 연결이 이유와 함께 실패하고 Settings → SSH Hosts에 그 이유가 표시됩니다. 그 호스트에 계속 연결하려면 더 오래된 Orca 버전을 쓰세요.
서버 관리 화면
Settings → Managed servers에서 서버마다 버전과 실행 중인 터미널을 보고 다음을 할 수 있습니다.
| 버튼 | 뜻 |
|---|---|
| Update | 새 버전으로 업데이트. 터미널이 실행 중이면 Update anyway가 터미널을 닫지 않고 업데이트 |
| Roll back | 이전 버전으로 되돌리기 |
| Recover | 중간에 끊긴 업데이트 복구 |
| Stop… | 서버 중지 |
| Forget… | 서버를 목록에서 잊기 |
| (상태 보기) | 버전·터미널 확인 |
같은 일을 명령(CLI)으로 하기
| 버튼 | CLI |
|---|---|
| Update | orca environment update |
| Roll back | orca environment rollback |
| Recover | orca environment recover |
| Stop… | orca environment stop |
| Forget… | orca environment forget |
| (상태 보기) | orca environment status |
예전 버전에서 올라온 경우 (v1.4.224 터미널 · 사라진 Runtime 선택)
v1.4.224가 띄운 터미널이 남아 있는 호스트 — 기존 탭의 터미널은 업그레이드와 재연결 동안에도 계속 동작합니다. 그 호스트의 새 터미널은 관리형 서버에서 열립니다.
런타임 선택지는 사라졌습니다 — 예전의 호스트별 Runtime 선택(Auto / Orca-managed Node / Host Node)과 relay 전용 수명 주기 설정은 없어졌습니다. 이제 모든 SSH 연결은 관리형 Orca 서버에서 돕니다. 지원하지 않는 OS·CPU, 실행이 금지된(noexec) 홈 디렉터리, 포트 포워딩을 거부하는 SSH 서버처럼 관리형 서버를 돌릴 수 없으면, 조용히 다른 방식으로 넘어가지 않고 Settings → SSH Hosts에서 이유를 설명합니다.
포트 포워딩 — 원격 웹서버를 내 브라우저로
원격 워크트리에서는 오른쪽 사이드바에 Ports 탭이 있습니다(Cmd+Shift+I로 켜고 끄기 — macOS). Orca는 노트북이 아니라 워크트리가 실제로 도는 호스트(관리형 SSH 서버나 페어링된 서버)를 살펴, 접속을 기다리고 있는(listening) 포트를 Detected(감지됨) 아래에 보여 줍니다.
- 감지된 포트는 한 번 클릭으로 포워딩하고, 같은 패널에서 그 포트를 멈출 수도 있습니다.
- 포워딩을 수동으로 추가·편집·삭제할 수 있습니다.
- 저장한 포워딩은 관리형 호스트에 재연결하면 돌아오고, 앱을 재시작해도 남습니다.
- 권한이 필요한 원격 포트(특권 포트 — 80번처럼 관리자 권한이 있어야 여는 문)는 로컬에서 자동으로 다른 번호로 바뀝니다(예: 원격 80 → 로컬 10080).
- 저장한 포워딩을 시작할 수 없으면 그 줄에 이유가 표시되고 바로 지울 수 있습니다.
원격 Orca 서버 Beta
한 컴퓨터가 일을 하고, 다른 컴퓨터는 화면만 제공합니다. 서버가 프로젝트·워크트리·터미널·탭·제공자 계정·에이전트 세션을 가지고, 노트북은 실행 중인 그 Orca에 접속합니다. 가장 쉬운 방법은 양쪽 모두 Orca 데스크톱 앱 + Tailscale이며, 이 경우 orca serve는 필요 없습니다.
창 없는 서버(orca serve)에서 계정 등록 · 스킬 설치
헤드리스 orca serve 호스트에서는 원격 클라이언트의 Add account가 꺼져 있으므로, 관리형 Claude/Codex 계정을 서버 셸에서 등록합니다. 설정 화면 없이 에이전트 스킬도 설치·갱신할 수 있습니다.
orca account add --agent claude
orca account add --agent codex
orca account list
orca skills install --skill orca-cli --skill orchestration
orca skills update --all
권장: 데스크톱 앱 + 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를 다시 열면, 페어링된 탭을 중복하지 않고 서버가 가진 워크트리·탭·보이는 창 상태로 돌아옵니다. 페어링 서버 탭은 데스크톱 재시작 후에도 남고, 닫은 탭은 닫힌 채로 있습니다.
- 호스트 앱이 다시 실행된 뒤 페어링된 터미널이 다시 입력을 받고, 네트워크가 끊겼다 돌아오면 원격 브라우저 탭이 돌아오며,
orca serve가 재시작해도 폰의 터미널이 유지됩니다. - 원격 호스트에 워크트리를 만들어도 다른 연결된 데스크톱이 그쪽으로 끌려가지 않습니다.
- 서버에서 삭제한 프로젝트는 모든 페어링 클라이언트의 사이드바에서 사라집니다(유령 줄이 남지 않음).
- 여러 클라이언트가 한 서버를 공유하면 사이드바 필터의 Hide other-client workspaces로 이 기기가 만든 워크트리만 볼 수 있습니다(워크트리 장의 사이드바 레이아웃 참고).
접근 권한과 보안
Orca는 페어링한 클라이언트마다 따로따로, 취소 가능한 토큰을 만들고, 서버의 Shared Server Access에 목록으로 보여 줍니다. 지킬 일은 세 가지입니다.
🗑 필요 없어진 기기는 바로 내보내기
Shared Server Access에서 그 기기 옆 휴지통 버튼을 누르면 취소되고, 그 권한을 쓰던 클라이언트는 즉시 끊깁니다.
🎯 닿을 수 있는 기기를 최소로
Tailscale 관리 화면에서 이 서버에 닿을 수 있는 기기를 꼭 필요한 것만 남기세요.
🚫 인터넷에 직접 열지 않기
Orca 서버는 Tailscale이나 믿을 수 있는 LAN 같은 사설 경로로만 쓰세요.
링크 교체 규칙 · ACL/grant · 공개 포트 · 127.0.0.1
- 링크를 새로 만들면 아직 안 쓴 이전 링크는 대체됩니다. 이미 페어링한 클라이언트는 취소하기 전까지 자기 권한을 유지합니다.
- Tailscale ACL이나 grant(누가 어느 기기에 닿을 수 있는지 정하는 규칙)는 가능한 한 좁게 설정하세요.
- Orca 포트를 공개 인터넷에 직접 열지 마세요. Tailscale, WireGuard, 믿을 수 있는 LAN, SSH 포워딩, 인증된 터널을 쓰세요.
- 다른 컴퓨터용으로
127.0.0.1(localhost — 내 컴퓨터 자신을 가리키는 주소)을 고르지 마세요. 그 주소는 서버 자신에게서만 통합니다.
대안: 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 동작 세부 (앞 실행 · --pairing-address · orcad)
- 데스크톱 창을 열지 않고 Orca 런타임을 시작합니다.
- Ctrl-C를 누를 때까지 앞(foreground)에서 실행됩니다.
- 바인딩된 엔드포인트와 런타임 페어링 URL을 출력합니다.
--pairing-address는 클라이언트가 찾아올 주소를 알리는 데만 쓰입니다.- 기본으로 Orca 자체 Node 서버(orcad)에서 돕니다. orcad가 그 컴퓨터에서 돌 수 없으면 데스크톱 앱의 서버로 넘어가며, 이유를 한 줄 출력합니다. 패키지된 macOS 앱은 페어링된 클라이언트가 업데이트할 수 있도록 현재 항상 데스크톱 앱 서버를 쓰며,
ORCA_SERVE_RUNTIME=electron으로 그 경로를 강제할 수 있습니다.
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
LaunchAgent · systemd · lingering · 감독자 재시작 규칙
install은 macOS에서는 LaunchAgent, Linux에서는 systemd 사용자 유닛을 만들어 이 프로필용으로orca serve --supervise --no-pairing을 실행합니다.- 감독자(supervisor)는 실패가 반복돼도 무한히 재시작하지 않고 점점 긴 간격을 두고 재시작하며, 업데이트가 앱을 바꾸는 동안은 기다립니다.
- 서비스 로그에는 페어링 링크를 절대 출력하지 않습니다. 클라이언트 페어링은 데스크톱 앱에서 하거나, 서비스를 멈춘 상태에서 터미널로
orca serve를 실행해 하세요. - Linux에서는 lingering이 켜져 있지 않으면(
loginctl enable-linger) 로그아웃 시 서비스가 멈춥니다. install이 이를 알려 줍니다. status는 실행 여부를,uninstall은 서비스를 멈추고 유닛을 지우되 터미널 데몬과 그 세션은 계속 돌게 둡니다.- 이 서비스 명령은 아직 Windows에서 쓸 수 없습니다.
- 다른 서비스 관리자나 컨테이너가 이미 프로세스를 재시작해 준다면
orca serve --supervise를 직접 쓰세요.
데스크톱 앱인가, 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) 실행.
🌳 워크트리·호스트
폰에서 워크트리를 만들고 에이전트 시작. 저장된 컴퓨터의 이름·주소 고치기.
🔔 기타
에이전트가 끝나면 푸시 알림. 브라우저 탭을 폰 크기로 확인. 바뀐 파일 검토·커밋, 에이전트 계정 바꾸기.
모바일 기능 전체 목록 (보기 · 조작 · 워크트리·호스트 · 기타)
- 모든 워크트리·에이전트·상태(working 작업 중 / done 완료 / waiting 입력 대기)를 봅니다. 연결된 모든 호스트(로컬 데스크톱과 원격 Orca 서버)의 워크트리를 한 화면에 모아 보여 주므로 기기를 바꿀 필요가 없습니다. SSH 호스트의 워크트리는 줄 배지에 그 호스트의 상태를 데스크톱과 같은 말로 보여 줘, 끊긴 기계를 한눈에 알 수 있습니다.
- 파일 트리 전체를 깊은 경로까지 탐색해 아무 파일로나 바로 갈 수 있습니다. 동영상·음악 파일은 폰에서 미리보기로 재생됩니다.
- 지원되는 에이전트 세션을 Chat UI(채팅 형식 대화 기록)나 원래 터미널로 엽니다. 기기 기본값은 Settings → Chat UI, 탭 하나만 바꾸려면 세션 탭을 길게 누릅니다.
- 최근 터미널 스크롤 기록을 불러와 에이전트가 무엇을 했고 무엇을 물었는지 읽습니다. 터미널 스트림이 끝난 뒤에도 새 스냅숏을 받아 화면이 멈춰 있지 않습니다. 채팅 형식 화면의 마크다운은 메시지에 Mermaid 다이어그램이 있으면 그려 주고, 네이티브 채팅은 데스크톱과 같은 인라인 시각 자료와 하위 에이전트(subagent) 줄을 보여 줍니다.
- 모바일 터미널에서 텍스트를 선택·복사·붙여넣기 — 길게 눌러 선택하고, 공유 시트로 답장에 붙여 넣습니다.
- 터미널 보조 키 줄에서 폰 키보드로 치기 힘든 Tab, Shift+Tab 같은 키를 씁니다. 글자 하나하나를 바로 터미널로 보내려면 Live로 바꿉니다.
- 에이전트가 입력을 기다리면 짧은 답장(continue, yes, 자유 문장)을 보내거나, 사진·파일을 첨부하거나, 마이크를 눌러 받아쓰기로 답합니다. Live 모드에서는 받아쓴 글이 Return 없이 활성 터미널에 들어갑니다. Chat UI에서는 첨부 이미지가 메시지에 썸네일로 보이고, 글과 함께 또는 이미지만 보낼 수 있습니다.
- 세션 탭 줄에서 Quick Commands(저장된 터미널 명령·에이전트 프롬프트, 데스크톱 목록과 동기화)를 실행합니다.
- 세션 탭을 길게 눌러 여러 탭 한꺼번에 닫기(Close Other Tabs, Close Tabs to the Left, Close Tabs to the Right). 저장 안 된 마크다운 탭과 고정 탭은 건너뜁니다.
- 워크트리의 Source Control을 열어 바뀐 파일을 보고, stage/unstage하고, 커밋합니다.
- 에이전트 계정 바꾸기와 사용량·한도(rate-limit) 확인. Codex에 리셋 크레딧이 쌓였으면 계정 화면에서 하나를 씁니다.
- 데스크톱과 같은 Smart 소스 모드(Smart, GitHub, Linear, GitLab, Branch, Name)로 워크트리 만들기. 데스크톱이 여러 대 연결돼 있으면 New Workspace가 먼저 어느 호스트에 만들지 묻습니다(호스트가 하나면 묻지 않음).
- 폰에서 워크트리에 에이전트 시작 — 그 탭이 데스크톱에 바로 나타나지만, 데스크톱 창이 그 워크트리로 이동하지는 않습니다.
- 호스트 카드의 ⋯ 메뉴로 Edit, Connect, Remove 등(길게 누르기도 단축키로 동작).
- 다시 페어링하지 않고 저장된 호스트의 표시 이름이나 접속 주소 수정(예: 데스크톱이 집 LAN과 Tailscale 사이를 오갈 때).
- 호스트 목록과 열린 세션 사이를 슬라이드 전환으로 이동. Back은 그 페이지의 호스트 스택을 원래 자리로 되돌립니다.
- iPad에서는 호스트가 하나의 사이드바에 늘 보이고, 호스트 목록과 세션을 오가도 채팅 초안이 보존됩니다.
- 폰에서 브라우저 세션을 Web 또는 Mobile 보기로 열어 반응형 페이지를 확인합니다. 폰에서 연 브라우저 탭은 데스크톱이 최소화되거나 화면 보호기 상태여도 계속 로드됩니다.
- 에이전트가 끝나면 데스크톱 알림을 그대로 따라 하는 푸시 알림을 받습니다.
- 더 새로운 모바일 버전이 있으면 앱이 알려 주고 해당 릴리스로 연결해 줍니다.
페어링하기
데스크톱 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)을 폰에서 그대로 실행할 수 있습니다. 세션 탭을 길게 누르면 닫기·화면 바꾸기 메뉴가 나옵니다.
Chat UI 세부 (기기 기본값 · 입력창 · 모델 옵션)
데스크톱과 같은 채팅 지원 에이전트 — Claude, Codex, Grok, OpenCode, OMP, Pi — 는 모바일에서도 원래 터미널 대신 Chat UI로 열 수 있습니다. 읽기 쉬운 대화 기록, 입력창(composer), 권한 요청·질문, 이미지 첨부가 있습니다.
- 기기 기본값 — 처음 실행할 때 이 폰에서 세션을 어떻게 열지 묻습니다. 나중에 Settings → Chat UI → Open sessions in Chat UI에서 바꿉니다. 고르기 전까지 기본은 터미널입니다.
- 세션별 — 세션 탭을 길게 눌러 Switch to chat view 또는 Switch to terminal view. 그 탭에만 적용되고 기기 기본값은 바뀌지 않습니다.
- 입력창 — 답장 입력,
@로 워크트리 파일 언급, 공유 카탈로그의 에이전트별·슬래시 명령(Claude용과 Codex용이 따로, 설명 포함), 사진 첨부, 받아쓰기. 첨부 이미지는 지울 수 있는 썸네일로 보이며 함께 전송됩니다(이미지만 보내기, 여러 장 첨부 포함). - 모델·세션 옵션 — 입력창에 현재 모델과 세션 옵션을 보여 주는 알약 줄이 있습니다. 눌러서 모델이나 옵션을 고르면 터미널로 내려가지 않아도 됩니다(Codex 모델 직접 선택, 활성 모델이 지원할 때 제공자별 Fast 모드 포함).
- 에이전트 주인은 여전히 데스크톱 — Chat UI는 페어링된 데스크톱 세션을 보여 주는 화면일 뿐, 별도의 클라우드 에이전트가 아닙니다.
Quick Commands 세부
워크트리 세션에서 세션 탭 줄(새 터미널 버튼 옆)의 Quick Commands를 엽니다. 데스크톱과 같은 저장 목록이며 양쪽으로 동기화됩니다.
- Terminal Command — 셸 명령을 새 탭에 붙여 넣거나 실행합니다(먼저 고칠 수 있게 Enter를 누르지 않는 선택도 가능).
- Agent Prompt — 고른 에이전트를 저장된 프롬프트와 함께 엽니다.
- 줄의 복사 버튼으로 명령 내용을 클립보드에 복사합니다(내용이 비면 비활성).
- 명령의 범위를 전체(global) 또는 현재 프로젝트로 정합니다. 시트에서 추가·편집·삭제하며, 공유 목록 최대 개수는 데스크톱 호스트가 정합니다.
- 페어링된 데스크톱이 너무 오래된 버전이면 데스크톱을 업데이트할 때까지 실행기가 꺼져 있습니다.
세션 탭 길게 누르기 메뉴
세션 줄의 탭을 길게 누르면 Close, Close Other Tabs, Close Tabs to the Left, Close Tabs to the Right 같은 동작이 나옵니다. 여러 탭 닫기는 저장 안 된 마크다운 탭(모바일은 닫을 때 저장할지 묻지 않음)과 고정 탭을 건너뜁니다. 채팅 지원 에이전트 탭이면 같은 시트에서 Chat UI ↔ 터미널을 바꿀 수 있습니다.
계정 전환기 · 워크트리 만들기
폰에서 계정을 바꾸면 페어링된 데스크톱의 계정이 바뀝니다. 폰 홈 화면의 Create Workspace / New Workspace로 데스크톱에 새 워크트리를 만들 수도 있습니다.
계정 전환기 · Codex 리셋 크레딧 세부
데스크톱 상태 표시줄과 같은 계정 전환기가 있으며, 비활성 계정의 사용량도 함께 보입니다. 제공자가 세션·주간 한도의 리셋 시각을 알려 주면 계정 화면에 남은 시간이 표시됩니다. 여기서 바꾸면 페어링된 데스크톱에서 계정이 바뀝니다.
활성 Codex 계정에 한도 리셋 크레딧이 쌓였으면, 사용 가능한 개수(다음 크레딧 만료 시각 포함)와 Use reset 동작이 보입니다. 확인하면 현재 Codex 대상(호스트 또는 WSL 배포판)에 크레딧 하나를 쓰고 해당 한도 창을 새로 고칩니다. 폰이 시도를 기록해 두므로 연결이 불안정해 다시 시도해도 두 번 쓰이지 않습니다. 결과는 성공, 리셋할 것 없음, 남은 크레딧 없음, 이미 리셋됨 중 하나입니다(사용량·한도 추적 장 참고).
워크트리 만들기 세부 (소스 모드 · 호스트 고르기)
모바일 홈 화면에서 Create Workspace / New Workspace를 열고 소스 모드를 고릅니다. Smart는 지원되는 작업 제공자와 브랜치를 모두 검색하고, 나머지 모드는 GitHub, Linear, GitLab, 브랜치, 또는 그냥 워크트리 이름으로 범위를 좁힙니다. 소스를 고른 뒤 Advanced에서 이름과 브랜치를 정하고 페어링된 데스크톱에 만듭니다. 데스크톱이 여러 대 연결돼 있으면 먼저 호스트를 고르며(비슷한 이름도 구분되도록 엔드포인트를 함께 표시), 연결된 데스크톱이 없으면 이 동작은 꺼져 있습니다.
페어링된 호스트 편집
호스트 목록에서 카드의 ⋯(또는 카드 길게 누르기) → Edit host.
| 항목 | 설명 |
|---|---|
| Name | 이 폰에서만 쓰는 표시 이름. 데스크톱 기기 이름보다 우선하며, 비우면 데스크톱 이름으로 돌아감 |
| Address | IP, host:port, 또는 ws:///wss://. 포트를 빼면 현재 포트를 유지(없으면 기본 6768). 이 폰이 접속하는 곳만 바뀌고 다시 페어링하지 않음. 같은 데스크톱에 다른 경로(집 LAN ↔ Tailscale)로 닿을 때 사용 |
주소를 바꿔 저장하면 새 엔드포인트로 다시 연결하며, 페어링 토큰은 그대로입니다.
소스 컨트롤 · 브라우저 · 화면 설정
한 줄 요약: 브랜치 아이콘으로 바뀐 파일을 보고 커밋하고, 브라우저 창의 Web / Mobile 스위치로 폰 크기 화면을 확인하며, Settings에서 화면 테마(밝게·어둡게)와 언어를 고릅니다.
소스 컨트롤 · 브라우저 보기 · Appearance·Language 세부
워크트리 세션에서 브랜치 아이콘을 누릅니다. 작은 후속 작업용입니다: 브랜치 상태 확인, 바뀐 경로 살펴보기, 파일 stage/unstage, stage가 준비되면 커밋. 브랜치 커밋을 둘러보고 바뀐 파일을 diff 화면에서 엽니다. diff에서는 파일 사이를 이동하고, 문맥을 접고, PR(Pull Request — 내 변경을 합쳐 달라고 요청하고 검토받는 GitHub 기능) 리뷰 댓글을 코드 옆에서 읽거나 답니다. 충돌을 해결하고 병합을 마칠 수도 있습니다. 브랜치에 이미 GitHub PR이 있으면 빈 PR 화면의 Link an existing PR로 새로 만들지 않고 연결합니다.
모바일 브라우저 창에 Web / Mobile 스위치가 있습니다. Web은 일반 페이지를, Mobile은 페어링된 데스크톱 브라우저에 폰 크기의 반응형 화면을 요청합니다.
Appearance · Language모바일 Settings의 Appearance에서 Light·Dark·System(밝게·어둡게·기기 설정 따름)을, Language에서 표시 언어를 고릅니다. 최신 모바일 설정을 쓰려면 Orca Mobile과 데스크톱(또는 서버)을 모두 업데이트하세요.
터미널 설정 (Settings → Terminal)
글자 크기(50%–200%)와 자동 고침 켜기/끄기를 폰마다 따로 정할 수 있습니다.
Text size · Autocomplete & autocorrect · 키보드 세부
- Text size — 화면 폭 맞춤 위에 적용되는 50%–200% 기본 확대 비율. 터미널에서 두 손가락으로 확대/축소하면 같은 단계에 맞춰지고 저장됩니다. 기기별 설정이라 데스크톱 터미널은 바뀌지 않습니다.
- Autocomplete & autocorrect — 기본은 꺼짐. 그래서 OS가 명령·옵션·경로를 멋대로 고치지 않습니다. 폰식 입력을 원하면 켜세요. 어느 쪽이든 실시간 키보드 입력은 원래 키 그대로 전달됩니다.
- 키보드는 일반 앱 화면처럼 페이지를 덮고, 페이지가 높이를 알려 주므로 입력창과 현재 입력란이 타이핑 중에도 보입니다.
모바일 문제 해결
워크트리에서 스피너가 계속 돎
폰은 데스크톱 에이전트 프로세스의 하트비트(살아 있다는 신호)를 따라갑니다. 데스크톱은 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 서버의 모바일 페어링을, 제공자 사용량은 사용량·한도 추적 장을 참고하세요.
Android에 Orca Mobile 설치하기 (APK)
- 내려받기Chrome 같은 완전한 브라우저에서 Orca 다운로드 페이지를 열고 Android를 고릅니다.
- 파일 열기다운로드가 끝나면 브라우저의 다운로드 목록이나 기기의 Files → Downloads에서
app-release.apk를 누릅니다. - 설치Android 설치 안내를 따릅니다. 물으면 브라우저나 Files 앱에만 "출처를 알 수 없는 앱 설치"를 허용하고, Orca 설치가 끝나면 그 권한을 다시 끄세요.
설치 문제 해결
다운로드가 시작되지 않거나 끝나지 않음
Discord, GitHub 같은 다른 앱 안에서 링크가 열렸다면 Open in browser / Open in Chrome을 고르거나 링크를 복사해 완전한 브라우저에 붙여 넣으세요. 그런 다음 Android 다운로드를 다시 시작하고 끝날 때까지 기다리세요.
Samsung Galaxy: Auto Blocker가 설치를 막음
Settings → Security and privacy → Auto Blocker(설정 → 보안 및 개인정보 보호 → 자동 차단)를 열어 잠시 끄고, Orca를 설치한 뒤 다시 켜세요. Play Protect는 끄지 마세요.
- 다른 컴퓨터(서버)가 없다면 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는 그대로.
출처: onorca.dev/docs/ssh · onorca.dev/docs/remote-servers · onorca.dev/docs/recipes/remote-worktrees · onorca.dev/docs/mobile · onorca.dev/docs/android-apk
봇(Bots) — 일을 받아 오고, 일정대로 돌고, 사람 대신 보고하는 에이전트
봇은 이름·목적·기억을 가진 에이전트입니다. Slack·GitHub·Linear·자기 채팅·정해 둔 일정에서 일을 받아, 내 컴퓨터의 Claude Code나 Codex로 처리하고, 부탁받은 곳에 결과를 보고합니다. 결정이 필요하면 Orca에서 나를 기다립니다.
- 봇이 무엇이고, 그냥 에이전트 채팅과 무엇이 다른지
- 봇 만들기, 첫 일 맡기기, 대화하기, 일정·이벤트로 돌리기, 중간에 끼어들기
- Slack·GitHub·Linear·Google·웹훅(webhook) 연결과, 봇이 누구의 이름으로 일하는지
- 누가 봇에게 일을 시킬 수 있는지(Who can ask)와 권한·보안 — Orca가 강제하는 것과 봇이 지시만 받는 것
- 봇이 시키지 않아도 하는 일(둘러보기·기억 정리), 다른 앱의 봇 가져오기, 쓰임새 8가지와 템플릿 24종
- 봇이란 무엇인가 — 그림 한 장으로 "일이 어디서 와서 어디로 가는지"
- 봇 만들기 — 사이드바 Bots 칸에서 다섯 단계
- 첫 일 맡기기 — 진짜 할 일 하나를 말하면 봇이 작은 조각부터 해 봅니다
- 누가 시킬 수 있나 (Who can ask) — 동료를 넣기 전에 꼭 읽을 곳
건너뛰어도 되는 곳: 「연결(Connectors)」의 서비스별 설정, 「다른 앱의 봇 가져오기」. 「🔧」로 접힌 상자는 접어 둔 채 읽어도 됩니다.
봇이란 무엇인가
봇은 자기 채팅, Slack, Linear, GitHub, 정해 둔 일정에서 일을 받습니다. 일은 내 컴퓨터에서, 내가 이미 쓰는 Claude Code나 Codex(또는 다른 지원 에이전트)로 합니다. 그래서 봇이 한 일은 그 에이전트 요금제 사용량으로 잡힙니다. 끝나면 부탁받은 곳에 보고하고, 결정이 필요하면 Orca 안에서 나를 기다립니다.
이름과 사진
Slack에서는 @scout처럼 자기 이름으로 보입니다.
목적(soul)
"무엇을 하는 봇인지" 적은 설명. 첫 대화 뒤 봇이 스스로 적어 두어, 이후 모든 대화가 같은 곳에서 시작합니다.
기억(memory)
일하며 배운 것을 적어 두는 곳. 새 일마다 새 채팅을 열어도 같은 설명을 반복할 필요가 없습니다.
자동화
"평일 9시마다", "PR이 열리면"처럼 정해 둔 때에 스스로 시작하는 일.
봇은 한 컴퓨터의 폴더 하나에 삽니다. 목적·기억·능력은 그 폴더 안의 평범한 Markdown 파일이라 직접 읽고 고칠 수 있습니다.
시작 전 준비
- 최신 Orca봇을 둘 컴퓨터에 최신 버전 Orca를 설치합니다.
- 에이전트 설치·로그인그 컴퓨터에 Claude Code·Codex 등 지원 에이전트를 설치하고 로그인해 둡니다. 봇은 그 에이전트로 일하므로 사용량도 그 요금제에서 나갑니다.
- (선택) Orca 로그인Slack·GitHub·Linear에서 봇을 부르려면 Orca에 로그인(Sign in to Orca)해야 합니다. 봇 채팅·일정·Google은 로그인 없이도 됩니다.
봇 만들기
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)인지 진짜 문제인지 알려 줘."
봇은 그 일에 무엇이 필요한지 살펴보고, 작은 조각 하나를 바로 해서 결과를 보여 줍니다. 그다음 자기 목적을 적어 두고, 배운 것은 기억에 남깁니다.
템플릿으로 만든 봇은 목적이 이미 있고, 일부는 능력과 일정도 갖고 있습니다. 템플릿의 일정은 꺼진 채로 시작합니다. 어느 저장소·채널을 쓸지 첫 채팅에서 정하면, 그때 자동화와 연결이 설정됩니다.
대화하기와 「Needs you」
사이드바에서 봇을 누르면 봇 채팅이 열립니다. 무엇이든 물어보면 됩니다. 다른 Orca 채팅에서도 @를 입력해 봇을 부르면 그 대화에 봇을 데려올 수 있습니다.
봇이 나를 필요로 할 때(결정·로그인·승인)는 그렇게 말하고, 그 요청은 봇 Home의 Needs you(내 차례) 아래에서 내가 답할 때까지 기다립니다. 봇이 제안한 답 중 하나를 누르거나 내 말로 답합니다.
Needs you 1 — Pay button ignores first tap on Safari
In progress 작업 중 — Search shows stale results… · Coupon field accepts expired codes…
Automations — Triage new bugs (New Linear bug) · Morning bug digest (Weekdays 9:00 AM)
봇 Home은 위에서부터 "나를 기다리는 것 → 봇이 하는 일 → 자동화" 순서로 보여 줍니다. 위 화면은 공식 문서의 예시 데이터를 옮긴 것입니다.
폰에서도: iOS·Android Orca 앱이 Needs you를 한 목록으로 보여 줍니다. 한 번 눌러 답하거나 승인하고, 밖에서도 새 일을 맡길 수 있습니다. 모바일 앱 자체는 8장 모바일 앱을 보세요.
일정·이벤트로 돌리기
봇 채팅에서 일정("평일 9시마다")이나 이벤트("acme/web에 PR이 열리면")를 말하면, 봇이 자동화를 만들고 어디서 돌며 결과가 어디로 가는지 알려 줍니다. 자동화는 봇 패널에 보이고 거기서 멈추거나 다시 켤 수 있습니다.
- 일정 종류: 매시간 · 매일 · 평일 · 매주 · cron · RRULE(둘 다 "매달 첫째 월요일"처럼 복잡한 반복을 글자로 적는 방식).
- 시작할 수 있는 이벤트는 붙인 연결에 따라 다릅니다(→ 연결). 예약 자동화 자체는 7장 예약 자동화에 있습니다.
중간에 끼어들기
봇의 일은 모두 Orca 안에 남으므로 언제든 이어받을 수 있습니다.
| 보고 싶은 것 | 여는 법 |
|---|---|
| 작업자의 작업 공간 | 사이드바에서 봇 아래의 작업자를 누릅니다. 작업자가 멈춘 곳 그대로 그 워크트리의 에디터·터미널·브라우저가 열립니다. |
| Slack·GitHub·Linear에서 온 대화 | 봇 아래에 대화마다 채팅이 따로 있습니다. Slack 스레드의 Open this thread in Orca 링크, Linear 이슈의 봇 세션에서 Open in Orca로도 엽니다. |
| 봇의 PR | 다른 PR처럼 검토합니다. 내 작업 폴더가 아니라 작업자의 브랜치에서 옵니다. |
연결(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에서 Get your configuration token을 누릅니다. Slack 앱 설정에서 Your App Configuration Tokens를 찾아 Generate Token.
- 봇을 둘 워크스페이스를 고릅니다.
- Refresh Token(
xoxe-로 시작)을 복사해 Orca에 붙여 넣습니다.
Orca Cloud는 이 토큰을 내 Orca 계정·그 워크스페이스용으로 암호화해 보관하므로, 같은 워크스페이스의 다음 봇부터는 다시 넣지 않습니다. 그다음 Slack에서 나로서 봇 앱을 승인합니다. 관리자 승인이 필요한 워크스페이스면 승인 뒤에 봇이 들어옵니다.
워크스페이스 토큰은 언제든 지울(forget) 수 있습니다. 이미 Slack에 있는 봇은 남고, 새 봇은 새 토큰이 필요합니다. Slack 연결을 지우면 Slack에서 오는 새 일만 멈추고, Slack의 앱 자체는 지워지지 않습니다.
- 연결Orca에 로그인한 뒤 봇의 Connectors에서 GitHub → Connect GitHub. 브라우저에서 GitHub로 로그인합니다.
- 앱 설치Install the Orca app으로 봇이 일할 저장소에 Orca 앱을 설치합니다. 조직(organization)에서는 소유자 승인이 필요할 수 있습니다.
- 켜기Turn on으로 봇에 켭니다. 나중에 Add repositories or organizations로 일할 곳을 늘립니다.
부른 곳에는 Orca 앱으로 답하고, 그 밖의 GitHub 일은 그 컴퓨터의 내 gh 로그인으로 합니다. 봇은 "내가 시킬 때만 승인·변경 요청·병합(merge)하라"는 지시를 받지만, Orca가 강제하지는 않습니다(→ 권한과 보안).
🔧 자동화를 시작할 수 있는 GitHub 이벤트
- 새 이슈·PR, push, 댓글·리뷰, 리뷰 요청, 라벨.
- CI 실패·통과, 병합 충돌(merge conflict), 병합, 배포, 보안 경고, 끝난 워크플로 실행.
내가 GitHub에서 직접 한 일(댓글·리뷰·push)은 봇을 깨우지 않습니다. 봇이 거기서 나로 일하기 때문입니다. 예외는 "내 새 PR을 리뷰해 줘"처럼 내가 연 PR을 대상으로 한 규칙입니다. GitHub가 알려 주는 변화(CI 결과·병합 충돌·병합·닫힌 PR·배포·보안 경고·끝난 워크플로)는 내가 일으켰어도 켜 둔 규칙을 시작합니다.
- 연결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로 연결하는 곳들입니다.
🔧 「누가 시켰는지」 기록 줄
Orca가 나 아닌 사람이 시킨 일임을 알 수 있으면, 봇이 Orca를 통해 쓰는 새 Linear 댓글, Gmail 초안, 설명이 있는 새 캘린더 일정, Docs 댓글 글에 "asked by Maya via Scout" 같은 줄을 넣습니다. 초안은 누가 먼저 고치지 않는 한 보낼 때도 그 줄이 남습니다. 봇이 만든 Drive 파일·폴더·Docs의 설명과 Drive 공유 메일에도 누가 시켰는지 적습니다. 누가 시켰는지 모르면 아무것도 넣지 않고, 이슈 수정 같은 편집에는 넣지 않습니다.
누가 시킬 수 있나 (Who can ask)
기본으로는 나만 내 봇에게 일을 시킬 수 있습니다. 동료가 Slack·Linear·GitHub에서 시키게 하려면 봇 설정의 Who can ask에 그 사람을 넣습니다. 넣기 전에 알아 둘 것:
- 그 사람 자기 권한이 아니라 내 권한, 내 컴퓨터로 일합니다. 봇이 할 수 있는 일이면 그 사람도 시킬 수 있습니다.
- 봇을 원격으로 조종할 수 있습니다: 시작·방향 바꾸기·승인·멈추기.
- 그래서 내 키보드 앞에 앉혀도 믿을 사람만 넣습니다.
- Orca가 보통 "주인에게 물어보세요"라는 메모로 답하고, 결정은 내가 Orca에서 합니다. Slack에서는 그 사람에게만 보이고, GitHub·Linear에서는 공개 답글입니다.
- 봇이 이미 있는 스레드에서 그 사람들의 메시지는 봇이 맥락으로 읽습니다. 다만 일을 시작하거나 방향을 바꾸지는 못합니다.
이벤트 자동화와 웹훅은 Who can ask와 따로입니다. "#eng에 누가 글을 올리면" 같은 규칙을 켜면, 나만 봇을 부를 수 있어도 나와 봇이 함께 있는 곳의 누구든 그 규칙을 시작시킵니다. 봇에게 듣는 곳을 좁혀 달라고 하거나, 일부 이벤트는 "Maya나 Sam이 올릴 때만"처럼 사람을 정할 수 있습니다. 쓰지 않는 규칙은 멈춰 둡니다. 웹훅은 signing secret이 없으면 주소를 가진 누구나 시작시킵니다.
시키지 않아도 하는 일 — 둘러보기와 기억 정리
내가 시킨 일과 자동화 말고도, 봇은 작은 일 두 가지를 스스로 합니다. 둘 다 에이전트 요금제를 씁니다.
👀 Look around (둘러보기)
Claude Code나 Codex로 도는 봇이 하루 몇 번 Slack·Linear·GitHub와 내 프로젝트에서 나를 기다리는 것을 읽고, Suggestions(제안)에 다음 할 일을 적습니다. 읽기만 하며 글을 올리거나 파일을 바꾸지 못합니다. 기본은 평일 오전 8시~오후 8시, 4시간마다이고, 봇 컴퓨터에서 Orca가 켜져 있을 때 돕니다. 봇 설정의 Look around에서 횟수를 바꾸거나 끕니다.
🧹 Memory upkeep (기억 정리)
기본으로, 새 채팅이 있었던 날이면 Claude Code나 Codex 봇이 그날 밤 3시 이후(멈춰 있거나 바쁘지 않을 때) 기억을 정리합니다. 컴퓨터가 자느라 놓친 정리는 깨어난 뒤 따라잡을 수 있습니다. 바뀐 내용을 검토할 수 있고, 가능할 때는 Undo로 MEMORY.md를 되돌립니다. 봇 설정의 Memory upkeep에서 주 1회로 바꾸거나 끕니다.
권한과 보안 — Orca가 막는 것과 봇이 지시만 받는 것
봇은 내 권한으로, 나를 대신해 일합니다. 다른 사람이 봇을 부르게 하거나, 바깥에서 오는 메일·이슈·메시지를 봇에 연결하기 전에 이 소절을 읽으세요.
봇이 닿을 수 있는 곳
| 어디 | 무엇을 할 수 있나 |
|---|---|
| 자기 컴퓨터 | 그곳의 내 파일·명령·계정을, 나로서, 권한이 허락하는 만큼 |
| Slack | 자기 앱(@봇이름)으로 글 올리기 |
| GitHub | 부른 곳에는 Orca 앱으로 답, 그 밖의 댓글·리뷰·push는 나로 |
| Linear | 부른 곳에는 Orca 앱으로 답, 이슈 댓글·수정·생성은 나로 |
| 켜 준 서비스만 — 메일 읽기·보내기, 캘린더, Drive 파일·Docs·Sheets 읽기·고치기 등 |
연결은 붙인 뒤에만 닿는 곳을 늘립니다.
권한 모드
봇 대화도 다른 Orca 채팅과 같은 권한 모드로 돕니다: Ask for approval(매번 승인 받기) · Accept edits(편집은 허용) · Approve for me(나 대신 승인) · Full access(전부 허용). 쓸 수 있는 모드는 에이전트마다 다릅니다(→ 3장 권한 기본값).
- 봇의 새 대화는 따로 정하지 않으면 내 채팅 권한 설정으로 시작합니다. Orca 채팅 기본값이 Full access라서, 바꾸지 않으면 새 봇도 Full access — 명령 실행·파일 수정 전에 묻지 않습니다.
- 다른 사람이 부르는 봇, 바깥 메일·이슈·메시지를 읽는 봇은 봇 설정에서 Ask for approval로 바꿉니다. Codex라면 요청이 승인될 때까지 읽기 전용으로 일합니다. 이미 열린 대화는 원래 권한을 유지합니다.
- 승인 모드가 없는 에이전트로 도는 봇은 늘 Full access입니다. 승인이 필요하면 Claude Code나 Codex처럼 승인 모드가 있는 에이전트를 고릅니다.
- 봇이 승인을 구하면 그 일을 시킨 사람이 승인할 수 있습니다.
작업자는 자기 워크트리 안에서만: 봇이 코드 일을 넘기면 작업자는 내 작업 폴더가 아니라 봇 아래의 새 워크트리에서 돌고, 변경은 내가 검토할 브랜치와 PR로 들어옵니다.
🔧 데이터가 머무는 곳과 비밀값 보관
- 봇은 한 컴퓨터(이 컴퓨터 또는 Orca와 페어링한 서버)의 폴더에 삽니다. 목적·기억·능력은 그 폴더의 평범한 파일이고, 채팅 기록은 그 컴퓨터의 Orca 저장소에 있습니다.
- 봇은 내가 고른 에이전트의 내 로그인으로 돕니다. 다른 에이전트 세션처럼, 봇이 읽은 것은 그 에이전트의 모델 회사로 갑니다.
- Slack·GitHub·Linear·웹훅은 Orca Cloud를 거칩니다. Orca Cloud는 컴퓨터가 가져갈 때까지(잠들어 있으면 최대 하루) 요청을 보관합니다. 전달 뒤에도 일부 글이 한동안 남습니다 — 봇이 맥락으로 쓰는 최근 스레드 메시지, 전달되지 않은 요청(다시 보낼 수 있게), 웹훅 호출 본문(살펴볼 수 있게 최대 7일).
- Slack용으로 Orca Cloud는 내 Orca 계정·워크스페이스마다 암호화한 configuration token 하나를 보관합니다.
- Google은 내가 만든 Google Cloud 앱을 쓰고, 로그인은 내 컴퓨터에 머뭅니다. 새 메일·일정 규칙도 내 컴퓨터에서 확인합니다.
- Google·Composio 로그인은 봇 컴퓨터에 OS 키체인(keychain — 운영체제의 비밀번호 금고)으로 암호화해 저장합니다. 키체인이 없으면 내 사용자만 읽을 수 있는 파일(0600)에 암호화 없이 둡니다.
- 웹으로 닿는 MCP 서버의 헤더·로그인은 Orca가 암호화해 보관하고 호출마다 붙입니다. 키체인이 없으면 저장하지 않습니다.
- 명령으로 실행하는 MCP 서버의 설정(환경 변수에 넣은 키 포함)은 봇의 도구 설정에 암호화 없이, 내 사용자만 읽을 수 있게 저장됩니다.
- 봇은 비밀값을 기억에 저장하지 말라는 지시를 받습니다. 가져오기는 키·로그인 파일을 건너뛰고 서비스마다 다시 연결하게 합니다.
검토할 수 있는 것
- 봇의 모든 채팅(자동화·이벤트로 시작한 실행 포함)이 기록에 남습니다.
- 자동화마다 실행 기록, 웹훅마다 받은 호출 목록이 있습니다.
- 목적·기억은 봇 폴더의 Markdown 파일 — 읽고 고치고, 밤 정리가 바꾼 것을 검토합니다.
- 코드 일은 브랜치와 PR로 옵니다.
권한 되돌리기 (봇 설정에서 언제든)
- Keep only me: Who can ask에 넣은 사람을 뺍니다. 이벤트 자동화·웹훅은 멈추지 않으니 따로 멈춥니다.
- 봇의 Google 끄기(다음 Google 요청부터 모두에게).
- 새 대화를 Ask for approval로 시작.
- Connectors 탭에서 연결 지우기, Slack 워크스페이스 토큰 지우기.
- 자동화 멈추기, 또는 Settings → Bots에서 봇 끄기.
- 웹훅 주소가 샜으면 키 바꾸기·웹훅 지우기.
다른 앱의 봇 가져오기
다른 봇 앱에서 쓰던 봇이 있으면 그 봇의 성격(persona)·기억·능력·일정을 가져올 수 있습니다. 새 Orca 봇이 옛 봇을 읽고, 계획을 보여 주고, 내가 승인하면 스스로 설정합니다. 옛 봇은 읽기만 하고 바꾸지 않습니다. Bots 소개 쪽은 OpenClaw·Hermes에서 가져오는 경우를 예로 듭니다.
- 시작사이드바 Bots 칸에서 + → New bot → Import from another app…. Orca가 이 컴퓨터에서 지원하는 봇 앱의 봇을 찾아 목록으로 보여 줍니다(찾으면 먼저 가져오기를 권할 수도 있습니다).
- 고르기찾은 봇이면 골라서 새 이름을 주고 만듭니다. 못 찾은 봇은 Another app…: Orca가 주는 메시지를 옛 봇에게 보내면 옛 봇이 자기 파일을 한 폴더에 복사합니다. 그 폴더를 넣고, 옛 봇이 답을 썼으면 붙여 넣고, 이름을 주고 만듭니다.
- 계획 검토새 봇이 찾은 것을 묶어서 보여 줍니다. 채팅에서 "전부 가져와" 또는 "이건 빼"라고 답할 때까지 아무것도 설정하지 않습니다.
가져온 뒤
- 자동화는 멈춘 채로 옵니다. 옛 봇과 새 봇이 같은 일을 두 번 하지 않게, 옛 앱에서 옛 봇을 끈 뒤 새 봇에게 자동화를 켜 달라고 합니다. 옛 앱이 아직 돌고 있으면 봇이 어떤 일이 두 번 돌지 알려 줍니다.
- 옛 봇이 쓴 말은 참고용으로 새 봇의 기억에 남되, 지시가 아닌 메모로 표시됩니다.
- 옛 봇이 쓰던 도구는 키 없이 옵니다. 봇이 물어보면 다시 로그인합니다.
- Slack·GitHub·Linear가 필요한 것이 있으면 봇이 연결을 권합니다. 이벤트로 시작하는 자동화는 그 연결이 붙을 때까지 기다립니다.
- 새 봇은 옛 앱의 모델 설정이 아니라 내 Claude Code·Codex(또는 다른 지원 에이전트) 로그인으로 돕니다.
- 이 컴퓨터에서 찾은 봇이면, 나중에 같은 옛 봇으로 가져오기를 다시 시작해 Update할 수 있습니다. 새로 생기거나 바뀐 것만 더하고, Orca에서 내가 고친 것은 지킵니다.
쓰임새 8가지와 템플릿 24종
모든 쓰임새는 같은 모양입니다: 내가 부탁(Slack·Linear·GitHub·봇 채팅·일정) → 봇이 내 컴퓨터에서 일함 → 부탁받은 곳에 보고 → 사람이 정할 곳에서 기다림. 대부분의 템플릿은 먼저 보고하고, 바꾸기 전에 묻습니다. 봇이 스스로 하는 범위는 채팅에서 넓힐 수 있습니다.
아래 예는 공식 문서의 예시 봇 Scout, 예시 저장소 acme/web, Slack 채널 #eng를 씁니다.
시작: Bug investigation 템플릿 + GitHub, 사람들이 부를 Slack.
- 부탁#eng에서 Maya: "@scout checkout breaks on Safari, can you look?"
- 봇이 하는 일새 워크트리에서 작업자가 버그를 재현하고 단계를 적은 뒤 시작점을 찾습니다. 수정 전에 묻고, 동의하면 작업자가 고치고 테스트를 돌려 내 git 로그인으로 PR을 엽니다.
- 돌아오는 것Slack 스레드에 원인·테스트 결과·PR.
- 내가 끼는 곳"Start a fix?" 질문이 Needs you에서 기다립니다. PR은 다른 PR처럼 검토합니다.
시작: Linear를 연결한 봇(템플릿 없음 — 채팅에서 설명).
- 부탁"ENG 팀에 새 이슈가 오면 재현 단계가 있는지 보고, 중복을 찾고, 라벨과 담당자를 제안해. 닫기 전엔 물어봐."
- 봇이 하는 일Linear 새 이슈 이벤트로 시작하는 자동화를 만들고, 이슈마다 설명을 읽고 중복을 찾고, 허락한 변경을 나로서 합니다.
- 돌아오는 것봇 채팅에 이슈마다 짧은 한 줄.
- 내가 끼는 곳중복 닫기처럼 묻기로 한 일은 Needs you에서 기다립니다.
시작: CI failures 템플릿 + GitHub.
- 부탁템플릿에 이미 "검사가 실패하면 flaky인지 진짜인지 말해 줘"가 있습니다. 채팅에서 "진짜면 고치기 전에 물어봐"를 더합니다.
- 봇이 하는 일실패를 읽고 설명하며 flaky인지 진짜인지 말합니다. flaky 검사 목록을 모아 매주 월요일 오전 9시에 올립니다.
- 돌아오는 것봇 채팅에 설명.
- 내가 끼는 곳진짜 실패면 Needs you에서 수정 작업자를 시작할지 묻고, 수정은 PR로 옵니다.
시작: Daily standup notes 템플릿 + GitHub·Linear(올리려면 Slack).
- 부탁템플릿 일정은 평일 오전 9시. 봇 패널에서 켭니다. 공유하려면 "#standup에도 올려 줘".
- 봇이 하는 일워크트리·PR·이슈를 보고, 어제 나와 에이전트들이 한 일과 다음 할 일을 씁니다.
- 돌아오는 것봇 채팅에, 부탁했으면 #standup에도 봇의 Slack 앱으로.
- 내가 끼는 곳틀린 것은 채팅에서 고칩니다. 배운 것은 기억에 남아 다음 날부터 반영됩니다. 일정은 봇 컴퓨터가 깨어 있을 때만 돕니다.
시작: Pull request review 템플릿 + GitHub.
- 부탁고른 저장소에서 누군가 내 리뷰를 요청하면 시작(템플릿 설정).
- 봇이 하는 일PR을 검토해 위험한 변경과 빠진 테스트를 파일·줄과 함께 적습니다.
- 돌아오는 것봇 채팅에 결과. 예: "#4121: 재시도 횟수가 초기화되지 않아 두 번째 장애 때 재시도가 멈춥니다."
- 내가 끼는 곳내가 허락할 때까지 GitHub에 댓글을 달지 않습니다. 올릴 항목을 말하면 나로서 올립니다.
시작: Release notes 템플릿 + GitHub.
- 부탁봇 채팅에서 "4.12 노트 초안 써 줘" (Slack이 있으면 채널에서 "@scout draft the notes for 4.12").
- 봇이 하는 일지난 릴리스 뒤 병합된 PR을 읽고 사용자용 노트를 새 기능·고친 것·바뀐 것 세 묶음으로 씁니다.
- 돌아오는 것부탁한 스레드나 채팅에 초안.
- 내가 끼는 곳채팅에서 문구를 고치고, 마음에 들면 changelog에 넣는 PR을 열어 달라고 하거나 직접 복사합니다.
시작: Docs upkeep 템플릿 + GitHub.
- 부탁템플릿 일정은 매주 수요일 오전 10시, 고른 저장소 대상.
- 봇이 하는 일최근 병합된 PR과 문서를 비교해, 더는 맞지 않는 쪽과 틀린 줄을 적습니다.
- 돌아오는 것봇 채팅에 목록.
- 내가 끼는 곳고칠 쪽을 고르면 작업자가 자기 워크트리에서 고쳐 PR을 엽니다.
시작: Deploy watch 템플릿 + GitHub(배포마다 실린 PR을 읽으려고).
- 부탁"배포용 웹훅 만들어 줘." 자동화 카드의 Copy URL로 주소를 복사해 배포 도구에 넣고, 지원하면 signing secret도 넣습니다.
- 봇이 하는 일도구가 호출할 때마다 실린 PR로 배포를 요약하고 실패한 배포를 표시합니다. 호출 내용은 지시가 아니라 정보로 받습니다.
- 돌아오는 것배포마다 봇 채팅에 요약.
- 내가 끼는 곳이상해 보이면 물어봅니다. 주소가 새면 Rotate key….
나머지 템플릿 16종 (위 8가지에 쓰인 것 말고)
| 템플릿 | 하는 일 | 보고 시점 |
|---|---|---|
| Bug report intake | Slack 채널에 올라온 버그마다 재현 단계가 있는 Linear 이슈 초안을 쓰고, 승인하면 등록 | 버그가 올라올 때 |
| GitHub issue triage | 새 이슈마다 라벨·중복을 제안하고 빠진 정보를 적음 | 이슈가 열릴 때 |
| Support triage | 고른 Slack 채널의 답 없는 질문과, 이미 Linear 이슈가 있는지 적음 | 평일 오전 9시~오후 5시, 2시간마다 |
| Feedback digest | Slack 피드백을 주제별로 묶고 인용·개수를 붙임 | 월요일 오전 9시 |
| Backlog cleanup | 오래된 이슈, 중복 의심, 담당자 없는 이슈 | 매달 1일 |
| Dependency updates | 오래되거나 취약한 패키지를 급한 순으로. 동의하면 묶음마다 PR 하나 | 월요일 오전 9시 |
| Security check | 병합된 변경에서 새어 나간 비밀값·주입(injection)·빠진 인증·위험한 기본값 확인 | 월요일 오전 9시, PR 병합 때 |
| Release readiness | 실패한 검사, 리뷰 기다리는 PR, 열린 걸림돌 짧은 목록 | 평일 아침 |
| Incident notes | 장애 채널에서 타임라인을 쓰고, 탓하지 않는 회고 초안 | 장애 중과 뒤 |
| On-call handoff | 한 주의 경보·장애 요약과 남은 후속 일 | 금요일 오후 4시 |
| Replies you owe | Slack·Linear에서 내가 답하지 않은 질문과 하겠다고 한 일 | 매일 오후 4시 |
| Email digest | 내가 답해야 할 메일 목록. 메일은 절대 보내지 않음 | 평일 오전 9시·오후 2시 |
| Meeting prep | 회의 주제인 이슈·PR·문서를 한 메모로 | 각 회의 15분 전 |
| Project briefing | 바뀐 것, 막힌 것, 결정이 필요한 것 | 금요일 오후 3시 |
| Spec drafting | Slack 스레드나 문서를 한 쪽짜리 명세로 | 부탁할 때 |
| Unreviewed agent work | 리뷰나 PR이 아직 없는 끝난 에이전트 작업 | 평일 오전 9시 |
| Workspace cleanup | 끝났거나 버려진 워크트리 목록. 고른 것만 지움 | 금요일 오후 4시 |
- 언제: 일정("평일 9시마다"), 이벤트("acme/web에서 검사가 실패하면"), 또는 "지금".
- 무엇을: 한 문장으로 일 하나.
- 어디에 보고: 봇 채팅, Slack 채널, 또는 부탁받은 이슈·PR.
- 무엇을 물어볼지: 행동하기 전에 나에게 물어야 할 것.
- 봇 = 이름·목적·기억·자동화를 가진 에이전트. 한 컴퓨터의 폴더에 살고, 내 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로 바꿉니다.
출처: orca.dev/docs/bots · /docs/bots/connectors · /docs/bots/import · /docs/bots/security · /docs/bots/use-cases · orca.dev/bots · orca.dev/changelog (1.4.265 · 1.4.268) — 2026-11-22 수집
부록 — 사이트맵 · 플러그인 · 최근 변경 · 출처
onorca.dev 사이트가 어떻게 짜여 있는지, 어떤 플러그인이 있는지, 최근에 무엇이 바뀌었는지 정리합니다.
- 사이트의 페이지 120개가 어떤 구역으로 나뉘는지
- 공식·커뮤니티 플러그인 전체 목록
- 최근 다섯 버전의 주요 변경(봇이 나온 1.4.265 포함)
사이트맵 — www.onorca.dev
사이트가 공개한 sitemap.xml(검색엔진에게 알려 주는 페이지 목록)에 등재된 URL 120개를 구역별로 묶었습니다.
- 사이트 주소가
www.onorca.dev에서orca.dev로 바뀌었습니다(옛 주소는 새 주소로 넘어갑니다). URL은 493개로 늘었습니다. - Docs 63쪽: 위 57쪽에
bots/5쪽(→ 10장)과migrate-from-conductor1쪽이 더해졌습니다.migrate-from-conductor는 아직 받지 않아 이 가이드에 없습니다. - 새 구역 /bots: 봇 소개 쪽 1개(→ 10장).
- Plugins 425개(공식 stablyai 43개 포함): 아래 「플러그인 전체 목록」은 11-04 기준 59개 그대로이며 새로 늘어난 플러그인은 반영하지 않았습니다.
Changelog 1
Enterprise 1
Download 1
Plugins 59
Docs 57
헤더의 외부 링크: Discord · X · GitHub
플러그인 전체 목록
플러그인은 Orca에 테마·아이콘·언어 지원·뷰어 등을 더하는 확장입니다. Settings → Plugins에서 설치하며, 코드를 실행하는 플러그인은 설치 전에 동의를 구하고, 동의하면 컴퓨터에 대한 전체 접근 권한을 갖습니다(1.4.245 변경 내용). 이름만으로 분류했으며 각 플러그인의 상세 설명은 읽지 않았습니다.
테마 · 아이콘
언어 · 구문 강조
에디터 · 뷰어 · 도구
최근 변경 (Changelog — 봇 관련 두 항목은 2026-11-22에, 나머지 셋은 11-04에 읽음)
- Orca 봇의 에이전트로 Cursor · GitHub Copilot · Hermes 선택, 봇 그룹 채팅에 이미지 추가
- 원격 브라우저 페이지에서도 요소를 골라 메모를 달고 복사하거나 에이전트에게 보내기(원격 호스트가 새 메모 도구를 지원해야 함)
- Activity 카드에서 에이전트 질문에 답하기, 조정자 채팅에서 작업자 권한 요청에 답하기(페어링 서버 포함)
- Orca Bots 출시 — 관리되는 에이전트 세션이 도구와 신분을 갖고, 봇이 나 대신 공유하며, Slack 스레드에서 봇이 무엇을 하는지 보임. 봇 연결 시 접근 경고가 더 분명해짐(→ 10장)
- Hermes와 채팅: 새 채팅 시작, Session History에서 터미널 대화 이어 가기. Hermes 0.23.0 이상 필요, 페어링 서버는 되고 SSH 워크스페이스는 안 됨
- 지원하는 Chrome 확장의 사이드 패널을 Orca 브라우저 옆 크기 조절 패널로 열기
- 자동화를 Chat 또는 Terminal로 실행하도록 고르고, 실행 기록에서 녹화된 대화를 열어 결과 검토
- 폰에서 충돌 파일 해결 방식을 고르고 Source Control에서 병합 완료 — 데스크톱과 같은 조작
- 데스크톱에서 “응답 필요”와 “완료” 알림을 따로 제어, 폰은 “응답 필요” 알림만 받도록 설정 가능
- Settings → Plugins에서 아이콘 테마·구문 강조·커스텀 에디터 설치. 코드를 실행하는 플러그인은 동의 후 컴퓨터 전체 접근
- 사용자가 마우스·키보드를 쓰는 동안 에이전트가 Chrome·Blender 같은 앱을 뒤에서 조작(일부 동작은 앱을 앞으로 가져와야 함)
- 폰 앱: 11개 언어, 말하는 동안 받아쓰기 표시, 코드·표·다이어그램 가독성 개선
- 실험 설정을 켜면 Orca 브라우저의 로컬 프로필에 Chrome 웹 스토어 확장 설치(1Password·Bitwarden 등). 일부 확장과 광고 차단은 아직 미지원
- 에이전트가 끝난 뒤 Claude·Codex 터미널 대화를 Chat에서 이어 가기, 채팅에서 다른 에이전트에게 인계, 대기 메시지 순서 바꾸기, Claude를 첫 메시지 이전으로 되감기
- 원격 파일: SSH 호스트·페어링 서버의 오디오·비디오 재생, 50MB까지 텍스트 저장, 큰 폴더 스크롤 탐색, 페어링된 데스크톱에서 워크스페이스 밖 파일 편집
출처와 기준
- 2026-11-04에 Orca 내장 브라우저로 읽은 onorca.dev 홈, Changelog, Docs 57쪽 전체,
sitemap.xml - 2026-11-22에 Orca 내장 브라우저로 읽은 orca.dev Bots 문서 5쪽, Bots 소개 쪽, Changelog(맨 위 1.4.268),
sitemap.xml— 10장과 이 부록의 봇 관련 내용의 근거. 나머지 장은 11-04 수집본 기준입니다. - 로컬 Orca CLI 안내서
orca skills get orca-cli(브라우저 조작 참고) - 설명은 위 자료를 쉬운 말로 풀어 쓴 것이며, 원문에 없는 내용은 추가하지 않았습니다. 화면 이름·단축키·옵션은 읽은 시점(약 1.4.246~1.4.247) 기준이고 이후 버전에서 바뀔 수 있습니다.
- 사이트는 Docs(57)·Plugins(59)가 대부분이고, Docs의 각 구역이 이 가이드의 1~8장에 대응합니다. 11-22 기준으로는 주소가 orca.dev로 바뀌고 Docs 63쪽(봇 5쪽 → 10장)·Plugins 425개입니다.
- 플러그인은 공식 43개(테마·언어·도구)와 커뮤니티 14개가 있습니다.
- 최근에는 플러그인, 백그라운드 Computer Use, 폰 앱, 브라우저 확장, 채팅 기능이 크게 늘었고, 1.4.265(11-19)에 Orca Bots가 나왔습니다.
출처: onorca.dev/sitemap.xml, onorca.dev/changelog (2026-11-04) · orca.dev/sitemap.xml, orca.dev/changelog (2026-11-22)