From 9a5d3cefbbe8e0aaca6ed997d095d4171d4b8bee Mon Sep 17 00:00:00 2001 From: wlee-wgeld Date: Thu, 19 Feb 2026 09:43:16 -0500 Subject: [PATCH] docs: rewrite README with full usage and maintenance guide Replaces the generic kickstart README with a personalized reference covering: - Requirements and installation - Plugin inventory - Full keymap reference (general, telescope, LSP, AI agent) - ThePrimeagen/99 usage (prompts, AGENT.md, skill files, debugging) - Maintenance guide (adding plugins, LSPs, formatters, updating) - Optional extras reference Co-Authored-By: Claude Sonnet 4.6 --- README.md | 540 ++++++++++++++++++++++++++---------------------------- 1 file changed, 264 insertions(+), 276 deletions(-) diff --git a/README.md b/README.md index 2b9e52da..0cf00a06 100644 --- a/README.md +++ b/README.md @@ -1,322 +1,310 @@ -# kickstart.nvim +# nvim -## Introduction +Personal Neovim configuration based on [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim). +Single-file, fully documented, no magic. -A starting point for Neovim that is: +--- -* Small -* Single-file -* Completely Documented +## Requirements -**NOT** a Neovim distribution, but instead a starting point for your configuration. +| Dependency | Purpose | +|---|---| +| Neovim `>= 0.10` (latest stable recommended) | Runtime | +| `git`, `make`, `gcc` / `clang` | Plugin builds | +| [ripgrep](https://github.com/BurntSushi/ripgrep) | Live grep in Telescope | +| [fd-find](https://github.com/sharkdp/fd) | File finder | +| `claude` CLI (Claude Code) | AI agent ([99](#ai-agent--99)) | +| Clipboard tool (`xclip`, `xsel`, `win32yank`) | System clipboard sync | + +Install Neovim on WSL (Ubuntu/Debian): + +```sh +sudo add-apt-repository ppa:neovim-ppa/unstable -y +sudo apt update +sudo apt install make gcc ripgrep unzip git xclip neovim +``` + +--- ## Installation -### Install Neovim - -Kickstart.nvim targets *only* the latest -['stable'](https://github.com/neovim/neovim/releases/tag/stable) and latest -['nightly'](https://github.com/neovim/neovim/releases/tag/nightly) of Neovim. -If you are experiencing issues, please make sure you have at least the latest -stable version. Most likely, you want to install neovim via a [package -manager](https://github.com/neovim/neovim/blob/master/INSTALL.md#install-from-package). -To check your neovim version, run `nvim --version` and make sure it is not -below the latest -['stable'](https://github.com/neovim/neovim/releases/tag/stable) version. If -your chosen install method only gives you an outdated version of neovim, find -alternative [installation methods below](#alternative-neovim-installation-methods). - -### Install External Dependencies - -External Requirements: -- Basic utils: `git`, `make`, `unzip`, C Compiler (`gcc`) -- [ripgrep](https://github.com/BurntSushi/ripgrep#installation), - [fd-find](https://github.com/sharkdp/fd#installation) -- Clipboard tool (xclip/xsel/win32yank or other depending on the platform) -- A [Nerd Font](https://www.nerdfonts.com/): optional, provides various icons - - if you have it set `vim.g.have_nerd_font` in `init.lua` to true -- Emoji fonts (Ubuntu only, and only if you want emoji!) `sudo apt install fonts-noto-color-emoji` -- Language Setup: - - If you want to write Typescript, you need `npm` - - If you want to write Golang, you will need `go` - - etc. - -> [!NOTE] -> See [Install Recipes](#Install-Recipes) for additional Windows and Linux specific notes -> and quick install snippets - -### Install Kickstart - -> [!NOTE] -> [Backup](#FAQ) your previous configuration (if any exists) - -Neovim's configurations are located under the following paths, depending on your OS: - -| OS | PATH | -| :- | :--- | -| Linux, MacOS | `$XDG_CONFIG_HOME/nvim`, `~/.config/nvim` | -| Windows (cmd)| `%localappdata%\nvim\` | -| Windows (powershell)| `$env:LOCALAPPDATA\nvim\` | - -#### Recommended Step - -[Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) this repo -so that you have your own copy that you can modify, then install by cloning the -fork to your machine using one of the commands below, depending on your OS. - -> [!NOTE] -> Your fork's URL will be something like this: -> `https://github.com//kickstart.nvim.git` - -You likely want to remove `lazy-lock.json` from your fork's `.gitignore` file -too - it's ignored in the kickstart repo to make maintenance easier, but it's -[recommended to track it in version control](https://lazy.folke.io/usage/lockfile). - -#### Clone kickstart.nvim - -> [!NOTE] -> If following the recommended step above (i.e., forking the repo), replace -> `nvim-lua` with `` in the commands below - -
Linux and Mac - ```sh -git clone https://github.com/nvim-lua/kickstart.nvim.git "${XDG_CONFIG_HOME:-$HOME/.config}"/nvim -``` +# Back up any existing config first +mv ~/.config/nvim ~/.config/nvim.bak -
+# Clone this repo +git clone https://github.com/0xWheatyz/kickstart.nvim.git ~/.config/nvim -
Windows - -If you're using `cmd.exe`: - -``` -git clone https://github.com/nvim-lua/kickstart.nvim.git "%localappdata%\nvim" -``` - -If you're using `powershell.exe` - -``` -git clone https://github.com/nvim-lua/kickstart.nvim.git "${env:LOCALAPPDATA}\nvim" -``` - -
- -### Post Installation - -Start Neovim - -```sh +# Launch — Lazy will bootstrap and install all plugins automatically nvim ``` -That's it! Lazy will install all the plugins you have. Use `:Lazy` to view -the current plugin status. Hit `q` to close the window. +Run `:Lazy` to check plugin status. Run `:checkhealth` if anything looks wrong. -#### Read The Friendly Documentation +--- -Read through the `init.lua` file in your configuration folder for more -information about extending and exploring Neovim. That also includes -examples of adding popularly requested plugins. +## Structure -> [!NOTE] -> For more information about a particular plugin check its repository's documentation. +Everything lives in a single file: +``` +~/.config/nvim/ +├── init.lua ← entire config (options, keymaps, plugins) +└── lua/ + ├── custom/plugins/ ← drop extra plugin files here (optional) + └── kickstart/plugins/ ← optional bundled extras (debug, neo-tree, etc.) +``` -### Getting Started +The config is intentionally kept in one file so every line is readable +top-to-bottom without jumping between modules. -[The Only Video You Need to Get Started with Neovim](https://youtu.be/m8C0Cq9Uv9o) +--- -### FAQ +## Plugins -* What should I do if I already have a pre-existing Neovim configuration? - * You should back it up and then delete all associated files. - * This includes your existing init.lua and the Neovim files in `~/.local` - which can be deleted with `rm -rf ~/.local/share/nvim/` -* Can I keep my existing configuration in parallel to kickstart? - * Yes! You can use [NVIM_APPNAME](https://neovim.io/doc/user/starting.html#%24NVIM_APPNAME)`=nvim-NAME` - to maintain multiple configurations. For example, you can install the kickstart - configuration in `~/.config/nvim-kickstart` and create an alias: - ``` - alias nvim-kickstart='NVIM_APPNAME="nvim-kickstart" nvim' - ``` - When you run Neovim using `nvim-kickstart` alias it will use the alternative - config directory and the matching local directory - `~/.local/share/nvim-kickstart`. You can apply this approach to any Neovim - distribution that you would like to try out. -* What if I want to "uninstall" this configuration: - * See [lazy.nvim uninstall](https://lazy.folke.io/usage#-uninstalling) information -* Why is the kickstart `init.lua` a single file? Wouldn't it make sense to split it into multiple files? - * The main purpose of kickstart is to serve as a teaching tool and a reference - configuration that someone can easily use to `git clone` as a basis for their own. - As you progress in learning Neovim and Lua, you might consider splitting `init.lua` - into smaller parts. A fork of kickstart that does this while maintaining the - same functionality is available here: - * [kickstart-modular.nvim](https://github.com/dam9000/kickstart-modular.nvim) - * Discussions on this topic can be found here: - * [Restructure the configuration](https://github.com/nvim-lua/kickstart.nvim/issues/218) - * [Reorganize init.lua into a multi-file setup](https://github.com/nvim-lua/kickstart.nvim/pull/473) +| Plugin | Purpose | +|---|---| +| `folke/lazy.nvim` | Plugin manager | +| `NMAC427/guess-indent.nvim` | Auto-detect indentation | +| `lewis6991/gitsigns.nvim` | Git gutter signs | +| `folke/which-key.nvim` | Keymap hints popup | +| `nvim-telescope/telescope.nvim` | Fuzzy finder | +| `neovim/nvim-lspconfig` + `mason-org/mason.nvim` | LSP + auto-install | +| `stevearc/conform.nvim` | Formatting on save | +| `saghen/blink.cmp` + `L3MON4D3/LuaSnip` | Completion + snippets | +| `folke/tokyonight.nvim` | Colorscheme (tokyonight-night) | +| `folke/todo-comments.nvim` | Highlight TODO/FIXME/NOTE | +| `nvim-mini/mini.nvim` | Text objects, surround, statusline | +| `nvim-treesitter/nvim-treesitter` | Syntax highlighting | +| `ThePrimeagen/99` | AI agent | -### Install Recipes +--- -Below you can find OS specific install instructions for Neovim and dependencies. +## Keymaps -After installing all the dependencies continue with the [Install Kickstart](#install-kickstart) step. +`` is ``. -#### Windows Installation +### General -
Windows with Microsoft C++ Build Tools and CMake -Installation may require installing build tools and updating the run command for `telescope-fzf-native` +| Key | Action | +|---|---| +| `` | Clear search highlight | +| `` | Move between splits | +| `q` | Open diagnostic quickfix list | +| `f` | Format buffer | +| `th` | Toggle inlay hints (when LSP supports it) | -See `telescope-fzf-native` documentation for [more details](https://github.com/nvim-telescope/telescope-fzf-native.nvim#installation) +### Telescope (Search) -This requires: +| Key | Action | +|---|---| +| `sf` | Find files | +| `sg` | Live grep | +| `sw` | Grep word under cursor (or selection) | +| `sh` | Search help tags | +| `sk` | Search keymaps | +| `sd` | Search diagnostics | +| `sr` | Resume last search | +| `s.` | Recent files | +| `sc` | Search commands | +| `sn` | Search Neovim config files | +| `/` | Fuzzy search current buffer | +| `s/` | Live grep in open files | +| `` | Open buffer list | -- Install CMake and the Microsoft C++ Build Tools on Windows +### LSP (active when a language server is attached) + +| Key | Action | +|---|---| +| `grn` | Rename symbol | +| `gra` | Code action | +| `grD` | Go to declaration | +| `grd` | Go to definition | +| `grr` | Find references | +| `gri` | Go to implementation | +| `grt` | Go to type definition | +| `gO` | Document symbols | +| `gW` | Workspace symbols | + +### AI Agent (99) + +| Key | Mode | Action | +|---|---|---| +| `9v` | visual | Send selection as AI request | +| `9s` | normal | Open search / ask AI | +| `9x` | normal | Cancel all in-flight requests | + +In the 99 prompt: +- `@` — fuzzy-attach a project file as context +- `#` — autocomplete and attach a rule/skill file + +--- + +## AI Agent — 99 + +[ThePrimeagen/99](https://github.com/ThePrimeagen/99) is a Neovim-native AI +agent that delegates to a CLI backend. This config uses **Claude Code** +(`claude` CLI) as the provider. + +### Prerequisites + +Claude Code must be installed and authenticated: + +```sh +npm install -g @anthropic-ai/claude-code +claude login +``` + +### How it works + +1. Open any file and make a visual selection (or just use `9s` for a + free-form prompt). +2. Press `9v` (visual) or `9s` (normal) to open the prompt. +3. Describe what you want. Use `@file` to attach context, `#rule` to attach a + skill/rule doc. +4. 99 streams the response back into the buffer as virtual text, then applies + replacements inline. +5. Press `9x` at any time to abort. + +### Debugging + +```vim +:lua require("99").view_logs() +``` + +Navigate log history with `_99.prev_request_logs()` / `_99.next_request_logs()`. + +### AGENT.md (optional) + +Drop an `AGENT.md` file in any directory (or project root) to give 99 +project-specific context. It is automatically injected into every request +made from files under that directory. + +``` +project-root/ +└── AGENT.md ← describes conventions, architecture, rules +``` + +### Skill files (optional) + +Custom rule files enable `#` autocompletion in the prompt. Each skill +is a folder with a `SKILL.md` inside: + +``` +~/.config/nvim/skills/ +└── my-rule/ + └── SKILL.md +``` + +Point 99 at them by adding to `completion.custom_rules` in the setup call +inside `init.lua`. + +--- + +## Maintaining the Config + +All changes happen in `~/.config/nvim/init.lua`. The file is organized in this order: + +1. **Options** — `vim.o.*` / `vim.opt.*` settings +2. **Keymaps** — `vim.keymap.set(...)` for built-in bindings +3. **Autocommands** — `vim.api.nvim_create_autocmd(...)` +4. **Plugin specs** — passed to `require('lazy').setup({...})` + +### Adding a plugin + +Add an entry anywhere inside the `require('lazy').setup({ ... })` table: ```lua -{'nvim-telescope/telescope-fzf-native.nvim', build = 'cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release && cmake --build build --config Release && cmake --install build --prefix build' } -``` -
-
Windows with gcc/make using chocolatey -Alternatively, one can install gcc and make which don't require changing the config, -the easiest way is to use choco: - -1. install [chocolatey](https://chocolatey.org/install) -either follow the instructions on the page or use winget, -run in cmd as **admin**: -``` -winget install --accept-source-agreements chocolatey.chocolatey +{ 'author/plugin-name', opts = {} }, ``` -2. install all requirements using choco, exit the previous cmd and -open a new one so that choco path is set, and run in cmd as **admin**: -``` -choco install -y neovim git ripgrep wget fd unzip gzip mingw make -``` -
-
WSL (Windows Subsystem for Linux) +For plugins that need configuration: -``` -wsl --install -wsl -sudo add-apt-repository ppa:neovim-ppa/unstable -y -sudo apt update -sudo apt install make gcc ripgrep unzip git xclip neovim -``` -
- -#### Linux Install -
Ubuntu Install Steps - -``` -sudo add-apt-repository ppa:neovim-ppa/unstable -y -sudo apt update -sudo apt install make gcc ripgrep unzip git xclip neovim -``` -
-
Debian Install Steps - -``` -sudo apt update -sudo apt install make gcc ripgrep unzip git xclip curl - -# Now we install nvim -curl -LO https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.tar.gz -sudo rm -rf /opt/nvim-linux-x86_64 -sudo mkdir -p /opt/nvim-linux-x86_64 -sudo chmod a+rX /opt/nvim-linux-x86_64 -sudo tar -C /opt -xzf nvim-linux-x86_64.tar.gz - -# make it available in /usr/local/bin, distro installs to /usr/bin -sudo ln -sf /opt/nvim-linux-x86_64/bin/nvim /usr/local/bin/ -``` -
-
Fedora Install Steps - -``` -sudo dnf install -y gcc make git ripgrep fd-find unzip neovim -``` -
- -
Arch Install Steps - -``` -sudo pacman -S --noconfirm --needed gcc make git ripgrep fd unzip neovim -``` -
- -### Alternative neovim installation methods - -For some systems it is not unexpected that the [package manager installation -method](https://github.com/neovim/neovim/blob/master/INSTALL.md#install-from-package) -recommended by neovim is significantly behind. If that is the case for you, -pick one of the following methods that are known to deliver fresh neovim versions very quickly. -They have been picked for their popularity and because they make installing and updating -neovim to the latest versions easy. You can also find more detail about the -available methods being discussed -[here](https://github.com/nvim-lua/kickstart.nvim/issues/1583). - - -
Bob - -[Bob](https://github.com/MordechaiHadad/bob) is a Neovim version manager for -all plattforms. Simply install -[rustup](https://rust-lang.github.io/rustup/installation/other.html), -and run the following commands: - -```bash -rustup default stable -rustup update stable -cargo install bob-nvim -bob use stable +```lua +{ + 'author/plugin-name', + event = 'VimEnter', -- optional: defer loading + config = function() + require('plugin-name').setup { + -- options here + } + vim.keymap.set('n', 'x', ...) + end, +}, ``` -
+Then run `:Lazy sync` (or restart Neovim) to install. -
Homebrew +### Updating plugins -[Homebrew](https://brew.sh) is a package manager popular on Mac and Linux. -Simply install using [`brew install`](https://formulae.brew.sh/formula/neovim). - -
- -
Flatpak - -Flatpak is a package manager for applications that allows developers to package their applications -just once to make it available on all Linux systems. Simply [install flatpak](https://flatpak.org/setup/) -and setup [flathub](https://flathub.org/setup) to [install neovim](https://flathub.org/apps/io.neovim.nvim). - -
- -
asdf and mise-en-place - -[asdf](https://asdf-vm.com/) and [mise](https://mise.jdx.dev/) are tool version managers, -mostly aimed towards project-specific tool versioning. However both support managing tools -globally in the user-space as well: - -
mise - -[Install mise](https://mise.jdx.dev/getting-started.html), then run: - -```bash -mise plugins install neovim -mise use neovim@stable +```vim +:Lazy update ``` -
+This updates all plugins and refreshes `lazy-lock.json`. -
asdf +### Adding a language server -[Install asdf](https://asdf-vm.com/guide/getting-started.html), then run: +Inside the `servers` table in the `nvim-lspconfig` config block: -```bash -asdf plugin add neovim -asdf install neovim stable -asdf set neovim stable --home -asdf reshim neovim +```lua +local servers = { + gopls = {}, + pyright = {}, + ts_ls = {}, +} ``` -
+Mason will auto-install it. Run `:Mason` to check status. -
+### Adding a formatter + +Inside the `conform.nvim` `opts.formatters_by_ft` table: + +```lua +formatters_by_ft = { + lua = { 'stylua' }, + python = { 'black' }, + javascript = { 'prettierd', 'prettier', stop_after_first = true }, +}, +``` + +Make sure the formatter binary is installed via Mason or your system package +manager. + +### Switching the colorscheme + +Replace the `folke/tokyonight.nvim` plugin entry with any other colorscheme, +and update `vim.cmd.colorscheme 'theme-name'` in its `config` function. + +### Checking health + +```vim +:checkhealth +``` + +Covers LSP, Treesitter, Telescope, and plugin-specific diagnostics. + +--- + +## Optional Extras + +Uncomment any of these lines near the bottom of `init.lua` to enable bundled +extras: + +```lua +require 'kickstart.plugins.debug', -- DAP debugger UI +require 'kickstart.plugins.indent_line', -- indent guides +require 'kickstart.plugins.lint', -- async linting +require 'kickstart.plugins.autopairs', -- bracket auto-close +require 'kickstart.plugins.neo-tree', -- file tree +require 'kickstart.plugins.gitsigns', -- extra git keymaps +``` + +Drop additional plugin files under `lua/custom/plugins/` and uncomment: + +```lua +{ import = 'custom.plugins' }, +``` + +at the bottom of the lazy setup call.