Project Structure

Directory Layout

navi/
├── cmd/
│   └── navi/
│       └── main.go                 # Entry point — initializes Bubble Tea
├── internal/
│   ├── session/
│   │   └── session.go              # Session types, status constants, sorting
│   ├── tui/
│   │   ├── model.go                # Main TUI model and Update logic
│   │   ├── view.go                 # View rendering (layout, headers, footers)
│   │   ├── dialog.go               # Dialog modes (new, kill, rename, git, metrics)
│   │   ├── 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
│   │   ├── taskview.go             # Task panel rendering
│   │   ├── tasks.go                # Task panel state management
│   │   └── 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, diff)
│   ├── metrics/
│   │   └── metrics.go              # Token, time, tool metrics
│   ├── tokens/
│   │   └── ...                     # Token parsing from transcripts
│   ├── 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
├── providers/
│   ├── markdown-tasks.sh           # Markdown task file provider
│   └── github-issues.sh            # GitHub issues provider
├── install.sh                      # Installation script
├── .navi.yaml                      # Project task configuration
├── prd.md                          # Product requirements document
├── go.mod / go.sum                 # Go module dependencies
└── docs/
    └── delivery/                   # PBI and task documentation

Package Responsibilities

cmd/navi

Entry point. Initializes the Bubble Tea program with the TUI model.

internal/session

Defines the core Info struct that represents a Claude Code session. Includes status constants (StatusWaiting, StatusWorking, etc.), the TeamInfo/AgentInfo types for agent teams, and the SortSessions function for priority ordering.

internal/tui

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

• model.go: The main Model struct (~100 fields) and Update function
• view.go: All rendering logic including layout calculations
• dialog.go: Seven dialog modes with their own input handling
• filter.go: Search, status filters, sort modes
• preview.go: tmux pane capture and preview rendering
• tasks.go / taskview.go: Task panel state and rendering
• contentviewer.go: Full-screen content overlay

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

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

Local git operations. Extracts branch info, dirty status, ahead/behind counts, and GitHub PR numbers using git and gh CLI tools.

internal/metrics

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

hooks/

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

providers/

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