blog · works with Claude Code

How to tell when Claude Code needs you without staring at the terminal

by Zuziverse · 5 min read

You give Claude Code a task. Then you either watch every line scroll by, or you tab away and come back twenty minutes later to find it was waiting on a yes the whole time. Neither feels great.

Here are the real ways to know when it needs you. Most of this is free and takes five minutes.

first, what "needs you" means

There are two different moments, and it helps to treat them differently:

it's asking. A permission prompt, or a question it can't answer alone. Nothing moves until you reply.
it's done. It finished its turn and is waiting for your next message. Nothing is blocked, but your time is.

The first one deserves a tap on the shoulder. The second one can usually wait until you look up.

1. turn on claude code's own notifications

Inside a session, run /config and find Notifications. In the version we checked, the choices are auto, terminal_bell, iterm2, iterm2_with_bell, kitty, ghostty and notifications_disabled.

terminal_bell rings your terminal's bell. Most terminals can turn a bell into something visible, like a dock bounce or a mark on the tab. Look in your terminal's settings under bell or notifications.
iterm2, kitty, ghostty use that terminal's own notification support, so you get a proper system notification.

One gotcha: on a Mac, check System Settings → Notifications and make sure your terminal app is allowed to show them. If it isn't, nothing appears.

2. hooks: run your own command

Claude Code hooks run a shell command at certain moments. Two are handy here:

Notification runs when Claude Code sends a notification, for example when it wants permission or is waiting for you.
Stop runs right before Claude finishes its response.

Hooks live in a settings file: ~/.claude/settings.json for you everywhere, or .claude/settings.json inside one project. This one shows a macOS notification whenever Claude Code wants you:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs you\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

If you already have a settings file, merge the "hooks" part in instead of pasting over everything. Run /hooks in a session to see what's set up.

A few things we learned the gentle way:

start with Notification, not Stop. Stop fires at the end of every single response, so it gets chatty fast. Add it later if you want a "done" ping on long tasks.
want a sound? Add afplay /System/Library/Sounds/Glass.aiff to the command. Pick a soft one. You'll hear it a lot.
a printed bell won't help. A hook's output isn't shown in your session when it succeeds, so a hook that only prints a bell character does nothing useful. Use the terminal_bell option from step 1 for that.
on Linux, notify-send does the same job as osascript, if your desktop has it.
hooks run as you, with your permissions. Only paste commands you understand.

3. let your terminal tabs do the talking

Start each session with a name: claude -n api-fix. The name shows in the prompt box, in the /resume picker and in the terminal title, so every tab says what's inside it. With the bell on, many terminals also mark the tab that rang, so you can see which agent wants you without opening each one.

If you live in tmux, its bell monitoring flags the window that rang in the status bar. Same idea, fewer tabs.

And if you start sessions in the background with claude --bg, claude agents lists them in one place.

4. a calm, glanceable pond

Notifications interrupt you. That's their job. But with three or four agents running, you often just want to look up once and know everyone's fine.

That's why we made Charmpond. Each Claude Code session or teammate is a little critter:

working: it sways and hops, and its tag shows the exact step. Its log changed in the last 90 seconds after a tool call or a prompt.
needs you: a lily pad floats up with a slow ripple. The agent replied and nothing has happened for under 20 minutes. No alarms.
napping: zz. Anything quieter than that.

One honest caveat: an agent inside one long command, like a test run or a build, also shows as napping until it writes to its log again. So a napping critter during npm test is normal.

It only reads Claude Code's session logs in ~/.claude/projects and serves one page on your own computer. No account, no network calls, no analytics.

It pairs well with the hook above. The hook says "come back". The pond says "how's everyone".

a setup that works

In /config, set Notifications to your terminal's option or terminal_bell.
Add the Notification hook so a permission prompt never waits for long.
Name every session with -n.
Keep something glanceable open, so "done" can wait until you look up.

Then go do something else. Running several agents? Read running many Claude Code agents at once next.