Architecture Overview

High-Level Architecture

Navi follows a pipeline architecture: Hooks → JSON → Poller → TUI.

Claude Code Session (in tmux)
    │
    ├── Hook Events (UserPromptSubmit, Stop, PermissionRequest, ...)
    │       │
    │       ▼
    │   notify.sh / tool-tracker.sh
    │       │
    │       ▼
    │   ~/.claude-sessions/<session>.json   (status files)
    │
    ▼
Navi TUI (Bubble Tea)
    │
    ├── Session Poller (500ms) ──── reads JSON files ──── cross-refs tmux
    ├── Git Poller (5s cache) ──── runs git commands in session CWDs
    ├── Remote Poller ──────────── SSH to remote machines
    ├── Task Poller (30s) ──────── runs provider scripts
    └── Token Reader ───────────── reads ~/.claude/projects/ transcripts

Design Principles

• Hooks are fire-and-forget: Shell scripts write JSON files and exit. No persistent daemon.
• Polling over events: The TUI polls the filesystem rather than using file watchers, keeping the design simple and portable.
• Source of truth is the filesystem: Session state is stored as JSON files. If navi crashes, no data is lost.
• Feature parity: Remote sessions support the same operations as local sessions.

Component Interaction

The TUI is built with Bubble Tea, Charm’s Go framework for terminal applications. It follows the Elm architecture:

1. Model: Application state (sessions, UI state, caches)
2. Update: Handle messages (key presses, timer ticks, async results)
3. View: Render the current state to the terminal

All async operations (polling, SSH commands, git info) are implemented as Bubble Tea commands that return messages to the Update function.