Neovim Text Where You Already Edit

The short answer: in Neovim, enter insert mode in a buffer (markdown, init.lua, commit message, or a scratch note for :help-style text), press ⌃+⌥+R (Mac) or Ctrl+Alt+R (Windows/Linux) to start recording, speak, press the hotkey again to stop, and AICHE inserts transcribed text at your cursor. Press Esc and keep editing with normal-mode motions.

Neovim is where you already write prose: README sections, comment blocks above functions, vim.g and require() explanations in Lua config, notes while reading :help, and commit messages when git opens $EDITOR. AICHE does not run inside Neovim as a plugin. It is a desktop app that inserts into whichever terminal field has focus, including Neovim in insert mode inside tmux, WezTerm, Kitty, or Alacritty.

The Problem

Neovim optimizes navigation and edits, not long typing sessions. You :help a option, understand it, then still need sentences in a config comment or team doc. Treesitter gives you precise highlights once queries and parsers are set; explaining those choices in init.lua means paragraphs at the keyboard. Git opens Neovim for the commit subject and body; most commits stay one line because the body is tedious to type. Markdown buffers and COMMENT blocks suffer the same gap: you know what to say, the editor waits for keys.

What Changes

Toggle recording in insert mode so you never leave the buffer workflow. Speak the :help summary you wish existed, the rationale for a require('nvim-treesitter.configs').setup block, or the full commit body. AICHE runs cloud-default transcription. Audio streams to Groq and is discarded immediately after processing, within 1 second. Optional Message Ready cleanup adds punctuation and drops filler before insert.

Math: speaking runs about 150 words per minute. Typing in a terminal runs about 40. A 150-word commit body that takes four minutes to type takes about one minute to speak.

How It Works

1. Install AICHE on macOS, Windows, or Linux.
2. Open Neovim in your terminal (or GUI wrapper). Use your usual $EDITOR for git.
3. Move the cursor to where text should go. Enter insert mode (i, a, o, or a mapping).
4. Press ⌃+⌥+R (Mac) or Ctrl+Alt+R (Windows/Linux) once to start. The hotkey is toggle on/off, not push-to-talk.
5. Speak. Pause between sections if you want paragraph breaks in markdown or commit bodies.
6. Press the hotkey again. AICHE transcribes and inserts at the cursor. You stay in insert mode until you press Esc.
7. Edit with Neovim motions, save, and continue (:wq on commit messages as usual).

Offline: recordings queue locally and process when connectivity returns.

Profiles: turn on the Software Development profile (Pro) for snake_case, require(), LSP server names, and Treesitter parser names. Add repo-specific terms under Custom Vocabulary.

:help and Documentation Buffers

:help pages are Vim's canonical docs. When you are writing internal docs, a scratch buffer, or a team wiki page in markdown that mirrors help style (*tag* lines, section headers), dictate the explanation while the :help window is still open on another split.

Workflow: :vsplit your notes file, insert mode in the notes split, toggle hotkey, speak a concise definition of the option you just read (what it does, default, when to set it). You get readable prose without transcribing help verbatim.

For plugin README sections you maintain in-repo, the same loop applies: cursor in doc/*.txt or README.md, insert mode, dictate install steps and caveats.

Lua Config Comments (init.lua, lua/)

Neovim config is Lua: require, opts, lazy.nvim specs, LSP on_attach hooks. Future you needs why a line exists.

In init.lua or lua/plugins/treesitter.lua, enter insert mode on the comment line above a block and dictate rationale: which parsers you enabled, why ensure_installed lists those languages, indent rules, and highlight groups you customized. Dictate keymap comments the same way (-- space f f: Telescope files, respect .gitignore via file_ignore_patterns).

AICHE inserts plain text. You add -- or --- comment leaders and run gq or formatter if you want wrap at 80 columns.

Treesitter and Syntax Context

Treesitter drives highlighting, indentation, and textobjects once configured. Comments in config should name real parsers and queries (bash, typescript, query for injections) so teammates know what breaks if someone removes a parser.

Dictate above your nvim-treesitter setup: which filetypes use custom queries, why you injected javascript into tsx, or that a large node_modules tree is excluded from highlight via disable on size. You are not dictating code; you are dictating the design note that makes the Lua block maintainable.

In source buffers, use insert mode above a complex function to add a block comment explaining control flow. Neovim does not auto-format docstrings; you shape --- or // after insert.

Markdown Buffers

Project docs live in markdown buffers: README.md, ARCHITECTURE.md, CONTRIBUTING.md. Neovim treats them like any other file.

Insert mode at the heading level you need, toggle hotkey, speak the section (install, env vars, failure modes). Lists and code fences you can add after insert with textobjects and snippets you already use. The win is getting paragraph substance down without leaving the terminal.

Git Commit Messages in the Terminal

When git commit opens Neovim, you get a subject line and body. The subject should stay short; the body carries context reviewers need.

Insert mode in the body (below the comment # lines), toggle hotkey, speak: what changed, why, risk, test commands run, and follow-ups. Stop recording, :wq. Your message follows normal git format; you only skipped typing the body.

For git rebase -i or merge commit templates, the same insert-mode dictation works in any commit buffer Neovim opens.

Toggle Recording in Insert Mode

You do not need normal mode to record. Start and stop from insert mode so the cursor never moves to a different mode mid-thought. If you need to fix a word, stay in insert mode and use Neovim edits on the inserted text.

If the hotkey conflicts with a Neovim mapping, change the AICHE hotkey in settings or unmap the conflicting chord in Lua. Default AICHE chords do not overlap default Vim leader keys.

Common Questions

Q: Does AICHE work inside tmux or SSH Neovim?
A: Yes, when Neovim runs in a terminal on the machine where AICHE is installed and that terminal window has focus. If you SSH from a laptop into a remote server, AICHE on the laptop still inserts into your local terminal window (the SSH session) as long as that window is focused. You only need AICHE installed on the remote machine when you use a remote desktop or GUI session on that host without a local terminal in front of you.

Q: Will dictation break insert mode or Tree-sitter highlight?
A: Insert is text at the cursor. Syntax highlighting updates as for typed text. Save with :w as usual.

Q: Can I dictate into the command line (:)?
A: AICHE inserts into the focused field. For : commands, click the command line, enter insert there, then use the hotkey. Most people dictate into buffers, not ex commands.

Q: Code with lots of symbols and backticks?
A: Use the Software Development profile and Custom Vocabulary. Speak symbol names plainly; add backticks in Neovim after insert if markdown requires them.

Q: Does AICHE run :help or commit for me?
A: No. It only inserts text. You run :help, git commit, and plugins yourself.

Result: Neovim keeps handling navigation and edits; long-form text (:help notes, Lua comments, Treesitter rationale, markdown, commit bodies) arrives at speaking speed without a separate dictation app or GUI editor.

Try it now: open init.lua, put the cursor on a comment line above a plugin you barely remember, enter insert mode, toggle the hotkey, and explain in one minute what that plugin does and which keys you bound.