Claude Code git 브랜치 모드: 프롬프트 위에 브랜치와 변경 사항 표시

Claude Code git 브랜치 모드는 입력창 위에 한 줄을 띄워 git에서 현재 어디에 있는지 알려 줍니다: ⎇ main · 3 changed · ↑1 ↓0. 브랜치 이름, git status가 변경되었다고 보고하는 경로 수, 그리고 브랜치가 업스트림보다 얼마나 앞서고(ahead) 뒤처져(behind) 있는지를 볼 수 있습니다. HEAD가 분리된 상태라면 대신 짧은 커밋 해시를 보여 줍니다. git 저장소 밖에서는 이 줄이 아예 나타나지 않습니다.

이 모드는 Claude가 사용자를 대신해 파일을 편집할 때 가장 유용합니다. 세션이 기능 브랜치가 아닌 main에서 시작되었다면 바로 알아챌 수 있고, Claude가 편집할수록 변경 수가 올라가므로 언제 검토하고 커밋해야 할지 알 수 있습니다. Claude Code 2.1.287 이상이 필요합니다.

녹화 영상에서는 작은 데모 프로젝트에서 모드를 불러온 채 Claude Code를 시작합니다. 첫 프롬프트를 입력하기 전부터 입력창 위 띠에 브랜치와 변경된 파일 수가 표시됩니다. 이어서 Claude에게 src의 파일 목록을 요청하면, 턴이 진행되는 동안 띠는 그 자리에 머물러 있다가 턴이 끝나면 갱신됩니다.

설치 블록의 세 가지 방법 중 아무것이나 사용하십시오. 한 줄 방식은 실행 중인 세션 안에서 작동하며, 셸 방식은 이미 열려 있는 세션에서 /reload-plugins가 필요합니다.

모드는 최신 git 상태를 $.state 아톰에 보관하고 AbovePrompt 렌더 사이트에 그립니다. hooks/register.tsx의 훅은 다음과 같습니다.

on('session.start', async ($, e, next) => {
  const started = await next(e)
  await refresh($)
  $.clock.every(intervalMs, () => {
    refresh($).catch(() => undefined)
  })
  return started
})

on('turn.complete', async ($, e, next) => {
  const result = await next(e)
  if (e.agentId === undefined) await refresh($)
  return result
})

on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
  const ran = await next(e)
  if (mentionsGit(e.command)) await refresh($)
  return ran
}).catch(($, e, next) => next(e))

갱신 시점은 세 가지입니다. session.start는 첫 번째 상태를 읽고, Claude Code 밖에서 일어난 변경을 잡기 위한 타이머를 시작합니다. turn.complete는 메인 루프의 각 턴이 끝난 뒤 갱신하며, 서브에이전트 턴(agentId가 있는 턴)은 건너뜁니다. Bash에 대한 tool.call 훅은 await next(e)로 명령을 먼저 실행한 다음, 명령에 git이나 gh pr checkout/merge가 들어 있을 때만 갱신합니다. 이 훅의 .catch는 호출을 그대로 통과시키므로, 모드에 오류가 나도 명령이 막히는 일은 없습니다.

refresh는 $.session.cwd()에서 git status --porcelain=v1 -b를 한 번만 실행합니다. 이 명령 하나로 브랜치, 업스트림, ahead/behind, 변경 목록을 모두 얻을 수 있으므로 rev-parse나 rev-list를 따로 호출할 필요가 없습니다. hooks/git.ts의 순수 함수 parseStatus는 커밋이 없는 새 저장소와 분리된 HEAD도 처리합니다. git이 없거나 느리면 오래된 데이터를 보여 주지 않고 띠를 숨깁니다.

다음 옵션은 /config에서 모드 이름 아래에 있으며, 값을 바꾸면 모드가 새 값으로 다시 로드됩니다. 타이머의 기본값은 register 맨 위의 Math.max(2_000, ... 15_000)에서 정해지며, 이 코드가 2초 하한도 강제합니다. 띠의 모양을 바꾸려면 ui.render 훅의 Text 요소를 수정하십시오. 브랜치는 cyan 색의 bold로, 세부 정보는 dimColor로 그려집니다.

명령어 실행은 모드가 $.process.run을 호출하기 때문에 표시됩니다. 모드는 정확히 두 프로그램만 실행합니다. 하나는 git status --porcelain=v1 -b이고, 다른 하나는 HEAD가 분리된 상태일 때만 실행되는 git rev-parse --short HEAD입니다. 둘 다 읽기 전용이며, 셸 없이 argv 배열을 사용하고, 10초 시간 제한이 있습니다.

도구 호출 가로채기는 Bash의 tool.call을 훅하기 때문에 표시됩니다. 모드는 관찰만 할 뿐 명령을 바꾸거나 거부하지 않으며, 명령이 끝난 뒤에 갱신합니다. UI 변경은 띠 표시에 해당합니다.

파일 내용을 읽거나 네트워크를 사용하거나 모델을 호출하지 않습니다. 영구적으로 끄려면 /plugin disable cm-git-branch를 실행하고, 모든 모드를 끈 채 세션을 한 번 시작하려면 claude --safe-mode를 사용하십시오.

macOS 터미널에서 Claude Code 2.1.291로 테스트했습니다. 띠가 나타나지 않는다면 다음을 순서대로 확인하십시오.

• claude --version이 2.1.287 이상인지 확인하십시오.
• 세션을 git 저장소 안에서 시작했는지 확인하십시오. 같은 폴더에서 git status가 작동해야 합니다.
• 모드가 활성화되어 있는지 확인하십시오. /plugin 메뉴의 Installed 탭에 "mod active" 줄과 함께 표시되어야 합니다.
• 이미 열린 세션에 셸로 설치했다면 /reload-plugins를 실행하십시오.
• 입력창 위에 설문이나 다른 프롬프트가 열려 있을 수 있습니다. 그것이 보이는 동안 띠는 비켜 있다가 닫히면 다시 나타납니다.

아주 큰 저장소에서는 intervalMs를 늘려 git status가 덜 자주 실행되도록 하십시오.