plannotator는 모든 agent diff 앞에 사람이 확인하는 지점을 둡니다

agent와 함께하는 개발에는 일이 나아지기는커녕 나빠지는 순간이 있어요. agent가 작업을 끝내고 요약을 출력한 뒤 받아들이겠냐고 물어요. 스크롤을 내려요. diff는 사백 줄이에요. 제대로 읽는 데 드는 시간이 직접 쓰는 시간보다 길어서 승인 버튼을 눌러요.
이번 주에 10,500 스타 근처까지 빠르게 오르고 있는 plannotator는 그 순간을 고치려는 시도예요. 코딩 agent에 붙어서, agent가 사람에게 물어볼 게 생겼을 때 열리는 로컬 브라우저 기반 리뷰 화면이에요. 계획이나 문서, diff에 표시를 남기면 그 코멘트가 agent의 다음 입력으로 돌아가요.
태그라인은 루프 안에 남는 이야기예요. 구조가 다루는 건 더 좁고 더 쓸모 있는 것이에요. 사람의 주의를 선택적인 단계에서 정식 단계로 끌어올리는 일이에요.
어떻게 붙는가
당신의 agent를 대체하지 않아요. agent에 끼워지는 것이에요. README에는 Claude Code, Codex, Copilot CLI, Gemini CLI, OpenCode, Kiro, Droid, Amp, DeepSeek Harness, Pi가 올라 있고, Inbox는 Grok Bot, Muse, Hermes, OpenClaw 같은 개인 비서와도 동작해요. 연결은 각 harness의 플러그인과 hook, 명령을 거치기 때문에 도구마다 통합 깊이가 달라요.
명령은 익숙한 모양이에요.
/plannotator-review # uncommitted changes
/plannotator-review <github-pr-url> # a pull request
/plannotator-annotate README.md # a file
/plannotator-annotate https://docs.rs # a URL
/plannotator-last # the agent's last message
plannotator inbox # the queue
Codex에서는 슬래시 명령이 `!plannotator ...`가 되거나 패키징된 skills를 써요. 계획 모드에는 명령이 아예 필요 없어요. 각 harness의 hook에 연결돼 있어서 agent가 계획을 쓰면 리뷰 화면이 알아서 열려요. 이 세부 사항은 들리는 것보다 중요해요. 직접 불러야 하는 체크포인트는 바쁜 날에 건너뛰게 되고, 바로 그 바쁜 날이 필요한 날이에요.
리뷰는 Git, GitButler, Jujutsu, Perforce, GitHub, GitLab을 아우르기 때문에 특정 forge에 묶이지 않아요. 줄에 코멘트를 달고 코드를 제안할 수 있고, 코멘트는 아무도 안 읽는 PR 스레드가 아니라 agent에게 돌아가요.
받은편지함이 진짜 재미있는 부분이에요
단일 agent 리뷰는 이미 풀린 문제고, 해법도 지루해요. diff를 열고 코멘트를 남기면 돼요.
Inbox는 대부분의 사람이 실제로 놓인 상황을 위해 팀이 만든 것이고, 그 상황은 여러 agent가 동시에 도는 것이에요. 로컬 창 하나에 agent가 메시지와 질문, 파일, 안내형 리뷰를 남기고 계속 일해요. 질문에는 클릭 한 번으로 답하고, 파일에 주석을 달고, 시간이 될 때 전송을 눌러요. 그동안 어떤 agent 세션도 열린 채로 붙잡히지 않고, 답장은 질문한 세션으로 돌아가요.
이 한 문장이 실제 교착을 풀어요. human-in-the-loop의 표준 패턴은 agent가 멈춰서 기다리는 것이에요. agent 하나면 괜찮아요. 넷이 되면 당신이 시스템에서 가장 느린 프로세스가 되고, 나머지 셋은 당신이 점심을 마칠 때까지 컨텍스트를 태워요. 비동기 받은편지함은 세션이 아니라 질문을 대기시켜요.
Claude Code, Pi, OpenCode는 플러그인으로 연결돼서 답장이 다음 턴으로 도착해요. 나머지는 MCP로 `plannotator inbox mcp`를 써요. 그리고 `plannotator inbox --help`는 agent가 이 프로토콜을 배우는 문서 역할도 해요. 작은 설계인데 효과는 커요. 도움말 텍스트가 통합 명세예요.
왜 브라우저이고, 왜 로컬인가
터미널 diff는 코드를 읽기에는 충분하고 다른 것을 읽기에는 나빠요. 제품 스펙이나 HTML 목업, 렌더링된 보고서를 페이저에서 리뷰하는 건 눈을 가늘게 뜨는 일이고, agent는 이제 이 셋을 꾸준히 만들어 내요. 브라우저에 렌더링하고 리뷰어가 결과 위에 핀을 꽂게 하는 것이 그런 산출물에 맞는 화면이에요.

