Learn Neovim through an epic three-act terminal quest — no Neovim required.
nvim-quest teaches real Vim motions and edits by making you use them. You press
the actual keys (h j k l, d w, c w, / …) and a live buffer reacts instantly,
exactly like the real editor. Solve rooms in as few keystrokes as you can for stars,
build combo streaks, guard your hearts, and beat the clock in boss fights.
✨ YOUR JOURNEY ✨
ACT 1 · THE CURSOR DOJO
> ▶ The Two Stances
🔒 First Steps
🔒 Way of the Word
🔒 The Great Leaps · boss: Sensei's Trial
ACT 2 · THE MOTION CRYPTS ACT 3 · THE NEON GRID
🔒 Hall of Insertion 🔒 Trace Evasion
🔒 The Deletion Pits 🔒 Power Surge · boss: The Grid Core
🔒 Echo Chamber
🔒 The Shapeshifter · boss: The Gravewright
With Go (recommended) — requires Go 1.24+. Lessons are embedded in the binary, so it runs from anywhere:
go install github.com/StrangeNoob/nvim-quest@latest
nvim-questThis installs to $(go env GOPATH)/bin (add it to your PATH if it isn't already).
Prebuilt binary — download the archive for your OS/arch from the
Releases page, extract it, and put
the nvim-quest binary on your PATH:
# example: macOS (Apple Silicon)
tar -xzf nvim-quest_*_darwin_arm64.tar.gz
sudo mv nvim-quest /usr/local/bin/Keep the binary named
nvim-questsonvim-quest updatecan self-replace it.
From source — clone the repo and:
go run . # start the game
go run . stats # print a progress summary
go run . reset # erase all progress (asks to confirm)nvim-quest # start the game
nvim-quest version # version, commit, build date
nvim-quest update # self-update to the latest releaseWhen a newer release exists, the title screen shows a ✨ vX available notice (a
throttled, background check; disable it with --no-update-check or the
NVIM_QUEST_NO_UPDATE_CHECK env var). To upgrade, run nvim-quest update (or
go install github.com/StrangeNoob/nvim-quest@latest).
Your progress is saved to ~/.nvim-quest/progress.json.
The game needs an interactive terminal at least 80×24. It runs on the Bubble Tea TUI framework.
You move through five screens: a welcome intro (first launch only), the world map, a room (a single challenge), a boss fight, and a results screen.
Navigation (menus & map):
| Key | Action |
|---|---|
j / k |
move selection down / up (arrow keys are intentionally disabled — it's a Vim trainer) |
enter |
play the selected lesson |
esc |
back to the title |
Inside a room you type real Vim keys. The HUD shows everything you need:
-- NORMAL -- ♥ ♥ ♥ ⚡x2 keys 4 · par 5
[?] hint · [esc] back to map
-- NORMAL --/-- INSERT --— the current mode (pressito type,Escto leave)♥ ♥ ♥— hearts: a wrong/disallowed key costs one; lose all three and the room resets (no XP penalty)⚡x2— combo: clearing rooms without losing a heart multiplies your XP (up to ×5)keys N · par M— par golf: solve in≤ parkeystrokes for ⭐⭐⭐,≤ par+2for ⭐⭐, otherwise ⭐[?]— toggle a hint at any time (free; never counts against par)
Boss fights end each act: a multi-step challenge against a draining timer. Run out of time and you retry from the first step.
| Act | World | Lessons | Vim covered |
|---|---|---|---|
| I | The Cursor Dojo | The Two Stances · First Steps · Way of the Word · The Great Leaps | modes & i/Esc, h j k l, w/b, 0 $ gg G |
| II | The Motion Crypts | Hall of Insertion · The Deletion Pits · Echo Chamber · Opening Lines · The Inner Cut · Rewind · The Shapeshifter | i/a, x dw dd, yy/p/P, o/O, ciw/diw, u/Ctrl-r, cw cc |
| III | The Neon Grid | Trace Evasion · Power Surge | / search & n, count prefixes (4w, 3dd, 4x) |
Each act has a distinct color palette (dojo greens, crypt embers, neon magenta/cyan) and ends with a timed boss. Lessons unlock sequentially; clearing an act's boss unlocks the next act.
The curriculum is inspired by Learn-Vim-and-NeoVim by Richard Callaby — see docs/LESSONS.md for the roadmap of future lessons.
go test ./... # full suite (engine, content, game, progress, ui)
go vet ./...
gofmt -l . # should print nothing
go build ./...Highlights of the test suite:
internal/engine— table-driven keystroke tests for every motion, operator, and editinternal/content— content-integrity test (every lesson parses, cursors are in bounds, goals/hints are populated) plus a solvability test that plays an optimal solution through the real engine for every challenge and asserts it's winnable at parinternal/ui— model-level screen-transition tests (menus, rooms, bosses, results)
- docs/ARCHITECTURE.md — package layout, the engine, and data flow
- docs/LESSONS.md — the lesson JSON schema, how to add a lesson, and the future-lessons roadmap
docs/superpowers/specs/anddocs/superpowers/plans/— the original design spec and implementation plan
Lessons are plain JSON files in assets/lessons/ — no code changes
needed. Drop in a file and the content-integrity test validates it automatically. The
schema and a worked example live in docs/LESSONS.md.
Released under the MIT License. The curriculum it's based on, Learn-Vim-and-NeoVim, is also MIT-licensed.