Nudge
A Chrome extension for coding agents
Your agent is waiting on you. Nudge makes sure you notice.
You start a task, tab over to the browser for a second, and come back ten minutes later to find Claude (or Codex, or Grok) sitting on a question. Nudge puts a small pixel mascot on whatever tab you're reading, with the question in a bubble. Ignore it and it gets annoyed.
That's Nudge in the corner. This page just pretended your agent asked you something. Keep reading and see what happens.
Free and open source. Nothing leaves your machine. Needs Node 18 and Chrome 116 or newer.
The longer you ignore it, the harder it tries
Questions and permissions block Claude until you answer, so those escalate. Pick a level to see it live. On this page the clock is sped up; the real timings are shown.
"Done" nudges never escalate; they auto-dismiss after 20 seconds. Pick Gentle (levels 1 and 2), Full Chaos (adds the alarm), or Off. From level 1 there's a Snooze button.
What shows up, and when
- QuestionClaude asked you something. The question and its option labels are in the bubble, so you can tell whether it's worth tabbing back. Stays until you act.
- PermissionClaude wants to run a tool or command. The permission message is in the bubble. Stays until you act.
- DoneClaude finished. Its last message is in the bubble, expandable. Goes away on its own.
- IdleClaude has been waiting a minute with nothing to do. Off by default.
Nudge follows you: switch tabs or windows and it reappears there with the same countdown. Dismiss it once and it's gone everywhere. Answer in the terminal and it's gone too.
Works with six coding agents
Every agent runs the same tiny hook. The relay picks an adapter for that agent and turns its event into the one shape the bubble understands, so badges, Jump to terminal, the session switcher and the waiting stats work the same everywhere. setup with no flags installs hooks for every agent it finds; pick one below to install just that.
Claude Code Verified in daily use
The original. The only agent you can answer from the bubble or your phone.
npx nudge-mascot setup --agent claude-code
- Hooks go in
~/.claude/settings.json, backed up first, plus the approval hooks that let you reply from the bubble- Nudges
- questionpermissiondoneidle
- Answer from
- The bubble (Allow / Deny, pick an option), your phone once paired, or the terminal
OpenAI Codex CLI Built from the docs
Detected from ~/.codex or a codex binary.
npx nudge-mascot setup --agent codex
- Hooks go in
~/.codex/hooks.json:PermissionRequest,PostToolUse,UserPromptSubmit,Stop- Nudges
- permissiondonequestion (unverified)no idle event
- Answer from
- The terminal
Codex only runs hooks you trust: after setup, type /hooks in Codex and trust the Nudge entries.
Google Gemini CLI Built from the docs
Detected from ~/.gemini/settings.json or a gemini binary (Antigravity creates ~/.gemini too, so the folder alone isn't enough).
npx nudge-mascot setup --agent gemini
- Hooks go in
~/.gemini/settings.json:Notification,AfterAgent,BeforeAgent,AfterTool- Nudges
- permissiondoneno question or idle hook
- Answer from
- The terminal
Some Gemini CLI versions (0.45 to 0.55.1) never fire AfterAgent, so "done" may not arrive there.
xAI Grok Build Built from the source
Detected from ~/.grok/config.toml or a grok binary.
npx nudge-mascot setup --agent grok
- Hooks go in
- Their own file,
~/.grok/hooks/nudge.json(user hook files are always trusted; uninstall deletes it) - Nudges
- permissionquestiondoneidle
- Answer from
- The terminal
Grok also runs the hooks in ~/.claude/settings.json. Nudge spots those copies and drops them, so a Grok turn never shows up as "Claude is done".
Cursor Built from the source
The editor's agent and the cursor-agent CLI. Detected from ~/.cursor or a cursor-agent / cursor binary.
npx nudge-mascot setup --agent cursor
- Hooks go in
~/.cursor/hooks.json(flatversion: 1entries):stop,afterAgentResponse,beforeSubmitPrompt- Nudges
- doneno approval event
- Answer from
- Cursor itself
Cursor has no hook for its approval prompts, so Nudge doesn't fake one. "Done" shows the agent's last reply. Like Grok, Cursor also runs Claude Code's hooks, and Nudge drops those copies.
OpenCode Built from the source
OpenCode 2 has no shell hooks, only plugins, so Nudge installs a small one. Detected from ~/.config/opencode or an opencode binary.
npx nudge-mascot setup --agent opencode
- Installs
- A plugin,
~/.config/opencode/plugins/nudge.js, that pipes OpenCode's events into the same hook - Nudges
- permissionquestiondone
- Answer from
- The terminal
Needs OpenCode 2 or later. Restart OpenCode after setup so it loads the plugin.
# every agent found on this machine npx nudge-mascot setup # or name them, comma-separated npx nudge-mascot setup --agent claude-code,grok,opencode # a fake nudge from one agent, hook status for all, remove everything npx nudge-mascot test permission --agent cursor npx nudge-mascot status npx nudge-mascot uninstall
Restart running agent sessions after setup; they read hooks at startup. "Built from the docs / source" means the adapter follows that agent's published hook format but hasn't been confirmed against a live install yet. Tell us if yours behaves differently.
How it works
- Your agent fires a hookClaude Code, Codex, Gemini CLI, Grok Build and Cursor run one small shell script that forwards the event with curl and names the agent (
nudge-hook.sh grok). OpenCode's plugin pipes its events into the same script. It never blocks the agent. - A relay on your machine turns it into one eventA zero-dependency Node server bound to 127.0.0.1 picks that agent's adapter and maps the payload to the shared shape: a question, permission, done or idle nudge. It accepts connections from the extension only and rejects any web page.
- The extension draws Nudge on your active tabThe sprite and bubble live in a closed shadow root, so page styles can't touch them and the script never reads the page.
agent hook → curl → relay on 127.0.0.1 → per-agent adapter → WebSocket → extension → Nudge on the tab you're looking at
Private by construction
Install in two steps
- Add the extension to ChromeClick "Add to Chrome" on the Web Store listing. The extension opens a setup page with one command to copy.
- Run that command in your terminalIt adds Nudge's hooks to every agent it finds (Claude Code's
~/.claude/settings.json, Codex, Gemini CLI, Grok Build, Cursor, OpenCode), backing up each config first. It also starts the local relay and keeps it running at login. Then restart any open agent session. To pick agents, add--agent: see Works with six coding agents.
npx nudge-mascot setup
To check it works, run npx nudge-mascot test or press Preview nudge in the extension popup. Nudge pops up on the current tab.
Then just keep working
- Work in your agent as usual. When it asks a question, needs permission, or finishes, Nudge appears on whatever tab is open with the message in a bubble and the agent's name on a badge.
- Questions and permissions escalate the longer you ignore them. Done messages stay quiet and fade after 20 seconds.
- Answer in the terminal and Nudge disappears everywhere. For Claude Code you can also answer right in the bubble. Or press Esc, click Got it, or snooze for five minutes.
- Several sessions waiting at once, even from different agents, get a row of pills so you can switch between them. Jump to terminal brings the right window forward.
- The popup holds the settings: which events to show, Gentle or Full Chaos or Off, sound, corner, and timings.
Coming next
Shipped since launch: answering Claude Code from the bubble or your phone, Jump to terminal, the session switcher, weekly waiting stats, and adapters for Codex, Gemini CLI, Grok Build, Cursor and OpenCode.
Next: mascot and sound packs, answering the other agents from the bubble where their hooks allow it, desktop apps on the same relay, and a Firefox port.