gitwtfhub

wtf is navi-agent?

ojnadjarm/navi-agent — explained in plain English

Analysis updated 2026-05-18

2TypeScriptAudience · developerComplexity · 3/5Setup · moderate

TL;DR

A floating fairy-styled desktop notifier that alerts you when an AI coding agent like Claude Code needs your attention.

Mindmap

mindmap
  root((navi-agent))
    What it does
      Runs MCP notify server
      Shows floating fairy overlay
      Rings chime on events
    Tech stack
      TypeScript
      Electron
      MCP protocol
    Use cases
      Get alerted when an agent needs approval
      Watch task status without terminal
      Connect agents from WSL2
    Audience
      Claude Code users
      MCP client developers
    Limitations
      Windows only
      Listens on all network interfaces
      No exclusive fullscreen support

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Get a visual and audio alert when Claude Code needs your approval.

REASON 2

Register the notify tool so any MCP-compatible agent can reach the desktop overlay.

REASON 3

Connect agents running inside WSL2 to the notifier on the Windows host.

REASON 4

Build a standalone exe to run the notifier without a dev environment.

What's in the stack?

TypeScriptElectronMCPNode.js

How it stacks up

ojnadjarm/navi-agent4ssh1/mine-sweeperachawla19/intuitcode-extension
Stars222
LanguageTypeScriptTypeScriptTypeScript
Last pushed2026-01-31
MaintenanceMaintained
Setup difficultymoderatemoderatemoderate
Complexity3/52/54/5
Audiencedevelopervibe coderdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 30min

Windows-only, requires Node.js and allowing a Windows Firewall prompt for WSL2 connections.

Wtf does this do

Navi is a small desktop app for Windows that gives AI coding agents like Claude Code a way to get your attention, styled after the fairy companion from a well known video game. She floats on your screen as a small transparent overlay, and when an agent needs you, she rings a chime, changes color, and shows a message in a speech bubble instead of you having to keep watching a terminal window. Under the hood, one Electron application does two jobs at once. It runs a small local server that speaks the MCP protocol, the same standard used to connect AI agents to external tools, exposing a single function that lets an agent send a message with an urgency level of urgent, warning, or success. The same app also draws the floating fairy overlay window itself, which glows and drifts around a corner of the screen while idle and can be dragged anywhere. Because it relies on a transparent always on top window and audio playback, Navi only runs on Windows 10 or 11 with Node.js installed. Agents connecting to it do not need to run on the same machine though, since anything that can reach the right network port works, including agents running inside WSL2 on the same PC. Setup involves installing dependencies, starting the app, and registering it with your agent using a short command that Navi's own speech bubble displays for you. The README notes a couple of limitations: the notification server listens on all network interfaces by default, so anyone on the same local network could trigger a notification unless you firewall the port, and the always on top window will not appear over a game running in exclusive fullscreen mode.

Yoink these prompts

Prompt 1
Walk me through installing and running Navi from source on Windows.
Prompt 2
Explain how to connect an agent running in WSL2 to Navi's MCP server.
Prompt 3
Help me add a standing instruction so my agent calls the notify tool automatically.
Prompt 4
Tell me what the known limitations mean for using this on my setup.

Frequently asked questions

wtf is navi-agent?

A floating fairy-styled desktop notifier that alerts you when an AI coding agent like Claude Code needs your attention.

What language is navi-agent written in?

Mainly TypeScript. The stack also includes TypeScript, Electron, MCP.

How hard is navi-agent to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is navi-agent for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.