Crow

Crow는 Claude Code, Codex, Cursor, OpenCode 등 다양한 AI 코딩 에이전트를 병렬로 실행하기 위한 자체 호스팅 데몬 및 웹 UI입니다. 각 에이전트는 독립적인 git worktree에서 작동하며, 사용자의 GitHub, GitLab 또는 Jira 보드에 의해 구동됩니다.

왜 필요한가. 터미널 하나에서 코딩 에이전트 하나를 사용하는 것은 쉽습니다. 하지만 다섯 개를 한 번에 사용하는 것은 아닙니다. 각각은 서로 간섭하지 않도록 자체 브랜치와 체크아웃이 필요하며, 어떤 터미널이 어떤 티켓에 속하는지 기억해야 하고, 모든 PR(Pull Request)은 리뷰 코멘트, 실패한 체크, 병합 충돌 등을 감시해야 합니다. Crow가 이러한 기록 관리(bookkeeping)를 수행합니다. 티켓을 선택하면 worktree를 생성하고, 해당 티켓을 컨텍스트로 에이전트를 실행하며, 보드를 가로질러 티켓의 상태를 이동시키고, PR이 병합될 때까지 추적합니다. 또한 PR을 검토하고, 리뷰 피드백에 답변하며, 오래된 브랜치를 자체적으로 리베이스(rebase)할 수도 있습니다.

누구에게 적합한가. 이미 코딩 에이전트를 사용해 본 개발자 중 여러 티켓을 추적하는 데 어려움을 겪지 않고 한 번에 실행하고 싶은 사람들에게 적합합니다. Crow는 사용자 자신의 기기(또는 제어 가능한 서버)에서 작동하며, 이미 설치하고 로그인한 git, gh/glab, 그리고 에이전트 CLI를 구동합니다. 따라서 호스팅되는 서비스가 아닙니다.

설치 (Install)

아직 안정화된 릴리스는 없습니다. Prereleases에는 macOS 빌드가 포함되어 있지만, 안정 버전이 게시될 때까지 소스에서 빌드하는 것이 Crow를 설치하는 지원되는 방법입니다. 안정 버전이 출시되면 다운로드 경로가 소스 빌드 상단에 추가될 것입니다.

소스에서 빌드 (Build from source)

아래의 전제 조건이 필요합니다. 최소한 Swift 6 툴체인, git, tmux 그리고 코딩 에이전트가 필요합니다.

# 1. Clone
git clone https://github.com/corveil/crow.git
cd crow
...

crowd는 시작 시 HTTP/WS listening on http://127.0.0.1:8787을 출력합니다. 이 URL을 브라우저에서 열면, 첫 화면이 남아 있는 모든 설정을 안내해 줄 것입니다.

참고: 필요한 GitHub 범위(scope)는 project의 쓰기(write) 범위입니다. read:project만으로는 불충분한데, 이는 Crow가 updateProjectV2ItemFieldValue GraphQL mutation을 통해 티켓 상태를 업데이트하기 때문입니다. 자세한 내용은 docs/getting-started.md를 참조하십시오.

crow와 crowd를 PATH에 추가하기

Manager 터미널과 /crow-workspace 스킬 호출은 단순히 crow ...만 사용하므로, 전체 경로로만 실행할 수 있는 빌드는 해당 워크플로우를 중단시킵니다. 따라서 모든 곳에서 호출할 수 있도록 바이너리를 설치해야 합니다:

make install                       # crow와 crowd를 ~/.local/bin에 symlinks로 연결합니다

만약 ~/.local/bin이 이미 PATH에 없다면, 다음 내용을 ~/.zshrc에 추가하고 셸을 다시 시작하십시오:

export PATH="$HOME/.local/bin:$PATH"

BINDIR를 사용하여 다른 디렉토리를 사용할 수도 있습니다. 예를 들어, make install BINDIR=/usr/local/bin을 사용하세요.

make install은 .build/debug/에 symlinks를 생성하므로, 나중에 실행하는 make build가 이를 제자리에 업데이트합니다. 따라서 다시 실행할 필요가 없습니다. make install은 릴리스 빌드(release build)로 전환할 때(make daemon CONFIG=release && make install CONFIG=release) 또는 make clean을 수행한 후(이는 .build/를 제거하고 symlinks를 매달린 상태(dangling)로 남겨두어 다음 빌드까지는 아무것도 하지 않음)에만 다시 실행하십시오. symlinks는 make uninstall로 제거할 수 있습니다.

자동으로 로그인 시 crowd를 시작하려면 CLI reference의 crow autostart install을 참조하십시오.

원격 접속

crowd는 기본적으로 127.0.0.1:8787에 바인딩되므로, 해당 장치에서 실행된 경우에만 접근할 수 있습니다. 다른 장치에서 접근하려면 HTTPS 리버스 프록시(예: tailscale serve)로 앞에 두고 **설정(Settings) → 웹 액세스(Web Access)**에서 **웹 비밀번호(web password)**를 설정하거나 crow web-password set을 사용해야 합니다. 비밀번호가 설정되고 연결이 HTTPS인 경우까지는 루프백 요청(Non-loopback requests)은 차단됩니다.

