Stagecoach

프로그램 소개/무엇인지

Stagecoach는 사용자가 이미 설치한 로컬 코딩 에이전트(예: Claude Code, Cursor, pi 등)를 활용하여 커밋 메시지를 생성하는 스냅샷 기반 AI 도구입니다. 별도의 API 키나 토큰 비용 없이 기존 코딩 플랜의 할당량을 재사용하여 작동하며, 개발자가 에이전트와 직접 상호작용하지 않아도 안정적이고 원자적인 커밋을 생성합니다. 이 도구는 에이전트가 Git 히스토리를 조작하지 못하도록 설계되어 저장소의 무결성을 보호합니다.

주요 기능

멀티 커밋 분해

더티 워킹 트리가 아무것도 스테이지되지 않은 상태에서 Stagecoach는 변경 사항을 논리적으로 분리된 다중 커밋 시퀀스로 자동 분해합니다. 플래너 → 스테이저 → 메시지 → 아비터의 4단계 에이전트 파이프라인을 통해 각 개념을 별도의 커밋으로 만듭니다. 시작 시 스냅샷을 동결하여 실행 중인 변경 사항이 커밋에 포함되지 않도록 보장합니다.

페이로드 최적화 및 제한

에이전트에 전송되는 디프는 이름 변경 인식(-M), 감소된 컨텍스트(-U1), 컴팩트 파일 스켈레톤으로 트리밍되며, 선택적으로 토큰 제한을 통해 모델의 컨텍스트 창을 초과하지 않도록 보장합니다. .stagecoachignore 또는 –exclude 옵션을 통해 특정 파일의 디프를 모델 입력에서 숨길 수 있지만 커밋에는 포함됩니다.

메시지 포맷팅 및 작업 설명 모드

–format 옵션을 통해 자동, 컨벤셔널, 깃모지, 일반 스타일 중 선택할 수 있으며, +body를 추가해 subject+body 형태를 강제할 수 있습니다. –work-description 옵션으로 사용자 설명을 프롬프트 앞에 배치하고, 에이전트가 필요 시 READ 명령으로 스테이지된 디프를 온디맨드로 읽도록 할 수 있습니다.

Git 훅 및 도구 통합

stagecoach hook install 명령으로 Git 커밋 시 메시지를 자동으로 채우는 훅을 설치할 수 있으며, 사전 커밋 훅은 존중되지만 블로킹되지 않습니다. 모든 stagecoach 커밋 주변에 저장소의 pre-commit → prepare-commit-msg → commit-msg → post-commit 훅이 동결된 스냅샷 범위에서 실행됩니다. stagecoach integrate install git-alias 또는 lazygit 명령을 통해 git stagecoach 별칭이나 lazygit 키바인딩을 설정할 수 있습니다.

다운로드·설치 방법

Windows 사용자는 Chocolatey를 통해 간단히 설치할 수 있습니다. 관리자 권한으로 PowerShell 또는 CMD를 열고 다음 명령을 실행합니다:

choco install stagecoach

설치 후, stagecoach –version 명령을 실행하여 버전을 확인할 수 있습니다. Chocolatey 외에도 Scoop, PowerShell 설치 스크립트, Homebrew, npm 등 다양한 채널을 통해 설치 가능하며, stagecoach upgrade 명령으로 현재 설치 채널에 따라 자동 업데이트를 처리할 수 있습니다.

기본 사용법

변경 사항을 스테이지한 후, 단순히 stagecoach 명령을 실행하면 스냅샷 생성 → 메시지 생성 → 원자적 커밋까지 전체 파이프라인이 실행됩니다. 예를 들어:

git add feature/login.js
stagecoach
# [abc1234] feat: add login flow
# M src/login.js

모든 변경 사항을 한 번에 스테이지하고 커밋하려면 -a 플래그를 사용합니다. 생성된 메시지를 커밋 없이 미리 보려면 –dry-run 옵션을 사용하며, 이는 생성 실패 시 종료 코드 1과 짧은 메시지를 반환합니다.

이런 경우에 유용합니다

자주 커밋하지만 매번 에이전트 세션을 시작하고 컨텍스트를 로드하는 오버헤드가 싫은 개발자에게 유용합니다. Stagecoach는 스냅샷 기반 접근으로 에이전트 세션 없이도 작동하므로, lazygit 키바인드, git stagecoach 별칭, 또는 셸 한 줄 명령으로 즉시 사용할 수 있습니다. 특히 설정 파일 조정이나 한 줄 수정과 같은 에이전트 작업이 아닌 커밋에 적합합니다.

에이전트가 Git 히스토리를 의도치 않게 재작성하거나 강제 푸시하는 것을 방지하고 싶은 팀에서도 유용합니다. Stagecoach는 에이전트에 commit, rebase, push 명령을 전달하지 않고 git plumbing(write-tree + commit-tree + update-ref)을 통해 원자적으로 커밋을 생성하므로 저장소 손상 위험이 없습니다.

제한 사항·확인 사항

Stagecoach는 자체 모델이 없으므로, pi, Claude Code, opencode, Cursor, agy, codex 중 적어도 하나의 코딩 에이전트 CLI가 설치되어 있고 $PATH에 있어야 작동합니다. 에이전트가 감지되지 않으면 도구는 즉시 종료되며 부분적인 상태를 남기지 않습니다.

최신 버전·업데이트

현재 버전은 0.1.14이며, v3.0부터 stagecoach upgrade 명령을 통해 셀프 업데이트를 지원합니다. 이 명령은 설치된 채널(Homebrew, Scoop, Chocolatey, npm, Nix, mise/asdf, go install 등)을 감지하여 해당 채널의 업데이터에 위임하며, 직접 설치된 바이너리의 경우 자체 교체 방식으로 작동합니다. 패키지 관리자로 설치된 경우 해당 관리자의 파일을 덮어쓰지 않아 충돌이 발생하지 않습니다.

FAQ

• Stagecoach는 내 코드를 어디론가 전송합니까?
• 아니요. Stagecoach는 사용자의 기존 에이전트와 인증 및 청구 환경을 그대로 사용합니다. 커밋 경로에서는 Stagecoach 자체가 네트워크 호출을 하지 않으며, 오직 사용자의 에이전트가 일반적인 방식으로 연결을 엽니다. 유일한 예외는 stagecoach upgrade로, 이는 오직 이 프로젝트의 자체 GitHub 릴리스 아티팩트와 체크섬만 가져옵니다.
• 에이전트가 Git 히스토리를 조작할 수 있나요?
• 아니요. Stagecoach는 에이전트에게 commit, rebase, push 명령을 절대 전달하지 않습니다. 에이전트는 오직 텍스트(커밋 메시지)만 반환하며, Stagecoach는 git write-tree + commit-tree + update-ref를 통해 원자적으로 커밋을 생성하므로 실패 시에도 저장소는 바이트 단위로 변경되지 않습니다.