Herdr-mesh

herdr-mesh
herdr 내부에서 멀티 에이전트 워크플로를 오케스트레이션하기 위한 MCP 서버로,
실시간 통신, pane 관리, 컨텍스트 핸드오프를 가능하게 합니다.

한국어: README.ko.md

왜 필요한가
herdr는 이미 여러 에이전트를 오케스트레이션하는 데 필요한 모든 것을 갖추고 있습니다 — 실제 pane,
영속 세션, 의미론적 에이전트 상태(idle/working/blocked/done), 그리고 이 모든 것을 제어하는 CLI +
소켓 API까지. 부족했던 것은 에이전트 스스로가 그것을 사용할 수 있는 표준 인터페이스였습니다.

그래서 herdr 안에서 여러 에이전트(Claude, Codex, …)를 실행할 때, 사람이 터미널 사이를 오가지 않고도
서로의 컨텍스트를 읽거나, 세션을 공유하거나, 메시지를 주고받을 깔끔한 방법이 없었습니다.

herdr-mesh가 그 간극을 메웁니다: herdr의 CLI를 MCP 도구로 노출하여, MCP를 지원하는
모든 에이전트가 — 유형에 관계없이 — 다른 에이전트의 pane을 읽고, 컨텍스트를 핸드오프하고, 협업하고,
스스로 새 에이전트를 띄울 수 있게 합니다. 목표는 herdr의 멀티 에이전트 워크플로를 에이전트 스스로가
하나의 표준적이고 에이전트에 구애받지 않는 인터페이스를 통해 프로그래밍 가능하게 만드는 것입니다.

사용 사례
herdr-mesh가 지루한 터미널 전환 작업을 단 한 문장의 자연어 지시로 바꿔주는 구체적인 상황들입니다.

1. 코드 → 리뷰 → 수정 루프
Claude가 코드를 작성하고 Codex가 리뷰하는 상황. Codex가 버그를 발견하면 — 보통은
직접 Claude에게 복사해 넘겨야 합니다. 대신:

"Codex에게 Claude가 방금 한 변경 사항을 리뷰하게 해줘. 문제를 찾으면 Claude에게 보내서
고치게 하고, 그다음 Codex에게 다시 리뷰를 요청해. 깔끔해질 때까지 반복해."

오케스트레이션하는 에이전트는 herdr_agent_read(Codex의 리뷰 가져오기) →
herdr_agent_send(발견 사항을 Claude에게 전달) → herdr_agent_wait(Claude가 끝날 때까지 대기) →
그리고 리뷰를 반복합니다. pane 사이의 복사-붙여넣기가 없습니다.

2. 병렬 팬아웃

"이 리팩터링을 나눠줘: Claude는 API 계층을, Codex는 테스트를 맡고, 그다음 두 결과를 모아서 요약해."

herdr_agent_start / herdr_agent_send로 두 에이전트를 생성/지정하고,
herdr_agent_wait로 각각을 기다린 뒤, herdr_agent_read로 출력을 병합합니다.

3. 장시간 핸드백

"빌드 에이전트에게 전체 테스트 스위트를 실행하라고 하고, PASS 또는 FAIL이 출력될 때까지 기다린 뒤,
실패한 케이스들을 가져와 줘."

herdr_pane_run으로 실행을 시작하고 herdr_wait_output으로 결과를 블로킹 대기합니다 — pane을
지켜보는 대신 완료되는 순간 알림을 받습니다.

4. 막힌 에이전트 해제
에이전트가 확인을 기다리며 프롬프트에 멈춰 있는(blocked) 동안 당신은 다른 pane에 집중하고 있습니다.

"입력을 기다리며 막힌 에이전트가 있어? Codex가 y/n 프롬프트에서 멈춰 있으면, 계속 진행할 수 있게 승인해 줘."

herdr_agent_list가 blocked 상태를 드러내고, herdr_agent_send +
herdr_pane_send_keys가 프롬프트에 응답합니다 — 당신 쪽의 컨텍스트 전환이 필요 없습니다.

5. 스펙 → 구현 → 검증 파이프라인

"아키텍트 에이전트의 pane에 있는 계획을 가져다가 Claude에게 구현하게 하고, 그다음 테스터 에이전트가
결과에 대해 스위트를 실행하게 해."

