코딩 에이전트를 붙여 쓰면 병목이 옮겨갑니다. 코드를 치는 시간이 줄어든 대신, 에이전트가 내놓은 계획과 변경분을 읽는 시간이 늘어납니다. Claude Code나 Codex가 “이렇게 고치겠습니다”라며 내미는 계획서는 스무 줄을 넘고, 승인 버튼을 한 번 누르면 파일 대여섯 개가 한꺼번에 바뀝니다.
터미널에서 스크롤을 올렸다 내리며 승인하는 그 순간이 사실상 유일한 검수 지점인데, 화면에는 긴 텍스트만 흐르고 어디에 표시를 남길 곳은 없습니다. Plannotator는 이 승인 지점을 브라우저 화면으로 옮긴 오픈소스 도구입니다. 계획서의 한 문장을 선택해 “이 단계는 이번 범위에서 빼주세요”라고 적으면, 그 주석이 구조화된 피드백으로 바뀌어 에이전트의 다음 턴으로 돌아갑니다.
이 글은 2026년 11월 20일 기준으로 GitHub 저장소(README, 릴리스 노트 v0.29.1, 저장소 메타데이터)와 공식 사이트를 직접 열어 확인한 내용만 담았습니다. 직접 설치해 본 체험기가 아니라 공개된 문서를 대조한 정리이므로, 기능이 실제 환경에서 어떻게 동작하는지는 각자 환경에서 확인이 필요합니다.
한눈에 정리
- 무엇인가: AI 코딩 에이전트가 낸 계획·코드 변경·문서를 로컬 브라우저 화면에서 주석 달아 검수하고, 그 피드백을 에이전트에 그대로 돌려주는 도구입니다.
- 어떤 에이전트를 지원하나: Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness, Pi까지 10종입니다.
- 비용: 로컬 플러그인은 무료이고 소스가 공개돼 있습니다(Apache 2.0 또는 MIT, 둘 중 선택). 팀용 Workspaces는 별도의 호스팅 계층으로 준비 중입니다.
- 최신 버전: v0.29.1. 2026년 11월 19일 20시 8분(UTC)에 공개됐습니다.
- 가장 조심할 점: 원격·SSH 모드에서는 로컬 서버가 로그인 없이 모든 네트워크 인터페이스에 열립니다. 신뢰할 수 없는 망에 포트를 열어두면 안 됩니다.
1. Plannotator가 하는 일: 승인 버튼 앞에 놓인 검수 화면
Plannotator는 설치하면 로컬에서 작은 서버를 띄우고, 필요할 때 브라우저 탭을 엽니다. 화면에 뜨는 것은 웹 서비스가 아니라 내 컴퓨터에서 도는 리뷰 화면입니다. 계획서는 마크다운으로 렌더링되고, 문장을 선택해 삭제 표시·코멘트·대체 문장을 남길 수 있습니다.
핵심은 자동으로 걸리는 지점입니다. README가 설명하는 계획 검수 흐름은 다섯 단계입니다. 에이전트가 계획을 끝내고 ExitPlanMode를 호출하면, 권한 훅(PermissionRequest)이 발동해 로컬 서버가 계획을 읽고 브라우저를 엽니다. 사람이 주석을 달고 승인하거나 거절하면, 거절 시에는 구조화된 피드백이 에이전트로 전달되고, 수정된 계획은 이전 버전과 diff로 비교됩니다.

