.nav-config.json Schema

The canonical configuration file for Navigator. It controls the v7 hook runtime (dispatcher + ops), the ToM features, loop and task modes, the knowledge graph, code simplification, auto-update, PM/chat integration, and Tier-1 instant answers.

Location: .agent/.nav-config.json (project root, relative to the repo).

Created by: nav-init writes the initial file when you initialize Navigator in a project.

Edited by: nav-features (toggle blocks interactively) or by editing the JSON directly. After changing it, the new values apply on the next session start; some hook changes require a Claude Code restart to take effect.

All keys below are taken from the live, authoritative file. Defaults shown are the values Navigator ships with.

v7: hook runtime, not prose mandates

As of v7.0.0, Navigator’s workflow is enforced by the hook runtime — a single dispatcher routing op modules — instead of prose mandates in CLAUDE.md. The v6 WORKFLOW CHECK block requirement is retired; every enforced behavior now maps to an op with a config off-switch:

New blocking features ship off: tier1.enabled and stop_completion.continue_enabled both default to false — you opt in explicitly. Setting the PILOT_EXECUTOR environment variable disables all interactive/blocking hook behavior regardless of config.

Layering: shared file plus personal override (v7.8.0)

Two files are read, in order, over DEFAULTS:

1. .agent/.nav-config.json — committed, shared with the team.
2. .agent/.nav-config.local.json — gitignored, personal; merged last, so any key set here wins.

Dicts merge key-wise; scalars and lists replace. A missing or unparsable local file changes nothing (the config_guard op warns when either file fails to parse). nav-features enable|disable <feature> --local writes to the local file; show marks locally decided rows with L.

Defaults-safe and additive migration

• Defaults-safe: any block missing from your file falls back to safe defaults via nav_hook_lib.config.DEFAULTS. A partial config is always valid.
• Additive migration from v6: on first run, the config migrator preserves your existing v6 blocks and adds the new v7 blocks (dispatcher, tier1, stop_completion, brief_hook). Nothing is removed or rewritten.

Annotated example

{
  "version": "8.3.5",
  "project_management": "none",
  "task_prefix": "TASK",
  "task_id_source": "local",
  "team_chat": "none",
  "auto_load_navigator": true,
  "compact_strategy": "conservative",
 
  "dispatcher": { "enabled": true },
 
  "tier1": { "enabled": false, "rules": {} },
 
  "stop_completion": {
    "enabled": false,
    "continue_enabled": false,
    "max_continues": 2
  },
 
  "reject_log": {
    "enabled": true
  },
 
  "deep_research": {
    "enabled": false,
    "max_sources": 30,
    "min_sources": 8,
    "fetchers": 4,
    "max_full_reads": 10,
    "critic_enabled": true,
    "models": { "fetcher": "sonnet", "writer": "opus", "critic": "opus", "patcher": "opus" }
  },
 
  "judge": {
    "enabled": false,
    "provider": "typesafe",
    "endpoint": "https://api.typesafe.ai/v1/systemone",
    "model": "jev-latest",
    "timeout_ms": 1500,
    "min_confidence": 0.4,
    "noul_low": 0.4,
    "noul_high": 0.6,
    "api_key_env": "TYPESAFE_API_KEY",
    "api_key_file": "~/.config/typesafe/api_key",
    "max_state_chars": 4000
  },
 
  "task_mode": {
    "enabled": true,
    "auto_detect": true,
    "defer_to_skills": true,
    "complexity_threshold": 0.5,
    "show_phase_indicator": true
  },
 
  "tom_features": {
    "verification_checkpoints": true,
    "confirmation_threshold": "high-stakes",
    "profile_enabled": true,
    "diagnose_enabled": true,
    "belief_anchors": false
  },
 
  "loop_mode": {
    "enabled": false,
    "max_iterations": 5,
    "stagnation_threshold": 3,
    "exit_requires_explicit_signal": true,
    "show_status_block": true,
    "iteration_approval": "none",
    "periodic_interval": 3,
    "never_pause_on_stagnation": false,
    "stagnation_diversify_strategy": "combine"
  },
 
  "simplification": {
    "enabled": true,
    "trigger": "post-implementation",
    "scope": "modified",
    "model": "opus",
    "skip_patterns": ["*.test.*", "*.spec.*", "*.md", "*.json", "*.yaml"],
    "max_file_size": 50000,
    "auto_apply": false,
    "preserve_comments": true,
    "rules": {
      "avoid_nested_ternary": true,
      "max_nesting_depth": 3,
      "max_function_length": 50,
      "prefer_explicit_returns": true,
      "consolidate_imports": true
    }
  },
 
  "auto_update": {
    "enabled": true,
    "check_interval_hours": 1,
    "curl_fallback": false,
    "last_check": "2026-06-08T16:11:33.109699"
  },
 
  "pilot": {
    "enabled": true,
    "label": "pilot",
    "repo": null
  },
 
  "knowledge_graph": {
    "enabled": true,
    "auto_capture_corrections": true,
    "auto_capture_decisions": true,
    "auto_surface_relevant": true,
    "max_session_memories": 5,
    "confidence_decay_rate": 0.01,
    "staleness_threshold_days": 90,
    "git_tracked": true
  },
 
  "reply_modes": {
    "enabled": true
  },
  "adhd_mode": {
    "enabled": true,
    "on": null
  },
  "ste_mode": {
    "enabled": true,
    "on": null
  },
 
  "session_start_hook": {
    "enabled": true,
    "include_sections": ["navigator", "marker", "config", "graph", "profile", "tasks", "auto_update"],
    "char_budget": 9500
  },
  "compact_hook": {
    "enabled": true,
    "include_transcript_summary": true,
    "include_git_state": true,
    "char_budget": 8000,
    "append_post_compact_summary": true
  },
  "brief_hook": { "enabled": true },
  "task_graph_sync_hook": { "enabled": true },
  "workflow_state_hook": { "enabled": true },
  "profile_sync_hook": { "enabled": true },
  "workflow_enforcer_hook": { "enabled": true, "strict_block": true },
  "read_guard_hook": {
    "enabled": true,
    "warn_threshold": 3,
    "escalate_threshold": 5,
    "strict_block": true,
    "allowlist": ["DEVELOPMENT-README.md", ".nav-config.json", ".user-profile.json", "knowledge/graph.json"]
  }
}

