grove nav grove nav

grove nav grove nav

nav is a command-line tool for managing tmux sessions, windows, and navigation between project directories.

Features

  • Project Sessionizer (nav sessionize or sz): A terminal interface that lists projects discovered via grove-core’s discovery service. It displays git status, context information, and other metadata. The interface supports filtering, focusing on specific ecosystems, and toggling informational columns.
  • Session History (nav history or h): A terminal interface listing recently accessed project sessions, sorted from most to least recent. nav last or l provides a non-interactive way to switch to the most recently used session.
  • Key Mapping (nav key manage or km): A terminal interface to map project paths to single-character hotkeys. It allows reordering and locking of key positions. Additional CLI commands under nav key support adding, updating, and removing individual key mappings through interactive prompts.
  • Window Management (nav windows): A terminal interface for managing windows within the current tmux session. It allows for switching, filtering, renaming, closing, and reordering windows, and includes a preview pane showing window content.
  • Hotkey Generation: Creates a tmux configuration file (~/.config/grove/gmux/generated-bindings.conf) with bind-key commands for each mapped project. This file is intended to be sourced by the user’s ~/.tmux.conf.
  • Session Creation (nav launch): A command to create tmux sessions with specified window names, a session-wide working directory, and multiple panes. Working directories can also be set on a per-pane basis.
  • Scripting Commands: Subcommands (session exists, session kill, wait, capture) for checking and controlling tmux session state from shell scripts.
  • Worktree Discovery: Finds Git worktrees and lists them hierarchically under their parent repository in the sessionizer interface.

How It Works

nav uses grove-core’s DiscoveryService to find projects. This service reads the groves configuration from the global ~/.config/grove/grove.yml file.

The terminal interfaces (sessionize, history, key manage, windows) operate on data fetched from the local system. The sessionize and key manage interfaces execute background commands (e.g., git, nb, cx) to gather and display project metadata. This data is cached in JSON files within ~/.config/grove/gmux/ to reduce startup latency on subsequent runs.

Session key mappings are stored in ~/.config/grove/gmux/sessions.yml. Changes to these mappings trigger a regeneration of ~/.config/grove/gmux/generated-bindings.conf.

Session access is tracked in an access history file. A tmux hook (client-session-changed) is configured via the generated bindings file to call nav record-session, which keeps the history current when switching sessions.

Direct interaction with the tmux server is performed by executing tmux commands.

Installation

Install via the Grove meta-CLI:

bash
grove install nav

Verify installation:

bash
nav version

This requires the grove meta-CLI.