TL;DR

firstmate는 한 명의 'first mate' 에이전트가 여러 자율 crewmate를 tmux 창과 독립 git worktree로 기동·감독해 병렬 코딩 작업을 PR·로컬 병합·리포트로 완결하는 운영 디렉터리이다. 사용자는 단일 채팅 인터페이스로 요청을 전달하면 firstmate가 각 작업을 별도 tmux 창(fm-taskX)에 배치하고 treehouse 기반의 깨끗한 worktree에서 실행해 작업 충돌을 피한다. 운영은 이벤트 기반 bash 워처로 필요할 때만 활성화하며, 기본 브랜치 안전 정책과 디스크·tmux 기반 상태 복구로 세션 재시작에 견고하게 설계되어 있다. 제약으로는 로컬 에이전트 하니스(claude 등), tmux, git 인증이 필수이며 GUI가 아닌 터미널 중심 워크플로를 전제로 한다.

주요 기능

• 단일 인터페이스로 작업 요청을 분배·감독
• tmux 창 단위로 각 작업을 시각적으로 실행·개입
• 각 작업을 별도 git worktree(treehouse)에 배치해 충돌 방지
• 이벤트 기반 워처로 필요 시에만 감독자 활성화
• 프로젝트 모드(no-mistakes/direct-PR/local-only)로 출고 방식 제어

어떻게 동작하는가

사용자 요청을 firstmate 디렉터리의 라우트·상태 파일로 기록하고, tmux의 send-keys와 상태 파일을 통해 crewmate 프로세스를 창별로 기동한다. 각 crewmate는 독립 git worktree(treehouse)를 사용해 작업을 수행하고, 이벤트 기반 bash 워처가 변경 발생 시만 first mate를 깨워 감독 흐름을 이어간다.

해결 문제

터미널 기반 단일 에이전트로 여러 코드 작업을 병렬 실행·감독하면서 작업 간 충돌과 세션 관리 부담을 제거한다.

차별점

• 각 작업을 별도 tmux 창과 git worktree에 배치해 실시간 관찰과 수동 개입이 가능하다
• treehouse 기반 disposable worktrees로 병렬 작업의 파일 충돌을 구조적으로 차단한다
• 이벤트 기반(zero-token) 워처로 불필요한 감독 호출을 최소화해 비용·권한 노출을 줄인다
• 운영 체크아웃에 대해 읽기 전용 보수 정책을 적용해 실수로 인한 변경을 방지한다

사용 사례

• 한 리포지토리에서 테스트 수정·기능 추가·스타일 개선 같은 복수 작업을 동시에 실행해 PR을 개별 생성하고 병합 승인으로 완결할 때
• 버그 재현·보안 감사·조사형 업무를 격리된 scout 작업으로 실행해 보고서를 산출할 때
• 도메인별 상시 감독자(secondmate)를 두어 장기적 프로젝트 상태·정책을 관리할 때
• 로컬 개발 환경에서 여러 에이전트의 작업을 시각적으로 검토하거나 중간에 수동으로 개입해야 할 때

시작하기

GitHub 인증 후 레포를 클론하고 로컬 에이전트(harness)를 실행하면 AGENTS.md 규칙으로 firstmate가 작업을 인계받는다. 예: gh auth login && git clone https://github.com/kunchenguid/firstmate && cd firstmate && claude

요구사항

• macOS 또는 Linux
• 검증된 에이전트 하니스(예: claude, codex, opencode, pi)
• git (GitHub 인증 필요)
• tmux