Guide

Know the moment Claude Code needs your permission.

Claude Code pauses whenever a tool call needs your approval. If the terminal is behind another window, it just waits. Here is how to see that moment the second it happens.

Why Claude Code sits waiting

Claude Code asks before it runs a command, edits a file outside the allowed list or uses a tool you haven't approved. Until you answer, the session is paused. That's the right default, but it costs time when you are in another window: you come back ten minutes later to find it stopped on the first prompt.

Claude Code tells the outside world about this moment through a hook. Hooks are commands that Claude Code runs on events in a session, configured in ~/.claude/settings.json. The one you want is Notification: it fires when Claude Code needs your permission to use a tool, and when a prompt has been waiting for input for a while.

Option 1: a Notification hook of your own

Add a Notification entry under hooks in ~/.claude/settings.json. The command receives a JSON object on stdin with the session id, the folder and a message such as "Claude needs your permission to use Bash".

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "node ~/notify.js" }
        ]
      }
    ]
  }
}

Your notify.js can do anything: play a sound, show a system notification, send a message to your phone. A minimal version that logs the message:

let raw = '';
process.stdin.on('data', c => (raw += c));
process.stdin.on('end', () => {
  const event = JSON.parse(raw || '{}');
  console.error(`[${event.session_id}] ${event.message}`);
  process.exit(0); // never fail: a hook should not get in Claude's way
});

This works well for one session. With three or four sessions open it gets noisy: every alert looks the same, and you still have to find the right terminal.

Option 2: a sticker that says "needs you"

Agent Peeps uses the same hook. npx agentpeeps init adds a Notification hook (plus the session, tool and stop events) to your Claude Code settings, keeping a backup of the file. Every Claude Code session then gets a small sticker in the corner of your screen, and when one needs your permission:

  • its sticker switches to the needs you state and shakes,
  • a speech bubble opens by itself with the message and the folder,
  • the other sessions keep showing what they are doing, so you know which one to answer.

The hook appends one line to ~/.agent-presence/events.jsonl and exits. It runs asynchronously and always exits 0, so it can never block or fail a session.

$ npx agentpeeps init
$ npx agentpeeps overlay

Prefer the terminal? npx agentpeeps watch draws a small pixel sticker per session that shakes when it needs you.

Codex, Copilot and Antigravity

The same problem exists with every agent. Codex has a PermissionRequest event and Copilot a notification event; Agent Peeps hooks both, so one overlay covers all of your agents. See how the hooks compare.

Try it in one command

Agent Peeps is free and open source (MIT). It only reads hook events on your machine: no account, no server, no network.

$ npx agentpeeps init
$ npx agentpeeps overlay

See the stickers in your browser · Read the docs · Star it on GitHub