plannotator/herdr-annotate

Annotate terminal text, review documents and agent replies in Herdr, and send the feedback straight back to the agent.

herdr‑annotate 란?

herdf‑annotate는 Herdr 터미널/AI 에이전트 환경을 위한 Rust 기반 플러그인입니다. 이를 통해 다음을 수행할 수 있습니다.

터미널 출력을 선택하여 활성 LLM 에이전트로 보낼 수 있는 번호가 매겨진 Markdown 주석으로 변환합니다.
동반 프로젝트 plannotator‑tui 기반 TUI에서 전체 Markdown 문서 또는 에이전트의 이전 답변을 검토합니다.
이러한 주석을 Herdr 내에서 직접 에이전트 프롬프트에 관리, 복사, 보관, 붙여넣기합니다.

요컨대, 터미널에서 보는 원시 텍스트와 LLM 기반 어시스턴트의 피드백 루프 사이의 간극을 메웁니다.

주요 기능

기능	설명
전체 vs 라이트 설치	전체 는 문서 검토 UI를 추가합니다. 라이트 는 터미널 텍스트 주석만 제공합니다.
키보드 중심 워크플로	`prefix+a` (캡처), `prefix+ctrl+s` (보내기 및 보관), `prefix+o` (폴더 검토 열기) 같은 키 바인딩으로 터미널에 머물 수 있습니다.
Markdown 피드백 형식	주석은 작업 공간/탭 메타데이터와 인용된 소스 텍스트가 포함된 `## Annotation N` 블록으로 출력되어 LLM이 바로 사용할 수 있습니다.
클립보드 인식	macOS/Linux에서는 시스템 클립보드(`wl‑clipboard`, `xclip`, `xsel`)를, Windows에서는 PowerShell을 사용하며, 원격 세션에는 OSC 52도 출력합니다.
에이전트 비종속	Claude Code, Codex, pi, Copilot CLI, Droid, Hermes CLI, OpenCode 등과 작동합니다.
원격 세션 지원	SSH 또는 `herdr --remote`를 통해 로컬 키 입력 없이 `herdr plugin action invoke annotate.capture`를 호출하여 실행할 수 있습니다.
Links 부가 기능	`file://*.md` 링크를 `Ctrl‑click` 하면 plannotator‑tui 리뷰어에서 열리도록 하는 선택적 부가 기능입니다.
크로스 플랫폼	macOS, Linux, Windows(전체 변형은 미리 보기).

설치

# 전체 설치(기본) – 문서 검토 UI 포함
herdr plugin install plannotator/herdr-annotate

# 라이트 설치 – 터미널 주석만
herdr plugin install plannotator/herdr-annotate/lite

# Windows 전체 (미리 보기) – Herdr ≥ 0.9.0 필요
herdr plugin install plannotator/herdr-annotate/windows-full

이 명령은 미리 빌드된 herdr-annotate 바이너리를 다운로드하고 SHA‑256 체크섬을 확인하여 Herdr 플러그인으로 등록합니다. 추가 런타임은 필요 없습니다.

기본 사용법 (전체 설치)

키	동작
`prefix+a`	선택한 터미널 텍스트를 주석으로 캡처합니다.
`prefix+shift+a`	모든 주석(Markdown)을 클립보드에 복사합니다.
`prefix+ctrl+a`	모든 주석을 복사하고 보관합니다.
`prefix+ctrl+v`	주석을 포커스된 에이전트의 프롬프트에 붙여넣습니다(보내지 않음).
`prefix+ctrl+s`	주석을 다음 에이전트 메시지로 보내고 보관합니다.
`prefix+m`	주석 관리자를 엽니다(목록, 복사, 보관, 삭제).
`prefix+o`	폴더 전체 문서 검토자(plannotator‑tui)를 엽니다.
`prefix+shift+o`	에이전트의 가장 최근 답변을 검토합니다.
`prefix+ctrl+o`	선택기 없이 최신 답변을 검토합니다.

관리자 창은 주석이 생성된 순서대로 표시하므로 LLM이 피드백을 순차적으로 받습니다.

문서 검토 (전체 설치)

prefix+o를 눌러 현재 폴더의 파일 트리 보기를 시작합니다.
prefix+shift+o 또는 prefix+ctrl+o를 사용하여 최근 에이전트 답변을 탐색합니다.
TUI 내에서 편집, 주석, 보내기를 할 수 있으며 검토 내용을 에이전트로 보낼 수 있습니다 (E는 보내기, q는 종료).
선택적 Links 부가 기능을 설치하여 file://*.md 링크를 Ctrl‑click 하면 리뷰어에서 직접 열리도록 할 수 있습니다:
```
herdr plugin install plannotator/herdr-annotate/links
```

원격 / SSH 워크플로

서버에서 선택 항목을 유지하려면 서버의 ~/.config/herdr/config.toml에서 copy_on_select = false를 설정합니다.
로컬 머신에서 키 입력 없이 캡처 작업을 호출합니다:
```
ssh host herdr plugin action invoke annotate.capture
```
플러그인은 Herdr API를 통해 선택 항목을 읽어 로컬 클립보드의 필요성을 우회합니다.

개발 및 확장성

플러그인은 rust/에 있으며 Cargo로 빌드됩니다.

일반적인 개발 주기:

cargo test --manifest-path rust/Cargo.toml
cargo clippy --manifest-path rust/Cargo.toml -- -D warnings
bash scripts/stage-local.sh   # 바이너리 빌드 및 스테이징
herdr plugin link $PWD        # 로컬 테스트용 링크

각 디렉터리를 링크하여 Lite 및 Full 변형 간에 전환할 수 있습니다.
Links 부가 기능에는 컴파일된 구성 요소가 없으며 file:// 클릭을 Full 바이너리로 전달하는 플러그인만 등록합니다.

이런 분들에게 유용합니다

LLM 기반 개발자로서 터미널에서 작업하며 코드 출력, 오류 메시지, 로그에 빠르게 주석을 달고 이를 어시스턴트에게 피드백하려는 분.
프롬프트 엔지니어링을 반복하는 연구자. 관리자를 사용하면 과거 피드백을 보관하고 재생할 수 있습니다.
Herdr을 공유 AI 어시스턴트 인터페이스로 사용하며 세션 간 일관된 주석 형식이 필요한 팀.

빠른 참조 치트 시트

# 키 바인딩 예시 (`~/.config/herdr/config.toml`에 배치)
[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "annotate.capture"
description = "annotate text"

# … README의 지침에 따라 나머지 추가 …

요약: herdr‑annotate는 터미널 선택 항목을 구조화된 LLM 준비 피드백으로 변환하고 전체 문서를 검토할 수 있게 해줍니다. 모든 작업을 Herdr 환경에서 벗어나지 않고 수행할 수 있습니다.