Herdr 플러그인 예제 딥다이브
— "SDK 없이" 터미널 에이전트를 4개 언어로 확장하기

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README의 자기소개는 짧다: "Small example plugins for Herdr. Each subdirectory is a standalone plugin with its own herdr-plugin.toml." — "herdr용 작은 예제 플러그인들. 각 하위 폴더가 자기 매니페스트를 가진 독립 플러그인이다." 즉 이건 라이브러리도, 프레임워크도 아니고 "복사해서 시작하라"고 만든 참고용 레시피 모음이다. README도 못 박는다 — "as-is로 제공되고 적극적으로 유지보수하지 않는다. 이 저장소에 의존하지 말고 필요한 걸 네 플러그인으로 복사해가라."

herdr 본체(별도로 이미 딥다이브한 herdr-deep-dive 참고)가 "여러 코딩 에이전트를 터미널 pane에 늘어놓고 지휘하는 멀티플렉서"라면, 이 저장소는 그 확장 표면(extension surface)을 어떻게 두드리는지 보여주는 4개의 미니 튜토리얼이다. 그래서 이 딥다이브는 herdr 본체의 내부 구조가 아니라 "herdr 플러그인을 어떻게 만드는가"에 초점을 맞춘다.

2왜 주목받는가

트렌딩 이유 · 다른 플러그인 시스템(VS Code·tmux) 대비 배울 점.

직접적 이유는 herdr 본체가 지금 TrendShift 상위권(Daily 3위)에서 급상승 중이고, 이 저장소가 그 생태계의 공식 예제라는 점이다. 하지만 초보자가 여기서 진짜 얻어갈 건 따로 있다 — "확장 시스템(plugin system)을 어떻게 가볍게(lean) 설계하는가"의 교과서다. herdr는 무거운 SDK, 언어별 바인딩, 별도 격리 런타임을 만들지 않았다. 대신 "매니페스트 + 아무 프로세스 + CLI로 되부르기" 세 조각만으로 확장성을 확보했다.

다른 플러그인 시스템과 무엇이 다른가

3기술 스택 전체 지도

폴리글랏(polyglot) — 매니페스트는 하나, 구현 언어는 예제마다 다르다.

이 저장소의 "스택"은 특이하다. 공통 규격은 TOML 매니페스트 하나뿐이고, 나머지는 예제마다 언어가 다르다. 그게 바로 요점 — 폴리글랏 (polyglot): 여러 프로그래밍 언어가 한 시스템 안에 공존하는 것이 herdr 플러그인의 자랑이다.

4아키텍처 심화 분석

"herdr가 프로세스를 띄우고, 플러그인은 CLI로 되부른다" — 양방향 계약.

herdr 플러그인 모델은 딱 두 방향의 흐름으로 요약된다. 내려오는 방향: herdr가 매니페스트를 읽고, 때가 되면 플러그인 명령을 별도 OS 프로세스로 실행하며 환경변수로 맥락을 넣어준다. 올라가는 방향: 플러그인이 더 많은 일이 필요하면 $HERDR_BIN_PATH로 herdr CLI를 되불러 pane을 만들거나 제목을 바꾼다. 이 그림 한 장이 전부다.

매니페스트가 두드릴 수 있는 5개의 확장 표면

플러그인이 herdr에 개입하는 지점은 매니페스트에 선언하는 5종이 전부다(런타임에 코드로 등록하는 방식은 v1에 없다 — 전부 선언형). 이 저장소의 예제 4개가 이들을 골고루 시연한다.

흐름 한 줄기 끝까지 따라가기 — "에이전트가 끝나면 텔레그램 알림이 가기까지"

가장 대표적인 예제(agent-telegram-notify, JavaScript)로, 이벤트 하나가 알림이 되어 날아가는 전 과정을 추적해보자.

주목할 점: notify.mjs는 외부 npm 패키지를 하나도 안 쓴다. HTTP 요청은 Node 18+에 내장된 fetch, 파일 읽기는 내장 fs, .env 파싱조차 직접 짠 20줄짜리 로더(lib.mjs)로 해결한다. "플러그인은 가볍게, 의존성은 최소로"라는 이 저장소 전체의 정신이 여기 압축돼 있다.

