pi-cowboy로 Codex와 Claude Code 작업을 병렬화한다

pi-cowboy는 pi에서 Codex, Claude Code, OpenCode 등 여러 코딩 도구를 하위 에이전트로 실행해 작업을 나누고 병렬로 처리하는 오케스트레이터다. 각 에이전트는 Herdr의 별도 터미널 창과 독립된 copy-on-write Git 작업 트리에서 실행된다. 사용자는 진행 상황을 지켜보거나 에이전트에 직접 지시할 수 있고, 작업이 끝나면 결과를 검토하고 병합한 뒤 자원을 정리할 수 있다.

프로젝트 저장소는 MIT 라이선스로 공개됐다.

작업 분리와 실행 환경

pi-cowboy는 큰 작업을 지시가 명확한 작은 하위 작업으로 나눠 각 에이전트에 맡긴다. 에이전트는 각자 브랜치에 커밋하므로 하위 작업별로 검토하고 병합할 수 있다. 단일 작업에 기대 사항을 길게 나열하는 대신 범위를 좁힌 작업을 맡기면 작업이 빗나가거나 과도하게 확장될 여지가 줄어든다는 것이 프로젝트의 설명이다.

Pi에서 시작해 Claude Code로 이어가고 OpenCode로 마치는 식으로 서로 다른 실행 환경(harness)을 한 세션에서 함께 쓸 수 있다. pi-cowboy는 Codex, Claude Code, OpenCode뿐 아니라 PiG와 Pi-Bolt도 감지한다. 해당 프로그램이 PATH에 설치돼 있어야 한다. 프롬프트에서 사용할 실행 환경을 직접 요청하거나 설정 문서와 에이전트 템플릿에서 기본값을 지정할 수 있다. 다른 실행 환경 지원을 요청하려면 GitHub 이슈를 열 수 있다.

각 작업은 Herdr에서 별도 프로세스와 작업 공간, 탭, 터미널 창을 받는다. 사용자는 언제든 해당 작업 공간으로 이동해 진행 상황을 확인하거나 에이전트에 직접 추가 지시를 보낼 수 있다. 에이전트마다 셸이 있고, 주의가 필요할 때 알림도 표시된다. 작업 트리는 기본적으로 ~/.pi/agent/pi-cowboy/worktrees/ 아래에 만들어진다.

copy-on-write 작업 트리는 저장 공간을 줄이면서 여러 에이전트가 동시에 편집·빌드·테스트할 수 있도록 설계됐다. 프로젝트가 제시한 비교는 파일 153,607개, 추적 중인 파일 479 MiB, 추적되지 않는 파일까지 포함한 전체 크기 27 GiB인 Git 저장소를 기준으로 한다.

설치와 실행

지원 운영체제는 Linux와 macOS다. herdr 0.8 이상이 필요하며, Herdr의 pi 통합 기능을 활성화해야 한다. macOS에서는 copy-on-write 작업 트리에 python3을 사용한다. macOS 12.3 이후에는 python3이 기본 제공되지 않으므로 다음 명령으로 Xcode Command Line Tools를 설치해야 한다.

xcode-select --install

파일 시스템도 copy-on-write를 지원해야 한다. macOS에서는 APFS, Linux에서는 BTRFS 또는 ZFS를 사용할 수 있다. ext4는 copy-on-write를 지원하지 않으므로, 이 파일 시스템에서는 agent.worktreeMaterialization이 checkout 방식으로 대체된다.

npm에서 설치한다.

pi install npm:pi-cowboy

Git 저장소 안에서 pi를 실행하면 pi-cowboy가 자동으로 활성화된다. /cowboy를 입력하면 대화형 메뉴가 열리고, 하위 명령을 바로 입력할 수도 있다. 메뉴의 각 화면은 메뉴 안내에 설명돼 있다.

에이전트 실행부터 정리까지

작업을 나눠 맡기면 pi-cowboy는 하위 에이전트를 백그라운드에서 바로 실행한다. 예를 들어 보안 감사 결과를 바탕으로 관련 파일을 10개 그룹으로 나눠 병렬 에이전트에 맡길 수 있다. 기본 전역 동시 실행 한도는 4다. 따라서 처음에는 4개가 시작하고, 나머지 6개는 자리가 생길 때까지 대기한다. 한도를 넘겨 요청한 에이전트는 큐에 들어간다.

에이전트가 작업을 마치면 완료 보고가 부모 세션에 메시지로 도착한다. 보고에는 작업 내용과 브랜치·작업 트리 위치가 포함된다. 부모 세션은 보고를 검토하고, 추가 작업을 지시하거나 브랜치를 병합할 수 있다. 병합은 에이전트 브랜치를 저장소의 주 작업 트리에 반영한다. 충돌이 발생하면 pi-cowboy는 충돌 상태를 그대로 남겨 사용자가 해결하도록 한다. 병합할 때 주 작업 트리는 대상 브랜치에 있어야 하며, 미커밋 변경 사항이 없어야 한다.