README의 프라이버시 절은 이 규모의 도구로서는 드물게 구체적이어서, 요약보다 내용을 그대로 옮길 만해요. 텔레메트리는 없어요. 계획과 diff, 주석, 초안, 기록은 기본적으로 로컬에 남아요. 각 화면은 로드할 때 GitHub에 최신 릴리스를 확인하고, 이 확인은 끌 수 없어요. 로컬 Git 리뷰는 기본 브랜치와 오래된 기준선을 감지하려고 설정된 origin에 `git ls-remote`를 실행할 수 있고, 이 조회는 리뷰를 열 때, diff를 불러올 때, base를 바꿀 때, fetch를 누를 때 나가요. 놀고 있는 리뷰 페이지는 네트워크를 부르지 않아요. 대부분의 도구가 하는 약속보다 강해요.
콘텐츠가 기계 밖으로 나가는 건 네트워크 기능이 필요할 때뿐이에요. URL 주석은 페이지를 가져오고, GitHub 리뷰는 인증된 CLI를 쓰고, Ask AI는 고른 질문과 컨텍스트를 설정한 공급자에게 보내고, 공유는 암호문을 paste 서비스에 업로드해요.
소스 코드 위에 앉은 도구로서 이런 공개 수준은 옳은 본능이에요. agent 도구의 전형적인 고장은 친절해 보이는 조수가 말없이 저장소를 서버로 보내는 것이고, 사용자가 가진 유일한 방어는 묻기 전에 경계를 적어 두는 유지관리자예요.
불편한 함의
이 프로젝트 전체가 하나의 내기에 걸려 있어요. agent 작업의 제약은 모델 능력이 아니라 사람의 리뷰 대역폭이라는 내기예요.
그 내기는 맞아 보여요. 여러 agent를 돌리는 아는 사람들은 하루의 대부분을 읽는 데 써요. 계획, diff, 테스트 출력, agent가 스스로 했다고 생각하는 일의 요약이에요. 생성 부분은 빠르고 점점 더 빨라져요. 검증 부분은 사람이 읽고 결정하는 속도로 상한이 정해져요.
이름을 붙일 만한 이차 효과도 있어요. 결정을 담는 리뷰 화면은 결정의 기록을 남겨요. plannotator에는 저장된 계획 결정을 읽기 전용으로 훑는 archive 명령이 있고, 주석은 데이터 디렉터리에 남아서 터미널 리뷰와 앱 리뷰가 한곳에 쌓여요. 코멘트가 붙은 승인된 계획이 수백 개쯤 되면 어떤 단일 세션에도 없는 것을 갖게 돼요. 팀이 어떻게 결정하는지에 대한 기술이에요.
자산은 그거예요. diff 뷰어는 누구나 만들어요. 쌓이는 건 추론의 흔적이에요.
아직 아픈 곳
두 가지고, 둘 다 구조적이에요.
첫째, 리뷰 도구가 개선하는 건 리뷰이고 리뷰는 정확성과 달라요. 나쁜 아키텍처에 대한 잘 주석 달린 승인은 여전히 나쁜 아키텍처의 승인이에요. 그리고 정돈된 리뷰 화면은 승인을 성실함처럼 느끼게 해요. Inbox는 특히 큐를 비우기 쉽게 만들고, 큐를 비우는 것과 이해하는 것은 다른 행동이에요.
둘째, 이 도구는 터미널뿐이던 워크플로에 브라우저와 로컬 서버, hook 계층을 더해요. 깨질 것이 셋 늘고, hook이 깨질 때의 실패는 조용해요. agent는 체크포인트 없이 진행하고, 당신은 나중에 알게 돼요.
둘 다 사는 물건에 비하면 감당할 비용이에요. 사는 것은 사람이 설 자리예요. 다른 방식은 오늘 대부분의 팀이 하는 것인데, 채팅 기록을 읽고 중요한 부분이 거기 있기를 바라는 것이에요.
하나만 해 본다면
다음에 커밋하지 않은 변경이 있을 때 `/plannotator-review`를 돌리고 세 줄에 코멘트를 달아 보세요. 할 말이 없어도 괜찮아요. 코멘트는 곁다리예요. 알게 되는 것은 화면이 리뷰를 위해 설계됐을 때 실제 리뷰가 얼마나 걸리는지고, 그 숫자가 당신의 새 처리량 상한이에요. 대부분의 팀은 그걸 재 본 적이 없어요.