본문으로 건너뛰기
JournalTORIS / FIELD NOTES

← 블로그개발 도구

Plannotator(backnotprop/plannotator) — AI 코딩 에이전트 계획·코드 리뷰를 브라우저에서 한 번에 검수하기

GitHub 주간 트렌딩 1위 Plannotator(v0.29.1)의 Plan Review, Code Review, Plannotator Inbox 작동 원리와 Claude Code·Codex·Gemini CLI 연동 및 보안 주의점을 정리했습니다.

#Plannotator #Claude Code #코드 리뷰 #AI 에이전트 #오픈소스

Read in English

Plannotator(backnotprop/plannotator) — AI 코딩 에이전트 계획·코드 리뷰를 브라우저에서 한 번에 검수하기

Q. Plannotator는 무엇이고, 왜 터미널 코딩 에이전트 사용자들이 이 도구를 쓰기 시작했을까요? Plannotator(backnotprop/plannotator)는 Claude Code, Codex, Gemini CLI, OpenCode 같은 AI 코딩 에이전트가 세운 계획(Plan)과 코드 변경점(Diff), HTML 결과물을 로컬 브라우저 화면에서 직접 주석(Annotate) 달아 검수하고, 한 번의 클릭으로 구조화된 피드백을 에이전트에 되돌려 보내는 오픈소스 워크스페이스입니다. 터미널의 좁은 스크롤 화면에서 긴 마크다운 계획과 수백 줄의 diff를 눈으로 쫓느라 생기는 피로와 승인 실수를 줄여 줍니다.

⚠️ 정확도 가드레일: 이 글은 2026년 11월 20일 기준 backnotprop/plannotator 공식 GitHub 저장소(v0.29.1, Stars 13,770+)와 공식 사이트(plannotator.ai) 문서에서 직접 확인한 사양을 바탕으로 작성했습니다. 지원 에이전트 범위, 설치 옵션, 공유 링크 만료 정책(7일) 등은 이후 릴리즈에 따라 바뀔 수 있으며, 실제 작업 환경별 체감 성능은 직접 벤치마크하지 않았습니다.

30초 요약

  • 핵심 역할: AI 코딩 에이전트가 ExitPlanMode로 계획을 제안하거나 코드를 수정했을 때, 로컬 브라우저(또는 TUI/에디터)에서 인라인 코멘트·삭제 표시·코드 제안을 달아 에이전트 다음 턴으로 바로 전달합니다.
  • 지원 에이전트: Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness, Pi를 지원하며 Plannotator Inbox는 MCP 연동도 제공합니다.
  • 주요 기능: Plan Review(계획 변경 이력·버전 비교), Code Review(Git·GitButler·Jujutsu·Perforce·GitHub PR·GitLab MR 및 Guided Review), HTML/로컬 서버(localhost:5173) 실시간 주석, Obsidian·Bear·Notion 자동 저장.
  • 보안·프라이버시: 기본 실행은 로컬이며 사용량 텔레메트리를 수집하지 않습니다. 링크 공유는 PLANNOTATOR_SHARE=disabled로 완전히 끌 수 있고, 설치 시 --verify-attestation으로 SLSA·SBOM 검증을 지원합니다.
  • 라이선스: Apache-2.0 또는 MIT 듀얼 라이선스(무료 오픈소스).

Plannotator GitHub 공식 저장소 화면

터미널 코딩 에이전트의 가장 큰 병목: '계획은 길고, 리뷰는 어렵다'

AI 코딩 에이전트를 실무에 쓰다 보면 코드를 짜는 속도보다 에이전트가 세운 계획과 수정한 diff를 사람이 검수하는 시간이 더 오래 걸립니다. 터미널 안에서 수십 줄짜리 마크다운 계획이 지나가면 특정 문단만 콕 집어 수정 지시를 내리기 어렵고, 결국 긴 텍스트를 복사해 다시 프롬프트로 고쳐 적게 됩니다.

Plannotator는 바로 이 지점을 브라우저 기반 리뷰 레이어로 분리합니다. 에이전트가 계획을 제출하거나 /plannotator-review를 실행하면 로컬 서버가 열리면서 문서 편집기·PR 리뷰어와 같은 화면을 띄워 줍니다.

듀얼 모니터에서 Plannotator 코드 리뷰와 터미널 에이전트를 함께 사용하는 작업 환경

광고

작동 원리와 Plannotator Inbox 구조

Plannotator는 에이전트의 수명 주기 훅(Hook), 슬래시 커맨드, 스킬(Skill), 또는 MCP를 통해 연결됩니다.

