Navi

Navi is my personal terminal code editor: familiar enough to start using immediately, but built for real projects with an explorer, editing, search, Git, C++ tests, Build / Run actions, Todos, and integrated terminals.

This repository is my personal workbench, built first for my Linux and Windows workflow. It is public for collaboration and learning, not a polished general-purpose editor or a promise of support for other users. macOS is not a supported target right now: I do not build or test it, and it may or may not work.

Why Navi?

Navi reflects what I want from an editor: direct navigation through code, projects, tools, and terminals without turning the experience into a maze.¹

It is written in modern C++, uses FTXUI for the terminal interface, and is released under the MIT license. The current version is 0.1.0-dev.

What works today

• A mouse- and keyboard-friendly Explorer with expandable folders, automatic refresh, hidden-file filtering, file opening, and confirmed deletion.
• A NAV/EDIT editor model with tabs, precise mouse cursor placement, drag selection, clipboard operations, undo/redo, scrolling, session restore, and batched review of files changed by another process.
• File find and replace, plus fast Git-ignore-aware project search and replace powered by rg. A project-wide replacement can be undone in one operation.
• Syntax highlighting for C++, Typst, BibTeX, and TeX/LaTeX, with a lexical fallback for other text formats.
• Terminal, Find, Search, Tests, Git, Build / Run, and Todo tool tabs.
• CTest discovery and execution with live progress, failed tests first, and source navigation when CTest reports a file location.
• Git status, staging, diffs, commits, and paged history through the installed Git CLI.
• Named, long-lived terminals that can be created, switched, and closed independently while Navi is running, with launch presets for Bash, Codex, Claude, and Copilot plus their interactive resume pickers.
• Project Todos with completion state, deadlines, and one active time tracker.
• Midnight, High Contrast, and Paper themes; workspace layout and open files are restored from navi.json.
• Read-only PNG previews rendered directly in compatible terminals.

Navi has no dedicated agent protocol layer. Codex, Claude, and Copilot run as their real CLI tools in Navi's named terminals, alongside ordinary build and development shells.

Build

Navi requires CMake 3.28 or newer, Git, and a C++20 compiler. Clone its pinned Tree-sitter and vcpkg submodules before configuring. CMake bootstraps the pinned vcpkg checkout and installs the manifest dependencies automatically.

git submodule update --init --recursive
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel
ctest --test-dir build --output-on-failure
./build/navi --help

The release presets statically link third-party dependencies and package a single executable. A Linux host can build both supported targets. The Windows cross-build also requires MinGW-w64 and Ninja.

cmake --preset linux-release
cmake --build --preset linux-release --parallel
cpack --config build/linux-release/CPackConfig.cmake -C Release \
  -B build/linux-release/packages

cmake --preset windows-release
cmake --build --preset windows-release --parallel
cpack --config build/windows-release/CPackConfig.cmake -C Release \
  -B build/windows-release/packages

Project search requires rg on PATH. On Linux and macOS, terminal sessions use Bash. On Windows, Navi prefers PowerShell 7, then Windows PowerShell, and falls back to Command Prompt. Git Bash is also offered as a terminal preset when bash.exe is available on PATH; it is optional. Git features similarly require the Git CLI.

Run

Open a directory as a workspace, or open a file directly:

./build/navi path/to/project
./build/navi +42 path/to/file.cpp

Usage: navi [OPTIONS] [PATH]

  +LINE          Open PATH at a positive line number
  --wait         Wait until the opened buffer is closed
  --safe         Do not trust project configuration or restore project state
  --no-restore   Start without restoring the previous workspace
  --config PATH  Use this global configuration file
  --health       Report detected tooling and configuration paths
  --version      Print Navi version
  -h, --help     Show help

Opening a file starts in NAV mode. Press i to edit and Esc to return to NAV mode. Mouse clicks place the cursor and dragging selects text. Ctrl+C, Ctrl+X, and Ctrl+V copy, cut, and paste; Ctrl+Z and Ctrl+Y undo and redo.

The most useful global shortcuts are:

Shortcut	Action
Ctrl+S / Ctrl+Q	Save / quit gracefully
Alt+N / Ctrl+O	New file / open file
Ctrl+N / Ctrl+P / Ctrl+W	Next buffer / previous buffer / close buffer
Ctrl+F / F3	Find in file / next match
Ctrl+G	Search project with ripgrep
Ctrl+R	Replace the current Find or Search result
Ctrl+B / Alt+X	Toggle Explorer / focus Explorer
Alt+E / Alt+T	Focus editor / focus or cycle tool tabs
Ctrl+L or F9	Show or hide the tool panel
Ctrl+T	Open the Terminal tool and choose a preset when it is empty
Alt+R	Lock or unlock tool-panel resizing
Ctrl+Up / Ctrl+Down	Resize an unlocked tool panel
F4 / F5	Trust project / run the default Build / Run action
F6 / F7 / F8	Git status / stage or unstage / commit
F1	Show the in-editor shortcut reference

