missuo/herdrm

Native macOS console for herdr — all your coding agents and their live terminals, across devices

📦 herdrm – herdr AI-코딩 에이전트 런타임용 네이티브 macOS 콘솔

herdrm은 macOS 전용 GUI 애플리케이션( SwiftUI로 구축)으로, herdr 백그라운드 서버( Claude, Codex, Gemini, Grok, OpenCode 등 AI 코딩 에이전트를 실행하는 데몬)와 상호작용할 수 있게 해줍니다. herdr이 관리하는 원격 또는 로컬 PTY를 실제 기능이 풍부한 터미널 패널로 전환하며, 장치, 공간, 에이전트, 파일을 탐색할 수 있는 그래픽 사이드바를 제공합니다.

✨ 어떤 기능을 제공하나요 (README에 설명됨)

기능	제공되는 기능
모든 장치	로컬 맥과 SSH로 접근 가능한 모든 장치(일반 SSH, Tailscale SSH, 또는 macOS 키체인에 저장된 비밀번호)에 연결 가능. 앱은 각 장치에 대해 재접속 루프를 유지합니다.
실시간 상태	사이드바에서 연결된 모든 장치의 Spaces → Agents → Terminals를 실시간 상태(실행 중, 차단됨, 완료됨)로 표시합니다.
실제 터미널	에이전트나 쉘의 실제 PTY에 연결(채팅 래퍼가 아님). 네이티브 텍스트 선택, 적절한 폰트, 줄 간격 조절, 연결이 끊어져도 재접속 가능한 강력한 세션을 제공합니다.
어떤 파일도 붙여넣기	파일이나 이미지를 드래그 앤 드롭. 로컬에서는 클립보드를 통해, 원격에서는 일시적 캐시를 통해 에이전트로 스트리밍됩니다.
파일 이동	두 패널 파일 매니저로 로컬 맥과 SSH 호스트 간 파일 복사 가능. 진행 상황, 취소, 충돌 처리 기능 포함.
알림	에이전트가 입력을 기다리거나 완료했을 때 macOS 알림이 발생. 클릭하면 바로 해당 패널로 이동합니다.
⌘K 검색	모든 장치, 공간, 에이전트를 대상으로 하는 글로벌, 퍼지 검색. 한 키로 어디든 바로 이동 가능.
네이티브 macOS 느낌	유니버설 바이너리(Apple Silicon + Intel), 라이트/다크 모드, Sparkle를 통한 자동 업데이트, 서명 및 노타라이즈됨.

🤔 왜 herdrm을 사용해야 하나요?

이미 herdr을 사용해 에이전트를 실행하고 있지만, 기본 herdr attach 워크플로우는 터미널 중심이며 tmux 스타일의 탐색이 필요합니다.
herdrm은 포인트 앤 클릭 UI(사이드바 행, 컨텍스트 메뉴)를 제공하면서도 실제 PTY를 노출하므로, 멀티플렉서의 정신적 부담 없이 완전한 TUI 경험을 유지할 수 있습니다.
순수 네이티브 – Electron이나 내장 브라우저를 사용하지 않아 즉시 시작되고 가볍습니다.
모든 장치를 한 창에서 통합 관리하여, 풀링 없이 상태를 모니터링하고 에이전트에 응답할 수 있습니다.

📦 설치 방법

방법	명령어 / 단계
Homebrew (권장)	`brew install owo-network/brew/herdrm`
수동 설치	Releases 페이지에서 최신 `herdrm-x.y.z.zip`을 다운로드, 압축 해제 후 `herdrm.app`을 `/Applications` 폴더로 드래그. 이후 업데이트 확인… 메뉴를 통해 자동 업데이트가 이루어집니다.

⚠️ 보안 주의 – 서명되고 노타라이즈된 빌드는 공식 GitHub 리포지토리와 Homebrew cask에서만 제공됩니다. 제3자 미러는 동일한 이름으로 관련 없는 Windows 페일로드를 배포한 바 있습니다.

⚡ 빠른 시작 가이드 (README에서)

herdrm을 실행 – 아직 데몬이 실행 중이지 않으면 로컬에서 herdr 데몬을 자동 시작합니다.
(선택 사항) 원격 장치 추가 – 예: you@dev-box, you@dev-box:2222, 또는 Tailscale 호스트.
⌘N을 눌러 장치와 CLI(Claude, Codex 등)를 선택 – 해당 실시간 터미널에 연결됩니다.
⌘K를 눌러 검색하고, 어떤 장치의 어떤 에이전트나 터미널로든 바로 이동합니다.

🏗️ 아키텍처 (고수준 개요, README에서)

herdr  (백그라운드 서버, PTY 소유) ──► Unix-소켓 RPC / SSH 터널 ──► HerdrKit (Swift 패키지, UI 독립적 전송 및 장치 저장소) ──► HerdrM (SwiftUI 앱: 사이드바, 터미널, 검색, 알림)

herdr – Spaces, Agents, 그리고 그들의 PTY를 생성하고 지속하는 데몬.
Packages/HerdrKit – 소켓-RPC, SSH 터널링, 장치 기록을 처리하는 Swift 패키지. 별도로 단위 테스트 가능 (make kit-test).
Sources/HerdrM – 실제 macOS 앱. SwiftTerm (Metal 기반 터미널 에뮬레이터)를 기반으로 하며 SwiftUI를 통해 UI와 연결됩니다.

🛠️ 개발 및 기여

빌드 전제 조건: brew install xcodegen.
명령어:
- make build – xcodegen로 Xcode 프로젝트 생성 후 앱 빌드 (herdrm.app).
- make run – 빌드된 앱 실행.
- make kit-test – HerdrKit 통합 테스트 실행 (로컬 herdr 데몬 필요).
프로젝트는 초기 단계입니다: 테스트 커버리지 제한, 버그 예상, PR 환영. README의 기여 가이드라인 따르기.

📄 라이선스

PolyForm Non-commercial 1.0.0 – 비영리 목적 사용, 수정, 공유는 무료. 영리 목적 사용은 유지보수자로부터 별도 라이선스 필요.

⚠️ 상태

초기 단계 – 기능은 있지만 자동 테스트로 완전히 커버되지 않음. 간헐적인 충돌이나 에지 케이스 처리 누락 가능성 있음.

결론: 이미 herdr AI-코딩 에이전트 런타임을 사용하고 있으며, 여러 장치를 관리하고 에이전트 상태를 모니터링하며 그래픽 앱의 편안함을 유지하면서도 실제 PTY로 작업하고 싶다면, herdrm은 정확히 그 목적을 위해 만들어진 클라이언트입니다.