Use Cases
Navigator is organized around moments in a developer’s day — the points where sessions die, work stalls, or knowledge evaporates. Each case below names the problem first and the features that solve it second.
1. Long feature work that used to die mid-session
“My AI session crashes at exchange 6.”
The flagship case. Bulk-loading 150k tokens of documentation kills the session before the feature ships. Navigator loads a ~2k index and lazy-loads the rest on demand — ~12k per session — so the window stays open for 20+ exchanges and the feature gets finished in one sitting instead of restarted three times.
“I compacted and lost my place.”
Context markers capture git state, active tasks, and conversation summary around every compaction. The next session resumes from the marker instead of re-explaining the work — a ~130k conversation compresses to a 2–5k marker.
“Claude read 15 files and burned my window.”
The read guard catches fan-out file reads and redirects them to a research agent running in a separate context, before your window is gone.
Features: Context Engineering · nav-marker · read guard (hook runtime)
2. Unattended and semi-attended execution
“Run until done: migrate these 40 files.”
Loop Mode iterates with structured status blocks, progress phases, and stagnation
detection. You check in on NAVIGATOR_STATUS snapshots instead of babysitting every
exchange.
“It said ‘done’ but the tests never ran.”
The completion gate checks observable evidence at the end of a turn — is the git tree clean, did a test command run, were docs touched? If the work looks unfinished and no explicit exit signal was given, Navigator forces one continuation to close the gap. Evidence-based, not vibes-based.
“I need this safe for headless pipelines.”
Executor mode (PILOT_EXECUTOR) turns off all interactive and blocking hook behavior at
a single policy point, so the same runtime that guides you interactively runs clean in
CI or under an autonomous executor.
Features: Loop Mode · Autonomous Completion · Task Mode
3. Starting work with the right shape
“A vague ticket just landed in chat.”
Ambiguous task-shaped prompts get an intent brief — Goal, Scope, Approach, Limits, Verify, Won’t do — on one screen before any file changes. Scope disputes happen in the brief, not after 40 edits.
“Is this a quick fix or a project?”
Complexity scoring at prompt time routes work automatically: trivial asks execute directly, substantial work gets phase guidance (research → plan → implement → verify). No ritual for small things, no chaos for big ones.
“Stop scaffolding before we agreed on the design.”
Workflow gating enforces research-before-code on task-shaped prompts, so architecture conversations happen before the first file is written.
Features: Task Mode · intent briefs and workflow gating (hook runtime)
4. Team memory that survives people and sessions
“Why did we choose X?”
Decisions are captured with their rationale and queryable in plain language — “What do we know about auth?” — instead of buried in a chat scrollback.
“We hit this bug before.”
Pitfall memories surface at prompt time, and research agents get the top relevant memories injected into their context automatically.
“New hire, productive in 48 hours.”
Task docs, SOPs, and the knowledge graph are git-tracked — the same docs the AI loads are the onboarding path humans read. The knowledge travels with the repo.
Features: Knowledge Graph · nav-graph · nav-sop · nav-task
5. Zero-cost operational queries
“nav stats” · “show features” · “graph health”
A narrow set of exact-match commands is answered deterministically by the hook runtime — zero model invocation, zero tokens, rendered as terminal-style cards. Instant, and it can’t hallucinate: the answer comes from your project state, not a model.
Features: Tier-1 instant answers (hook runtime) · nav-stats
6. Code quality without ceremony
“The AI code works but reads badly.”
A post-implementation simplification pass runs before commit: nested ternaries flattened, early returns, descriptive names. Clarity over brevity, functionality preserved absolutely.
“Output quality degraded mid-session.”
Quality-drop detection notices when collaboration is drifting and suggests a compact with markers, instead of letting you fight a degraded context for another hour.
Features: nav-simplify · nav-diagnose · Theory of Mind
7. Pipeline hand-off
“Plan interactively, execute headlessly.”
Navigator shapes the task — research, intent brief, task doc — and hands the spec off: “Dispatch TASK-42 to Pilot” turns a Navigator task doc into a labeled GitHub issue for Pilot to execute autonomously. The shared hook runtime honors executor mode, so nothing blocks the machine that picks the work up.
Features: Pilot integration · project management integrations
Where to start
If one of these is your daily pain, install and try that case first:
/plugin marketplace add qf-studio/navigator
/plugin install navigator