비밀번호와 AI 게이트웨이는 로컬 전용 인터페이스입니다. 이는 로컬 브라우저나 crow CLI(유닉스 소켓을 통해 통신)에서 설정할 수 있으며, 원격 웹 클라이언트에서는 거부됩니다. 원격 세션이 비밀번호를 변경하여 원격 접근을 제한하거나 게이트웨이 자격 증명을 읽는 것을 허용해서는 안 됩니다. CLI 참조 → 게이트웨이 명령어를 참조하세요.

필수 조건 (Prerequisites)

시스템 요구 사항 (System Requirements)

crowd가 유일하게 실행하는 프로세스이며, 호스트의 git, tmux, 코딩 에이전트들을 구동하므로 유닉스와 유사한 호스트 환경이 필요합니다:

• macOS 14.0 이상 (Sonoma 또는 그 이후 버전), 또는 Linux (x86_64 또는 arm64).
  Windows는 지원하지 않습니다.
• Swift 6 툴체인: macOS에서는 Xcode Command Line Tools에 포함되어 있거나, Linux에서는 swift.org/install에서 설치해야 합니다.
• UI를 위한 최신 웹 브라우저

빌드 종속성 (Build Dependencies)

런타임 종속성 (Runtime Dependencies)

위에 명시된 설치 명령어는 macOS/Homebrew용입니다. Linux에서는 배포판의 패키지 관리자(예: apt install git tmux; gh/glab은 자체 apt 리포지토리를 사용)를 사용하십시오. claude가 기본 코딩 에이전트이며, Codex, Cursor, OpenCode, Grok Build, Antigravity, 그리고 Muse Code도 지원되며 세션별로 선택할 수 있습니다(설정 → 일반 또는 crow agents set). 사용하는 에이전트를 설치하십시오. 설치되지 않은 에이전트도 피커에 회색으로 표시됩니다. 각 에이전트가 무엇을 할 수 있고 무엇을 할 수 없는지는 agent harness matrix를 참조하십시오.

아키텍처 개요 (Architecture at a glance)

flowchart TB
    subgraph clients["클라이언트 (순수, 특권 상태 없음)"]
        WEB["웹 UI — 브라우저 또는 Tauri 창<br/>web UI + xterm.js"] 
... 

변경 이력: Crow는 원래 네이티브 macOS(AppKit) 앱으로 시작했습니다. ADR 0009 및 ADR 0010에 따라 해당 앱은 폐지되었으며, crowd가 유일한 권한(sole authority)을 가지며 모든 UI는 순수 클라이언트입니다.

데스크톱 앱 (crow 위에 네이티브 창)

브라우저 탭보다 네이티브 창을 선호하십니까? crow-desktop/은

실행 시 window는 127.0.0.1:8787에서 이미 수신 대기 중인 crowd가 있는지 확인합니다. 만약 발견하면, 이를 **재사용(reuses)**하고 종료해도 계속 실행 상태로 둡니다. 없다면, 자체적인 crowd를 생성합니다 — 디버그 빌드에서는 .build/debug/crowd, 릴리스 빌드에서는 Crow.app 내부에 번들된 사이드카(sidecar)가 됩니다 — 그리고 종료 시 이를 중지시킵니다.

플랫폼: macOS 전용으로 사전 구축되었습니다. 셸의 macOS 관련 코드는 cfg-gated되어 있어, cargo로 Linux에서 컴파일되도록 의도되었지만, make로는 그곳에서 빌드되지 않으며 테스트되거나 Linux용으로 출시된 적이 없습니다 — Linux에서는 브라우저를 사용하세요. Windows는 지원하지 않습니다. 왜냐하면 crowd가 tmux가 필요한 Unix 호스트를 필요로 하기 때문입니다.

데스크톱 셸을 작업 중인가요, 아니면 웹 UI를 작업 중인가요? docs/development.md를 참조하세요.

문서화 (Documentation)

Crow 사용하기

• 시작하기 — 클론(Clone), 빌드(build), 인증(authenticate), 실행(run)
• 설정 (Configuration) — 파일 위치, 워크스페이스 설정, 디렉토리 레이아웃, 세션 수명 주기
• 자동화 (Automation) — 자동 생성(Auto-create), 자동 응답(auto-respond), 자동 완성(auto-complete) 및 설정 → 자동화 탭
• 웹 UI 스킨 — 내장 색상 스킨과 자신만의 스킨을 만드는 방법
• MCP — Crow의 읽기 전용 MCP 서버: Cowork 또는 외부 봇이 보드(board)를 가리키도록 함
• 문제 해결 (Troubleshooting) — 빌드 및 런타임 오류

CLI

• CLI 참조 — 표준 참고 자료: 모든 crow 하위 명령어와 플래그를 포함하며, 명령 자체(make docs)에서 생성되므로 변경될 수 없습니다
• CLI 가이드 — 보조 가이드: 각 동사(verb)의 용도, JSON 응답 형태, 실습 예제 및 주의사항을 다룹니다. 테스트를 통해 참고 자료의 모든 동사를 포함하도록 유지됩니다.

