naviClaude

TUI for managing Claude Code sessions across tmux sessions.

A "bring your own tmux" alternative to tools like cmux -- layers on top of your existing tmux setup instead of replacing it.

Features

• Session sidebar -- lists active and recently closed Claude Code sessions, grouped by project
• Live preview -- real-time tmux pane capture of the selected session
• Activity sparklines -- per-session message activity visualization on the selected item
• Context usage bar -- shows current token usage vs context window limit
• Breathing status dots -- active sessions pulse green, waiting sessions pulse amber
• Passthrough mode -- type directly into a session without leaving the TUI
• Changed-files sidebar -- a right-hand panel listing the files the selected session edited, with per-file +/- counts (live git diff while uncommitted, a persistent transcript estimate afterwards); open any file in your editor
• Fuzzy search -- filter sessions by name
• Session management -- create new sessions, kill existing ones, and resume closed sessions into any tmux session (or a brand-new one) via a target picker
• Detail popup -- view session metadata (model, project, cost, token counts)
• Rich preview header -- status badge, uptime, message count, CPU/memory
• Usage statistics -- per-project breakdown with bar charts
• 10 built-in color themes with a live theme picker
• Configurable key bindings and layout options
• Auto-collapse -- idle project groups collapse automatically

Requirements

• tmux -- naviClaude must be run inside a tmux session (brew install tmux)
• Claude Code CLI (claude)

Installation

Homebrew

brew install thbits/tap/naviclaude

Manual

git clone https://github.com/thbits/naviClaude.git
cd naviClaude
make install

This installs the binary to ~/.local/bin/naviclaude. Set a custom prefix with PREFIX=/usr/local make install.

Run as a tmux popup

Bind it to a key in ~/.config/tmux/tmux.conf to open a centered popup with <prefix> g:

bind g display-popup -E -w 85% -h 85% -x C -y C "naviclaude"

Usage

Launch naviClaude from any terminal inside tmux:

naviclaude

Key bindings

Key	Action
j / k	Navigate sessions
Tab / Shift+Tab	Cycle focus across the visible panes (session list -> preview passthrough -> changed files)
Ctrl+]	Exit passthrough straight to the session list
Ctrl+U / Ctrl+D	Scroll preview
/	Search
Enter	Focus an active session (passthrough mode); on a closed session, open the resume picker
f	Jump to pane. On a closed session, fast-resume into the current tmux session
Ctrl+F	Jump to pane (from passthrough)
n	New session (same tmux session)
N	New tmux session (prompts for name)
r	Rename session
K	Kill session
F	Toggle the changed-files sidebar and focus it (Esc drops focus but keeps it open)
e / Enter	In the changed-files sidebar, open the selected file in your editor
d	Detail popup
s	Statistics popup
T	Theme picker
?	Help overlay
q	Quit

All key bindings except navigation and passthrough exit keys are configurable.

Configuration

Config file location: ~/.config/naviclaude/config.yaml

naviClaude creates this file automatically when you save a theme. All fields are optional -- missing fields use defaults.

keys:
  quit: "q"
  search: "/"
  focus: "enter"
  jump: "f"
  new_session: "n"
  new_tmux_session: "N"
  kill_session: "K"
  rename_session: "r"
  detail: "d"
  stats: "s"
  toggle_changed: "F"
  help: "?"

sidebar_width: 30
refresh_interval: "200ms"
closed_session_hours: 8
group_sort_order: "name"
session_sort_order: "name"
popup_width: 85
popup_height: 85
resume_in_current_session: true
process_names: ["claude"]
collapse_after_hours: 8
active_window_secs: 5
cpu_active_threshold: 5
theme: "tokyo-night"
claude_command: "claude"
check_for_updates: true
focus_last_session: true
remember_group_state: true
# editor: "cursor"   # falls back to $EDITOR, then vi
# new_session_dir: "~/projects"

Option	Default	Description
sidebar_width	30	Width of the session list panel
refresh_interval	200ms	How often to refresh session data
closed_session_hours	8	Show closed sessions from the last N hours
group_sort_order	name	Sort tmux session groups: name (alphabetical) or activity
session_sort_order	name	Sort sessions within groups: name (alphabetical) or activity
popup_width	85	Popup width (percentage of terminal)
popup_height	85	Popup height (percentage of terminal)
resume_in_current_session	true	Resume sessions in the current tmux pane
process_names	["claude"]	Process names to detect as Claude sessions
collapse_after_hours	8	Auto-collapse groups idle longer than N hours (0 to disable)
active_window_secs	5	Seconds after last transcript write to keep a session "working" (fallback signal)
cpu_active_threshold	5	Process-subtree CPU% above which a session counts as "working"
theme	tokyo-night	Color theme name
claude_command	claude	Command to start Claude (sent via send-keys, supports aliases)
check_for_updates	true	Check GitHub on startup for a newer release and show "update available" in the status bar
focus_last_session	true	On startup, re-focus the session you last had selected; falls back to the first session if it no longer exists
remember_group_state	true	On startup, restore the open/closed state of groups you manually toggled
editor	$EDITOR, else vi	Editor for opening changed files from the changed-files sidebar; may include flags. GUI editors (cursor, code, zed, ...) open in their own window; terminal editors (vim, nvim, nano, ...) take over the TUI and return on exit
new_session_dir	~	Working directory for new tmux sessions created with N

Themes

Available built-in themes:

• catppuccin-latte
• catppuccin-mocha
• dracula
• gruvbox
• kanagawa
• nord
• one-dark
• rose-pine
• solarized-dark
• tokyo-night (default)

Press T to open the theme picker with live color swatches. Selected themes are saved to the config file.

License

MIT