저장소 규모를 보면 이 흐름이 혼자 쓰는 실험이 아니라는 점도 확인됩니다. 저장소는 2025년 12월 28일에 만들어졌고, 2026년 11월 20일 기준 별 약 1만 3,800개, 포크 1,400개, 커밋 1만 1,509개, 브랜치 1,922개, 릴리스 232개입니다. 기여자는 208명이고 코드의 93%가 TypeScript입니다.
다만 별 수가 많다는 것이 이 도구가 내 워크플로에 맞는다는 뜻은 아닙니다. 아래에서 지원 범위와 설치 방식, 그리고 실제로 걸리는 조건을 나눠 봅니다.
2. 지원 에이전트와 설치: 한 줄 설치, 남는 건 한 단계
설치 스크립트는 거의 모든 에이전트를 한 번에 처리합니다. 바이너리를 받아 깔고, 컴퓨터에 설치된 에이전트를 찾아 훅·스킬·슬래시 명령을 각각 설정합니다. macOS·Linux·WSL에서는 아래 한 줄입니다.
curl -fsSL https://plannotator.ai/install.sh | bash
Windows PowerShell은 irm https://plannotator.ai/install.ps1 | iex를 씁니다. 바이너리만 필요하면 --minimal을 붙여 스킬·훅·슬래시 명령 설정을 건너뛸 수 있고, 특정 버전에 고정하려면 --version v0.29.1처럼 지정합니다. 설치 단계에서 SLSA 빌드 증명까지 검증하려면 --verify-attestation을 추가합니다(이 옵션은 gh CLI가 필요합니다).
설치 후 남는 작업은 에이전트마다 다릅니다. Codex·Gemini CLI·Kiro CLI는 별도 작업 없이 자동 설정되고, Claude Code·Copilot CLI·Droid는 플러그인 마켓플레이스에서 설치한 뒤 재시작해야 합니다. OpenCode는 opencode.json에 플러그인 한 줄을 추가하고, Pi는 설치 스크립트 대신 pi install npm:@plannotator/pi-extension을 씁니다. Amp는 plannotator.ts를 플러그인 폴더로 복사합니다.

버전 조건이 걸리는 곳도 있습니다. 아래 표는 README와 릴리스 노트에서 확인한 조건만 모은 것입니다.
| 항목 | 확인된 조건 |
|---|---|
| Gemini CLI | 0.36.0 이상이어야 훅·정책·슬래시 명령이 자동 설정됨 |
| Claude Code | 2.1.287 이상에서는 계획·코드·주석 검수가 세션을 붙잡지 않음(에이전트 턴이 끝나고 결정이 나중에 메시지로 도착). 고전 흐름으로 되돌리려면 PLANNOTATOR_CLAUDE_MOD=0 |
| Codex (네이티브 Windows) | 훅이 실험 단계라 설치 스크립트가 수동 설정 절차를 출력 |
| Droid | 명령은 지원하지만 계획 가로채기는 아직 없음 |
| Pi | 설치 스크립트가 아닌 npm 확장으로 설치. 플랜 모드는 --plan 또는 /plannotator-plan-mode |
| 업데이트 | 바이너리·명령은 설치 스크립트 재실행. Claude Code 플러그인은 마켓플레이스 갱신 후 플러그인 업데이트를 따로 하고 재시작(마켓플레이스 갱신만으로는 반영되지 않음) |
설치 스크립트는 바이너리를 GitHub 릴리스에서 내려받고, 전체 설치일 때는 GitHub과 npm에도 접속합니다. 사내망처럼 외부 통신이 막힌 환경이라면 이 통신 범위가 도입 판단의 첫 번째 관문이 됩니다.
3. 화면 세 가지: 계획 검수, 코드 리뷰, 인박스
계획 검수는 명령을 외울 필요가 없습니다. 각 에이전트의 훅에 연결돼 있어, 계획이 나오는 순간 화면이 열립니다. 문서 어디에나 인라인 코멘트를 달 수 있고, 범위에서 빼야 할 항목은 삭제로 표시합니다. 계획을 거절하면 그 표시가 그대로 에이전트에 전달되고, 다시 올라온 계획은 이전 버전과 diff로 비교됩니다. 주석은 서버가 죽거나 재시작해도 살아남도록 자동 저장됩니다.
코드 리뷰는 /plannotator-review로 시작합니다. 커밋하지 않은 변경을 git diff로 잡아 PR처럼 보여주고, GitHub PR이나 GitLab MR 주소를 넣으면 원격 변경도 같은 화면에서 열립니다. 라인 단위 주석과 코드 제안, 파일 트리 이동, 커밋 전 스테이지·언스테이지가 한 화면에 있습니다.
v0.29.0에서 이 창이 크게 바뀌었습니다. 두 개의 패널, 파일 트리, 이미지 diff, 미니맵이 들어갔고, 옮기거나 이름을 바꾼 코드를 의미 단위로 따라가는 semantic diff가 추가됐습니다. 큰 변경은 Guide(Cmd/Ctrl+Shift+G)로 diff를 챕터로 나눠 볼 수 있는데, 에이전트가 변경의 핵심부터 정리하고 각 챕터에 짧은 개요를 붙입니다.

