popup-permissions

🔔 claude-popup-permissions

Never miss a Claude Code permission prompt again.

You kick off a task in Claude Code, switch to your browser, and… nothing happens for ten minutes. You tab back and there it is — a permission prompt, patiently waiting, having blocked everything the whole time.

This tiny tool fixes that. When Claude Code needs permission, a native macOS dialog pops up front and center — over whatever app you're in — with a beep and one-tap buttons:

┌─────────────────────────────────────────────┐
│  ⚠️  Claude Code — my-app                   │
│                                             │
│  📁 𝗺𝘆-𝗮𝗽𝗽                                   │
│                                             │
│  Tool: Bash                                 │
│                                             │
│  git push origin main                       │
│                                             │
│        [ Deny ]   [ Skip ]   [ Approve ]    │
└─────────────────────────────────────────────┘

The project folder you're approving for is always visible — in the dialog title and in bold at the top of the body — so you never approve the wrong session.

Hit Return to approve. That's it. Back to whatever you were doing.

Why it's nice

• 🪶 Actually lightweight — one ~90-line script run by macOS's built-in osascript. No app, no daemon, no menu bar icon, no dependencies, nothing to keep running. A process spawns when a prompt appears and exits when you click.
• 🎯 Zero overhead — hooks Claude Code's PermissionRequest event, which fires only when a permission dialog would appear. Auto-approved tools are untouched.
• 🛟 Can't get stuck — Skip, Esc, or 120 seconds of silence hands the decision back to the normal terminal prompt. The popup is a fast path, never a trap.
• 🔍 Shows you what you're approving — the actual shell command, file path, or URL, plus which project it's for.
• ⌨️ Return = Approve, Esc = decide in terminal — muscle memory friendly.

Install

Requirements: macOS, Claude Code ≥ 2.1.

As a plugin (easiest)

Inside any Claude Code session:

/plugin marketplace add komalboyo/claude-popup-permissions
/plugin install popup-permissions@claude-popup-permissions

As a global hook (applies to every project, no plugin system)

Clone this repo anywhere, then add to ~/.claude/settings.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -l JavaScript \"/absolute/path/to/claude-popup-permissions/hooks/permission-popup.js\"",
            "timeout": 150
          }
        ]
      }
    ]
  }
}

New sessions pick it up automatically; already-running ones need /hooks opened once (or a restart).

First run: macOS may ask once to let your terminal display dialogs — click OK and you're set forever.

How it works

Claude Code's hooks system includes a PermissionRequest event that fires exactly when a permission prompt would appear, and whose stdout can answer it:

1. Claude Code pipes the hook a JSON payload — tool name, full tool input, project directory.
2. The script (hooks/permission-popup.js, plain JXA) summarizes it into one readable line and shows a native displayDialog, activated to the front of all apps.
3. Your click becomes the decision:

You press	Script prints	Result
Approve (or Return)	{"decision": {"behavior": "allow"}}	Tool runs instantly
Deny	{"decision": {"behavior": "deny"}}	Tool call blocked, Claude told why
Skip / Esc / timeout	nothing	Normal terminal prompt appears

Config

Environment variables (set them wherever you launch Claude Code):

Variable	Default	What it does
CLAUDE_POPUP_TIMEOUT	120	Seconds before the dialog gives up and falls back to the terminal
CLAUDE_POPUP_TEST_BUTTON	–	Approve | Deny | Skip — bypasses the dialog, for testing wiring

Try it without Claude Code:

echo '{"tool_name":"Bash","tool_input":{"command":"git push"},"cwd":"'$PWD'"}' \
  | osascript -l JavaScript hooks/permission-popup.js

Good to know

• Interactive sessions only — headless claude -p runs skip this hook by design.
• Approving in the popup approves that one tool call, exactly like pressing "yes" in the terminal. Your allow/deny rules in settings still apply first.
• Multiple sessions prompting at once? Each gets its own dialog.

License

MIT — do whatever you like with it.