[opensourcedex]

claude-code.nvim is a free, open source ai interaction & interfaces project written in Lua and released under MIT. It has 2,098 GitHub stars, 70 forks and 77 open issues, and was last pushed 8 months ago. On this registry it ranks #62 of 76 tracked projects in AI Interaction & Interfaces, with 5 head-to-head comparisons available.

What is claude-code.nvim?

claude-code.nvim is a Neovim plugin that runs the Claude Code CLI inside a terminal buffer in the editor, giving Neovim users a single-keypress interface to Anthropic's Claude Code AI assistant without leaving their session.

What it is

claude-code.nvim is a Lua plugin for Neovim that wraps the Claude Code command-line tool in an in-editor terminal window. It belongs to the Neovim plugin ecosystem and depends on plenary.nvim for git operations. The plugin was built entirely with Claude Code, first in a Neovim terminal and then inside itself, and it is distributed under the MIT licence at version 0.4.2.

The concrete problem it solves is context switching. Using Claude Code normally means leaving Neovim, opening a separate terminal, and manually returning to the editor after the assistant has changed files. This plugin replaces that workflow: it toggles a terminal window inside Neovim, runs the Claude Code CLI there, and then watches for files the assistant has modified so buffers can be reloaded automatically. Users do not have to guess which files changed or re-open them by hand.

Key capabilities

  • Toggle Claude Code in a terminal window with a single key press.
  • Pass command-line arguments through to the CLI, such as --continue, and define custom variants.
  • Detect files modified by Claude Code and reload them automatically, with real-time buffer updates when files change externally.
  • Configure window position and size, including floating windows, via options such as split_ratio = 0.3 and position = "botright", "topleft", "vertical", or "float".
  • Integrate with which-key when that plugin is present.
  • Use the git project root as the working directory automatically when one is available.
  • Validate configuration to prevent errors, with LuaCATS type annotations and a testing framework covering 44 tests.

Who uses it and how

  • Neovim users on version 0.7.0 or later who already have the Claude Code CLI installed and available in PATH.
  • Developers working inside git repositories, where the plugin picks up the project root as the assistant's working directory rather than the current file's folder.
  • Users who want the assistant docked in a split or floating window sized to their layout, rather than in a separate terminal emulator.
  • Teams and individuals already using which-key, who get the plugin's commands surfaced through their existing keybinding hints.

Getting started

Install with lazy.nvim, packer.nvim, or vim-plug using the plugin name greggh/claude-code.nvim, with nvim-lua/plenary.nvim declared as a dependency, then call require("claude-code").setup(). The Claude Code CLI must be installed and on PATH before the plugin will work.

How it compares

No paid products or comparable tools are named in the available facts, so this entry stands alone in this registry.

When to use it — and when not to

A self-hoster must already run Neovim 0.7.0 or later, have the Claude Code CLI installed and resolvable on PATH, and install plenary.nvim as a dependency for git operations. Anyone not using Neovim, or not already using the Claude Code CLI, should not pick this plugin, since it integrates an existing tool rather than providing an assistant of its own. The project is at version 0.4.2 with 77 open issues against 2,098 stars, so expect active, pre-1.0 development rather than a frozen interface.

project readme (upstream, from github) — read inline

Claude Code Neovim Plugin

GitHub License GitHub Stars GitHub Issues CI Neovim Version Tests Version Discussions

A seamless integration between Claude Code AI assistant and Neovim

Features • Requirements • Installation • Configuration • Usage • Contributing • Discussions

Claude Code in Neovim

This plugin was built entirely with Claude Code in a Neovim terminal, and then inside itself using Claude Code for everything!

Features

  • 🚀 Toggle Claude Code in a terminal window with a single key press
  • 🧠 Support for command-line arguments like --continue and custom variants
  • 🔄 Automatically detect and reload files modified by Claude Code
  • ⚡ Real-time buffer updates when files are changed externally
  • 📱 Customizable window position and size (including floating windows)
  • 🤖 Integration with which-key (if available)
  • 📂 Automatically uses git project root as working directory (when available)
  • 🧩 Modular and maintainable code structure
  • 📋 Type annotations with LuaCATS for better IDE support
  • ✅ Configuration validation to prevent errors
  • 🧪 Testing framework for reliability (44 comprehensive tests)

Requirements

See CHANGELOG.md for version history and updates.

Installation

Using lazy.nvim

return {
  "greggh/claude-code.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim", -- Required for git operations
  },
  config = function()
    require("claude-code").setup()
  end
}

Using packer.nvim

use {
  'greggh/claude-code.nvim',
  requires = {
    'nvim-lua/plenary.nvim', -- Required for git operations
  },
  config = function()
    require('claude-code').setup()
  end
}

Using vim-plug

Plug 'nvim-lua/plenary.nvim'
Plug 'greggh/claude-code.nvim'
" After installing, add this to your init.vim:
" lua require('claude-code').setup()

Configuration

The plugin can be configured by passing a table to the setup function. Here's the default configuration:

