https://github.com/affirm/navi
Claude Code session monitor and notifier
https://github.com/affirm/navi
claude-code-plugin monitoring-plugin monitoring-tool notifications
Last synced: 27 days ago
JSON representation
Claude Code session monitor and notifier
- Host: GitHub
- URL: https://github.com/affirm/navi
- Owner: Affirm
- License: bsd-3-clause
- Created: 2026-04-17T20:00:18.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-02T14:37:04.000Z (29 days ago)
- Last Synced: 2026-06-02T16:22:33.912Z (29 days ago)
- Topics: claude-code-plugin, monitoring-plugin, monitoring-tool, notifications
- Language: Swift
- Homepage:
- Size: 147 KB
- Stars: 9
- Watchers: 0
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Navi ğŸ§
[](LICENSE)
[](https://github.com/Affirm/navi)
[](https://docs.anthropic.com/en/docs/claude-code)
**A floating macOS monitor for Claude Code sessions**
See what every Claude Code session is doing across all your terminals — at a glance, from one floating window.
## Installation
```shell
/plugin marketplace add Affirm/navi
/plugin install navi@navi
```
Hooks are registered automatically. Navi builds and launches itself the first time an event fires.
## What You Get
| Feature | Description |
|---------|-------------|
| **Session status** | Working (green), Idle (blue), needs attention (orange) at a glance |
| **Inline permissions** | Approve or deny tool permissions without switching terminals |
| **Session discovery** | Auto-detects running sessions by scanning `~/.claude/sessions/` |
| **Jump to terminal** | One-click focus the correct terminal tab for any session |
| **Auto-dismiss** | Stale permission cards clean up when approved in the terminal |
| **Menu bar icon** | Toggle the window; icon signals pending permissions |
| **Per-event sounds** | Configurable alerts for permission, completion, notification events |
| **Multi-session** | Monitor many concurrent Claude Code sessions side-by-side |
| **Session row badges** | Optional per-session badges for working folder, git status, permission mode, model, and open PR (each independently toggleable in Settings, all default off) |
## Requirements
- macOS (tested on macOS 15+)
- Xcode Command Line Tools (`xcode-select --install`)
- Python 3 (ships with macOS)
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
## Settings
Click the gear icon to configure sounds, font size, and experimental features (jump-to-terminal, menu bar icon, session status, instant notifications, etc.). Each feature is independently toggleable; most default on.
Each sound can be set to any macOS system sound (Glass, Ping, Submarine, etc.).
## Manual Setup
If you'd rather not use the plugin system:
```bash
git clone https://github.com/Affirm/navi.git
cd navi
bash build.sh # Downloads + verifies the published Navi.app release
open Navi.app
```
Then register the hooks from `hooks/hooks.json` in your `~/.claude/settings.json`, replacing `${CLAUDE_PLUGIN_ROOT}` with the absolute path to this directory.
## How It Works
```
Claude Code session
│
├── UserPromptSubmit ──→ userpromptsubmit.sh ──→ writes working signal ──→ /tmp/navi/events/
├── PreToolUse ────────→ pretooluse.sh ────────→ captures tool_use_id ──→ /tmp/navi/pretooluse/
├── PermissionRequest ─→ hook.sh → parse_event.py → event JSON ─────────→ /tmp/navi/events/
├── PostToolUse ───────→ hook.sh → parse_event.py → resolve signal ─────→ /tmp/navi/events/
├── Stop ──────────────→ hook.sh → parse_event.py → event JSON ─────────→ /tmp/navi/events/
├── StopFailure ───────→ hook.sh → parse_event.py → event JSON ─────────→ /tmp/navi/events/
├── Notification ──────→ hook.sh → parse_event.py → event JSON ─────────→ /tmp/navi/events/
└── PostToolUseFailure → hook.sh → parse_event.py → resolve signal ─────→ /tmp/navi/events/
~/.claude/sessions/*.json ──→ Navi session discovery (PID liveness + TTY lookup)
Navi.app
├── polls /tmp/navi/events/ (instant via kqueue watcher + fallback timer)
├── discovers sessions from ~/.claude/sessions/
├── tracks Working/Idle/Dead status per session
└── displays events in SwiftUI floating window + menu bar popover
│
User clicks Approve/Deny
│
writes response to /tmp/navi/responses/
│
hook.sh reads response, returns decision to Claude Code
```
For permission requests, `hook.sh` writes an event file and polls for a response file. When you click Approve/Deny, Navi writes the response, the hook picks it up and returns the decision to Claude Code. If no response comes within 120 seconds, it falls back to the terminal prompt.
For architecture details and guidance on extending Navi, see [`CONTRIBUTING.md`](CONTRIBUTING.md).
## Uninstall
```bash
claude plugin uninstall navi
pkill -x Navi 2>/dev/null
rm -rf /tmp/navi
```
## Development
```bash
git clone https://github.com/Affirm/navi.git
cd navi
bash scripts/build-from-source.sh ./out # Compiles Sources/ into ./out/Navi.app(.zip)
open ./out/Navi.app # Launch
```
`bash build.sh` is the *install* entrypoint — it downloads the pre-built release artifact for the version in `plugin.json` and verifies its checksum + Sigstore attestation, but does not compile from source. Contributors compile via `scripts/build-from-source.sh` (or `NAVI_BUILD_FROM_SOURCE=1 bash build.sh` to install a local build in place). See [`CONTRIBUTING.md`](CONTRIBUTING.md) for architecture, the feature-flag system, and guidance on adding experimental features.
## Troubleshooting
### `failed to build module 'SwiftUI'` / `this SDK is not supported by the compiler`
```
failed to build module 'SwiftUI', this SDK is not supported by the compiler
(the SDK is built with 'Apple Swift version 6.0.3 effective-5.10 (swiftlang-6.0.3.1.5),
while this compiler is 'Apple Swift version 6.0.3 effective-5.10 (swiftlang-6.0.3.1.10...)'
```
This is not a Navi bug — it means your Xcode Command Line Tools install is inconsistent: the SDK (`.swiftmodule` files for SwiftUI, AppKit, etc.) was produced by a sibling build of the Swift compiler than the one `swiftc` reports. That usually happens after a partial macOS/CLT update, or when Xcode.app and CLT end up on different update cycles.
**Check what's active:**
```bash
xcode-select -p
xcrun swift --version
xcrun --show-sdk-version
xcrun --show-sdk-path
```
`scripts/build-from-source.sh` prints the same information at the top of every build, so you can read it from the build output too.
**Fix in order of escalation:**
1. **Re-align the developer directory** (30 seconds). If you have Xcode.app installed, point to it; otherwise point to CLT:
```bash
# With Xcode.app installed
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
# CLT only
sudo xcode-select -s /Library/Developer/CommandLineTools
```
2. **Reinstall Command Line Tools** (5 minutes). Most reliable fix when you don't have Xcode.app, or when alignment didn't help:
```bash
sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install
```
3. **Update macOS + Xcode/CLT to current.** If the versions have drifted far apart across major releases, install all pending updates in System Settings → General → Software Update, then reinstall CLT.
After any of these, run `bash scripts/build-from-source.sh ./out` (or `bash build.sh` if you only meant to install the published release) again.
## Contributors
Created by [@Clast](https://github.com/Clast)
Navi started inside Affirm's internal plugin catalog before it became this standalone repo, so some contributors don't appear in this repo's git history. Special thanks to:
- [@KieranLitschel](https://github.com/KieranLitschel) — improved session status (Working / Idle), session names, auto-dismiss, jump-to-terminal button
- [@manassarpatwar](https://github.com/manassarpatwar) — menu bar UI, instant filesystem-watcher notifications, plus a long tail of stability fixes
- [@tarkatronic](https://github.com/tarkatronic) — suggested open-sourcing Navi and helped with open-source setup
## License
BSD 3-Clause — see [LICENSE](LICENSE).