또 하나의 흐름 — Lua 플러그인이 herdr를 되불러 pane을 조립

dev-layout-bootstrap(Lua)은 "올라가는 방향"의 좋은 예다. 플러그인이 herdr CLI를 반복 호출해 개발용 3분할 레이아웃을 만든다. 핵심은 herdr 명령의 JSON 출력에서 새로 생긴 pane의 id를 파싱해, 그 id를 다음 명령의 대상으로 넘기는 부분이다.

-- setup.lua (핵심만) : herdr를 CLI로 되불러 pane을 쪼갠다
local herdr_bin = os.getenv("HERDR_BIN_PATH") or "herdr"
local root_pane = os.getenv("HERDR_PANE_ID")   -- 현재 pane id

herdr("pane", "rename", root_pane, "editor")   -- 현재 칸 이름을 editor로

local files_json = herdr_capture(              -- 오른쪽으로 분할, 출력을 캡처
  "pane","split",root_pane,"--direction","right","--ratio","0.58","--no-focus")
local files_pane = pane_id_from_json(files_json) -- {"pane_id":"..."} 에서 id 추출

herdr("pane","run",files_pane,"ls -la")        -- 새 칸에서 명령 실행

이 프로젝트에서 "정상"인 모양새: 플러그인은 herdr 상태를 직접 만지지 못한다. 대신 herdr 명령을 실행 → 결과 JSON을 받아 → 다음 명령의 인자로 이어붙이는 "CLI 파이프라인" 패턴이 herdr 플러그인의 관용구다. 셸 인젝션을 막으려고 Lua 예제는 모든 인자를 shell_quote로 감싼다.

5디렉토리 구조 해부

폴더 하나 = 독립 플러그인 하나. 각자 다른 언어·다른 표면.

6학습 포인트 (기술별)

이 저장소 4개 예제로 배울 수 있는 것 + 실습 아이디어.

6-1. 매니페스트로 "확장 표면"을 선언하기

herdr 플러그인의 첫 배움은 코드가 아니라 선언(declaration)이다. 무엇을 언제 실행할지는 전부 herdr-plugin.toml에 적는다. 같은 스크립트라도 [[actions]]로 걸면 "사용자가 부를 때", [[events]]로 걸면 "사건이 일어날 때" 실행된다.

# agent-telegram-notify/herdr-plugin.toml (발췌)
[[actions]]                         # 사용자가 부르는 명령
id = "toggle"
title = "Toggle Telegram notify"
command = ["node", "toggle.mjs"]

[[events]]                          # herdr 사건에 자동 반응
on = "pane.agent_status_changed"
command = ["node", "notify.mjs"]

6-2. 이벤트 훅 — herdr가 넣어주는 컨텍스트 JSON 읽기

이벤트 훅으로 실행된 스크립트는 "무슨 일이 일어났는지"를 환경변수 HERDR_PLUGIN_EVENT_JSON·HERDR_PLUGIN_CONTEXT_JSON으로 전달받는다. notify.mjs는 여기서 에이전트 상태를 꺼내 필터링한다.

// notify.mjs (핵심 판단부)
const event = JSON.parse(process.env.HERDR_PLUGIN_EVENT_JSON ?? "{}");
const status = event?.data?.agent_status;      // "done" | "blocked" | ...
if (!["done", "blocked"].includes(status)) {
  process.exit(0);                             // 관심 없는 상태면 조용히 종료
}
// 여기 도달하면 done/blocked → 텔레그램 전송

6-3. 설정·상태 분리 + 의존성 0 유지 (lib.mjs)

lib.mjs는 이 저장소에서 가장 교육적인 파일이다. 외부 dotenv 패키지 없이 .env를 직접 파싱하고, on/off 토글 상태를 HERDR_PLUGIN_STATE_DIR 밑 파일에 저장한다. "설정은 CONFIG_DIR, 상태는 STATE_DIR, 코드는 ROOT"라는 3분리를 코드로 실천한다 — GitHub 설치본은 소스가 통째로 교체될 수 있으니 사용자 데이터를 소스 폴더에 두면 안 되기 때문이다.