require("claude-code").setup({
  -- Terminal window settings
  window = {
    split_ratio = 0.3,      -- Percentage of screen for the terminal window (height for horizontal, width for vertical splits)
    position = "botright",  -- Position of the window: "botright", "topleft", "vertical", "float", etc.
    enter_insert = true,    -- Whether to enter insert mode when opening Claude Code
    hide_numbers = true,    -- Hide line numbers in the terminal window
    hide_signcolumn = true, -- Hide the sign column in the terminal window
    
    -- Floating window configuration (only applies when position = "float")
    float = {
      width = "80%",        -- Width: number of columns or percentage string
      height = "80%",       -- Height: number of rows or percentage string
      row = "center",       -- Row position: number, "center", or percentage string
      col = "center",       -- Column position: number, "center", or percentage string
      relative = "editor",  -- Relative to: "editor" or "cursor"
      border = "rounded",   -- Border style: "none", "single", "double", "rounded", "solid", "shadow"
    },
  },
  -- File refresh settings
  refresh = {
    enable = true,           -- Enable file change detection
    updatetime = 100,        -- updatetime when Claude Code is active (milliseconds)
    timer_interval = 1000,   -- How often to check for file changes (milliseconds)
    show_notifications = true, -- Show notification when files are reloaded
  },
  -- Git project settings
  git = {
    use_git_root = true,     -- Set CWD to git root when opening Claude Code (if in git project)
  },
  -- Shell-specific settings
  shell = {
    separator = '&&',        -- Command separator used in shell commands
    pushd_cmd = 'pushd',     -- Command to push directory onto stack (e.g., 'pushd' for bash/zsh, 'enter' for nushell)
    popd_cmd = 'popd',       -- Command to pop directory from stack (e.g., 'popd' for bash/zsh, 'exit' for nushell)
  },
  -- Command settings
  command = "claude",        -- Command used to launch Claude Code
  -- Command variants
  command_variants = {
    -- Conversation management
    continue = "--continue", -- Resume the most recent conversation
    resume = "--resume",     -- Display an interactive conversation picker

    -- Output options
    verbose = "--verbose",   -- Enable verbose logging with full turn-by-turn output
  },
  -- Keymaps
  keymaps = {
    toggle = {
      normal = "<C-,>",       -- Normal mode keymap for toggling Claude Code, false to disable
      terminal = "<C-,>",     -- Terminal mode keymap for toggling Claude Code, false to disable
      variants = {
        continue = "<leader>cC", -- Normal mode keymap for Claude Code with continue flag
        verbose = "<leader>cV",  -- Normal mode keymap for Claude Code with verbose flag
      },
    },
    window_navigation = true, -- Enable window navigation keymaps (<C-h/j/k/l>)
    scrolling = true,         -- Enable scrolling keymaps (<C-f/b>) for page up/down
  }
})

Usage

Quick Start

" In your Vim/Neovim commands or init file:
:ClaudeCode

-- Or from Lua:
vim.cmd[[ClaudeCode]]

-- Or map to a key:
vim.keymap.set('n', '<leader>cc', '<cmd>ClaudeCode<CR>', { desc = 'Toggle Claude Code' })

Commands

Basic command:

  • :ClaudeCode - Toggle the Claude Code terminal window

Conversation management commands:

  • :ClaudeCodeContinue - Resume the most recent conversation
  • :ClaudeCodeResume - Display an interactive conversation picker

Output options command:

  • :ClaudeCodeVerbose - Enable verbose logging with full turn-by-turn output

Note: Commands are automatically generated for each entry in your command_variants configuration.

Key Mappings

Default key mappings:

  • ac - Toggle Claude Code terminal window (normal mode)
  • `` - Toggle Claude Code terminal window (both normal and terminal modes)

Variant mode mappings (if configured):

  • cC - Toggle Claude Code with --continue flag
  • cV - Toggle Claude Code with --verbose flag

Additionally, when in the Claude Code terminal:

  • `` - Move to the window on the left
  • `` - Move to the window below
  • `` - Move to the window above
  • `` - Move to the window on the right
  • `` - Scroll full-page down
  • `` - Scroll full-page up

Note: After scrolling with or, you'll need to press the i key to re-enter insert mode so you can continue typing to Claude Code.

When Claude Code modifies files that are open in Neovim, they'll be automatically reloaded.

Floating Window Example

To use Claude Code in a floating window:

require("claude-code").setup({
  window = {
    position = "float",
    float = {
      width = "90%",      -- Take up 90% of the editor width
      height = "90%",     -- Take up 90% of the editor height
      row = "center",     -- Center vertically
      col = "center",     -- Center horizontally
      relative = "editor",
      border = "double",  -- Use double border style
    },
  },
})

How it Works

This plugin:

  1. Creates a terminal buffer running the Claude Code CLI
  2. Sets up autocom

readme truncated — read the full docs on github

Frequently asked questions

Is claude-code.nvim free to use?

claude-code.nvim is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does claude-code.nvim do?

Seamless integration between Claude Code AI assistant and Neovim

What is claude-code.nvim written in?

claude-code.nvim is primarily written in Lua. Its source is publicly available at https://github.com/greggh/claude-code.nvim, and it has 2,098 GitHub stars.