Plan Annotator

Claude Code가 만든 실행 계획을 브라우저에서 리뷰하고, 피드백을 돌려보내는 플러그인입니다.

Claude Code가 plan을 세울 때마다 브라우저가 자동으로 열리고, 계획을 읽으면서 코멘트를 달거나 수정을 요청할 수 있습니다. 리뷰가 끝나면 피드백이 Claude Code에 전달됩니다.

빠른 시작

1단계: 설치

git clone https://github.com/kangju2000/plugin.git
cd plugin/plan-annotator
npm install
npm run build

2단계: Claude Code에 연결

Claude Code를 사용하는 내 프로젝트의 .claude/settings.json을 만들거나 열고, 아래 내용을 추가합니다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "cd /내/plan-annotator/경로 && npx tsx server/index.ts"
          }
        ]
      }
    ]
  }
}

/내/plan-annotator/경로 부분을 실제 절대 경로로 바꿔주세요. 예: cd /Users/me/plugin/plan-annotator && npx tsx server/index.ts

3단계: 사용

1. 내 프로젝트에서 평소처럼 Claude Code를 실행합니다
2. Claude가 계획을 세우면 브라우저가 자동으로 열립니다
3. 계획을 리뷰합니다
4. Approve 또는 Request Changes 버튼을 누릅니다
5. 피드백이 Claude Code에 전달되고, 브라우저 탭을 닫으면 됩니다

이게 전부입니다.

리뷰하는 방법

텍스트에 코멘트 달기

계획 본문에서 텍스트를 드래그하면 팝업이 나타납니다. 4가지 타입 중 하나를 선택하고 내용을 입력하세요:

• Comment — 의견 남기기 ("이 부분은 SSE가 더 나을 것 같아요")
• Replace — 다른 내용으로 교체 제안
• Insert — 빠진 내용 추가 제안
• Delete — 이 부분 삭제 요청

입력 후 Cmd+Enter로 저장합니다.

블록 단위로 승인/거부

각 블록(단락, 코드 블록, 리스트 등)에 마우스를 올리면 왼쪽에 버튼이 나타납니다:

• V — 이 블록 승인 (왼쪽에 초록 테두리)
• 말풍선 — 블록 전체에 코멘트
• X — 이 블록 삭제 요청 (왼쪽에 빨간 테두리)

사이드바

오른쪽 사이드바에서:

• 계획의 목차를 보고 클릭해서 이동
• 달아놓은 어노테이션 목록을 확인하고 클릭해서 해당 위치로 이동
• 필요 없는 어노테이션은 X 버튼으로 삭제

최종 결정

• Approve — 계획을 승인합니다. Claude Code가 바로 실행에 들어갑니다.
• Request Changes — 수정을 요청합니다. 어노테이션이 1개 이상 있어야 합니다. Claude Code가 피드백을 받고 계획을 수정합니다.

화면 하단 상태바

리뷰 중 브라우저 하단에 상태바가 표시됩니다:

• 초록 점 + "Connected to Claude Code" — 서버와 정상 연결 중
• 빨간 점 + "Disconnected" — 서버와 연결이 끊김
• 남은 시간 표시 — 5분 타임아웃 카운트다운. 60초 이하가 되면 빨간색으로 경고

탭을 실수로 닫으려 하면?

리뷰를 완료하지 않은 상태에서 탭을 닫으려 하면 브라우저가 확인을 물어봅니다.

탭을 닫아버리면?

서버가 약 9초 후 자동 종료됩니다. Claude Code에 "리뷰가 취소되었습니다"라고 전달됩니다.

아무것도 안 하면?

5분 후 자동 타임아웃됩니다.

고급 설정

고정 포트 사용

기본적으로 매번 랜덤 포트를 사용합니다. 고정 포트를 쓰고 싶다면 환경변수를 설정하세요:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "PLAN_ANNOTATOR_PORT=3456 cd /내/plan-annotator/경로 && npx tsx server/index.ts"
          }
        ]
      }
    ]
  }
}

이렇게 하면 항상 http://127.0.0.1:3456에서 열립니다.

브라우저가 안 열리는 경우

서버가 URL을 클립보드에 자동으로 복사합니다. Cmd+V로 브라우저 주소창에 붙여넣으세요.

그래도 안 되면 Claude Code 터미널에서 아래와 같은 로그를 찾아 URL을 직접 입력하세요:

[plan-annotator] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[plan-annotator]   Plan Annotator: http://127.0.0.1:xxxxx
[plan-annotator] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

다크 모드

리뷰 화면 오른쪽 상단의 해/달 아이콘을 클릭하면 다크/라이트 모드를 전환할 수 있습니다.

문제 해결

Hook이 실행되지 않아요

• .claude/settings.json이 내 프로젝트 루트에 있는지 확인하세요 (plan-annotator 폴더 안이 아님)
• matcher가 정확히 "Task" (대소문자 구분)인지 확인하세요
• npx tsx가 설치되어 있는지 확인: npx tsx --version

"dist/ directory not found" 에러

npm run build를 먼저 실행하세요:

cd /내/plan-annotator/경로
npm run build

이전 서버가 종료되지 않았어요

# 해당 포트를 사용하는 프로세스 찾기
lsof -i :포트번호 | grep LISTEN

# 프로세스 종료
kill PID

로컬에서 UI만 테스트하기

Claude Code 없이 UI를 먼저 구경해보고 싶다면:

cd plan-annotator
npm install
npm run dev

http://localhost:5173에서 샘플 데이터로 UI를 확인할 수 있습니다.

기술 스택

React 19 + TypeScript + Vite + Tailwind CSS v4 + Shiki