리눅스용 Claude Code 데스크톱 알림 브릿지 'Herald' 개발 (D-Bus 기반)

실용적 조언

KDE 사용자는 Konsole 설정에서 EnableSecuritySensitiveDBusAPI 옵션을 활성화하여 화면 전환 없는 응답 기능을 사용할 수 있다.
Wayland 환경에서 ydotool을 사용하려면 추가적인 권한 설정이 필요할 수 있으므로 공식 README를 참조해야 한다.

섹션별 상세

리눅스 환경에서 단일 모니터를 사용하는 사용자들이 Claude Code 실행 중 브라우저를 이용할 때 작업 상태를 파악하기 어려운 문제가 제기됐다. Claude가 권한 승인을 기다리거나 작업을 완료했는지 알 수 없어 불필요한 화면 전환(Alt-Tab)이 반복되는 불편함이 존재한다. 이를 해결하기 위해 데스크톱 알림을 통해 상태를 실시간으로 전달하는 브릿지 도구가 개발됐다.

Herald는 Claude Code의 이벤트 시스템에 훅(Hook)을 걸어 작동하는 구조를 가진다. Claude가 권한을 요청하거나 작업을 멈추면 Herald가 표준 입력(stdin)을 통해 JSON 페이로드를 수신하고 메시지를 추출한다. 추출된 정보는 D-Bus를 통해 freedesktop 표준을 따르는 데스크톱 알림으로 전송된다.

json

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "herald hook", "timeout": 0 }] }
    ],
    "PermissionRequest": [
      { "hooks": [{ "type": "command", "command": "herald hook", "timeout": 0 }] }
    ]
  }
}

Claude Code의 설정 파일(~/.claude/settings.json)에 Herald 훅을 등록하는 방법

알림 내 버튼 클릭을 통한 응답 처리는 터미널 종류에 따라 두 가지 방식으로 구현됐다. KDE Konsole의 경우 D-Bus PTY 액세스를 통해 터미널에 직접 입력을 전달하며, 그 외 터미널에서는 KWin 창 포커스 이동 후 ydotool을 이용해 키 입력을 주입한다. Konsole 환경에서는 화면 전환 없이 브라우저에서 즉시 'Yes/No' 선택이 가능하다.

Herald를 통해 생성된 리눅스 데스크톱 알림창 스크린샷 — ScreenshotClaude Code가 파일 삭제(rm) 권한을 요청할 때 나타나는 알림 UI를 보여준다. 알림 내에 'Yes', 'No' 등의 버튼이 포함되어 있어 사용자가 터미널로 이동하지 않고도 즉시 의사결정을 내릴 수 있음을 증명한다.

보안 측면에서 Claude Code가 이미 사용자 권한으로 임의 쉘 명령을 실행할 수 있다는 점을 전제로 설계됐다. Herald는 키 입력 주입 기능을 추가하므로 오염된 페이로드에 의한 예기치 않은 입력 위험이 존재할 수 있다. 개발자는 이를 방지하기 위해 훅 경로 주입을 숫자로 제한하고 알림 내용을 정화(Sanitize)하는 방어 기제를 적용했다.

용어 해설

디버스(D-Bus): — 리눅스 데스크톱 환경에서 여러 프로세스 간에 통신(IPC)을 가능하게 하는 메시지 버스 시스템이다. 애플리케이션이 시스템 알림을 보내거나 다른 프로그램의 기능을 제어할 때 표준 인터페이스로 사용된다.
가상 터미널(PTY): — Pseudo-terminal의 약자로, 실제 물리적 단말기 없이 소프트웨어적으로 터미널 입출력을 에뮬레이션하는 인터페이스이다. 터미널 에뮬레이터가 쉘과 통신하거나 외부 도구가 터미널 세션에 입력을 주입할 때 사용된다.
훅(Hook): — 소프트웨어의 특정 이벤트가 발생하기 전후에 실행되는 사용자 정의 코드를 의미한다. Claude Code는 작업 중단이나 권한 요청 시점에 외부 명령어를 실행할 수 있는 훅 시스템을 통해 기능을 확장한다.
웨이랜드(Wayland): — 리눅스에서 윈도우 서버와 클라이언트 간의 통신을 담당하는 최신 디스플레이 서버 프로토콜이다. 기존 X11을 대체하며 보안과 성능이 개선되었으나, 창 포커스 제어나 키 입력 주입 방식이 더 엄격하게 제한된다.

코드 예제

bash

cargo install --git https://github.com/Niek-Kamer/herald.git

Rust 패키지 매니저인 cargo를 이용한 Herald 설치 명령어

언급된 도구

Herald추천링크

Claude Code와 리눅스 D-Bus 알림 간의 브릿지 도구

ydotool중립

Wayland 환경에서 키보드 입력을 시뮬레이션하는 도구

Konsole추천

D-Bus를 통한 PTY 액세스를 지원하는 KDE 터미널 에뮬레이터

언급된 리소스

GitHubHerald GitHub Repository