NeuroVim

by Johannes Kaindl
5
4
3
2
1
Score: 55/100

Description

NeuroVim — learn Vim by playing a cyberpunk spy-thriller, inside Obsidian.

Reviews

No reviews yet.

Stats

0
stars
5,365
downloads
0
forks
113
days
5
days
5
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
354
commits

Latest Version

5 days ago

Changelog

Added

  • A "Status bar" switch in the settings (Appearance group), on by default. It shows or hides the mission timer in the status bar. An existing install keeps the timer; turning the switch off removes the entry, turning it on puts it back at the end of the bar. With the entry hidden a paused mission is no longer visible there (the floating reminder after the configured minutes still appears). The status bar is not shown on phones.

Changed

  • The model row in the CIPHER pane lists the models of every endpoint, grouped by endpoint. With the LLM Endpoint Manager installed the dropdown shows one group per endpoint (its "Default" entry, then its models) and picking a model also fixes its endpoint. A stored choice whose endpoint was switched off or deleted shows "Automatic" with a warning icon and the reason instead of silently sending the old model name to the automatic endpoint; the stored choice itself is left alone. The "Another endpoint …" entry is now "Manage endpoints …" and appears only when the manager is installed.
  • Thinking is a level dropdown inside the model row (the levels of the chosen model, the icon in front) instead of an on/off button next to it; models without levels show no control.
  • The model row and the model choice now name and bind the endpoint the manager really uses (before: the first enabled one, even when it was unreachable). A model choice made while its endpoint is switched off or deleted now acts on the automatically chosen endpoint.

README file from

Github

NeuroVim (vim-dojo)

🇬🇧 English · 🇩🇪 Deutsch

License: AGPL-3.0 Docs: CC BY-SA 4.0 Release Downloads Platform

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« vs ex»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 /v1 pitfall 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:

  1. Pick a mission (or hit "next mission"). A briefing explains the objective; BEGIN MISSION materializes the transmission as a note and starts the timer.
  2. 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.
  3. 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; 0 disables 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.
  • 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 localhost at 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.

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.jsonl anytime.

Documentation

Start at the documentation index:

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

A commercial license is available for uses the AGPL does not fit — see LICENSING.md.