herdr_agent_read로 스펙을 읽고, herdr_agent_send로 핸드오프하고,
herdr_agent_wait로 기다린 뒤, 세 번째 에이전트에서 검증을 트리거합니다 — 하나의 지시로 구동되는
3단계 릴레이입니다.

6. 컨텍스트를 가진 에이전트에게 질문 라우팅

"결제 서비스에서 작업 중인 에이전트가 이미 그 코드를 로드하고 있어 — 웹훅이 왜 재시도되는지 물어보고,
그 답을 가져와 줘."

직접 컨텍스트를 다시 로드하는 대신, herdr_agent_send가 이미 그 코드베이스에 있는 에이전트에게 질문을
던지고 herdr_agent_read가 그 답변을 반환합니다.

요점: 예전에는 중간에 사람이 필요했던 에이전트 간 핸드오프가 한 문장이 됩니다.

herdr는 이미 워크스페이스/에이전트 런타임을 CLI + 소켓 API로 노출하고 있습니다. herdr-mesh는
그 CLI를 Model Context Protocol 도구로 감싸서, 어떤
MCP 클라이언트든 표준 인터페이스를 통해 다른 에이전트의 pane을 읽고, 메시지를 보내고, 세션을 공유하고,
새 에이전트를 띄울 수 있게 합니다.

에이전트에 구애받지 않습니다: 도구는 herdr가 인식하는 모든 에이전트 — pi, omp,
claude, codex, opencode, hermes, qodercli, 그리고 향후의 모든 통합 — 에 대해 동작합니다. 대상은
터미널 id, 에이전트 이름, 보고된 에이전트 레이블, 또는 레거시 pane id를 받습니다; 특정 에이전트 유형에
묶이지 않습니다. 무엇이 사용 가능한지 보려면 herdr_integration_status를 사용하세요.

동작 방식
MCP client ──stdio(MCP)──> herdr-mesh ──exec "herdr …"──> herdr CLI ──socket──> herdr server

각 도구는 herdr CLI를 서브프로세스로 실행하고 그 JSON 출력을 반환합니다. 별도의 프로토콜 구현이
없습니다 — herdr 자체의 버전/프로토콜 처리가 권위를 유지합니다.

요구 사항

Node.js 18+
herdr가 설치되어 있고 서버가 실행 중이어야 합니다(herdr status가 running을 표시).
herdr가 PATH에 없으면 HERDR_BIN을 설정하세요.

설치 (권장)
전역으로 설치한 뒤, 내장 설치 프로그램이 에이전트를 감지하고 herdr-mesh를 등록하게 하세요:

npm i -g https://github.com/runchr-works/herdr-mesh/archive/refs/heads/main.tar.gz
herdr-mesh install

GitHub에서 직접 설치합니다(npm 레지스트리가 아님). 저장소에 미리 빌드된
dist/가 포함되어 있어 설치에는 네트워크 접근만 필요합니다 — 빌드 단계가 없습니다. 나중에 업데이트하려면
같은 명령을 다시 실행하세요.

더 짧은 npm i -g runchr-works/herdr-mesh도 git 설치를 깔끔하게 처리하는 npm 환경에서는 동작합니다;
동작하는 herdr-mesh 명령이 생성되지 않으면 위의 tarball URL을 사용하세요. 전역 설치를 아예 원하지
않으세요? 수동 등록 — npx는 전역 설치 없이도 동작합니다.

herdr-mesh install은 설치된 에이전트를 감지하고 선택한 에이전트에 herdr-mesh를 등록합니다:

Claude Code — claude mcp add -s user를 통해
Codex — ~/.codex/config.toml에 [mcp_servers.herdr-mesh]를 추가
opencode — ~/.config/opencode/opencode.json에 병합
기타 에이전트 — 붙여넣을 정확한 설정 스니펫을 출력

안전합니다: 기존 설정은 파싱되어 병합되며(절대 덮어쓰지 않음), 쓰기 전에 .bak
백업이 생성되고, 재실행 시 이미 등록된 에이전트는 건너뜁니다.
herdr-mesh install -y를 사용하면 감지된 모든 에이전트에 비대화식으로 등록합니다.

이후 에이전트를 재시작하여 herdr-mesh를 인식하게 하세요.

