A handler named CIPHER assigns you "missions" that are really Vim
exercises — restore CORP-corrupted documents, fix glitched transmissions, beat
the clock. You end up learning Vim almost by accident; the spy-thriller is the
hook. Same game ships three ways from one codebase: a web app, an Obsidian
plugin, and a native desktop app.
Screenshots
Features
- Story-driven campaign — a curriculum of Vim missions (motions, find-char, the dot
command, operators, text objects, search & replace, macros, registers, visual-block,
global commands, regex) wrapped in a narrative that unlocks progressively as you level up.
- Real editor — CodeMirror 6 with actual Vim keybindings, not a fake terminal.
- THE RAVEN sandbox — free-play: fix N injected glitches against the clock,
beat your best (EASY / NORMAL / HARD).
- Progression & mastery — XP, levels, progressive mission unlock, streaks, and
gold/silver/bronze par-tiers that score each run by keystrokes; progress saved
locally in your browser.
- Terminal / CRT aesthetic — restrained phosphor-green "Kuro" theme, monospace,
optional scanline.
- Plays anywhere — in the browser with no install, or as a ~3 MB native desktop
app (macOS / Windows / Linux).
Play
Run from source
npm install
npm run dev # web app → http://localhost:5173/
npm run build # full build (content → web)
npm test # test suite
npm run build:dmg # native desktop app + macOS DMG (needs Rust + Xcode CLT)
Contributor guide: CONTRIBUTING.md · architecture & internals
for agents/maintainers: AGENTS.md.
Manual
New players start with the Player Manual — a
Diátaxis-structured guide:
- Tutorial — play through your first mission, no Vim
knowledge needed.
- How-to guides — the sandbox, scoring, unlocks,
desktop install or build, the CIPHER uplink, resetting progress.
- Reference — the Vim keymap
and ranks & unlocks (generated from the game
data via
npm run build:manual).
- Explanation — why NeuroVim is shaped the way
it is.
Contributors and maintainers: the Developer docs follow the
same four-part structure.
Architecture
TypeScript · Preact · CodeMirror 6
A small monorepo (npm workspaces): a platform-neutral core (game logic, Web
Audio, Preact UI) with thin adapters for the web, Obsidian, and desktop. No
UI kit, no CSS framework. See AGENTS.md for the architecture.
Why there is a build step: the editor is the product here, and CodeMirror 6
only exists as an npm module graph — there is no single-file drop-in. On top of
that, one source tree has to come out as three different artifacts: a lazy-loading
web bundle and static assets for the Tauri desktop shell — and the same core is
vendored by the Obsidian plugin in its own repo. A bundler is what keeps that one
codebase instead of three.
Consumers
This repository is the upstream for every NeuroVim target. The vendor surface is
packages/core/src (game logic, engines, ports) plus packages/content/src
(missions and lore). Everything else — the web app, the Tauri project, the scripts —
is a consumer of that surface, not part of it.
To build on it: copy the surface into <your-repo>/src/vendor/neurovim/ and pin the
origin in a VENDOR.json next to it (source, tag, sha, version). Never edit
the copy — change it here and re-vendor. A copy that is edited in place is silently
discarded by the next re-vendor.
Current consumers and how far their pins lag: CONSUMERS.md.
Contributing
Issues and PRs welcome on git.jkaindl.de.
Please read CONTRIBUTING.md first.
License
NeuroVim is dual-licensed — see LICENSING.md.
- Open source: GNU AGPL-3.0 — copyleft with the network-use clause:
if you host a modified version so others can use it over the network, the source
of your variant must also be made available under the AGPL.
- Commercial license: for uses that the AGPL does not fit — e.g. a proprietary
or closed-source product, or an Apple App Store build (App Store terms are
incompatible with the AGPL) — a separate commercial license is available. See
LICENSING.md; contributions are covered by the CLA.
Documentation and narrative text (docs, missions, lore) are licensed under
CC BY-SA 4.0. The bundled JetBrains Mono font is under the
SIL Open Font License.
