Vim Coach

User Stats/Progress
User Goals (Suggested New Keystrokes)

Inspiration

Vim is powerful, but learning it usually happens away from the moments when a better command would actually stick. Cheat sheets teach commands in the abstract, while real editing habits are personal. I wanted a coach that could notice the exact edits I make, find a more idiomatic Vim sequence, and prove that the suggestion really works before teaching it to me.

What it does

Vim Coach is a native Neovim learning companion that stays quiet while you work. It captures bounded Normal, Insert, and supported Visual-mode editing and navigation episodes and queues them locally. When an episode is complete, analysis starts automatically. Episodes captured while analysis is running wait in a bounded queue and are included in the next batch; manual sync remains available for retries and debugging.

Every candidate—whether generated from a local feature catalog or proposed by an LLM—is replayed in a fresh headless Neovim process. A lesson appears only if the candidate reproduces the captured buffer, cursor position, final mode, and newline state while using fewer logical Vim keys. Unsafe, malformed, or incorrect suggestions are rejected.

Verified lessons go to a separate desktop review inbox instead of interrupting your flow. The inbox teaches one reusable Vim feature at a time, links to the relevant built-in :help documentation, and lets you dismiss a lesson or mark it as already known. Each new concept also becomes a learning goal, and Vim Coach tracks successful uses of the learned binding. A scratch-buffer practice mode lets you retry the latest captured edit without touching the original file.

How we built it

The Neovim plugin is written in Lua. It uses Neovim input callbacks and editor events to recognize bounded episodes, capture before/after state, and maintain an in-memory batch queue. A Python worker minimizes each episode and, when cloud analysis is explicitly enabled, sends it to an OpenAI-compatible model endpoint hosted on Modal.

The recommendation system is hybrid: a deterministic local catalog generates candidates for supported Vim features, and the model adds context-aware alternatives. Both sources pass through the same strict schema, grammar compiler, and replay verifier. The verifier launches disposable headless Neovim processes and compares concrete outcomes; model output is never executed as code.

A local Electron app reads the verified lesson and goal history and renders the review inbox, progress, and challenges. The project includes unit tests, replay fixtures, a reproducible minimal Neovim profile, and a deterministic 39-scenario evaluation corpus for the supported command grammar.

Challenges we ran into

The hardest problem was defining what “equivalent” means in a modal editor. Two commands can produce the same text but leave the cursor, mode, newline state, or registers different. Vim Coach therefore reports a precise editing-outcome guarantee rather than claiming universal Vim equivalence.

Automatic capture was another challenge. Neovim callbacks do not map perfectly to physical keypresses, and edits can span movements, mode changes, mappings, and idle boundaries. We built a small state machine with strict limits and fail-closed behavior for unsupported or ambiguous input.

We also learned that immediate AI popups were distracting. That changed the product direction: recording stays silent, analysis runs automatically in sequential batches, and learning moves to a dedicated review inbox.

Accomplishments that we're proud of

Suggestions are validated by actual replay, not trusted because an LLM said they were correct.
Provider failures degrade gracefully to locally generated, replay-verified candidates.
Raw source snapshots are not persisted. Cloud analysis requires explicit opt-in, and provider requests omit paths, registers, and unrelated buffers.
The supported feature catalog currently covers 54 replay-supported topics, and all 39 scenarios in the deterministic evaluation corpus verify their expected target.
New lessons become practice goals, and Vim Coach tracks whether the user actually starts using the learned bindings.

What we learned

AI is most useful here as a proposal engine, while deterministic software remains the correctness boundary. We also learned that good coaching is about timing and restraint: preserving flow matters as much as finding the cleverest command.

What's next for Vim Coach

Next we want to connect practice snapshots directly to the review inbox, expand the safely replayable Vim grammar, and improve curriculum ranking over time. We also want to measure whether verified, contextual lessons help users retain commands and reduce repeated inefficient patterns over longer sessions.