수동 등록
각 에이전트는 자체 MCP 클라이언트입니다; 에이전트마다 herdr-mesh를 한 번씩 등록하세요. 같은 머신의
모든 에이전트는 동일한 herdr 소켓을 공유하므로, 서로를 보고 메시지를 주고받을 수 있습니다. 서버 명령은
herdr-mesh입니다(전역 설치 후).

Claude Code:

claude mcp add -s user herdr-mesh herdr-mesh
Codex (~/.codex/config.toml):

[ mcp_servers . herdr-mesh ]
command = " herdr-mesh "
일반 MCP 설정(stdio):

{
"mcpServers" : {
"herdr-mesh" : {
"command" : " herdr-mesh "
}
}
}

전역 설치를 원하지 않으세요? 명령으로 herdr-mesh 대신 npx -y runchr-works/herdr-mesh를
사용하세요(npx는 GitHub에서 미리 빌드된 저장소를 가져옵니다; 다운로드하는 동안 첫 실행이 느립니다).

소스에서 빌드 (로컬 개발)
git clone https://github.com/runchr-works/herdr-mesh.git
cd herdr-mesh
npm install
npm run build
node dist/index.js # 서버를 직접 실행
node dist/index.js install # 또는 소스에서 설치 프로그램 실행
사용법 — 에이전트와 그냥 대화하세요
도구 이름을 직접 입력하지 않습니다. 에이전트(Claude, Codex, …)와 자연어로 대화하면, 에이전트가
언제 herdr-mesh 도구를 호출할지 결정하고 결과를 보고합니다. 아래 문구들은 무엇을 말하면 어떤 기능이
트리거되는지에 대한 예시입니다.

무엇이 실행 중인지 보기

"지금 herdr에서 어떤 에이전트들이 실행 중이야?" → 에이전트 + 상태 나열
"herdr가 어떤 에이전트 통합을 지원해?" → 통합 상태

다른 에이전트의 컨텍스트 읽기 (핸드오프 인)

"codex pane을 읽고 무엇을 작업 중인지 요약해 줘."
"reviewer라는 에이전트에서 마지막 100줄을 가져와 줘."

메시지 보내기 / 작업 핸드오프

"codex에게 말해: '이 브랜치의 diff를 리뷰해 줘'."
"reviewer 에이전트에게 테스트를 실행하고 보고하라고 해 줘."
"pane w65343…-3에 npm test를 보내고 실행해." (Enter로 실행)

협업 / 대기

"codex가 idle이 될 때까지 기다린 뒤, 다음 작업을 보내 줘."
"빌드 pane을 지켜보다가 'BUILD SUCCESS'가 출력되면 알려 줘."

에이전트 생성 / 관리

"오른쪽 분할에 새 codex 에이전트를 시작해서 내 작업을 리뷰하게 해 줘."
"claude를 실행하는 tester라는 새 에이전트를 열어 줘."

세션 & 워크스페이스

"herdr 세션을 나열해." / "docs 프로젝트를 위한 새 워크스페이스를 만들어 줘."

전형적인 핸드오프, 모두 자연어로:

"내 현재 변경 사항을 가져다가 새 codex 에이전트에게 리뷰를 위해 넘기고, 끝날 때까지 기다린 뒤,
그 피드백을 요약해 줘."

에이전트는 스스로 herdr_agent_start → herdr_agent_send → herdr_agent_wait →
herdr_agent_read를 연쇄 호출합니다.

요청을 표현할 때 알아두면 좋은 점

메시지를 그냥 전달하기만 원하는지 vs 실행/제출하기를 원하는지 명확히 하세요
— 예: "그냥 입력만 해 줘" vs "보내고 실행해 줘". (전달만 하면 다른 에이전트의 입력에
텍스트를 입력할 뿐, Enter를 누르지 않습니다.)
출력이 비어 보이면 "지금 화면에 있는 것을 기준으로" 요청하세요. "최근 명령 출력" 영역은
추적된 것이 없을 때 비어 있을 수 있습니다.

도구 (LLM을 위한 참조)
에이전트에 노출되는 도구 이름들입니다 — 참조용으로 나열한 것이며, 직접 입력하는 것이 아닙니다.

에이전트 메시징 & 컨텍스트 (핵심)

