>>> claude code hooks, put to work Claude Code Hooks. Know When Claude Needs You

// The events //

Seven Moments Claude Tells You About

Each hook gets the event as JSON on stdin (session id, transcript path, working folder, plus fields for that event) and runs with the pane's environment, so $TMUX_PANE tells you which tmux pane Claude is in. These are the ones that matter for knowing what Claude is doing:

// A Claude Code hooks example · 5 minutes //

Is Claude Done Yet? In 25 Lines

A Claude Code hooks example you can copy: a small script that turns hook events into one word per tmux pane, the raw material for Claude Code notifications: working, needs-you, done or idle. It already handles the traps below.

1. 01

   Save the script

   Put it in ~/bin/claude-state.sh. It reads the event from stdin and writes the state as a tmux pane option, @claude_state.

   #!/bin/sh
   # claude-state.sh <Event>: what is Claude doing in this tmux pane?
   [ -n "$TMUX_PANE" ] || exit 0
   event=$1
   json=$(tr -d ' \t\r\n')     # the event payload, whitespace removed
   set_state() { tmux set -p -t "$TMUX_PANE" @claude_state "$1"; exit 0; }
   case $event in
     UserPromptSubmit|PreToolUse) set_state working ;;
     Stop) case $json in
             *'"background_tasks":['*'"status":"running"'*) set_state working ;;
             *) set_state done ;;
           esac ;;
     Notification) case $json in
             *'"notification_type":"permission_prompt"'*) set_state needs-you ;;
             *'"notification_type":"elicitation_dialog"'*) set_state needs-you ;;
             *'"notification_type":"idle_prompt"'*) set_state done ;;
           esac ;;
     SessionStart) case $json in *'"source":"compact"'*) exit 0 ;; esac
           set_state idle ;;
     SessionEnd) tmux set -p -u -t "$TMUX_PANE" @claude_state ;;
   esac
   exit 0

   you@server: ~

   $ chmod +x ~/bin/claude-state.sh

   (Claude asks for permission…)

   [agents] 0:claude*claude: needs-you

2. 02

   Register the hooks

   Add this to ~/.claude/settings.json (merge it with anything already there). Every event runs the same script with its own name. Restart Claude Code, then check with /hooks.

   {
     "hooks": {
       "SessionStart":     [{ "hooks": [{ "type": "command", "command": "sh ~/bin/claude-state.sh SessionStart", "timeout": 5 }] }],
       "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "sh ~/bin/claude-state.sh UserPromptSubmit", "timeout": 5 }] }],
       "PreToolUse":       [{ "hooks": [{ "type": "command", "command": "sh ~/bin/claude-state.sh PreToolUse", "timeout": 5 }] }],
       "Notification":     [{ "hooks": [{ "type": "command", "command": "sh ~/bin/claude-state.sh Notification", "timeout": 5 }] }],
       "Stop":             [{ "hooks": [{ "type": "command", "command": "sh ~/bin/claude-state.sh Stop", "timeout": 5 }] }],
       "SessionEnd":       [{ "hooks": [{ "type": "command", "command": "sh ~/bin/claude-state.sh SessionEnd", "timeout": 5 }] }]
     }
   }

3. 03

   Show it in the status bar

   Add one line to ~/.tmux.conf. It shows the state of the pane you're looking at. Which is the catch: you have to be looking.

   set -g status-right "claude: #{@claude_state} "

// The traps //

Four Ways Your Status Script Lies

We learned these building agent status into RETRO TMUX and testing it against Claude Code 2.1. Most hook examples online fall into at least two, which is why so many Claude Code notifications arrive too early, too late, or for the wrong thing.

// Or skip all of this //

One Switch. Status On Your Phone

A status bar only helps if you're at the desk, looking at the right pane. RETRO TMUX installs these hooks for you with one switch, for Claude Code, Codex and Hermes, and shows every agent's state on your iPhone and iPad, across every session, without attaching.

> Codex hooks, and its review screen → · Claude Code on your iPhone →