Top-level

dispatcher

The v7 hook runtime: a single dispatcher (hooks/nav_dispatch.py) routes every hook event to op modules in hooks/ops/.

tier1

Tier-1 instant answers: a narrow, exact-match command set answered deterministically with zero model invocation. New in v7; ships off. See the Tier-1 tuning page.

stop_completion

The completion gate: derives completion indicators from observable turn evidence and can force one continuation when a codebase-mutating turn ends with unfinished work. New in v7; forced continuation ships off. See the completion gate tuning page.

deep_research

Web deep research via the nav-deep-research skill. New in v7.3.0; ships off because a run fetches dozens of third-party pages and spends several opus subagent calls.

judge

Typed prompt judge — see Typed Prompt Judge. New in v7.7.0; ships off because the prompt text is sent to the TypeSafe API when enabled. Every axis falls back to the keyword heuristic when the judge is undecided, times out, has no key, or errors.

reply_modes

The op behind every per-person reply mode (prompt_modes); see Reply Modes. Ships in v8.3.0, where it replaces prompt_adhd. Each mode keeps its own <key>_mode block below.

adhd_mode

Per-person reply-shape switch; see Reply Modes. New in v7.9.0. The block makes the mode available; the switch itself is the person’s (~/.config/navigator/adhd-mode.json, written by saying adhd mode on). Resolution: repo pin, then personal switch, then off.

ste_mode

Per-person Simplified Technical English switch (ASD-STE100 Part 1 subset, dictionary not applied); see Reply Modes. Ships in v8.3.0. Same shape and resolution as adhd_mode; the personal file is ~/.config/navigator/ste-mode.json, written by saying ste mode on or use ste.

task_mode

Unified workflow orchestration. Auto-detects substantial work and either defers to a matching skill or runs phased execution. Activation scoring runs at prompt-submit time via the prompt_gate op.

tom_features

Theory of Mind features for collaborative alignment.

loop_mode

Structured “run until done” iteration with explicit exit gating. In v7, exit evaluation runs on Stop via the stop_state and stop_completion ops.

simplification

Automatic code clarity pass before commit. Functionality is preserved; only form changes.

auto_update

Session-start notice when a newer release exists. Navigator never updates itself from a hook; the notice carries the command (claude plugin update navigator@navigator-marketplace), and nav-start Step 1.5 applies it.

pilot

Navigator → Pilot dispatch settings (one-way handoff of a task doc to a labeled GitHub issue).

knowledge_graph

Unified search and experiential memory across .agent/.

Hook toggle blocks

Each block is the off-switch for one op in the hook runtime (see the behavior → op table above). Changing a hook’s enabled flag generally requires a Claude Code restart to take effect.

session_start_hook

Off-switch for the session_start op — injects Navigator context on session start.

compact_hook

Off-switch for the compact_marker op — captures context markers around compaction.

brief_hook

Off-switch for the prompt_brief op — injects a NAV-BRIEF prompt (plus relevant knowledge-graph memories) on ambiguous task-shaped prompts, asking for a one-screen intent brief before files change.

task_graph_sync_hook

workflow_state_hook

Off-switch for the stop_state op — records workflow/loop state and completion indicators on Stop.

profile_sync_hook

workflow_enforcer_hook

Off-switch for the prompt_gate op — workflow gating at prompt-submit time. Task-shaped prompts are scored for loop triggers and complexity (>= 0.5 → Task Mode; below → direct execution). This replaces the v6 WORKFLOW CHECK prose mandate, which is retired in v7.

read_guard_hook

Off-switch for the read_guard op — guards against fan-out manual Reads that should be Task agents (upfront-loading anti-pattern).

Related

• /configuration/tier1
• /configuration/stop-completion
• /configuration/tom-features
• /configuration/loop-mode
• /configuration/task-mode
• /configuration/knowledge-graph
• /configuration/simplification
• /configuration/auto-update
• /configuration/pm-and-chat