A fast, complete Neovim setup for people who read more code than they write.
Built for navigating large codebases, reviewing PRs without leaving the editor, and making surgical edits at typing speed. ~100 ms startup. Works on any Mac or Linux machine with one script.
curl -fsSL https://raw.githubusercontent.com/blankdean/tech-lead-nvim/main/install.sh | bashOr the cautious way (same result, and you can read it first):
git clone https://github.com/blankdean/tech-lead-nvim ~/.config/nvim
~/.config/nvim/install.shThe script installs dependencies (ripgrep, fd, node, a Nerd Font — even a
native-arch Neovim if Homebrew/distro nvim is too old or the wrong CPU),
backs up any existing config, and pre-installs every plugin. Then set your
terminal font to JetBrainsMono Nerd Font and run nvim. That's it. Same
Lua config on Mac and Linux; install.sh is the only OS-specific piece.
Leader is Space. Press it and pause — which-key shows you everything.
Mac users: every shortcut here means Control (⌃), never Command (⌘).
Ctrl-h= hold ⌃ and press h. Command stays with your terminal app (⌘C, ⌘T, ⌘Q work as usual).
| Key | Does |
|---|---|
Space ff / Space fg |
Find file by name / grep entire repo |
Space a → Space 1..4 |
Pin file → jump to pin (harpoon) |
s + two chars |
Jump to any visible text (flash) |
gd / grr / Ctrl-o |
Definition / references / jump back |
grn / gra |
Rename symbol everywhere / code action |
Space gm |
Diff your branch against main |
Space gg |
Lazygit |
Ctrl-h/j/k/l |
Move between splits and tmux panes |
Space xx |
All diagnostics in one list |
Space e |
File tree |
Space o |
Toggle focus between the editor and the file tree / review panel |
Full reference: CHEATSHEET.md
Don't browse — search. Space fg and type an error message, a route path, a
distinctive string. You're in the right file in three seconds. Then gd to
chase definitions down, Ctrl-o to walk back up, grr to see every caller
before you touch a signature.
Space | and Space - split the window (same keys as tmux). Ctrl-h/j/k/l
moves between splits — and straight out into your tmux panes, one mental model.
Pin the 3–4 files you're living in with Space a, then Space 1..4 teleports
between them. Faster than any tab bar. (Ctrl-1..4 also works in terminals
that support it — see Notes.)
Ctrl-d/Ctrl-u— half-page down/up, cursor stays centered{/}— jump by paragraph/blocks+ 2 chars — flash jump to anything you can see12j— relative line numbers are on: the number to jump is in the guttern/Nafter a search stay centered too
ma drops mark a on the current line, `a jumps back to it — perfect for
"I need to check something over there and come back." ` ` (backtick
backtick) bounces between your last two positions. Capital marks (mA) work
across files. For files you return to all day, harpoon pins beat marks.
Text objects are the whole game — i = inside, a = around:
| Type | Result |
|---|---|
ci" |
Change inside the quotes |
ci( ci{ ci[ |
Change inside the brackets |
ciw |
Change the word under the cursor |
cit |
Change inside an HTML tag |
dap |
Delete the whole paragraph |
yi( |
Yank what's inside the parens |
Replace one word everywhere: grn (LSP rename — safe, project-wide).
Replace text everywhere: * to search the word, ciw new word Esc, then
n . n . — repeat-jump, repeat-edit, approving each change as you go.
Surround anything: ysiw" wraps the word in quotes, cs"' changes quotes to
single, ds( deletes the parens. Comment with gcc.
v— character-wise: select, thenyyank /ddelete />indentV— line-wise: grab whole lines,J/Kmoves them up and downCtrl-v— block: column select,Ito insert on every line at once (add a prefix to 20 lines in one motion)
Yanks go to the system clipboard automatically — copy in nvim, paste anywhere.
. repeats your last edit. For anything bigger: qq records a macro, q
stops, @q replays it, 20@q replays it twenty times. Recorded a rename-and-
reformat on one line? Apply it to the whole file while you sip coffee.
Type def, for, if in any language — snippet suggestions appear in the
completion menu (friendly-snippets ships hundreds, every major language).
Enter accepts, Tab hops between placeholder fields. Add your own in
~/.config/nvim/snippets/.
In the current file — the :%s substitute command:
:%s/old/new/g " replace every occurrence in the file
:%s/old/new/gc " same, but confirm each with y/n
:%s/\<log\>/trace/g " exact word only — won't touch `login`
:10,40s/old/new/g " only lines 10–40Searched with /old already? :%s//new/g reuses the last search. Visual-select
first and :s/old/new/g replaces only inside the selection.
Across the whole project:
Space fg— grep the thing ("word" -wfor whole-word, capitals = case-sensitive)Ctrl-q— dump every match into the quickfix list:cdo s/old/new/gc | update— apply across all files, confirming each
For code symbols skip all that: grn renames via LSP, scope-aware, everywhere.
Space gd/Space gm— working-tree / branch changes in one code pane, with additions highlighted inline and removed lines shown in place.- In the
Space gmfile panel:Enteropens and focuses the selected diff; double-click orgfopens the editable local file in your editor tab.Space oswitches between the file panel and the last diff window. Space gf— full history of the current file; answers "why is this like this?":Octo pr list— browse PRs, check out, comment on lines, approve/request changes, all in-editor (needsgh auth login)Space gr— read the current or selected PR in CodeDiff's single-pane view. It fetches the PR without checking out its branch.Space gR(capital R) — Octo's interactive review for inline comments and approvals. From a CodeDiff PR tab, it targets that same PR. Octo does not support single-pane interactive reviews, so this explicit workflow still uses its split.Space o— switch between the bottom review file list and the code window. With the file tree open (Space e), switch between the sidebar and the editor. Repeated presses return to the same code window; if both panels are open, the most recently visited panel is used.Space gq— close the entire CodeDiff / Octo review layout and return to your editor tab, from either the file panel or a code window.Space gy— copy the PR link for sharing. Also works as:Octo pr urlfrom review panes or regular files; outside an Octo review, it uses the current branch.Space gp/Space gb— preview hunk / blame lineSpace gg— lazygit for staging, committing, interactive rebase
CodeDiff replaces Diffview for unified diffs, including history. Its matching
native diff library downloads during :Lazy sync (or on first use); the plugin version is pinned in
lazy-lock.json. Merge-conflict resolution remains a dedicated multi-pane tool.
Lazygit uses its native unified renderer; when a file has both staged and unstaged
changes, Lazygit may still show those two separate states.
If a library download fails, run :Lazy build codediff.nvim with network access
and restart Neovim. This also avoids repeated “loop or previous error loading
module” messages from a failed first load.
lazy.nvim · telescope + fzf-native · harpoon2 · flash · blink.cmp · conform · gitsigns · CodeDiff · octo · trouble · snacks · which-key · nvim-surround · vim-tmux-navigator · catppuccin
LSP (auto-installed via mason): pyright + ruff, ts_ls, bashls, jsonls, yamlls (with SchemaStore), dockerls, docker-compose, html, lua_ls. Formatting on save: ruff, stylua, prettier, shfmt.
Add tmux-navigator.snippet.conf to your
~/.tmux.conf and Ctrl-h/j/k/l flows between nvim splits and tmux panes
seamlessly. Suggested layout: nvim in the main pane, a slim bottom pane for
server/tests — Ctrl-j to peek at logs, Ctrl-k back to code.
| What | How | When |
|---|---|---|
| Plugins | :Lazy update |
Weekly-ish. Updates lazy-lock.json — commit it so other machines get the same versions |
| LSP servers & formatters | :Mason, then press U (update all) |
When you notice a server lagging behind |
| Treesitter parsers | :TSUpdate |
After plugin updates, and always after upgrading Neovim itself |
| Neovim | brew upgrade neovim (macOS) · re-run install.sh (Linux tarball installs) |
When a new stable lands |
| This config | cd ~/.config/nvim && git pull (or re-run install.sh) |
Whenever you've pushed changes from another machine |
Your config lives at ~/.config/nvim and nowhere else — cloning this repo
somewhere like ~/github/ gives you a copy to edit, but nvim will not read it.
Push from the clone, pull in ~/.config/nvim.
If something breaks after an update: :Lazy log shows what changed, and
git checkout lazy-lock.json && :Lazy restore rolls every plugin back to the
last known-good commit. That's the whole point of committing the lock file.
Treesitter build fails with ENOENT — a build tool is missing. Parsers
compile locally and need BOTH a C compiler and the tree-sitter CLI:
- macOS:
xcode-select --installandbrew install tree-sitter - Linux:
apt install gcc(or dnf/pacman equivalent); the install script downloads the tree-sitter CLI automatically
Then :TSUpdate inside nvim.
Plugin errors like module '…' not found after failed installs (e.g.
async_job not found when opening telescope) — a plugin was half-cloned when
an earlier install died. Reset plugins to the pinned lock file:
rm -rf ~/.local/share/nvim/lazy
nvim --headless "+Lazy! restore" +qaMason can't install stylua / shfmt / servers — three usual suspects:
- Missing
unziportar(mason unpacks release archives) — install them. - Missing
node/npm(pyright, ts_ls, bashls, jsonls, yamlls are npm packages) — install node. - Corporate proxy blocking GitHub/npm downloads:
export HTTPS_PROXY=http://proxy.yourcompany.com:PORT # add to your shell rc git config --global http.proxy "$HTTPS_PROXY" npm config set proxy "$HTTPS_PROXY"
:checkhealth mason shows exactly what mason can and can't find.
Re-running install.sh prints a preflight report of every required tool.
Diagnose anything: :checkhealth, :Lazy log, :messages.
Built to be safe on a work machine:
- Every plugin is a mainstream community standard — 750 to 21k+ GitHub stars, most actively maintained (folke, telescope, treesitter core teams). No obscure or single-user dependencies.
- Versions are pinned —
lazy-lock.jsoncommits exact tested commits; a fresh install gets those, not whatever HEAD is that day. - No telemetry, no background network calls — the update checker is
disabled; nothing phones home. Network happens only when you run
:Lazy update/:Masonyourself. - Binaries come from official sources only — mason's registry pulls LSP
servers and formatters from their official GitHub releases / npm packages.
Same supply chain as
npm install/pip install. - Minimal plugin count: built-in features are preferred where they exist (native commenting, native LSP keymaps).
lazy-lock.jsonis committed — fresh installs get the exact tested plugin versions.:Lazy updatewhen you want newer.- Linux clipboard:
install.shpulls inxclip(X11) andwl-clipboard(Wayland). Yank withunnamedplusthen paste in any app. - Debian/Ubuntu: the
fdbinary is namedfdfind; the installer symlinks~/.local/bin/fdso Telescope find-files stays fast. - Apple Silicon with Intel Homebrew (
/usr/local): the installer drops an arm64 nvim + tree-sitter CLI in~/.local/binso parsers load. Keep~/.local/binon your PATH (ahead of/usr/local/bin). - Harpoon jumps:
Space 1..4works everywhere. TheCtrl-1..4variants only work in terminals speaking the kitty keyboard protocol (Ghostty, kitty, WezTerm) — macOS Terminal.app cannot send Ctrl+digit at all, and inside tmux you also needset -g extended-keys on. - Broken icons? Your terminal font isn't the Nerd Font yet.
:checkhealthdiagnoses everything.