인박스는 에이전트 여러 개를 동시에 굴릴 때 쓰는 화면입니다. plannotator inbox로 열면 각 에이전트가 남긴 질문·계획·파일·가이드 리뷰가 한 창에 쌓입니다. 질문에 클릭으로 답하고, 파일에 주석을 달고, 보낼 수 있을 때 보냅니다. 답을 기다리는 동안 에이전트 세션이 붙잡히지 않고, 답은 질문한 세션으로 돌아갑니다. Claude Code·Pi·OpenCode는 플러그인으로 연결되고, 그 밖의 에이전트는 plannotator inbox mcp로 MCP를 통해 붙습니다.
v0.29.1에서는 인박스의 기본값이 조심스러워졌습니다. 한 번도 인박스를 실행하지 않은 컴퓨터에서는 아무것도 자동으로 켜지 않고, plannotator inbox를 직접 실행해야 켜집니다. 백그라운드에서 조용히 도는 프로세스를 싫어하는 사람에게는 반가운 변경입니다.
문서 검수도 별도로 있습니다. /plannotator-annotate에 파일·폴더·URL을 넘기면 마크다운이나 웹 문서에 주석을 달 수 있고, /plannotator-last는 에이전트가 마지막으로 답한 메시지를 그대로 검수 화면으로 가져옵니다. plannotator annotate http://localhost:5173처럼 개발 중인 사이트를 로컬 프록시로 열어, 실제 화면에서 주석을 달면서 핫 리로드도 유지할 수 있습니다.
4. 도입 전에 확인할 것: 공유, 원격 접속, 데이터 위치
공식 사이트는 이 도구를 “로컬에서 실행되고, 기본값에 사용 텔레메트리나 분석이 없다”고 소개합니다. 검수 데이터는 기본적으로 ~/.plannotator 아래에 남고, PLANNOTATOR_DATA_DIR로 위치를 바꿀 수 있습니다.
공유는 기본값이 아니라 선택입니다. 계획을 링크로 보낼 수 있는데, 작은 공유는 링크 자체에 내용이 담기고, 큰 공유와 HTML 공유는 업로드 전에 암호화되며 7일 뒤 만료됩니다. 다만 링크 전체를 가진 사람은 누구나 읽을 수 있으므로, 사내 코드나 고객 정보가 담긴 계획을 링크로 뿌리는 것은 별개의 판단입니다. 공유 자체를 끄려면 PLANNOTATOR_SHARE=disabled를 설정합니다.
원격 접속은 따로 봐야 합니다. SSH 세션은 자동으로 감지되어 고정 포트 19432를 쓰고, devcontainer나 Docker에서는 PLANNOTATOR_REMOTE=1과 PLANNOTATOR_PORT를 직접 지정합니다. 문제는 이 모드에서 서버가 로그인 없이 모든 인터페이스(0.0.0.0)에 열린다는 점입니다. README도 “SSH 터널을 쓰더라도 그 포트에 닿을 수 있는 사람은 누구나 쓸 수 있으니, 신뢰하지 않는 망에는 포트를 열지 말라”고 적고 있습니다.