에이전트와 세션 로그

• Agent harness matrix — Crow 환경에서 각 지원 코딩 에이전트가 무엇을 할 수 있고, 무엇을 할 수 없는지, 그리고 그 이유
• Session-log collector — 워크스페이스별로 에이전트 스크립트를 Corveil에 업로드하는 방법
• Session backfill — 컬렉터 이전에 발생한 스크립트를 업로드하는 방법
• Harness transcript locations — 각 에이전트가 디스크에 스크립트를 작성하는 위치

개발 (Development)

• Development — 웹 UI 및 데스크톱 셸을 위한 crowd 개발 루프; 패키지 추가; 테스트
• Architecture — 패키지, 주요 구성 요소, 데이터 흐름
• Architecture Decision Records — Crow가 설계된 이유
• macOS release signing — 릴리스 빌드가 서명되고 공증되는 방법
• Harness gap audit — 하네스 매트릭스를 기반으로 한 버전 고정 감사(Version-pinned audit)
• Terminal runtime research — 보관됨: 초기 Ghostty 시대의 터미널 조사

사용법 (Usage)

웹 UI (The Web UI)

왼쪽 패널은 작업 내용을 그룹화합니다:

• 티켓 (Tickets) — 프로젝트 보드 상태별로 할당된 이슈가 그룹화됩니다(백로그, 준비됨, 진행 중, 검토 필요, 지난 24시간 완료). 상태를 클릭하여 필터링할 수 있습니다.
• 매니저 (Manager) — 작업을 오케스트레이션하기 위한 영구적인 Claude Code 터미널입니다. 새 세션을 생성하려면 여기에 /crow-workspace를 사용하세요. 기본적으로 --permission-mode auto로 실행되어 오케스트레이션 명령어(crow, gh, git)가 호출별 승인 절차를 건너뜁니다(최근 Claude Code 버전은 여전히 개발 루트 외부 파일 읽기에 대해 한 번의 프롬프트를 요청할 수 있습니다). 설정 → 자동화 → 매니저 터미널에서 옵트아웃 할 수 있습니다.
• 활성 세션 (Active Sessions) — 작업 컨텍스트별로 하나씩 존재합니다. 리포지토리, 브랜치, 이슈/PR 배지를 파이프라인 및 검토 상태와 함께 보여줍니다.
• 완료된 세션 (Completed Sessions) — PR이 병합되었거나 이슈가 닫힌 세션들입니다.

세션에서 마우스 오른쪽 버튼을 클릭하거나 (길게 누르기 / 터치 장치의 ⋮ 버튼 탭) 해당 세션의 작업(이름 변경, 삭제, 링크 복사 등)을 수행할 수 있습니다.

세션 생성하기

Manager 탭에서 Claude Code에게 어떤 작업을 할지 알려주세요:

/crow-workspace https://github.com/org/repo/issues/123

또는 자연어로 사용하세요:

/crow-workspace "acme-api API에 인증 추가"

이렇게 하면 다음 작업이 수행됩니다:

1. 기능 브랜치와 함께 git worktree 생성
2. 티켓 메타데이터가 포함된 세션 생성
3. 이슈 컨텍스트를 가지고 plan 모드로 Claude Code 실행
4. 이슈 자동 할당 및 프로젝트 상태를 "진행 중(In Progress)"으로 설정

기능

티켓 보드

• 프로젝트 보드 상태별 이슈를 보여주는 파이프라인 뷰
• 상태를 클릭하여 목록 필터링 가능
• "작업 시작(Start Working)" / "탐색 시작(Start Exploring)" 분리 버튼을 통해 이슈로부터 워크스페이스 생성 (탐색은 읽기/설명만 가능)
• 활성 세션과 연결된 이슈에는 탐색 버튼이 표시되며, 탐색 세션에는 'Exploring' 배지가 붙습니다.
• CLI에서 스크립팅 가능: crow list-tickets, crow work-on-issue, crow explore-issue, crow batch-work-on-issues, crow start-review, 그리고 crow quick-action이 보드 버튼과 동일한 작업을 수행합니다 (자세히는 CLI 참조 참고).

Jira 작업 + GitHub 코드 (크로스 백엔드 워크스페이스)

ADR 0005에 따라, 워크스페이스의 작업 백엔드(Task Backend) (티켓이 존재하는 곳)는 코드 백엔드(Code Backend) (코드 + PR이 존재하는 곳)와 독립적으로 선택됩니다. Jira에서 작업을 추적하면서 코드와 풀 리퀘스트를 GitHub에 유지할 수 있습니다. 즉, 작업 측은 acli을 통해 실행되고, PR 측은 여전히 gh을 통해 실행됩니다.

사전 준비 — acli 인증:

# 설치: https://developer.atlassian.com/cloud/acli/guides/install-acli/
acli jira auth login
acli jira auth status   #