Skip to content

About

Fast, complete Neovim setup for people who read more code than they write — large-codebase navigation, in-editor PR review, tmux integration. One-script install for macOS + Linux.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

22 Commits

Folders and files

Repository files navigation

⚡ tech-lead-nvim

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.

Neovim 0.12+ License: MIT Lua

Install

curl -fsSL https://raw.githubusercontent.com/blankdean/tech-lead-nvim/main/install.sh | bash

Or 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.sh

The 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.

The greatest hits

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

Navigate like a tech lead

Drop into unfamiliar code

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.

Work several files at once

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.)

Move fast inside a file

  • Ctrl-d / Ctrl-u — half-page down/up, cursor stays centered
  • { / } — jump by paragraph/block
  • s + 2 chars — flash jump to anything you can see
  • 12j — relative line numbers are on: the number to jump is in the gutter
  • n/N after a search stay centered too

Marks: leave breadcrumbs

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.

Surgical edits

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.

Visual mode, three flavors

  • v — character-wise: select, then y yank / d delete / > indent
  • V — line-wise: grab whole lines, J/K moves them up and down
  • Ctrl-v — block: column select, I to 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.

Repeat yourself, mechanically

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

Templates and snippets

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/.

Find & replace

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–40

Searched 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:

  1. Space fg — grep the thing ("word" -w for whole-word, capitals = case-sensitive)
  2. Ctrl-q — dump every match into the quickfix list
  3. :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.

Review PRs without leaving the editor

  • 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 gm file panel: Enter opens and focuses the selected diff; double-click or gf opens the editable local file in your editor tab. Space o switches 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 (needs gh 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 url from review panes or regular files; outside an Octo review, it uses the current branch.
  • Space gp / Space gb — preview hunk / blame line
  • Space 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.

What's inside

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.

tmux

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.

Keeping everything up to date

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.

Troubleshooting

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 --install and brew 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" +qa

Mason can't install stylua / shfmt / servers — three usual suspects:

  1. Missing unzip or tar (mason unpacks release archives) — install them.
  2. Missing node/npm (pyright, ts_ls, bashls, jsonls, yamlls are npm packages) — install node.
  3. 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.

Security posture

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.json commits 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 / :Mason yourself.
  • 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).

Notes

  • lazy-lock.json is committed — fresh installs get the exact tested plugin versions. :Lazy update when you want newer.
  • Linux clipboard: install.sh pulls in xclip (X11) and wl-clipboard (Wayland). Yank with unnamedplus then paste in any app.
  • Debian/Ubuntu: the fd binary is named fdfind; the installer symlinks ~/.local/bin/fd so Telescope find-files stays fast.
  • Apple Silicon with Intel Homebrew (/usr/local): the installer drops an arm64 nvim + tree-sitter CLI in ~/.local/bin so parsers load. Keep ~/.local/bin on your PATH (ahead of /usr/local/bin).
  • Harpoon jumps: Space 1..4 works everywhere. The Ctrl-1..4 variants 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 need set -g extended-keys on.
  • Broken icons? Your terminal font isn't the Nerd Font yet.
  • :checkhealth diagnoses everything.

License

MIT

About

Fast, complete Neovim setup for people who read more code than they write — large-codebase navigation, in-editor PR review, tmux integration. One-script install for macOS + Linux.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages