Configuration Files

File Locations

File	Purpose
~/.claude-sessions/	Session status JSON files
~/.claude-sessions/hooks/notify.sh	Main status hook script
~/.claude-sessions/hooks/tool-tracker.sh	Tool usage tracking hook
~/.claude/settings.json	Claude Code settings (hook configuration)
~/.config/navi/remotes.yaml	Remote machine configuration
~/.config/navi/sounds.yaml	Audio notification configuration
~/.config/navi/soundpacks/	Sound pack directories
~/.config/navi/pm/	PM agent data (events, memory, briefings)
~/.config/opencode/plugins/navi.js	OpenCode status plugin
.navi.yaml	Per-project task configuration
~/.navi/config.yaml	Global task configuration

~/.config/navi/remotes.yaml (Remote Machines)

Configures remote machines for SSH-based session aggregation. If this file doesn’t exist, remote support is disabled.

remotes:
  - name: dev-server
    host: dev.example.com
    user: sean
    key: ~/.ssh/id_rsa
    sessions_dir: ~/.claude-sessions
    jump_host: bastion.example.com

Fields

Field	Type	Required	Default	Description
name	string	Yes	—	Display name for the remote
host	string	Yes	—	SSH hostname or IP
user	string	Yes	—	SSH username
key	string	Yes	—	Path to SSH private key (supports ~)
sessions_dir	string	No	~/.claude-sessions	Sessions directory on the remote
jump_host	string	No	—	Jump/bastion host

See Remote Sessions for full details.

.navi.yaml (Per-Project)

Located in the project root. Configures the task provider for this project.

tasks:
  provider: "markdown-tasks"       # Provider script name (required)
  args:                            # Provider-specific arguments (optional)
    path: "docs/delivery"
  interval: "30s"                  # Refresh interval (optional, default: 30s)

Fields

Field	Type	Default	Description
tasks.provider	string	(required)	Name of the provider script
tasks.args	map	{}	Arguments passed to the provider script
tasks.interval	string	"30s"	How often to refresh task data

~/.navi/config.yaml (Global)

Global defaults for the task system.

tasks:
  default_provider: "markdown-tasks"   # Default provider when none specified
  interval: "30s"                      # Default refresh interval
  status_map:                          # Map provider statuses to navi statuses
    "todo": "open"
    "in_progress": "active"

~/.config/navi/sounds.yaml (Audio Notifications)

Configures audio notifications for session status changes. If this file doesn’t exist, audio is disabled.

enabled: true
pack: starcraft                  # Active sound pack name

volume:                          # Volume settings
  global: 80                     # 0-100, default 100
  events:                        # Per-event multiplier (0.0-1.0)
    error: 1.0
    done: 0.7
    waiting: 0.5

triggers:
  waiting: true
  permission: true
  working: false
  idle: false
  stopped: false
  done: true
  error: true

files:                           # Explicit per-status file overrides
  waiting: ~/sounds/waiting.wav
  permission: ~/sounds/permission.mp3
  done: ~/sounds/done.ogg
  error: ~/sounds/error.wav

tts:
  enabled: true
  template: "{session} — {status}"

cooldown_seconds: 5
player: auto
tts_engine: auto

Fields

Field	Type	Default	Description
enabled	bool	false	Master toggle for all audio
pack	string	—	Active sound pack directory name
volume.global	int	100	Global volume (0-100)
volume.events.<status>	float	1.0	Per-event volume multiplier (0.0-1.0)
triggers.<status>	bool	varies	Whether to notify on this status change
files.<status>	string	—	Explicit file override (takes precedence over pack)
tts.enabled	bool	true	Enable text-to-speech announcements
tts.template	string	"{session} — {status}"	TTS template with {session} and {status} placeholders
cooldown_seconds	int	5	Minimum seconds between notifications per session
player	string	"auto"	Audio player binary or "auto" for detection
tts_engine	string	"auto"	TTS engine binary or "auto" for detection

See Audio Notifications for full details on sound packs, volume control, player and TTS detection.

~/.config/navi/soundpacks/ (Sound Packs)

Each subdirectory is a sound pack containing audio files named by event:

~/.config/navi/soundpacks/
  starcraft/
    waiting.wav
    waiting-1.wav          # Multi-variant (randomly selected)
    waiting-2.wav
    permission.wav
    done.wav
    error.wav
  retro/
    waiting.mp3
    done.mp3

Supported formats: .wav, .mp3, .ogg, .flac. See Audio Notifications for details.

~/.config/navi/pm/ (PM Agent Data)

Stores PM engine data and Claude agent memory. Created automatically on first use.

~/.config/navi/pm/
├── events.jsonl              # Event log (24-hour rolling)
├── system-prompt.md          # Claude's instructions (code-controlled)
├── output-schema.json        # JSON schema for output (code-controlled)
├── last-output.json          # Cached briefing for fallback
└── memory/
    ├── short-term.md         # Recent context (~2000 tokens)
    ├── long-term.md          # Historical patterns (~3000 tokens)
    └── projects/
        └── <project>.md      # Per-project memory (~1000 tokens)

See PM Dashboard for details on the PM agent and memory system.

~/.claude/settings.json (Hook Config)

Navi’s hooks are configured as entries in Claude Code’s settings file.

{
  "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"
      }
    ],
    "SessionEnd": [
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/notify.sh offline"
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/notify.sh working"
      },
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/tool-tracker.sh"
      }
    ],
    "SubagentStart": [
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/notify.sh working"
      }
    ],
    "SubagentStop": [
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/notify.sh stopped"
      }
    ],
    "TeammateIdle": [
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/notify.sh idle"
      }
    ],
    "TaskCompleted": [
      {
        "type": "command",
        "command": "~/.claude-sessions/hooks/notify.sh done"
      }
    ]
  }
}