Navi 🧚

Hey! Listen!

A desktop notifier for AI agents, styled after the fairy from The Legend of Zelda: Ocarina of Time. Navi floats on your screen; when an agent (Claude Code or any MCP client) calls her notify tool, she rings, changes color, and shows the message in a speech bubble — so you know when an agent needs you without watching the terminal.

Kind	Meaning	Color	Chime volume
urgent	Agent needs your approval	🔴 Red	100%
warning	Something needs attention	🟡 Yellow	60%
success	Task finished	🟢 Green	35%

Idle, she glows soft blue, bobs, flaps her wings, sheds sparks, and drifts lazily around her corner of the screen. Drag her anywhere by her body.

How it works

One Electron app hosts both:

• An MCP server (streamable HTTP, stateless) on 0.0.0.0:8641, exposing a single tool:

  notify(kind: "urgent" | "warning" | "success", message: string, title?: string)
  

• The fairy overlay — a transparent, frameless, always-on-top window.

A tray icon provides per-kind test notifications, a "Copy MCP add command" shortcut, and Quit.

Requirements

• Windows 10/11 with Node.js LTS (the app is Windows-only: transparent overlay + audio).
• Agents can run anywhere that can reach port 8641 — including WSL2.

Run from source

npm install
npm start

Allow the Windows Firewall prompt on first launch (tick Public if your agents connect from WSL2 — the WSL virtual adapter is usually classified Public).

Build the exe

npm run package

Output: release/navi-win32-x64/navi.exe. Launching it starts the MCP server automatically; on startup Navi's speech bubble shows the exact command to register her with Claude Code.

Connect an agent

From Windows:

claude mcp add --transport http navi http://localhost:8641/mcp

From WSL2 (NAT mode — the default), use the Windows host IP instead:

HOST=$(ip route show default | awk '{print $3}')
claude mcp add --transport http navi http://$HOST:8641/mcp

The NAT IP can change after a reboot — re-run the command if calls stop connecting, or enable networkingMode=mirrored in .wslconfig so localhost works from WSL too. The tray's Copy MCP add command always has the current URL.

Then just ask your agent to use it, or add a standing instruction like:

When you finish a task, need my approval, or hit a problem, call the notify tool (kind: success / urgent / warning).

The chime

Drop your own sound at assets/hey_listen.mp3 (gitignored — bring your own; Nintendo's audio cannot be distributed with this repo). Without the file, Navi synthesizes a two-note fairy chime with WebAudio.

Development notes

• No bundler: two tsc projects (tsconfig.json for main/preload, tsconfig.renderer.json for browser-global renderer scripts).
• npm run build compiles both; see CLAUDE.md for the full development log and environment gotchas.

Known limitations

• The server listens on 0.0.0.0, so any LAN host can trigger notifications. Fine for a home setup; firewall the port if that bothers you.
• Always-on-top does not cover exclusive-fullscreen games.