// lib.mjs — 상태 파일 경로는 STATE_DIR 우선
export function modePath() {
  if (process.env.HERDR_PLUGIN_STATE_DIR)
    return join(process.env.HERDR_PLUGIN_STATE_DIR, "enabled");
  // STATE_DIR이 없던 옛 herdr용 폴백(XDG_STATE_HOME …)
}
// .env는 CONFIG_DIR/.env → 로컬 .env 순으로 직접 파싱 (dotenv 패키지 X)

6-4. Lua로 herdr를 되불러 pane 조립하기

setup.lua의 배움은 "herdr 명령의 출력(JSON)에서 새 pane id를 뽑아 다음 명령에 넘기는" 파이프라인이다(4장에서 본 그 패턴). 표준 라이브러리(os.execute/io.popen)만으로 외부 프로세스를 부르고, 정규식으로 pane_id를 긁는다. 셸 인젝션 방지를 위해 모든 인자를 shell_quote로 감싸는 습관도 함께 배운다.

6-5. Bash 링크 핸들러 + 전용 pane 열기

github-link-preview는 한 플러그인에 표면 3개(actions+panes+link_handlers)를 엮는다. 매니페스트의 정규식이 클릭된 URL과 매칭되면 액션이 뜨고, 액션은 herdr plugin pane open으로 옆 pane을 열며 --env로 URL을 그 pane에 전달한다.

# herdr-plugin.toml — 정규식으로 GitHub 이슈/PR URL만 가로챈다
[[link_handlers]]
pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+/?$"
action  = "open"

# open.sh — 클릭된 URL을 새 pane으로 넘긴다
exec "$herdr_bin" plugin pane open \
  --plugin examples.github-link-preview --entrypoint preview \
  --placement split --direction right \
  --env "GITHUB_URL=$url" --focus     # preview.sh가 이 URL로 gh 실행

6-6. Rust — 설치 시 컴파일 + 손수 짠 JSON 파서(의존성 0)

rust-release-check는 [[build]] 표면을 배우는 예제다. plugin install 시 herdr가 cargo build --release를 먼저 돌려 바이너리를 만든 뒤 등록한다. 컴파일 언어도 "매니페스트 + argv"라는 같은 계약에 자연스럽게 들어온다는 걸 보여준다. 놀랍게도 크레이트 의존성이 0 — serde_json조차 안 쓰고 컨텍스트 JSON에서 필요한 필드 하나만 문자열 스캔으로 뽑는다.

// main.rs (개념 요약) — 표준 라이브러리만 사용
let ctx  = env::var("HERDR_PLUGIN_CONTEXT_JSON").unwrap_or_default();
let repo = json_string_field(&ctx, "focused_pane_cwd")   // 직접 짠 파서
    .or_else(|| json_string_field(&ctx, "workspace_cwd"));
// git -C {repo} status --short 를 실행해 트리가 깨끗한지 검사

7시스템 요구사항

호스트 herdr 하나 + 예제별 런타임. 전부 가볍다.

8직접 해볼 수 있는 실습 과제

난이도별 6단계. herdr 0.7+ 설치 후, 신뢰할 수 있는 코드만 install 할 것.

9관련 기술 심화 학습 로드맵

이 예제 저장소를 출발점으로, 5주 코스.

10핵심 키워드 사전

본문에 나온 용어 빠른 참조.

11참고 링크

• 예제 저장소: ogulcancelik/herdr-plugin-examples
• herdr 본체: ogulcancelik/herdr · 함께 볼 herdr 딥다이브
• 예제 1 · JavaScript: agent-telegram-notify
• 예제 2 · Lua: dev-layout-bootstrap
• 예제 3 · Bash: github-link-preview
• 예제 4 · Rust: rust-release-check
• herdr 플러그인 공식 문서: docs/plugins
• Telegram Bot API: core.telegram.org/bots/api
• GitHub CLI: cli.github.com