Configuration

Configuration Files

Navi uses several configuration files for different purposes.

Session Status Directory

Location: ~/.claude-sessions/

This directory contains JSON status files, one per active session. These are written by the hook scripts and read by navi’s polling system. You generally don’t need to edit these directly.

Hook Scripts

Location: ~/.claude-sessions/hooks/

• notify.sh — Main status updater. Writes session status JSON when Claude Code fires hook events.
• tool-tracker.sh — Tracks tool usage metrics. Increments tool counts and maintains a recent tools list.

Claude Code Settings

Location: ~/.claude/settings.json

Hook event bindings are configured here. The install script merges navi’s hook configuration into this file.

Project Task Configuration

Location: .navi.yaml (per-project, in the project root)

Configures which task provider to use for the task view panel.

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

Global Task Configuration

Location: ~/.navi/config.yaml

Global defaults for the task system.

tasks:
  default_provider: "markdown-tasks"
  interval: "30s"
  status_map:
    "todo": "open"
    "in_progress": "active"

Remote Machine Configuration

Remote machines are configured at runtime via the TUI dialog interface. Configuration includes:

• SSH hostname and port
• Session directory path (default: ~/.claude-sessions)
• Cache TTL for session data

See Remote Sessions for details.

Task Providers

Navi ships with two built-in task providers:

markdown-tasks

Scans markdown files for task definitions. Groups tasks by parent directory (PBI).

.navi.yaml

tasks:
  provider: "markdown-tasks"
  args:
    path: "docs/delivery"

github-issues

Fetches issues from a GitHub repository. Requires the gh CLI to be installed and authenticated.

.navi.yaml

tasks:
  provider: "github-issues"
  args:
    repo: "owner/repo"

Custom Providers

Any executable script that outputs JSON in the standard format can be used as a provider. Place the script in the providers/ directory or specify a full path.

Provider output format:

{
  "groups": [
    {
      "id": "1",
      "title": "Group Name",
      "status": "in_progress",
      "tasks": [
        {
          "id": "1-1",
          "title": "Task Name",
          "status": "todo",
          "assignee": "user",
          "labels": ["bug"],
          "priority": 1,
          "url": "https://...",
          "created": "2026-01-01T00:00:00Z",
          "updated": "2026-01-02T00:00:00Z"
        }
      ]
    }
  ]
}