# 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

```powershell
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

```powershell
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:

```sh
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.