작업이 병합되면 cleanup_cowboy_agent로 에이전트의 Herdr 창과 탭을 닫고 작업 트리와 브랜치를 정리할 수 있다. 정리는 기본적으로 안전하게 동작한다. 실행 중인 에이전트는 건드리지 않고, 미커밋 변경이 남은 작업 트리는 보존하며, 이미 병합된 브랜치만 삭제한다. 일부 정리 단계가 실패해도 가능한 나머지 작업을 진행하고 실패 이유를 보고한다.

/cowboy status 메뉴에서 미커밋 변경이나 확인할 수 없는 상태 때문에 작업 트리를 제거하지 못하면 Force를 선택할 수 있다. 강제 제거는 작업 트리를 삭제하고 미커밋 변경 사항을 버린다. 따라서 제거 대상과 잃게 될 내용을 확인하는 절차가 표시되며, 결과에는 forced — <reason>이라고 기록된다. 강제 제거는 메뉴에서만 제공된다. cleanup_cowboy_agent 도구는 강제 제거를 하지 않으며, 메뉴도 실행 중으로 표시된 에이전트에는 이 선택지를 제공하지 않는다.

템플릿과 동시 실행 설정

반복 작업에 같은 지시를 사용한다면 에이전트 템플릿으로 묶을 수 있다. 템플릿에는 시스템 프롬프트, 모델, 실행 환경, 도구 권한을 지정한다. 예를 들어 release-notes 템플릿은 저장소의 이력과 태그를 읽어 릴리스 노트를 준비하도록 설정할 수 있다. 자세한 필드와 저장 위치는 에이전트 템플릿 문서를 참고하면 된다.

오케스트레이터 템플릿은 개별 에이전트가 아니라 실행하는 모든 에이전트에 적용되는 규칙을 정한다. 에이전트가 시작·대기·완료될 때 부모 세션에 보내는 상태 메시지, 즉 ‘cues’도 바꿀 수 있다. 예를 들어 적대적 검토 도구를 사용하는 경우, 커밋 전에 모든 에이전트가 해당 도구를 실행하고 검토에서 발견한 뚜렷한 문제를 수정하도록 요구할 수 있다. 활성 오케스트레이터는 /cowboy > Default orchestrator에서 바꾼다. 자세한 내용은 오케스트레이터 템플릿 문서에 있다.

동시 실행 한도는 서로 독립된 네 수준에서 설정한다.

• 전역 한도: 모든 에이전트에 적용되는 concurrency.default이며 기본값은 4다.
• 실행 환경별 한도: concurrency.harnesses.<harness-id>.
• 제공자별 한도: concurrency.providers.<provider>.
• 모델별 한도: concurrency.models["<provider>/<model-id>"].

실행 중인 에이전트는 자신에게 적용되는 모든 한도에서 자리를 차지한다. 작업을 마치면 자리를 반환하고, 모든 수준에서 실행 가능한 다음 대기 에이전트가 시작된다. 특정 모델 한도 때문에 기다리는 에이전트가 있어도 다른 모델을 쓰는 뒤쪽 대기 에이전트의 실행을 막지는 않는다. 완료된 에이전트에 추가 지시를 보내면 기존 창에서 다시 실행되며, 이 경우에는 일시적으로 한도를 초과할 수 있다. 한도는 config.json이나 세션의 /cowboy > Settings > Concurrency Settings에서 설정한다. 자세한 내용은 동시 실행 설정 문서를 참고하면 된다.

에이전트를 시작할 때 모델은 다음 우선순위로 선택된다.

• cowboy_agent 도구 호출에 전달한 model 매개변수.
• 세션별 실행 유형 모델 재정의(/cowboy > Model overrides).
• 설정 파일의 실행 유형별 재정의(agent.<agent-type>).
• 에이전트를 시작하는 실행 환경 계열에 맞춘 에이전트 템플릿의 모델.
• 세션 기본 모델(/cowboy model).
• 시작 실행 환경의 설정 기본값: Pi 계열은 agent.default, 다른 실행 환경은 agent.defaultModelByHarness.
• Pi 계열로 시작하는 경우 부모 세션에서 활성화된 모델.

전체 규칙은 모델 설정 문서에 설명돼 있다.

명령과 도구

/cowboy는 메뉴를 열고, 하위 명령은 세션의 에이전트와 기본 모델을 관리한다.

/cowboy                         # pi-cowboy 메뉴 열기
/cowboy status                  # 생성·대기·완료된 에이전트 나열
/cowboy spawn                   # 에이전트 직접 생성
/cowboy worktree                # 에이전트가 연결되지 않은 Git 작업 트리 생성
/cowboy model                   # 이 세션의 기본 에이전트 모델 선택
/cowboy model provider/model-id # 이 세션의 기본 에이전트 모델 설정
/cowboy model clear             # 세션 모델 재정의 지우기
/cowboy enable                  # pi-cowboy 활성화
/cowboy disable                 # pi-cowboy 비활성화