배포물 검증 체계는 갖춰져 있습니다. 모든 릴리스 바이너리에 SHA256 체크섬이 붙고, v0.17.2부터 SLSA 출처 증명이 제공되며, 현재 릴리스 워크플로는 CycloneDX SBOM을 만들어 취약점 스캐너로 검사한 뒤 Sigstore 증명을 첨부합니다. 사내에서 바이너리 반입 심사를 받아야 하는 조직이라면 이 부분이 판단 근거가 됩니다.
설정은 쿠키에 저장되고(훅이 매번 다른 포트에서 실행되기 때문), 환경 변수나 ~/.plannotator/config.json으로도 바꿀 수 있습니다. 선택 기능으로 Vim 키 조작 프로필이 있고, VS Code 확장·Obsidian·Bear·Notion 저장 연동도 공식 문서에 정리돼 있습니다.
5. 어떤 팀에 맞고, 어디서 한계가 오나
터미널에서 승인하는 방식, Plannotator, 이미 쓰고 있는 PR 리뷰를 같은 기준으로 놓고 비교하면 아래와 같습니다.
| 기준 | 터미널 승인 | Plannotator | PR 리뷰 |
|---|---|---|---|
| 검수 시점 | 계획 승인 순간 한 번 | 계획 승인 전, 커밋 전 | 푸시한 뒤 |
| 보이는 것 | 스크롤되는 텍스트 | 렌더링된 문서와 diff 뷰어 | diff와 체크 결과 |
| 피드백 형태 | 승인/거절, 또는 한 줄 | 문장·라인 단위 주석, 삭제 표시 | 코멘트, 리뷰 승인 |
| 여러 에이전트 | 세션마다 따로 | 인박스 한 창에서 | PR마다 따로 |
| 준비물 | 없음 | 로컬 바이너리와 에이전트 훅 | 원격 저장소와 CI |
맞는 경우는 분명합니다. 에이전트가 한 번에 큰 변경을 자주 내놓고, 그 범위를 승인 전에 줄이고 싶을 때입니다. 계획서에 “이 단계는 빼고, 이 파일은 건드리지 마라”를 문장 단위로 남길 수 있으면, 되돌리는 비용보다 미리 자르는 비용이 싸집니다. 여러 에이전트를 동시에 굴리면서 질문이 흩어지는 것이 문제라면 인박스가 직접적인 해법이 됩니다.
맞지 않을 수 있는 경우도 있습니다. 한두 줄 고치는 작업이 대부분이라면 브라우저 탭이 여닫히는 것 자체가 방해입니다. 이미 PR 리뷰 문화가 자리 잡혀 원격 diff에서 모든 논의가 끝난다면, 검수 지점이 하나 더 늘어나는 셈입니다. 원격 서버에서 돌리는데 포트 관리가 어려운 환경이라면 인증 없는 로컬 서버라는 조건을 먼저 해결해야 합니다.
한계도 문서에 그대로 적혀 있습니다. 계획 가로채기는 각 에이전트의 계획 단계 훅에 기대므로, 계획 없이 곧바로 수정에 들어가는 흐름은 자동으로 잡히지 않습니다. Droid는 계획 가로채기가 아직 없습니다. 팀용 호스팅 계층인 Workspaces는 사이트 메뉴에 “soon”으로 표시되고 대기자 명단을 받는 단계입니다. 로컬 도구만으로 팀 단위 이력 관리까지 해결되지는 않는다는 뜻입니다.

자주 묻는 질문
Q. 무료인가요?
로컬에서 도는 플러그인은 무료이고 소스가 공개돼 있습니다. 라이선스는 Apache 2.0과 MIT 중 고르면 됩니다. 팀 단위 공유·이력 관리용 Workspaces는 별도 호스팅 계층으로 준비 중이며, 아직 대기자 명단 단계입니다.
Q. 회사 코드가 외부로 나가나요?
기본값은 로컬입니다. 검수 데이터는 내 컴퓨터의 ~/.plannotator에 남고, 텔레메트리나 분석은 쓰지 않는다고 공식 사이트가 밝힙니다. 다만 계획을 링크로 공유하면 내용이 링크에 담기거나 암호화되어 업로드되고, 링크를 가진 사람은 7일 안에 읽을 수 있습니다. 공유를 원천 차단하려면 PLANNOTATOR_SHARE=disabled를 설정합니다.
Q. 승인할 때마다 브라우저가 열려 작업이 멈추지 않나요?
Claude Code 2.1.287 이상에서는 계획·코드·주석 검수가 세션을 붙잡지 않습니다. 에이전트가 턴을 끝내고, 사람의 결정은 나중에 메시지로 도착합니다. 예전처럼 화면을 닫을 때까지 기다리는 흐름을 원하면 PLANNOTATOR_CLAUDE_MOD=0으로 되돌립니다.
Q. 계획 단계가 없는 에이전트에서도 쓸 수 있나요?
쓸 수는 있지만 자동으로 열리지는 않습니다. 그때는 /plannotator-review나 /plannotator-annotate, /plannotator-last를 직접 호출해 변경분이나 문서를 검수 화면으로 가져옵니다. 계획 가로채기는 에이전트가 계획 단계를 지원할 때만 동작합니다.
출처
- github.com/backnotprop/plannotator — README, 설치·에이전트별 설정, 보안·공유·원격 설정 (2026년 11월 20일 확인)
- 릴리스 v0.29.1 — 2026년 11월 19일 20시 8분(UTC) 공개, 인박스 기본값 변경과 코드 리뷰 수정 내역
- 릴리스 v0.29.0 — 코드 리뷰 창 재설계, semantic diff, 가이드 리뷰
- plannotator.ai — 로컬 실행·무료 오픈소스 소개, 지원 에이전트, 설치 명령
- GitHub REST API 저장소 메타데이터 — 별 13,793개, 포크 1,395개, 이슈 211개, Apache-2.0, 2025년 12월 28일 생성 (2026년 11월 20일 조회)
