Nudge

You start a task in Claude Code, switch to the browser "just for a second", and ten minutes later Claude has been sitting on a permission prompt the whole time. Nudge fixes that.

Claude Code hook ──curl──▶ relay on 127.0.0.1 ──WebSocket──▶ extension ──▶ Nudge on your active tab

Install

npx nudge-mascot setup

That copies the relay and hooks into ~/.claude-nudge/, adds the hooks to ~/.claude/settings.json (backup saved next to it; Codex, Gemini CLI, Grok Build, Cursor and OpenCode too when found, see Other agents), including the two approval hooks that let you reply from the bubble, starts the relay and keeps it running at login (launchd on macOS, systemd user service on Linux), and prints where to load the extension and a connection code (see Privacy). Running it again is safe: hooks already present are left alone, the backup keeps your settings from before the first run, and the code stays the same.

Then add the extension from the Chrome Web Store (working on Nudge itself? load ~/.claude-nudge/extension unpacked from chrome://extensions instead). Click the Nudge toolbar icon, and paste the connection code into Connect (the welcome page that opens on install has the same field; npx nudge-mascot status prints the code again). Restart any running Claude Code session and run:

npx nudge-mascot test            # a question
npx nudge-mascot test done       # done / permission / approve / questions / resolved
npx nudge-mascot test jump       # a nudge whose "Jump to terminal" switches back to this terminal
npx nudge-mascot test multi      # three sessions waiting at once (the session switcher)
npx nudge-mascot status          # relay health, hook check (approval hooks included), the connection code
npx nudge-mascot uninstall       # removes everything it installed, approval hooks and stats included

Requires Node 18+ and Chrome 116+.

Other agents

Nudge also waits on OpenAI's Codex CLI, Google's Gemini CLI, xAI's Grok Build, Cursor and OpenCode. setup with no flags installs hooks for every agent it finds (~/.claude; ~/.codex or a codex binary; ~/.gemini/settings.json or a gemini binary, since Antigravity and Gemini Code Assist create ~/.gemini too; ~/.grok/config.toml or a grok binary, since the community grok-cli uses ~/.grok too; ~/.cursor or a cursor-agent / cursor binary; ~/.config/opencode or an opencode binary) and prints what it did. Pick agents explicitly with --agent:

npx nudge-mascot setup --agent codex          # hooks in ~/.codex/hooks.json
npx nudge-mascot setup --agent gemini         # hooks in ~/.gemini/settings.json
npx nudge-mascot setup --agent grok           # hooks in their own file, ~/.grok/hooks/nudge.json
npx nudge-mascot setup --agent cursor         # hooks in ~/.cursor/hooks.json
npx nudge-mascot setup --agent opencode       # a plugin, ~/.config/opencode/plugins/nudge.js
npx nudge-mascot setup --agent claude-code,codex
npx nudge-mascot test permission --agent codex  # a fake Codex nudge
npx nudge-mascot status                       # hook status per agent
npx nudge-mascot uninstall                    # removes the hooks from every agent's config

Every agent runs the same ~/.claude-nudge/nudge-hook.sh; the others pass their name (nudge-hook.sh codex), which the hook sends as POST /hook?agent=codex. OpenCode has no shell hooks, so its plugin pipes each relevant event into nudge-hook.sh opencode itself. In every case the relay's adapter for that agent (relay/adapters/) turns the payload into the same event. The first write backs up the config next to it (.bak-claude-nudge; later runs keep that backup), merges, and is safe to re-run. A config that isn't plain JSON (comments, say) is left alone with a warning. Bubbles from other agents name the agent ("Codex is done", "Gemini needs permission") and show an agent badge next to the project.

This is the beginning of the README. Read the rest at the original. Read the full README ↗