When the Explorer has focus, use arrows or j/k to move, Enter or Right to open, . to toggle hidden files, and D or Delete to request deletion. Navi refuses to delete an open file or a folder containing one.

Opening an empty Terminal tool or pressing Alt+N opens the preset picker; every terminal starts from that same flow. Alt+J/Alt+K switches terminals, Alt+M names one, and Alt+W closes one. Presets can start or resume Codex, Claude, and Copilot sessions. Agent presets are shown only when their CLI executable is available on PATH. Input and common control keys such as Ctrl+C, Ctrl+D, and Ctrl+L are sent to the active terminal.

Find and replace

Ctrl+F opens file find. Type the text and press Enter; the Find tool lists all matches, and F3 moves to the next one. Press Ctrl+R from the results, enter the replacement, then choose one replacement or all replacements.

Ctrl+G follows the same workflow across the workspace. It invokes ripgrep with Git-ignore handling and presents matches in the Search tool. Project replace reviews the matches before changing files; it does not open every matching file as an editor tab. A single Ctrl+Z undoes the most recent project-wide replace operation.

Tools

The bottom panel contains independent tools. Alt+T focuses it and repeated presses cycle its tabs; mouse clicks work as well.

• Find and Search keep navigable result buffers for file and project queries.
• Tests discovers CTest build trees. If several candidates exist, Navi asks which one to use and saves it in navi.json. Runs update interactively and sort failures to the top when complete.
• Git shows status, diffs, staging state, commits, and incrementally loaded history.
• Build / Run executes explicitly configured project actions after the project is trusted.
• Todo stores items, completion, deadlines, and tracked time in the project configuration.
• Terminal hosts multiple named Bash or coding-assistant CLI sessions in the workspace directory.

The panel can be resized with the mouse or keyboard after it is unlocked. Its height, lock state, visibility, and active tab are restored on the next launch.

Project configuration

Each workspace can contain a visible navi.json. User-owned settings and Navi-owned workspace state live together in this file; Navi preserves configured actions while updating its own state. There are no legacy configuration aliases.

{
  "$schema": "runtime/schemas/project-config.schema.json",
  "schemaVersion": 1,
  "name": "My project",
  "editor": {
    "tabSize": 2,
    "formatOnSave": false
  },
  "buildRun": {
    "configure": {
      "command": ["cmake", "-S", ".", "-B", "build"]
    },
    "build": {
      "command": ["cmake", "--build", "build", "--parallel"]
    },
    "test": {
      "command": ["ctest", "--test-dir", "build", "--output-on-failure"]
    }
  },
  "tests": {
    "cppBuildDirectory": "build"
  }
}

The complete machine-readable definition is in runtime/schemas/project-config.schema.json. Configured Build / Run actions are disabled until the project is trusted. Commands normally use an argument array; a shell action must explicitly set "shell": true and provide one Bash script string. Working directories cannot escape the project root.

Navi automatically persists the selected theme, Explorer and tool layout, hidden-file preference, active tool, open files, active file, Todos, deadlines, and time-tracking state. --safe ignores both trust and restored workspace state for that launch.

Recovery and language support

Unsaved edits are appended to a recovery journal. If a later launch finds one, Navi pauses editing until F2 restores it or F3 discards it. Cursor and viewport state are restored per document unless --no-restore or --safe is used.

C++, Typst (.typ), and BibTeX (.bib) highlighting use pinned Tree-sitter grammar submodules. The maintained LaTeX grammar source is pinned too; until its generated parser is incorporated reproducibly, TeX/LaTeX (.tex, .latex, .sty, and .cls) uses the lexical highlighter. Other text formats currently use the same fallback.

Crash reports

Navi installs its crash reporter before processing command-line arguments. On Linux, fatal signals write a native stack trace and still preserve the normal core-dump behavior. On Windows, Navi writes both a readable stack report and a minidump. Reports are retained only after a crash under the platform state directory's crashes folder; navi --health prints its exact location.

Keep the report together with the exact Navi executable that produced it, since native addresses can otherwise change between builds.

Scope and CI

Navi is in active development. Linux x64 and Windows 11 x64 are the supported targets; direct Windows testing remains important for ConPTY and terminal input. The next editor-facing priorities are stronger C++ and Python code navigation, support for my own languages, debugger integration, and richer Git workflows.

GitHub Actions builds and packages Linux x64 and a statically linked Windows x64 executable on Ubuntu. CI intentionally does not run the local test suite. The packaged executables are uploaded as workflow artifacts.

Footnotes

1. The project was originally called Vijai, after me, before I renamed it Navi. ↩