herdr_relay — 에이전트에 메시지를 전달하고 제출합니다(입력 + Enter).
메시징에 선호됨; "입력되었지만 제출되지 않은" 함정을 피합니다.
herdr_handoff — 작업을 보내고, 에이전트가 끝날 때까지 기다린 뒤, 결과를 다시 읽습니다
— 한 단계로. 리뷰/수정/검증 루프에 선호되어 체인이 끊기지 않게 합니다.
herdr_agent_list — 상태(idle/working/blocked/done)와 함께 에이전트 나열
herdr_agent_get — 에이전트 세부 정보
herdr_agent_read — 다른 에이전트의 pane 출력 읽기(컨텍스트 핸드오프)
herdr_agent_send — 저수준: 에이전트에 리터럴 텍스트 입력(Enter 없음)
herdr_agent_wait — 에이전트가 특정 상태에 도달할 때까지 블로킹
herdr_wait_output — pane의 출력이 텍스트/정규식과 일치할 때까지 블로킹

에이전트 수명 주기 & 탐색

herdr_agent_start — 새 에이전트 터미널 생성(지원되는 모든 에이전트)
herdr_agent_rename, herdr_agent_focus
herdr_integration_status — herdr가 알고 있는 에이전트 통합과 그 상태 나열

세션

herdr_session_list, herdr_session_stop, herdr_session_delete

Pane

herdr_pane_list / get / read / split / run / send_text / send_keys / close / rename
명령을 입력하고 Enter를 누르려면 herdr_pane_run을 사용하세요; 리터럴 텍스트에는 *_send_text를 사용하세요.

탭 & 워크스페이스

herdr_tab_* — list / create / get / focus / rename / close
herdr_workspace_* — list / create / get / focus / rename / close

동작 참고 사항 (LLM / 개발자용)
도구 수준의 동작 세부 사항입니다 — 최종 사용자 팁이 아니라, LLM이 도구를 올바르게 사용하기 위해
의존하는 것과 개발자가 이해해야 할 것입니다.

메시지 / 명령 보내기

텍스트만 전달: herdr_agent_send (Enter를 누르지 않음)
제출까지: 이어서 enter를 보내는 herdr_pane_send_keys
셸 명령 실행: herdr_pane_run (입력하고 Enter를 누름) — 가장 간단

출력 읽기: 컨텍스트 검색에는 source: "visible"이 화면 내용을 가장 안정적으로
반환합니다. recent / recent-unwrapped는 추적된 명령 출력 영역이 없을 때 비어 있을 수 있습니다.

컨텍스트 & 세션 공유

컨텍스트 공유: herdr_agent_read로 다른 에이전트의 출력을 가져오고,
herdr_agent_send / herdr_pane_run으로 밀어 넣습니다.
세션: 같은 herdr 서버에 연결된 모든 에이전트는 이미 하나의 세션(소켓)을 공유합니다 — 이것이
컨텍스트 공유가 의존하는 기반입니다. MCP를 통해 세션을 관찰/관리할 수 있습니다
(session_list / stop / delete). 사람의 원격 세션 연결(SSH attach)은 herdr의 네이티브 기능이며
대화식이므로, MCP 도구에서는 의도적으로 제외됩니다.

문제 해결
자연어 요청은 보통 동작하지만, 에이전트(LLM)가 궁극적으로 도구를 호출할지, 어떻게 호출할지를 결정하므로
100% 결정적이지 않습니다. 무언가 일어나지 않으면:

에이전트가 행동 없이 답만 했습니다. 명시적으로 기능을 지정하세요, 예:
"herdr-mesh를 사용해서 codex에게 메시지를 보내" 또는 "이걸 하려면 herdr 도구를 호출해".
메시지는 보내졌지만 아무것도 실행되지 않았습니다. herdr_agent_send는 Enter 없이 입력합니다.
"보내고 실행해 줘"라고 요청하거나, 대신 제출까지 해주는 herdr_relay / herdr_handoff를
사용하세요.
대상이 잘못되었거나 없습니다. "먼저 에이전트를 나열해"라고 하고, 그 목록의 이름/id로
지정하세요.
읽기 결과가 비어 있습니다. "지금 화면에 있는 것에서" 출력을 요청하세요
(source: visible); 추적된 "recent" 출력은 비어 있을 수 있습니다.
다단계 핸드오프가 중간에 멈췄습니다. herdr_handoff…