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
.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"

~/.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"
      }
    ]
  }
}