Orca 사용 방법

ORCA

ORCA 는 무엇인가?

menu_book 핵심정리

1. Orca는 AI모델이 아니라 여러 AI 코딩 CLI를 한곳에서 다루는 데스크톱 IDE.
2. 작업마다 별도 작업 공간(worktree)을 만들어 파일이 섞이지 않게 한다.
3. Orca 앱은 MIT 라이선스지만 연결하는 에이전트의 구독료와 API 비용은 별도다.
4. macOS는 Homebrew 한 줄 설치, Windows, Linux용 설치 파일 제공.

• ORCA 다운로드 | 다운로드 바로가기

ORCA 구성 요소

1. 프로젝트 = git 저장소, 로컬폴더
2. 작업공간 = 작업 1개를 위한 별도 폴더
   1. 작업공간의 탭 = 에이전트 , 터미널,브라우져,편집기

• 자세한 구성은 공식 레퍼런스 | 레퍼런스 바로가기

flowchart TD P["프로젝트<br/>Git 저장소 또는 관련 저장소 묶음 "] W[" worktree<br/>작업 하나를 위한 별도 폴더 "] T[" 탭<br/>에이전트, 터미널, 브라우저, 편집기 "] P --> W W --> T

작업트리(worktree)

1. 하나의 프로젝트에서 기능개발 과 버그 수정을 동시에 진행 할수 있다.
2. 만약 vscode 처럼 같은 폴더에서 두 작업을 하면 파일이 섞일 수 있는데 worktree는 작업마다 별도 폴더를 만들어 개별,병렬처리를 가능하게 해준다.
3. 작업이 끝나면 변경 내용을 비교해 마음에 드는 결과만 원본 프로젝트에 반영.
4. 터미널에서 만든 worktree도 Orca가 감지하면 알림에서 가져올 수 있다.

설치 방법

1. 맥 OS

   brew install --cask stablyai/orca/orca

   1. 다운로드(| 다운로드) 페이지에서 윈도우,리눅스,맥OS 직접 다운로드 하여 설치도 가능

설치 후 환경 설정

1. Settings → Agents에서 이미 설치하고 로그인한 CLI를 기본 에이전트로 선택

   - 변경이 가능하다.

2. 처음에는 Agent Permissions를 Manual로 바꾼다

   - 기본적으로 permission-bypass(Yolo) 인자와 함께 실행한다. worktree는 작업 중 서로의 파일을 즉시 덮어쓰는 문제를 막지만, 같은 줄을 수정하면 나중에 병합 충돌이 생길 수 있다.

   - Settings → Agents → Agent Permissions 에서 Manual을 선택하면 에이전트 자체의 승인 흐름을 유지할 수 있다.

   - 중요한 저장소는 이 상태에서 먼저 익숙해지는 편이 안전함.

---

첫 프로젝트 생성하기

프로젝트 생성

1. Add Repo로 연습 저장소를 추가하기

   - 빈 화면에서 Add Repo를 누르고 이미 내려받아 둔 로컬 Git 저장소를 선택.

   - Orca는 저장소의 Git 상태를 읽고 기본 branch를 새 worktree의 base ref로 잡는다.

   - 처음에는 망가져도 되는 개인 연습 저장소 하나만 추가한다.

   여러 저장소 가져오기, 원격 호스트, GitHub·Linear 연동은 기본 흐름을 익힌 뒤 진행해도 됨.

2. 설정 스크립트 필요한 프로젝트만 추가

   - 저장소를 추가하면 왼쪽 아래에 설정 스크립트 추가 카드가 나타날 수 있다.

    - 프로젝트에 따라 알아서 자동으로 설정 스크립트를 추가 해준다.

   - 새 worktree마다 의존성 설치가 필요한 프로젝트라면 README와 lockfile을 확인해 실제 사용하는 명령 하나만 넣는다.

   # 예시: 프로젝트가 실제로 쓰는 명령 하나만 선택.
   pnpm install
   npm ci
   yarn install --immutable

[+] 버튼으로 작업트리(worktree) 만들기

1. 저장소 추가 후 좌측 프로젝트에서 + 를 눌러 [새작업 트리 만들기]
2. 작업이름에 wk_test1를 입력(입력하지 않으면 orca가 자동으로 해양동물이름을 넣는다)
3. Start from은 보통 base ref인 origin/main을 선택. 다른 branch나 commit에서 시작해야 할 때만 바꾼다.
4. 기본 에이전트가 미리 선택됐는지 확인. 필요하면 다른 CLI나 빈 터미널을 고른다.
5. Create를 누르고 사이드바의 생성·setup 진행 상태가 끝날 때까지 기다린다.
6. 에이전트는 자동으로 현재pc에 설치된 에이전트가 선택된다.(언제든지 변경가능)

• Git fetch와 worktree 생성은 백그라운드에서 진행되며, 실패하면 작업 탭에서 오류와 Retry를 확인할 수 있다.
• 작업 이름에서 branch 이름이 자동으로 만들어지므로 목적을 알수있는 짧은 이름으로 하는걸 추천

첫 작업: 요청, 상태 확인, Diff, commit

1. Orca의 기본 흐름은 저장소 추가 → worktree 생성 → 에이전트 실행 → Diff 검토 → commit·push.
2. 처음에는 읽기 전용 요청으로 연결을 확인한 뒤, README처럼 영향이 작은 파일 하나만 수정해 전체 흐름을 한 번 수행해 본다.

파일을 고치기 전에 저장소부터 읽힌다

이 저장소가 어떤 프로젝트인지 파일을 수정하지 말고 설명해주고, 실행 방법과 주요 폴더를 간단히 알려줘.

1. 이 요청으로 Orca가 올바른 저장소와 에이전트에 연결됐는지 확인.
2. 답변은 프로젝트와 선택한 모델에 따라 달라진다.
3. 응답을 받은 뒤 프로젝트 설명이 README와 주요 설정 파일의 내용과 맞는지 확인한다.
4. 파일을 수정하지 말라고 요청했으므로 변경 내용(Diff)이 없어야 한다. 아래 명령으로도 확인할 수 있다.

   git status --short

   - 아무 내용도 나오지 않으면 파일 변경이 없는 상태다.

   - 변경 파일이 보이면 바로 commit하지 말고 Diff에서 무엇이 바뀌었는지부터 확인.

menu_book 여기까지 확인했다면 첫번째 성공

1. Orca에 로컬 Git 저장소가 보이는지 ?
2. 별도 worktree와 선택한 CLI 에이전트가 열렸는지?
3. 프로젝트 설명 응답 받았는지?.
4. 의도하지 않은 파일 변경이 없는지?