Claude Code 작업 완료 알림: 토스트와 알림음

완료 토스트는 Claude Code 작업 완료 알림을 제공합니다. 시간이 걸린 턴이 끝나면 Done in 2m 14s라는 토스트가 뜨고 두 음으로 된 짧은 알림음이 울립니다. 오류로 끝난 턴이라면 대신 Stopped on an error after 2m 14s라고 표시됩니다. 짧은 턴, 중단된 턴, 서브에이전트 턴은 조용히 넘어가므로, 알림음이 들리면 "돌아오세요, 답변이 준비되었습니다"라는 뜻입니다.

긴 작업 중에 다른 창에서 일한다면 시스템 알림 옵션을 켜십시오. 같은 메시지가 macOS 알림 센터나 Linux의 notify-send 팝업으로도 표시됩니다. Claude Code 2.1.287 이상이 필요합니다.

녹화 영상에서는 기준 시간보다 오래 걸리는 작업을 Claude에게 보냅니다. 턴이 끝나면 화면 아래쪽에 턴의 소요 시간이 담긴 토스트가 나타납니다.

설치 블록의 방법 중 하나를 선택하십시오. macOS에서는 별도 설정 없이 소리가 나며, 시스템 알림은 직접 켜야 합니다.

이 모드에는 훅이 하나뿐입니다. hooks/register.ts의 코드는 다음과 같습니다.

on('turn.complete', async ($, e, next) => {
  const result = await next(e)
  if (!shouldNotify(e, minSeconds)) return result

  const text = toastText(e, includeAnswerPreview)
  $.ui.toast(text)

  if (sound) {
    $.audio.play({ asset: 'sounds/done.wav' }).catch(() => undefined)
  }

  if (systemNotification) {
    platform ??= $.process
      .run(['uname', '-s'], { timeoutMs: 5000 })
      .then(ran => (ran.exitCode === 0 ? parseUname(ran.stdout) : undefined))
      .catch(() => undefined)
    platform
      .then(found =>
        found === undefined ? undefined : $.process.run(notificationArgv(found, 'Claude Code', text), { timeoutMs: 10000 }),
      )
      .catch(() => undefined)
  }

  return result
})

turn.complete는 Claude가 턴을 마칠 때 발생합니다. 훅은 먼저 next(e)를 기다리므로 턴의 결과를 지연시키지 않습니다. hooks/format.ts의 shouldNotify는 서브에이전트 턴(agentId가 있는 턴), 중단된 턴, minSeconds보다 짧은 턴에 대해 false를 반환합니다. toastText는 소요 시간을 45s, 2m 14s, 1h 3m 형식으로 표시합니다.

알림음은 모드에 포함된 sounds/done.wav이며 $.audio.play로 재생됩니다. 모드 API에는 플랫폼 필드도 알림 호출도 없기 때문에, 시스템 알림이 켜져 있으면 모드가 uname -s를 한 번 실행해 결과를 캐시합니다. 그런 다음 macOS에서는 osascript -e 'display notification …'를, Linux에서는 notify-send를 실행합니다. 인수는 셸을 거치지 않고 argv 배열로 전달되므로 Claude 답변에 따옴표가 있어도 명령 밖으로 빠져나갈 수 없습니다. 소리와 알림은 실행만 하고 결과를 기다리지 않으며, 오류는 무시됩니다.

다음 옵션은 /config에서 변경할 수 있습니다. 원하는 소리를 쓰려면 모드 폴더의 sounds/done.wav를 교체하거나 훅의 asset 경로를 바꾸십시오. 토스트 문구는 hooks/format.ts의 toastText에서 만들어지고, 알림 제목 'Claude Code'는 notificationArgv의 두 번째 인수입니다.

UI 변경은 토스트에 해당합니다. 소리 재생은 알림음에 해당합니다. 명령어 실행은 코드에 $.process.run이 있어서 표시되지만, systemNotification을 켰을 때만 사용됩니다. 그때는 uname -s를 한 번 실행한 뒤 고정된 인수로 osascript 또는 notify-send를 실행합니다. 기본 설정에서는 어떤 프로세스도 시작되지 않습니다.

이 모드는 도구 호출을 가로채지 않으며, 프롬프트를 읽거나 파일을 건드리거나 네트워크를 사용하지 않습니다. 끄려면 /plugin disable cm-done-toast를 실행하고, 모든 모드를 끈 채 세션을 시작하려면 claude --safe-mode를 사용하십시오.

macOS 터미널에서 Claude Code 2.1.291로 테스트했습니다. 턴이 끝나도 아무 일도 일어나지 않는다면 다음을 확인하십시오.

• claude --version이 2.1.287 이상인지, 그리고 /plugin에서 모드가 활성화되어 있는지 확인하십시오.
• 셸에서 설치했다면 /reload-plugins를 실행하십시오.
• 턴이 minSeconds보다 짧았을 수 있습니다.
• macOS 이외의 환경에서 소리가 나지 않는 것은 정상입니다.
• macOS에서 시스템 알림이 전혀 표시되지 않는다면 시스템 설정에서 터미널 앱의 알림을 허용하십시오.
• Linux에서 시스템 알림을 쓰려면 libnotify(notify-send)를 설치하십시오.