Hook System

Overview

Navi uses Claude Code’s hook system to receive real-time status updates. Hooks are shell scripts that Claude Code executes when specific events occur.

Hook Scripts

notify.sh

The main status updater. Receives a status argument and writes/updates a session JSON file.

Usage: notify.sh <status>

Where <status> is one of: working, done, permission, offline, idle, stopped

Stdin JSON: The hook reads JSON from stdin to extract event metadata:

{
  "teammate_name": "researcher",
  "team_name": "my-project",
  "session_id": "abc123",
  "hook_event_name": "SubagentStart"
}

Behavior:

• Determines the tmux session name from the environment
• If teammate_name is present, updates the teammate’s entry in team.agents[]
• If no teammate, updates the main session status
• Implements a stale event guard to prevent teammate events from overwriting the main session
• On Stop events, cleans up stopped agents from the team list

tool-tracker.sh

Tracks tool usage per session.

Stdin JSON:

{
  "tool_name": "Read",
  "tool_input": {"file_path": "/src/main.go"},
  "tool_response": "...",
  "tool_use_id": "abc123"
}

Behavior:

• Skips processing for teammate events (agent-level metrics not tracked)
• Increments the tool count in the session’s metrics
• Maintains a recent tools list (max 10 entries)

Hook Event Mapping

Claude Code Event	Script	Status
UserPromptSubmit	notify.sh	working
Stop	notify.sh	done
PermissionRequest	notify.sh	permission
SessionEnd	notify.sh	offline
PostToolUse	notify.sh	working
PostToolUse	tool-tracker.sh	(metrics update)
SubagentStart	notify.sh	working
SubagentStop	notify.sh	stopped
TeammateIdle	notify.sh	idle
TaskCompleted	notify.sh	done

Configuration

Hooks are configured in ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/notify.sh working"
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/notify.sh working"
      },
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/tool-tracker.sh"
      }
    ]
  }
}

The hooks/config.json file in the navi repository contains the complete configuration template. The install script merges this into your Claude Code settings.

Session Status Directory

Hook scripts write to ~/.claude-sessions/. Each active session has a JSON file named after its tmux session.

Files are:

• Created when a session first sends a hook event
• Updated on each subsequent event
• Cleaned up by navi when the corresponding tmux session no longer exists