GitHub (source code)

You set the course.Nav lights the way.

A pair-programming system where you keep the keyboard. A crew of AI models helps you explore, understand and change your code. You stay at the helm.

Install WithNav Read the docs

nav tui

▌captain
Swap the toml parser for an incremental one. Keep Config::load(p).
▌nav
I'll map the call sites first, then edit.
✓ grep "from_str" · 7 matches
vigie · scouting · read-only
◇ remark · nav · config.rs:42
A second parameter breaks "public API unchanged" in the intent record.
useful · noise · dismiss
✋ edit src/config.rs · needs your approval
y allow once · n deny
Illustration of a WithNav session: the Captain asks for a change, Nav maps the call sites while Vigie scouts, Nav leaves a remark that the change breaks the intent record, and the edit waits for the Captain's approval.

The Crew

One point of contact. Three specialists when needed.

You talk to Nav. Nav brings in Vigie, Lux or Mousse when the task calls for it. You see each one's goal and progress as it works, and each one only has the access its role needs.

Nav

The Navigator

Understands the course, proposes a route, coordinates the crew and asks before important decisions.

Edits after permission review

Vigie

The Lookout

Scouts the codebase, docs and web. Separates what it saw from what it assumes, and cites its sources.

Read-only

Lux

The Expert Advisor

When the route becomes uncertain, ask Lux: architecture, risks, reviews and hard bugs.

Read-only · recommends

Mousse

The Lightweight Deckhand

A quick hand for small, local edits: renames, formatting, basic tests. Hands the task back to Nav when it grows.

Small local edits · after review
  • On demand:
  • CartographeCharts modules, dependencies and flows
  • SondeurLooks for root causes

I remain in control, but I no longer navigate alone.

Under the hood · four layers

Fast layers watch. Slow layers think. You decide.

Each layer has its own model and its own job. The fast ones run often; the deep ones speak only when it is worth it.

  1. Captain

    You. You keep the helm, give each remark a verdict and decide what gets done. Nav does the work only when you hand it over.

    always in charge

  2. Reflex

    api · fim

    Ghost-text suggestions in the editor, accepted with Tab.

    as you type

  3. Instinct

    api · systemone

    Typed decisions: is this worth saying, is this tool call safe, is this subagent stuck.

    on every trigger

  4. Metacognition

    api · chat

    Short remarks beside your code, review of risky tool calls, and a wake for Nav when the code contradicts what you agreed.

    when it matters

  5. Cognition

    api · chat · agents

    Where Nav and the crew run: the build and plan agents, Vigie, Lux and Mousse in the background, tools, skills and rules.

    when you ask

Models come from the gateways you configure. One model per lower layer, one per agent, all in config.json.

You keep the helm

Built to work with you, not instead of you.

An intent record you share

Nav writes down the goal, the route and the decisions as they settle. When the code drifts from them, Nav says so beside the line.

.withnav/intent.md

Changes go through review

Writes, edits, shell commands and fetches pass a permission gate. Instinct clears the ordinary ones, risky ones get a Metacognition review, and anything still in doubt is asked to you. It guards against drift; it is not a sandbox.

allow once · always · deny

Remarks you can rate

Mark a remark useful or noise, or dismiss it. Verdicts go to a local decision log, and you can replay recorded runs against a changed flow without calling a model.

useful · noise · dismissed

One core, every surface

The same sessions in your terminal, editor and browser.

Every client talks to one local session server. Settings in any of them write the same config.json.

Terminal

Tabs, a command palette, a model picker, subagents and Settings, built with Ratatui.

nav tui

VS Code

Inline suggestions, remarks on the line, and the Nav chat beside your code.

pixmants.withnav

Browser

Workspaces and sessions on a private local link that changes on every run.

nav web

One task

Run one task and exit, with exit codes for scripts and CI.

nav run -p "…"

Or build your own client

HTTP for commands, Server-Sent Events for the stream. Every event carries a sequence number, so a client can reconnect and pick up where it left off. nav serve listens on loopback by default.

Server reference 
# start a session
curl -s -H 'content-type: application/json' \
  -d '{"workspace":"'"$PWD"'"}' 127.0.0.1:7310/v1/sessions

# follow it (resume with Last-Event-ID)
curl -N 127.0.0.1:7310/v1/sessions/<id>/events
id: 42
data: {"kind":"llm.delta", …}

Your models

Bring the gateways you already use.

models.json lists what you can reach, named gateway/id. config.json says which model each layer and agent uses. Change it from /config, VS Code or the browser; a session can switch its own model without touching the file.

// ~/.config/withnav/config.json
{
  "layers": {
    "reflex": "inception/mercury-edit-2",
    "instinct": "omniroute/typesafe/jev-1.13",
    "metacognition": {
      "model": "omniroute/combo/deepseek-v4-flash",
      "variant": "low"
    }
  },
  "default_agent": "build",
  "agents": {
    "build": { "model": "omniroute/cc/claude-opus-5-5" }
  }
}

Install

Pick the package for your setup.

Every release on GitHub ships ready-to-install files for Linux, with SHA256SUMS to check them.

VS Code on Linux

One package for x64 and one for arm64. Each has nav inside, so there is nothing else to install.

withnav-linux-x64-<version>.vsix

Universal VSIX

No binary inside. It uses nav from your PATH, or the path in withnav.serverPath.

withnav-<version>.vsix

The nav binary

Static Linux binaries for x64 and arm64, as tarballs. One nav runs the terminal, the browser and the server.

nav-<version>-x86_64-unknown-linux-musl.tar.gz

Nix

The flake builds both. Its overlay adds pkgs.withnav and pkgs.vscode-withnav.

nix build github:PixmaNts/withnav#withnav

From source

Clone the repository and build with cargo (Rust 1.89 or later).

cargo build --release --bins
Latest release Install guide

The extension needs VS Code 1.91 or later. It is not on the VS Code Marketplace yet: install the VSIX file with code --install-extension. Native Windows is not supported; use WSL or a VS Code Remote window with the Linux package. Then add your gateways and keys (see the quick start) and run nav doctor to check the setup.

Free and open source, dual-licensed MIT or Apache-2.0.

WithNav is developed in the open on GitHub. Read the code, ask a question, open an issue, or send a pull request to develop.

github.com/PixmaNts/withnav Discussions How to contribute
  • MIT OR Apache-2.0
  • Rust · TypeScript
  • Runs locally, with the model gateways you choose