CLI 확장
기준일: 2026-07-26
난이도: 중급
공식 기준: Extending the CLI
개요
Hermes TUI를 래퍼 CLI로 확장하는 방법입니다. 커스텀 위젯, 키바인딩, 레이아웃을 추가하면서 업스트림 TUI와 호환을 유지합니다.
핵심 개념
| 훅 | 역할 |
|---|---|
_get_extra_tui_widgets() |
추가 위젯 생성 |
_register_extra_tui_keybindings(kb, ...) |
키 바인딩 |
_build_tui_layout_children(**widgets) |
레이아웃 트리 조합 |
상세
Extension points
코어를 포크하기보다 래퍼에서 훅을 오버라이드합니다. 플러그인의 slash/command 확장과 역할이 다릅니다.
- 플러그인: 도구·훅·슬래시 커맨드
- CLI extension: 터미널 UI 구조·입력·표시
Quick start: wrapper CLI
- Hermes TUI 엔트리 서브클래스/래퍼 작성
- 위 세 훅 구현
- 콘솔 스크립트 엔트리포인트로 배포
- 기존
hermes와 병렬 설치 가능하도록 이름 분리
Hook reference
_get_extra_tui_widgets()
상태 패널, 사이드바, 커스텀 입력 보조 위젯 반환.
_register_extra_tui_keybindings
prompt_toolkit/키 바인딩 객체에 단축키 등록. 기존 바인딩과 충돌 검사.
_build_tui_layout_children
기본 레이아웃 children 사이에 위젯 삽입. 공식 레이아웃 다이어그램 순서를 유지하면 업스트림 변경에 덜 깨집니다.
Layout diagram (개념)
[ header / status ]
[ conversation buffer ][ optional side ]
[ input row + extra widgets ]
Tips
- upstream 업데이트 시 훅 시그니처 diff 확인
- UI 상태와 agent session 상태를 섞지 말 것
- 접근성: 키보드만으로 주요 동작 가능
- 테스트: headless에서 import/layout smoke
체크리스트
- 이 페이지의 공식 문서를 원문과 대조했다
- 로컬 환경에서 관련 명령/
config.yaml항목을 확인했다 - 보안·allowlist·자격증명 노출 위험을 점검했다
- 다음 단계 문서로 연결 경로를 확인했다
다음 단계
- 관련 공식 문서: Extending the CLI
- 상위 허브: Hermes Agent 소개
- 문제 해결: 트러블슈팅
기준일: 2026-07-26 — 공식 문서 동기화 코퍼스