Installation

Prerequisites

• Go 1.25+ (for building from source)
• tmux (required for session management)
• jq (optional, for automatic hook configuration merging)
• gh CLI (optional, for GitHub PR detection and the github-issues task provider)

Quick Install

Clone the repository and run the install script:

git clone https://github.com/stwalsh4118/navi.git
cd navi
./install.sh

The install script will:

1. Create ~/.claude-sessions/ and ~/.claude-sessions/hooks/
2. Copy hook scripts (notify.sh, tool-tracker.sh) with execute permissions
3. Merge hook configuration into ~/.claude/settings.json
4. Build the navi binary

If jq is not available, the script will save the hook configuration for manual merging and provide instructions.

Building Manually

go build -o navi ./cmd/navi

Move the binary to a directory in your $PATH:

mv navi ~/.local/bin/

Hook Setup

Navi relies on Claude Code hooks to receive status updates. The hooks are configured in ~/.claude/settings.json and fire shell scripts that write session status JSON files.

Hook Events

Event	Purpose
UserPromptSubmit	Marks session as working
Stop	Marks session as done
PermissionRequest	Marks session as needing approval
SessionEnd	Marks session as offline
PostToolUse	Clears stale permission status
SubagentStart	Tracks teammate agent start
SubagentStop	Tracks teammate agent stop
TeammateIdle	Tracks teammate idle state
TaskCompleted	Tracks task completion

Manual Hook Configuration

If automatic merging failed, add the hook arrays from hooks/config.json to your ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/notify.sh working"
      }
    ],
    "Stop": [
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/notify.sh done"
      }
    ],
    "PermissionRequest": [
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/notify.sh permission"
      }
    ]
  }
}

See hooks/config.json in the repository for the complete configuration.

First Run

1. Start one or more Claude Code sessions inside tmux
2. Run navi from any terminal
3. Sessions will appear as they send status updates via hooks
4. Use j/k to navigate, Enter to attach to a session