Skip to content
Navi

Project Structure

Directory Layout

Section titled “Directory Layout”
navi/
├── cmd/
│   └── navi/
│       └── main.go                 # Entry point — initializes Bubble Tea
├── internal/
│   ├── session/
│   │   └── session.go              # Session types, status constants, composite status, sorting
│   ├── tui/
│   │   ├── model.go                # Main TUI model and Update logic
│   │   ├── view.go                 # View rendering (layout, headers, footers, agents)
│   │   ├── dialog.go               # Dialog modes (new, kill, rename, git, metrics, sound picker)
│   │   ├── contentviewer.go        # Full-screen content viewer
│   │   ├── input.go                # Text input handling
│   │   ├── filter.go               # Search, filtering, sorting logic
│   │   ├── preview.go              # Preview pane capture and rendering
│   │   ├── sessions.go             # Session list rendering, PR commands
│   │   ├── taskview.go             # Task panel rendering
│   │   ├── tasks.go                # Task panel state, concurrent provider execution
│   │   ├── pmview.go               # PM three-zone view rendering
│   │   ├── pm.go                   # PM engine commands, invoker commands
│   │   └── styles.go               # Color schemes and styling constants
│   ├── task/
│   │   ├── types.go                # Task, TaskGroup, ProviderResult types
│   │   ├── provider.go             # Task provider interface
│   │   ├── config.go               # Project config (.navi.yaml) parsing
│   │   ├── discover.go             # Project config discovery
│   │   └── cache.go                # Provider result caching
│   ├── remote/
│   │   ├── sessions.go             # Remote session polling via SSH
│   │   ├── git.go                  # Remote git operations
│   │   ├── actions.go              # Remote session actions (kill, rename, dismiss)
│   │   └── ...                     # SSH pool, config types
│   ├── git/
│   │   ├── git.go                  # Git info (branch, PR number, diff)
│   │   └── pr.go                   # PR detail, checks, reviews, comments
│   ├── metrics/
│   │   └── metrics.go              # Token, time, tool metrics
│   ├── tokens/
│   │   └── ...                     # Token parsing from transcripts
│   ├── audio/
│   │   ├── config.go               # Config, VolumeConfig, SavePackSelection
│   │   ├── pack.go                 # ScanPack, ResolveSoundFiles, ListPacks
│   │   ├── player.go               # Audio player with volume control
│   │   ├── notifier.go             # Notification manager (mute, packs, randomization)
│   │   └── tts.go                  # Text-to-speech engine
│   ├── monitor/
│   │   └── monitor.go              # Background attach monitor (session + agent states)
│   ├── pm/
│   │   ├── types.go                # ProjectSnapshot, Event, TaskCounts, PMOutput
│   │   ├── briefing.go             # PMBriefing, ProjectBriefing, AttentionItem
│   │   ├── engine.go               # Engine orchestration pipeline
│   │   ├── snapshot.go             # Project discovery, snapshot capture
│   │   ├── diff.go                 # Snapshot diffing, event generation
│   │   ├── eventlog.go             # JSONL event log (append, read, prune)
│   │   ├── invoker.go              # Claude CLI invocation wrapper
│   │   ├── inbox.go                # Inbox payload construction
│   │   ├── output.go               # Output parsing, caching
│   │   ├── recovery.go             # Error recovery and resilience
│   │   ├── storage.go              # Directory layout, file I/O
│   │   ├── resolver.go             # Multi-strategy current-PBI resolution
│   │   └── branchinfer.go          # Branch pattern inference utility
│   ├── pathutil/
│   │   └── pathutil.go             # Path utilities (~ expansion)
│   └── debug/
│       └── debug.go                # Debug logging
├── hooks/
│   ├── notify.sh                   # Main hook — writes session status JSON
│   ├── tool-tracker.sh             # Tool usage tracking hook
│   └── config.json                 # Hook event configuration template
├── plugins/
│   └── opencode/
│       └── navi.js                 # OpenCode status hook plugin
├── providers/
│   ├── markdown-tasks.sh           # Markdown task file provider
│   └── github-issues.sh            # GitHub issues provider
├── install.sh                      # Installation script
├── .navi.yaml                      # Project task configuration
├── go.mod / go.sum                 # Go module dependencies
└── docs/
    └── delivery/                   # PBI and task documentation

Package Responsibilities

Section titled “Package Responsibilities”

cmd/navi

Section titled “cmd/navi”

Entry point. Parses subcommands (status, sound) and initializes the Bubble Tea program with the TUI model.

internal/session

Section titled “internal/session”

Defines the core Info struct that represents a Claude Code session. Includes status constants (StatusWaiting, StatusWorking, etc.), the TeamInfo/AgentInfo types for Claude Code agent teams, the ExternalAgent type for OpenCode and other agents, the CompositeStatus() function for multi-agent status aggregation, and SortSessions() for priority ordering.

internal/tui

Section titled “internal/tui”

The largest package — contains all TUI logic. Split across multiple files by responsibility:

  • model.go: The main Model struct and Update function
  • view.go: All rendering logic including layout calculations and agent indicators
  • dialog.go: Dialog modes including sound pack picker
  • filter.go: Search, status filters, sort modes
  • preview.go: tmux pane capture and preview rendering
  • tasks.go / taskview.go: Task panel state, rendering, and concurrent provider execution
  • sessions.go: Session list rendering and PR fetch commands
  • contentviewer.go: Full-screen content overlay
  • pmview.go: PM three-zone view (briefing, projects, events)
  • pm.go: PM engine and invoker command integration

internal/task

Section titled “internal/task”

Task provider system. Defines the Task, TaskGroup, and ProviderResult types. Handles config parsing from .navi.yaml, provider script execution, and result caching.

internal/remote

Section titled “internal/remote”

SSH-based remote session management. Handles connection pooling via ControlMaster, remote session polling, and remote action execution (kill, rename, dismiss, git info, preview).

internal/git

Section titled “internal/git”

Local git operations. Extracts branch info, dirty status, ahead/behind counts. Includes PR detail fetching (checks, reviews, comments, labels) via the gh CLI.

internal/audio

Section titled “internal/audio”

Audio notification system. Manages sound pack scanning and resolution, volume control with per-backend CLI flags, mute toggle, random variant selection, cooldown tracking, and TTS integration.

internal/monitor

Section titled “internal/monitor”

Background attach monitor. Runs while the terminal is attached to tmux, tracking both session and agent state transitions to fire audio notifications.

internal/pm

Section titled “internal/pm”

Project Manager engine. Handles project discovery, state snapshots, change diffing, event persistence, Claude CLI invocation, briefing parsing, memory system management, and multi-strategy current-PBI resolution.

internal/metrics

Section titled “internal/metrics”

Metrics types for token usage, time tracking, and tool activity. Provides formatting functions for human-readable display.

hooks/

Section titled “hooks/”

Shell scripts that Claude Code executes via its hook system. These run outside of navi and write JSON to ~/.claude-sessions/.

plugins/

Section titled “plugins/”

Agent plugins. The OpenCode plugin (plugins/opencode/navi.js) writes agent status to the shared session JSON file.

providers/

Section titled “providers/”

Task provider scripts that output standardized JSON. Can be extended with custom scripts.