모드 진입 방식 주요 동작 피드백 전달 방식
Plan Mode 에이전트 ExitPlanMode 훅 자동 가로채기 마크다운 계획 인라인 주석, 삭제 표시, 버전 간 diff 비교 승인 시 그대로 실행, 반려 시 구조화된 피드백 자동 전달
Code Review /plannotator-review 또는 PR/MR URL 로컬 미커밋 변경, GitButler 스택, GitHub PR/GitLab MR diff 리뷰 줄 단위 코멘트·코드 제안을 에이전트 세션에 반환
Annotate /plannotator-annotate <파일|폴더|URL> 마크다운, HTML 결과물(--render-html), localhost 앱 실시간 주석 페이지 위 코멘트를 모아 한 번에 전달
Plannotator Inbox plannotator inbox 또는 plannotator inbox mcp 여러 에이전트가 남긴 질문·계획·파일을 한 창에 비동기 수신 에이전트 세션을 멈추지 않고 답변 시 다음 턴으로 전달

특히 Plannotator Inbox는 여러 에이전트를 동시에 돌릴 때 유용합니다. T3 Code로 코딩 에이전트를 원격 제어하는 구성처럼 멀티 에이전트 작업을 병렬로 굴리면 각 세션이 사람 답변을 기다리며 멈춰 서기 쉬운데, Inbox를 쓰면 에이전트는 질문을 남기고 계속 작업하거나 턴을 넘기고, 사람은 한 화면에서 클릭과 코멘트로 순차 응답할 수 있습니다.

AI 코딩 에이전트와 Hooks·MCP를 통해 Plannotator 리뷰 화면으로 피드백이 순환하는 구조도

설치 방법과 에이전트별 연동 포인트

공식 설치 스크립트는 plannotator 바이너리를 내려받은 뒤 현재 PC에 설치된 에이전트를 자동 감지해 훅·스킬·슬래시 커맨드를 맞춰 줍니다.

# macOS / Linux / WSL
curl -fsSL https://plannotator.ai/install.sh | bash

# 바이너리만 최소 설치(훅·스킬 자동 설정 제외)
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal

설치 후 에이전트별로 남는 마무리 단계는 다음과 같습니다.

  • Claude Code: /plugin marketplace add backnotprop/plannotator 후 /plugin install plannotator@plannotator 실행 및 재시작(2.1.287 이상에서는 비동기 메시지 반환 지원).
  • Codex / Gemini CLI / Kiro CLI: 설치 스크립트가 훅과 스킬($plannotator-review 등)을 자동 구성합니다(Gemini CLI는 0.36.0+ 필요).
  • OpenCode / Pi: OpenCode는 opencode.json에 "plugin": ["@plannotator/opencode@latest"] 추가, Pi는 pi install npm:@plannotator/pi-extension으로 바로 설치할 수 있습니다.
  • 터미널 전용 환경: 브라우저를 띄우기 싫거나 SSH 환경이라면 herdr plugin install plannotator/herdr-annotate 또는 brew install plannotator/tap/plannotator-tui로 터미널 TUI 리뷰를 쓸 수 있고, SSH 세션에서는 고정 포트 19432가 자동 활성화됩니다.

보안·공유 옵션과 주의할 점

로컬 개발 도구를 설치할 때는 네트워크 경계와 공유 정책을 먼저 확인하는 습관이 중요합니다.

  • 공유 링크 비활성화: 사내 코드나 비공개 스펙을 다룬다면 export PLANNOTATOR_SHARE=disabled로 URL 공유 기능을 꺼 두는 편이 안전합니다. 기본적으로 큰 공유 파일은 업로드 전 암호화되며 7일 뒤 만료됩니다.
  • 원격 모드 포트 노출 주의: PLANNOTATOR_REMOTE=1 또는 SSH 환경에서는 인증 없이 0.0.0.0:19432로 열리므로, 반드시 신뢰하는 SSH 포트 포워딩(LocalForward 19432 localhost:19432) 안에서만 써야 합니다.
  • 설치 무결성 검증: gh CLI가 있다면 --verify-attestation 플래그로 SLSA 빌드 출처(provenance)를 검증하며 설치할 수 있습니다.

토리스의 판단

혼자 여러 AI 코딩 에이전트를 돌리는 1인 개발자라면 도입 가치가 매우 높습니다. 특히 Claude Code나 Codex의 Plan 모드에서 "3번 항목만 빼고 2번 파일 경로를 바꿔서 다시 짜줘" 같은 세부 수정을 매번 채팅으로 치는 번거로움을 크게 줄여 줍니다. 승인된 계획을 Obsidian이나 Notion에 자동 백업하는 기능도 장기 프로젝트 기록 관리에 실용적입니다.

반면 단순 1회성 질문이나 짧은 스크립트 수정만 시키는 경우에는 매번 브라우저 창이 뜨는 흐름이 오히려 거추장스러울 수 있습니다. 이럴 때는 --minimal로 CLI만 설치해 두고 필요할 때만 /plannotator-review나 /plannotator-annotate를 수동 호출하는 방식이 가장 깔끔합니다. 에이전트가 생성한 결과를 실제 CLI 도구로 연결해 쓰는 CLI-Anything 하네스 가이드와 함께 보면 에이전트 작업 파이프라인을 더 단단하게 잡을 수 있습니다.

출처

광고

YOUTUBE · TORIS STUDIO

토리스 영상 더 보기