README file from
GithubNeuroVim (vim-dojo)
🇬🇧 English · 🇩🇪 Deutsch
Learn Vim by playing a cyberpunk spy-thriller — inside Obsidian.
An AI handler named CIPHER assigns you "missions" that are really Vim exercises: restore CORP-corrupted transmissions, beat the clock, earn XP. You learn Vim almost by accident; the story is the hook.
NeuroVim originally started life as an Obsidian plugin, then grew into a multi-target
game (neurovim-standalone: web + desktop +
Obsidian). vim-dojo brings it back home as a first-class, standalone Obsidian plugin.
Features
- 54 playable missions across two story arcs — 40 story transmissions and 14 katas, each one a Vim exercise disguised as a transmission repair job. Missions unlock as you level up.
- Real Vim, real notes. Missions materialize as throwaway notes you edit with Obsidian's own Vim mode — not a simulator, not a sandbox widget.
- Mission HUD with live line progress, elapsed time, keystroke count, and a diff highlight that clears each line the moment you get it right.
- Hints on demand — character-precise, showing exactly where your line diverges
(
ex»it«vsex»fil«). - XP, levels, and best scores per mission (time and keystrokes), so a mission you already solved becomes a speedrun target.
- Pause-safe. Leave the mission note and the timer stops, Vim mode is restored, and a banner offers RETURN or ABORT — no phantom keystrokes from typing elsewhere.
- CIPHER uplink (optional) — in-character Vim advice and post-run debriefs from any OpenAI-compatible LLM endpoint, including fully local ones — or Claude, through the LLM Endpoint Manager.
- Cheatsheet — a searchable Vim reference built into the pane.
Requirements
- Obsidian 1.11.4 or newer, desktop or mobile.
- Obsidian's Vim mode (Settings → Editor → Vim key bindings) for the intended experience. Without it the game still works — you just fix transmissions without Vim keybindings, which rather misses the point.
- Optional, for CIPHER only: an OpenAI-compatible endpoint (LM Studio, Ollama,
OpenRouter, …). Leave the endpoint list empty and the whole feature stays off. Setting up
a local LLM server is covered once, centrally, in the
local LLM setup guide — including the
/v1pitfall and reaching your desktop server from a phone. - Optional, for Claude: the LLM Endpoint Manager plugin with a Claude entry (API key in the manager's keychain). CIPHER then sends its questions to Anthropic's API instead of a local model whenever that entry is the one in use — see the choice rule under CIPHER uplink below.
Install
From the community store: Settings → Community plugins → Browse → search "NeuroVim" → Install → Enable.
Manually, from a release: download main.js, manifest.json and styles.css from the
latest release into
<vault>/.obsidian/plugins/neurovim/, then enable NeuroVim under Community plugins.
Building from source is described under Develop / build from source.
Usage
Open the pane via the ribbon's terminal icon or the command NeuroVim: Open hub. It is organized in tabs:
- NEXUS — your status (level/XP), the welcome transmission, and a one-click "next mission" button.
- MISSIONS — the full mission list.
- ARCHIVE — the lore artifacts you have earned.
- GUIDE — a searchable Vim cheatsheet (filter by key or description).
- UPLINK — the CIPHER chat (appears once an endpoint is configured).
A mission runs like this:
- Pick a mission (or hit "next mission"). A briefing explains the objective; BEGIN MISSION materializes the transmission as a note and starts the timer.
- Fix the corrupted lines in the note using Vim. The HUD tracks progress, time and keystrokes; HINT points at the first line that still diverges.
- SUBMIT when the text matches. You earn XP, and your time and keystroke count are recorded — beating them later is the actual game.
Commands available in the palette: NeuroVim: Open hub, NeuroVim: Submit mission, NeuroVim: Reset mission.
Configuration
Settings → NeuroVim, grouped into Missions, Appearance, and CIPHER uplink; each section remembers whether you left it open or closed.
Missions
- Mission folder — where throwaway mission notes are created (default
_neurovim/). - Hide mission folder — hides it in the file explorer (display only; the folder still exists and still syncs). Off by default.
- Auto Vim mode — turn Obsidian's Vim mode on while a mission is active and restore your previous setting when it ends. Note that this changes your global editor Vim setting for the duration.
- Open pane on startup — off by default; the pane opens only when you ask for it.
- Paused reminder after — minutes a paused mission may sit before the floating
reminder appears;
0disables it. A paused mission always shows in the status bar either way. - Record run traces — see Run traces & privacy.
Appearance
- HUD placement — where mission control (timer, submit/reset/abort) appears during a mission. The floating box can also be dismissed per mission via its × button.
- CRT color scheme — on: a fixed cyberpunk look (dark background, phosphor green), theme-independent and always legible. Off: adaptive colors that blend into your light/dark Obsidian theme.
CIPHER uplink
- Endpoints — an ordered list rather than a single URL. The first reachable endpoint
wins, so one synced list covers the same local LLM server showing up as
localhostat your desk and as a LAN IP on the road. Add endpoints via presets or by typing a URL; "Test connection" probes every entry and marks the active one. Existing single-endpoint configs from 0.4.x migrate automatically — nothing to do on upgrade.
If the LLM Endpoint Manager plugin is installed, the endpoints (and their keys) come from it instead: the settings then offer an endpoint and model choice, and your local list stays as a fallback for when the manager is off. If the manager reports no endpoint, there is no fallback to the local list.
Claude (Anthropic): Claude is only offered through the manager: with a Claude entry in its list, CIPHER can use it, and then your questions go to Anthropic (not to a local model). With the choice on "Automatic" the first reachable, enabled chat entry in the manager's list order wins, so a Claude entry placed above your local one is used first; pick your local endpoint explicitly in the settings, or move it up in the manager's list, if you want CIPHER to stay local. Without the manager nothing changes.
- Model — picked from a dropdown populated by the active endpoint's
/v1/models, with a free-text fallback if the list is empty or the endpoint is unreachable. When the endpoint reports it (LM Studio, Ollama), the model's context length is shown below the endpoint row. - Request — what CIPHER sends with each question: sampling values (temperature, top_p, top_k, …) and the thinking level. The defaults come from a profile table per model family (Qwen, Gemma, gpt-oss) and backend, so a model gets the settings its vendor recommends instead of one fixed set for all. The section (collapsed by default) shows what is sent and what has an effect, lets you override a value per model family, and lists the last request and any deviations seen this session. Thinking is off by default, which is the faster path: CIPHER answers straight away instead of deliberating; set a level to let the model reason first. gpt-oss cannot be switched off entirely, so its lowest level is sent.
- API key — optional, for endpoints that require one. It is kept in Obsidian's keychain, not in the plugin's
data.json; a key from an earlier version moves there the first time CIPHER connects (or when you open these settings).
How it works
- Content is bundled in the plugin — the story is earned by playing, never spoiled by files sitting in your vault. Missions unlock progressively as you level up.
- Menus, story, and progression live in a plugin pane (NEXUS). XP and best times are
stored by the plugin (
data.json). - Missions materialize as throwaway notes in a folder you configure (default
_neurovim/). You fix the transmission in a real Obsidian note with real Vim mode. Deleting a mission note — or the whole folder — loses no progress; the next mission re-creates it. (Fits the lore: transmissions are ephemeral.)
The plugin never touches files outside the configured mission folder.
CIPHER uplink (experimental, optional)
Ask CIPHER for Vim advice — in character, powered by any OpenAI-compatible endpoint (LM Studio, Ollama, OpenRouter, …) or by Claude through the LLM Endpoint Manager. Configure endpoint + model under Settings → NeuroVim → CIPHER uplink; leave the endpoint list empty and the feature stays fully off. During a mission, the HUD gains a CIPHER button that opens the uplink with the mission's context attached.
A model row at the top of the UPLINK tab shows which model CIPHER is using and lets you switch without leaving the pane: the dropdown lists the models of the active endpoint ("Automatic" lets the endpoint decide), "Reload models" asks the endpoint again, "Other endpoint …" opens the LLM Endpoint Manager when it is installed, and the thinking toggle sits in the same row ("Thinking: off" switches it on at your last level; a level picker instead of the toggle is a setting under Request). The row is locked while CIPHER is answering.
Privacy: What goes out with the chat: your question, the earlier questions and answers of the same chat, and — with a mission active — its ID, title, category, the line on why the skill matters and the par; plus the bundled Vim quick reference and key cheatsheet that CIPHER works from. A debrief sends the same mission fields, the keystroke count, the time and the keystroke sequence of the run. Never any other vault content. It goes to the endpoint in use: a local one keeps it on your machine, a hosted one and Claude (Anthropic) do not.
Run traces & privacy
NeuroVim can record the keystroke sequence of each successful mission to a local file
(traces.jsonl, inside the plugin folder). This powers CIPHER's debrief ("you walked to
word 3 with l l l — 3w is one move") and lets you analyse mission balance offline.
- Local only. Traces are written to your vault's plugin folder and never sent anywhere automatically. Requesting a CIPHER debrief sends that run's sequence to the LLM endpoint you configured (a local model via LM Studio/Ollama stays on your machine) — the same connection the CIPHER chat already uses.
- Claude gets the key sequence too. If CIPHER uses a Claude entry of the Endpoint Manager, a debrief sends the run's sequence to Anthropic.
- Scoped. Only keystrokes inside an active mission's editor are recorded. Nothing else in your vault is ever touched.
- Optional. Turn it off in Settings → "Record run traces". Delete
traces.jsonlanytime.
Documentation
Start at the documentation index:
- Getting started — from the install to your first finished mission.
- Troubleshooting — the message you see, what it means, what to do.
Develop / build from source
npm install
npm run vendor # snapshot @neurovim/core + @neurovim/content from the monorepo
npm run build # → main.js
npm run gate # lint + typecheck + tests
npm run vendor reads the monorepo from NEUROVIM_MONOREPO (default: the maintainer's
checkout of neurovim-standalone at ~/Projects/jkaindl/apps/neurovim —
set the variable if yours lives elsewhere) and writes a pinned snapshot into
src/vendor/neurovim/ (see src/vendor/neurovim/VENDOR.json). The monorepo remains the
single source of truth for game logic and content.
npm run lint runs eslint-plugin-obsidianmd — the same rule set the community store
scans with — at --max-warnings 0. Manual smoke test:
docs/SMOKE.md.
Before opening a pull request, please read
CONTRIBUTING.md —
in particular which changes belong here and which belong in the monorepo. Conventions live in
AGENTS.md, the architecture in
docs/internal/architecture.md, the known gotchas per area in
.claude/rules/.
Release
npm run release <version> follows the ecosystem's dual-push flow (Forgejo origin +
GitHub mirror; the GitHub tag triggers the community-store release). The release tooling
itself lives centrally in ../tools/release/, so releasing requires the repo to sit inside
the obsidian-plugins/ workspace; building and testing work from a standalone clone.
Prerequisites, set up once: a Forgejo repo as origin, a github remote
(git remote add github [email protected]:<owner>/<repo>.git), and ~/.forgejo-token.
Security
The plugin never touches files outside the configured mission folder, and makes no network
requests until you configure a CIPHER endpoint. What gets recorded, what gets sent where, and
how to report a vulnerability privately:
SECURITY.md.
License
- Code: GNU AGPL-3.0-or-later.
- Documentation & text: CC BY-SA 4.0.
- Missions and story: inherited from the monorepo under CC BY-SA 4.0.
A commercial license is available for uses the AGPL does not fit — see
LICENSING.md.