Gemini CLI 알림: 작업이 끝나거나 내가 필요할 때 소리나 알림 받기
다른 것을 읽는 동안 Gemini CLI는 "Waiting for confirmation"에서 태연하게 멈춰 있습니다. 사실 Gemini CLI는 이를 알려 줄 수 있습니다. 다만 이 설정이 기본적으로 꺼져 있고, Windows에서는 문서에 적힌 것과 다르게 동작합니다.
핵심 요약
~/.gemini/settings.json에서 "general": { "enableNotifications": true }를 설정하세요(또는 /settings → General → Enable Notifications). 그러면 Gemini CLI가 승인이 필요할 때와 세션이 완료되었을 때 알려 줍니다. Windows Terminal과 VS Code 터미널에서는 자동 모드가 터미널 벨만 울리므로, 실제 데스크톱 알림을 원한다면 notificationMethod: "osc9"를 시도해 보세요. 직접 고른 소리를 원한다면 Notification 훅(도구 권한 프롬프트에서 발생)과 AfterAgent 훅(턴이 끝날 때 발생)을 추가하세요.
시작하기 전에: 어떤 Gemini CLI를 쓰고 있는지 확인
Gemini CLI 문서의 배너에 따르면, 무료 등급 및 Google One 사용자의 경우 2026년 6월 18일에 Gemini CLI가 Antigravity CLI로 대체되었습니다. 아래 내용은 모두 Gemini CLI 자체(gemini 명령과 ~/.gemini/settings.json)에 관한 것입니다. Antigravity로 옮겼다면 설정은 다른 곳에 있습니다.
사람들은 이 기능을 오래전부터 원해 왔습니다. Gemini CLI 저장소의 오디오 알림 기능 요청(#4310)은 추천 74개를 받았고, 한 메인테이너는 "to reflect how many people care"(얼마나 많은 사람이 관심을 갖는지 반영하기 위해) 우선순위를 높였습니다. 이후의 한 토론(#13313)은 이렇게 간단히 표현했습니다. "I can never tell when it is done."(언제 끝났는지 도무지 알 수가 없어요.)
기본 알림 켜기
Gemini CLI에는 실험적 알림 기능이 있으며, 기본적으로 비활성화되어 있습니다. CLI에서 /settings → General → Enable Notifications로 켜거나 설정 파일에서 켜세요.
켜고 나면 Gemini CLI는 두 가지 이벤트에 대해 알려 줍니다.
- 조치 필요: 모델이 입력이나 도구 승인을 기다리고 있습니다.
- 세션 완료: 세션이 성공적으로 끝났습니다.
알림 제목은 "Gemini CLI needs your attention"과 "Gemini CLI session complete"입니다. Gemini CLI는 자체적으로 소리를 내지 않습니다. 터미널에 이스케이프 시퀀스를 보내고, 무슨 일이 일어날지는 터미널이 결정합니다.
알림이 전달되는 방식(그리고 Windows가 다른 이유)
두 번째 설정인 general.notificationMethod가 알림을 보내는 방식을 정합니다. 값은 auto(기본값), osc9, osc777, bell입니다.
알림 페이지에는 CLI가 OSC 9 이스케이프 시퀀스를 사용하고 터미널 벨로 대체한다고 적혀 있습니다. 소스 코드는 더 구체적입니다. auto 모드에서는(packages/cli/src/utils/terminalNotifications.ts) 다음과 같습니다.
| 터미널 | auto가 보내는 것 |
|---|---|
| iTerm2 | OSC 9(데스크톱 알림) |
| Windows Terminal, VS Code 터미널, Alacritty, Apple Terminal | 벨(BEL)만 |
| 그 밖의 모든 터미널 | OSC 777 |
따라서 Windows Terminal에서는 토스트 알림이 아니라 벨이 울립니다. 벨이 무엇을 할지는 Windows Terminal 설정에 달려 있습니다. bellStyle은 all, audible, window, taskbar, none을 받으며 기본값은 audible입니다. all로 설정하면 Windows Terminal은 소리를 내고 작업 표시줄 아이콘을 깜박이며, bellSound로 소리를 고를 수 있습니다.
벨 대신 실제 데스크톱 알림을 시도해 보고 싶다면 방식을 강제로 지정하세요.
특정 터미널이 OSC 9를 Windows 알림으로 바꿔 주는지는 터미널 버전에 따라 다릅니다. 아무것도 나타나지 않으면 auto나 bell로 돌아가 bellStyle: "all"을 사용하세요. 벨은 Gemini CLI 자체 코드가 Windows Terminal을 위해 선택한 방식입니다.
tmux나 screen 안에서는 Gemini CLI가 시퀀스를 패스스루 이스케이프로 감싸므로 바깥 터미널까지 전달됩니다.
훅으로 나만의 소리 내기
특정 소리, 팝업, 휴대폰 메시지를 원한다면 훅을 사용하세요. Gemini CLI는 정해진 지점에서 훅 명령을 실행하고 끝날 때까지 기다립니다. 여기서 중요한 이벤트는 두 가지입니다.
Notification은 CLI가 시스템 알림을 낼 때 발생합니다. 현재 유일한 유형은ToolPermission(도구가 승인을 기다리는 중)입니다. 이 훅은 아무것도 승인하거나 차단할 수 없으며, 참고용입니다.AfterAgent는 턴마다 한 번, 모델의 최종 응답 이후에 발생합니다. Gemini의 모범 사례 페이지는 "you only need to check the final completion"(최종 완료만 확인하면 되는) 경우에 이를 권장합니다.
훅은 기본적으로 켜져 있습니다(hooksConfig.enabled). 훅은 stdout에 정확히 하나의 JSON 객체만 출력해야 하며 그 외에는 아무것도 출력하면 안 됩니다(할 말이 없으면 {}로 충분합니다). 종료 코드 0은 성공, 2는 차단(차단 가능한 이벤트에서만 의미 있음)이며, 그 밖의 코드는 경고로 처리되고 CLI는 계속 진행합니다. 기본 타임아웃은 60초입니다(timeout의 단위는 밀리초).
Windows(PowerShell)
Windows에서 Gemini CLI는 pwsh -NoProfile -Command로 훅 명령을 실행하며, PowerShell 7이 설치되어 있지 않으면 powershell.exe를 사용합니다. 다음 스크립트를 %USERPROFILE%\.gemini\hooks\ding.ps1로 저장하세요.
그런 다음 두 이벤트 모두 이 스크립트를 가리키게 합니다.
-ExecutionPolicy Bypass는 가장 흔한 실패, 즉 PowerShell이 스크립트 실행을 거부하는 문제를 피하게 해 줍니다. Gemini 문서는 영구적인 해결책으로 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser를 제안합니다.
macOS 및 Linux
다른 시스템에서 훅은 bash -c로 실행됩니다. 한 줄짜리 스크립트로 충분합니다.
실행 권한을 주고(chmod +x ~/.gemini/hooks/ding.sh) 같은 두 이벤트에서 "command": "$HOME/.gemini/hooks/ding.sh"를 사용하세요.
"승인 필요"와 "완료"에 서로 다른 소리를 원하나요? 스크립트를 두 개 만드세요. 훅은 stdin에서 이벤트를 읽을 수도 있습니다. Notification 입력에는 notification_type, message, details가 담겨 있으므로 팝업에 실제 요청 내용을 보여 줄 수 있습니다.
훅이 실행되지 않는 이유
/hooks panel을 확인하세요. Gemini CLI가 로드한 모든 훅이 나열됩니다. 훅이 비활성화되어 있다면/hooks enable-all로 다시 켤 수 있습니다.- 신뢰하지 않는 폴더. 신뢰하지 않는 폴더에서 Gemini CLI는 프로젝트의
.gemini/settings.json을 무시하므로 프로젝트 훅이 로드되지 않습니다. 알림 훅은 사용자 설정(~/.gemini/settings.json)에 넣어 어디서나 작동하게 하세요. - 변경된 훅은 새 훅으로 취급됩니다. Gemini CLI는 프로젝트 훅의 지문을 저장합니다. 훅의 이름이나 명령이 바뀌면 신뢰되지 않은 새 훅으로 처리됩니다.
- stdout에 다른 내용이 있음. JSON 앞에 붙은 불필요한
echo나 PowerShell 경고는 파싱을 망가뜨립니다. 로그는 stderr로 보내세요. - Matcher.
Notification과AfterAgent에서는"*"(또는 빈 문자열)를 사용해 모든 항목과 일치시키세요. 수명 주기 이벤트는 정확한 문자열 matcher를, 도구 이벤트는 정규식을 사용합니다.
아니면 질문 횟수 줄이기
알림은 더 빨리 응답하는 데 도움이 되지만, Gemini CLI가 사용자를 필요로 하는 횟수 자체를 줄일 수도 있습니다. general.defaultApprovalMode는 default(묻기), auto_edit(편집은 승인, 나머지는 묻기), plan(읽기 전용) 중 하나입니다. Shift+Tab으로 순환합니다. tools.allowed에는 확인 대화 상자를 건너뛰는 도구를 나열하고(예: run_shell_command(git)), tools.confirmationRequired에는 항상 물어야 하는 도구를 나열합니다.
YOLO 모드(--yolo 또는 Ctrl+Y)는 모든 것을 승인하며 기본적으로 샌드박스를 켭니다. 명령줄에서만 활성화할 수 있으며, 컴퓨터를 다른 사람과 함께 쓴다면 security.disableYoloMode로 영구히 끌 수 있습니다.
Pet Island의 역할
비프음은 무언가 일어났다는 것만 알려 줄 뿐, 어느 터미널인지, Gemini가 무엇을 실행하려는지는 알려 주지 않습니다. Pet Island는 Gemini CLI를 다른 에이전트와 함께 화면 상단의 작은 아일랜드에 띄웁니다. 작업 중인지, 확인을 기다리는지, 완료되었는지 볼 수 있고, 클릭 한 번으로 해당 터미널로 이동합니다.
Gemini CLI에서는 확인 자체가 여전히 Gemini 안에서 이루어집니다. Pet Island는 요청을 보여 주고 그곳으로 데려다주지만, Gemini의 도구를 대신 승인하지는 않습니다. (반면 Claude Code와 Codex의 요청은 아일랜드에서 바로 응답할 수 있습니다.)
자주 묻는 질문
Gemini CLI에 알림 기능이 있나요?
네. 다만 실험적 기능이며 기본적으로 꺼져 있습니다. ~/.gemini/settings.json에서 general.enableNotifications를 true로 설정하거나 /settings → General → Enable Notifications를 사용하세요.
Gemini CLI가 Windows에서 비프음만 내는 이유는 무엇인가요?
auto 모드에서 Gemini CLI 코드는 Windows Terminal과 VS Code 터미널에 터미널 벨만 보냅니다. Windows Terminal의 bellStyle 설정에 따라 그 벨이 소리를 낼지, 작업 표시줄을 깜박일지, 둘 다 할지가 정해집니다.
Gemini CLI 훅으로 도구를 자동 승인할 수 있나요?
Notification 훅으로는 안 됩니다. 문서에 따르면 이 훅은 알림을 차단하거나 권한을 부여할 수 없습니다. 대신 tools.allowed나 정책 엔진으로 도구를 미리 승인하세요.
Gemini CLI가 끝나면 어떤 훅이 발생하나요?
AfterAgent입니다. 턴마다 한 번, 모델의 최종 응답 이후에 발생합니다.
모든 프로젝트에서 작동하게 하려면 훅을 어디에 두어야 하나요?
사용자 설정인 ~/.gemini/settings.json에 두세요. 신뢰하지 않는 폴더에서는 프로젝트 설정이 무시됩니다.
출처
이 페이지의 모든 설정과 동작은 2026년 10월 26일에 아래 페이지와 대조해 확인했습니다. 에이전트는 빠르게 바뀌므로, 내용이 더 이상 맞지 않으면 공식 페이지를 따르세요.
- Gemini CLI 문서: Notifications(알림, 실험적)
- Gemini CLI 문서: Hooks(훅)
- Gemini CLI 문서: Hooks reference(훅 레퍼런스)
- Gemini CLI 문서: Writing hooks(훅 작성, PowerShell 예시)
- Gemini CLI 문서: Configuration reference(구성 레퍼런스)
- Gemini CLI 문서: Trusted folders(신뢰할 수 있는 폴더)
- Gemini CLI 소스: terminalNotifications.ts
- Gemini CLI 이슈 #4310: 오디오 알림
- Gemini CLI 토론 #13313: Gemini가 끝나면 소리 내기
- Microsoft Learn: Windows Terminal 프로필 설정(bellStyle, bellSound)
- Microsoft Learn: Console.Beep