Neovim setup from scratch for AI coding agents

When an AI agent changes my code, I want to see what happened. I want the files open, the diff nearby, and the conversation beside them.

That is what I built my Neovim setup around. The agent runs in a terminal. Neovim gives me a place to read, edit, and review its work.

You can build a small version of that setup yourself. If you prefer something ready to use, there is NvSinner, my Neovim distribution for AI agents. But starting from scratch helps you understand which parts you actually need.

01Start with the basics

You need Neovim, Git, and a terminal you like. Install ripgrep for searching inside files. A Nerd Font is useful if you want icons, but you can start without one.

Check your Neovim version:

nvim --version

Check each plugin’s requirements before installing it. An older Neovim package can work perfectly on its own and still be too old for a plugin.

Install your CLI agent separately too. Whether you use Claude Code, Codex, or another tool, make sure it works from a regular terminal first. Its login and configuration stay with the CLI.

If you prefer learning through video, I recommend From 0 to IDE in NEOVIM from scratch, the first episode of typecraft’s free course. I like his content, and his channel has plenty more on Neovim when you want to go further.

02Keep your existing setup safe

You do not need to replace your current configuration to try this.

Neovim supports separate setups through NVIM_APPNAME. On macOS or Linux, create a directory for this one:

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/nvim-agents"
NVIM_APPNAME=nvim-agents nvim

Use another name if you already have a configuration called nvim-agents.

This instance gets its own configuration, plugins, state, and cache. Running plain nvim still opens your usual setup.

Inside Neovim, run :echo stdpath('config') to check where your new files belong. Keep using the same NVIM_APPNAME prefix when you launch it.

I explain this in more detail in how to try a Neovim distribution safely.

03Add a plugin manager

I use lazy.nvim to manage plugins. Its installation guide provides the bootstrap code and a simple structure:

init.lua
lua/
  config/
    lazy.lua
  plugins/

Your init.lua loads the configuration. The lua/config/ directory holds the plugin manager setup, and lua/plugins/ holds your plugin definitions.

Follow the installation guide before adding plugins. Once you have a working setup, keep the generated lazy-lock.json with your configuration. It records the plugin versions you installed.

I also avoid updating everything in the middle of another task. If something breaks, I want to know whether it came from my project or from changing the editor.

04Choose a few useful tools

You do not need a large plugin collection. Start with the things that help you move through a project and understand its code.

Telescope handles file search. Use :Telescope find_files to open files and :Telescope live_grep to search their contents. The content search needs ripgrep installed.

For language support, nvim-lspconfig provides configurations for language servers. Start with the language you use most and follow its setup instructions. Installing the plugin alone does not install the server.

Completion can stay simple at first. Neovim’s built-in LSP supports completion with Ctrl-X followed by Ctrl-O in Insert mode when the connected server provides it.

Gitsigns marks added, changed, and deleted lines beside your code. Diffview gives you a view of changes across the repository. Those two are especially useful when an agent edits several files.

A file tree is optional. Neovim already has a directory browser through :Explore. If you want a permanent tree, Neo-tree is the one I use in NvSinner.

Treesitter can come later too. It adds syntax-aware highlighting, but follow the documentation for the branch you install. Its requirements and configuration differ between versions.

05Give the agent a place beside your code

A terminal beside your code is enough to start. ToggleTerm can manage it as a vertical split.

Once lazy.nvim is set up, create lua/plugins/terminal.lua:

return {
  {
    "akinsho/toggleterm.nvim",
    version = "*",
    opts = {
      direction = "vertical",
      size = 50,
      open_mapping = [[<c-t>]],
      terminal_mappings = true,
      persist_mode = false,
    },
  },
}

Restart Neovim and let lazy.nvim install the plugin. Open the editor from your project directory, press Ctrl-T, and run your agent inside the terminal.

Press Ctrl-T again to hide it. The process keeps running while your Neovim session is open. Closing Neovim does not preserve that session.

To move back to your code without hiding the terminal, press Ctrl-\ followed by Ctrl-N, then Ctrl-W h to focus the window on the left. Use Ctrl-W l to move right and i to type in the terminal again.

I prefer a side column because I can read the agent’s response while looking at the file it changed. On a small screen, I hide the terminal when I need more room.

NvSinner adds its own controls, including <leader>j to toggle the agent column. Those mappings belong to NvSinner; installing ToggleTerm alone does not create them.

I explain the layout in my note about AI agents in a terminal column. If you eventually work with several agents, the Herdr integration helps keep track of them.

06Make reviewing changes easy

Agents edit files outside the editor. Add this to init.lua:

vim.opt.autoread = true

Then use :checktime to check for changes on disk. Neovim can reload a changed file when its buffer has no unsaved edits. Avoid editing the same file as the agent at the same time.

Use :Gitsigns preview_hunk to inspect the change under your cursor. Open :DiffviewOpen when you need to review the repository. Check staged and unstaged changes, including newly created files. Use :DiffviewClose to return to your editing layout.

Read the diff, then run the project’s checks. If you cannot explain a change, ask about it before committing.

That is the point behind my definition of AI slop as output nobody read. Having an agent inside your editor does not remove the need to review its work.

07Let the setup grow with your work

I would skip dashboards, extra themes, and complicated shortcuts on day one. Start with one project and one agent. Add something when you can name the problem it solves.

Automatic formatting can wait until you know which formatter the project uses. More agent sessions can wait until you are comfortable following the changes from one.

If that small setup is enough, keep it. If you want the session controls and integrations already assembled, take a look at NvSinner, my Neovim distribution for AI agents.

Its source code is also there if you only want to borrow a few ideas.