cowboy_agent는 하나 이상의 작업을 에이전트에 위임한다. 기본적으로 호출은 각 작업의 에이전트 ID를 반환하고, 에이전트가 완료될 때마다 결과가 부모 세션에 도착한다. run_in_background를 false로 설정하면 같은 턴에서 결과를 기다리지만, 이 설정은 작업이 하나일 때만 허용된다. agents[]에는 작업마다 객체를 하나씩 넣는다. 각 객체는 필수 항목인 작업 지시 prompt와 브랜치·작업 트리·탭 이름으로 쓸 2~3단어의 task_name을 받는다. 선택 항목은 에이전트 템플릿을 지정하는 agent_type, "provider/model-id" 형식의 모델 model, 실행 환경 harness_type이다. 실행 환경은 pi, pig, pi-bolt, opencode, codex, claude 중에서 고른다. harness_type은 템플릿의 값과 agent.harnessType 설정을 덮어쓴다. 해당 컴퓨터에서 요청한 실행 환경을 시작할 수 없으면 에이전트를 생성하기 전에 호출이 실패한다.

steer_cowboy_agent는 한 명 이상의 에이전트에 추가 메시지를 보낸다. 실행 중인 에이전트는 다음 모델 호출 전에 메시지를 받는다. 이미 작업을 마친 에이전트에 보내면 같은 창에서 다시 실행되고, 작업을 마치면 새 완료 메시지를 보낸다. 대기 중인 에이전트는 아직 창이 없으므로 지시를 받을 수 없다. 정리가 끝났거나 정리 중인 에이전트에도 지시할 수 없다. 도구는 대상 ID 목록 agent_ids[]와 전달할 message를 받는다.

stop_cowboy_agent는 실행 중인 에이전트를 중단하고 상태를 중지로 표시한다. 작업 트리, 브랜치, 창은 남겨 두므로 이후 확인하거나 정리할 수 있다. 매개변수는 대상 에이전트 ID 목록 agent_ids[]다.

merge_cowboy_branch는 작업을 마친 에이전트 브랜치 하나 이상을 저장소의 주 작업 트리에서 대상 브랜치로 병합한다. 필수 매개변수 branches[]에는 완료 보고에 나온 cow-<task>-<id> 형식의 브랜치 이름을 넣는다. 선택 매개변수 target은 병합 대상 브랜치로, 기본값은 main이다. repo에는 저장소 안의 경로를 지정하며, 기본값은 부모 세션의 작업 디렉터리다. 병합 충돌이 나면 충돌 상태를 남겨 사용자가 해결하도록 한다.

cleanup_cowboy_agent는 작업을 마친 에이전트 하나 이상에 대해 Herdr 창과 탭을 닫고 작업 트리를 제거한 뒤 브랜치를 삭제한다. 필수 매개변수 agent_ids[]로 대상을 지정한다. 실행 중인 에이전트는 정리할 수 없다. 부분 실패가 발생해도 도구 호출을 중단하지 않으며, 브랜치는 병합된 경우에만 삭제한다. 미커밋 변경이 남은 작업 트리는 보존하고 그 이유를 알린다.

자주 묻는 내용

에이전트가 실행되지 않고 대기하는 것은 해당 에이전트에 적용되는 모델·제공자·실행 환경·전역 한도 모두에 자리가 있어야 하기 때문이다. 모델과 제공자 한도는 실행 환경별로 지정할 수도 있다. 한도를 높이려면 /cowboy > Settings > Concurrency Settings나 설정 파일을 이용한다.

정리 뒤에도 작업 트리가 남았다면 미커밋 변경이 있거나 Git 상태를 확인하지 못했을 수 있다. 변경 사항을 커밋하거나 버리고, 에이전트가 중지됐는지 확인한 뒤 다시 정리해야 한다.

작은 변경 하나만 처리할 때는 새 프로세스를 시작하는 시간이 직접 수정하는 것보다 길 수 있다. pi-cowboy는 여러 작업을 병렬 실행해 시작 비용을 여러 에이전트가 함께 부담하는 사용 사례를 대상으로 한다. 시작 속도를 높이고 메모리 사용량을 줄이려는 경우, Go로 작성한 Pi 대체 프로그램인 PiG나 ahead-of-time 컴파일된 Pi 변형인 Pi-Bolt도 지원한다. 사용하려면 설정 문서에서 agent.harnessType을 설정한다.

카우보이 표시와 풀을 뜯는 소 이모지는 /cowboy > Settings 또는 설정 파일에서 각각 끌 수 있다. 자세한 설정은 설정 문서를 참고하면 된다.

추가 문서는 설정, 메뉴, 에이전트 템플릿, 오케스트레이터 템플릿 문서에서 확인할 수 있다.