0012. Claude 훅은 앱이 켜질 때 전역으로 알아서 설치한다

• 상태: 채택
• 날짜: 2026-09-28
• 관련: src/main/ipc/claude.ts, src/main/claude/claudeHookPolicy.ts, src/main/claude/claudeHooks.ts, 0002-color-roles.md, stablyai/orca

맥락

Claude 상태 훅과 statusLine은 상태 바의 칩을 눌러야 ~/.claude/settings.json에 설치됐다. 칩을 누르기 전까지는 탭의 작업 상태와 사용량이 나오지 않아, 앱을 처음 쓰는 사람은 기능이 없는 줄 알게 된다. 또 칩이 상태 바의 자리를 차지했다.

Orca는 앱이 켜질 때 훅을 알아서 설치하고, 끄는 스위치는 설정 화면에 둔다.

결정

설정의 훅 스위치(기본값 켜짐)가 켜져 있고 Claude CLI를 찾을 수 있으면, 앱이 켜질 때 훅과 statusLine을 설치한다. 상태 바의 칩은 지우고, 스위치와 설치 상태는 설정 화면의 “일반” 탭으로 옮긴다.

• 이미 설치돼 있으면 설정 파일을 다시 쓰지 않는다. 일부만 설치돼 있으면 다시 설치해 고친다.
• 앱이 켜질 때는 스위치가 꺼져 있어도 이미 있는 훅을 지우지 않는다. 훅을 지우는 것은 사용자가 스위치를 끌 때뿐이다.
• 사용자 자신의 statusLine은 덮어쓰지 않는다.
• Belloga statusLine을 한 번 심은 뒤 사용자가 직접 지웠으면 다시 심지 않는다. 심은 적이 있는지는 앱 설정 파일(claude-hooks.json)의 표식으로 가른다. 스위치를 끄면 표식을 되돌려, 다시 켤 때 새로 심는다.
• plan 훅은 이 자동 설치의 대상이 아니다.

근거 / 검토한 대안

• 지금처럼 칩을 눌러 설치한다. 사용자가 누르지 않으면 전역 설정 파일이 바뀌지 않는다. 그러나 기능을 발견하기 어렵고 상태 바 자리를 차지한다.
• 처음 켤 때 설치할지 묻는다. 동의를 받는다는 장점이 있지만, Orca 동작을 따른다는 목표와 어긋나고 안내성 UI를 하나 더 만들어야 한다.
• 채택안: Orca처럼 알아서 설치하고 설정 화면에서 끌 수 있게 한다. 시작할 때 지우지 않는 것은, 다른 도구나 사용자가 둔 설정을 앱이 켜질 때마다 건드리지 않기 위해서다. 지운 statusLine을 다시 심지 않는 것은 사용자의 의사를 앱이 되돌리지 않기 위해서다.

결과

• 사용자가 누르지 않아도 앱이 켜질 때 ~/.claude/settings.json이 바뀐다.
• 상태 훅 스크립트는 BELLOGA_PANE_ID가 없으면 아무것도 보내지 않아 Belloga 밖의 세션에는 영향이 없다. 그러나 자기 statusLine이 없는 사용자는 Belloga 밖의 Claude 화면에서도 Belloga statusLine을 본다.
• Claude CLI를 찾지 못하면 설치하지 않는다. Finder로 켠 macOS 앱은 PATH가 짧아서, macOS와 Linux는 사용자의 로그인 셸로 찾는다.
• 설치 상태를 보이는 유채색 점(ADR 0002의 예외)은 상태 바의 칩에서 설정 화면으로 옮겨졌다.