Search Sparktype

CLI 코딩 에이전트용 HUD 도구, 뭘 골라야 할까

tmux 기반 HUD부터 runtime 확장 계열까지 대안을 비교하고, 실제 저장소를 리뷰하며 발견한 파서 불일치·타임아웃 설정 문제를 정리합니다.

Share

터미널에서 CLI 코딩 에이전트를 쓰다 보면 현재 세션의 상태(플랜, 실행 중인 툴, 진행률)를 한눈에 보여주는 HUD(상태 표시) 도구가 아쉬워질 때가 있습니다. 대안을 비교하고, 그중 하나를 실제로 리뷰하며 발견한 문제를 정리합니다.

대안 비교

기존에 쓰던 HUD 도구가 유지보수가 끊겼다면, 후보를 고르는 기준은 이렇습니다.

  • 현재 에이전트 CLI와의 궁합이 좋은지
  • 소스 패치 없이 쓸 수 있는지
  • 최근 유지보수 흔적이 있는지
  • HUD 목적에 비해 과도하게 무겁지 않은지
유형특징적합한 경우
tmux 기반 HUDmulti-session overview, tmux 자동 활성화 등 운영 기능 중심“지금 바로 HUD 체감”이 목적일 때
Runtime 확장 계열HUD뿐 아니라 CLI 실행 환경 자체를 확장전체 작업 환경을 바꿀 의향이 있을 때
CLI 미수정 방향대상 CLI를 패치하지 않고 별도 프로세스로 동작프로젝트 성숙도는 낮아도 안전하게 시도해볼 때
Plugin 중심standalone 커맨드 + 실험적 패치 footer 병행native status line의 보조 도구로 쓸 때

바로 갈아탈 목적이면 tmux 기반 HUD부터 검증하고, 더 넓은 범위의 runtime 정리가 필요하면 확장 계열을 검토하는 순서가 무난합니다.

실제 리뷰에서 발견한 문제들

패치 기반으로 CLI에 상태 라인을 얹는 방식의 HUD 도구 하나를 리뷰하며 발견한 문제들입니다. CLI 에이전트의 세션 로그(rollout) 포맷과 파서가 어긋나거나, 설치 스크립트가 최신 버전에 대해 깨져 있는 경우가 흔했습니다.

1. 세션 로그 포맷과 파서의 불일치 (High)

HUD는 세션 로그 이벤트 이름을 하드코딩해서 파싱하는데, CLI 쪽 로그 포맷이 바뀌면 조용히 어긋납니다.

파서가 읽는 이벤트: turn_started / turn_complete / turn_aborted
실제 로그의 이벤트: task_started / task_complete

결과적으로 최신 버전 기준에서는 HUD가 계속 idle 상태로 남거나 플랜·툴 영역이 비어 있게 됩니다. 로그 포맷에 의존하는 외부 도구는 대상 CLI가 마이너 업데이트만 해도 깨질 수 있다는 걸 보여주는 사례입니다. 이런 도구를 쓸 때는 버전 호환 여부를 먼저 확인하는 게 안전합니다.

2. 설치 스크립트가 최신 버전에 대해 이미 깨져 있음 (High)

설치 스크립트가 대상 CLI 저장소를 최신 HEAD로 clone한 뒤 저장소 내 패치 파일을 즉시 적용하는 구조였는데, 실제로 git apply --check를 돌려보니 여러 파일에서 hunk failure가 났습니다.

git -C /tmp/cli-review apply --check patches/statusline-command.patch
# → 여러 파일에서 hunk failure

즉 신규 설치는 빌드 단계 전에 멈춥니다. 패치 기반 도구는 대상이 계속 바뀌는 프로젝트라면 CI로 최신 HEAD 대상 apply --check를 주기적으로 돌리지 않는 이상 이런 문제를 못 잡습니다.

3. 타임아웃 설정이 실측값보다 짧음 (High)

패치가 외부 상태 조회 커맨드에 150ms 타임아웃을 걸어뒀는데, 실제 커맨드를 5회 측정하니 약 0.21~0.23초가 걸렸습니다.

/usr/bin/time -p node dist/index.js --status-line --once --no-clear
# → 약 0.21~0.23초

기본 구현만으로도 타임아웃을 넘기고 있었던 것입니다. 게다가 이 구현은 대기 상태가 풀릴 때마다 커맨드를 다시 실행하는 구조라, 빈 상태 표시와 반복 프로세스 기동이 함께 발생할 수 있습니다. 타임아웃 값은 반드시 실제 커맨드 실행 시간을 측정해서 정해야 하고, 여유 마진 없이 설정하면 “기능은 있지만 항상 실패하는” 상태가 됩니다.

4. “현재 세션”이 아니라 “가장 최근 갱신된 아무 로그”를 참조 (Medium)

세션 로그 탐색 로직이 로그 디렉터리 전체를 재귀 스캔해서 수정 시각이 가장 최근인 파일 하나를 고르는 방식이었습니다. 별도로 세션 ID를 넘기지 않기 때문에, 같은 CLI 창을 두 개 이상 열어두면 지금 보고 있는 창이 다른 창의 상태를 보여줄 수 있습니다.

정리

HUD 같은 보조 도구를 CLI 에이전트에 붙일 때 반복적으로 나타나는 문제 패턴은 이렇습니다.

  1. 대상 CLI의 로그 포맷에 하드코딩으로 의존하면 버전이 바뀔 때 조용히 깨진다
  2. 패치 기반 설치는 대상이 계속 바뀌는 프로젝트라면 주기적으로 재검증이 필요하다
  3. 외부 프로세스 호출에 타임아웃을 걸 땐 실측값에 여유 마진을 두고 정해야 한다
  4. 멀티 세션 환경을 고려하지 않은 “최신 파일 찾기” 로직은 세션이 여러 개면 틀린 걸 보여준다

새 도구를 도입하기 전에 이 네 가지만 미리 체크해도, 설치는 됐는데 막상 상태가 안 맞는 상황을 많이 피할 수 있습니다.

Keep reading