A Vim plugin that integrates the Claude Code CLI directly into your editor. Run Claude Code in a managed terminal, send code context with a single keystroke, and get automatic file reloading when Claude edits your files — all without leaving Vim.
- One-key toggle — Open and close Claude Code with
<C-\> - 22 sub-commands — Explain, fix, refactor, test, document, commit, review, and more
- Selection-aware — Commands use visual selection when active, otherwise detect the current function
- Multiple window layouts — Right split (default), bottom split, top split, floating popup, or dedicated tab
- Automatic file refresh — Buffers reload when Claude modifies files on disk
- Git-aware — Starts Claude at the repository root; separate sessions per repo
- Health check —
:Claude doctorverifies your environment before you start - Configurable — 20+
g:variables with buffer-local overrides
Key features in one clip — toggle, fix, test generation, explain, git workflow, command discovery, and refactor. See DEMO.md for individual walkthroughs of other features.
- Vim 8+ compiled with
+terminal - Claude Code CLI installed and in
$PATH - Optional:
+popupwinfor floating window mode
Stable release — v1.1.0 Pin to the latest stable release using the examples below, or omit the tag to always track the latest commit on
main.
" Always track latest
Plug 'rishi-opensource/vim-claude-code'
" Pin to stable release
Plug 'rishi-opensource/vim-claude-code', { 'tag': 'v1.1.0' }Plugin 'rishi-opensource/vim-claude-code'Vundle does not support tag pinning. To pin manually after install:
cd ~/.vim/bundle/vim-claude-code && git checkout v1.1.0
cd ~/.vim/bundle
git clone --branch v1.1.0 https://github.com/rishi-opensource/vim-claude-code.gitmkdir -p ~/.vim/pack/plugins/start
cd ~/.vim/pack/plugins/start
git clone --branch v1.1.0 https://github.com/rishi-opensource/vim-claude-code.gitRun :Claude or press <C-\> to open Claude Code. Press it again to hide; again to restore. The session persists.
All sub-commands are tab-completable:
:Claude <Tab>
Run a health check to verify your setup:
:Claude doctor| Command | Description |
|---|---|
:Claude |
Toggle the Claude Code terminal |
:Claude continue |
Toggle with --continue (resume last conversation) |
:Claude resume |
Toggle with --resume (interactive conversation picker) |
:Claude verbose |
Toggle with --verbose (detailed logging) |
| Command | Flags | Description |
|---|---|---|
:Claude explain |
--brief, --detailed |
Explain selected code or current function |
:Claude fix |
--apply, --safe |
Fix bugs and correctness issues |
:Claude refactor |
--extract, --simplify, --optimize, --rename |
Refactor code |
:Claude test |
--framework {name}, --edge-cases |
Generate unit tests |
:Claude doc |
--inline, --markdown |
Generate documentation |
| Command | Flags | Description |
|---|---|---|
:Claude commit |
--conventional, --amend |
Generate commit message from staged diff |
:Claude review |
--strict, --security |
Code review on current diff |
:Claude pr |
Generate PR description |
| Command | Description |
|---|---|
:Claude plan |
Generate implementation plan for current file |
:Claude analyze |
Analyze for complexity, performance, and security |
| Command | Description |
|---|---|
:Claude rename |
Suggest better variable/function names |
:Claude optimize |
Optimize code for performance |
:Claude debug |
Analyze error on current line |
:Claude apply |
Apply Claude's last suggestion to the file (prompts for confirmation) |
| Command | Description |
|---|---|
:Claude chat |
Send a free-form message with current file context |
:Claude context |
Preview what context will be sent to Claude |
:Claude model [name] |
Switch model (sonnet, opus, haiku) |
| Command | Description |
|---|---|
:Claude version |
Show plugin version, Vim version, Claude CLI version, and terminal support |
:Claude doctor |
Health check: verifies Claude CLI, Git, terminal support, and Vim version |
| Mode | Key | Action |
|---|---|---|
| Normal | <C-\> |
Toggle Claude Code terminal |
| Normal | <Leader>cC |
Toggle with --continue |
| Normal | <Leader>cV |
Toggle with --verbose |
| Terminal | <C-\> |
Hide Claude Code terminal |
| Terminal | <C-h/j/k/l> |
Navigate to adjacent window |
| Key | Command | Key | Command |
|---|---|---|---|
<Leader>ce |
explain | <Leader>cG |
commit |
<Leader>cf |
fix | <Leader>cR |
review |
<Leader>cr |
refactor | <Leader>cp |
pr |
<Leader>ct |
test | <Leader>cP |
plan |
<Leader>cd |
doc | <Leader>ca |
analyze |
<Leader>cn |
rename | <Leader>cD |
debug |
<Leader>co |
optimize | <Leader>cA |
apply |
<Leader>cc |
chat | <Leader>cx |
context |
<Leader>cm |
model |
Visual mode: <Leader>c + e/f/r/t/d/n/o operate on the selection.
To disable all default keymaps:
let g:claude_code_map_keys = 0
let g:claude_code_map_extended_keys = 0Set g:claude_code_position to one of:
| Value | Layout |
|---|---|
'bottom' |
Horizontal split at the bottom |
'top' |
Horizontal split at the top |
'left' |
Vertical split on the left |
'right' |
Vertical split on the right (default) |
'float' |
Floating popup (requires +popupwin) |
'tab' |
Dedicated tab page |
" Bottom split at 30% (override the default right split)
let g:claude_code_position = 'bottom'
let g:claude_code_split_ratio = 0.3
" Floating popup
let g:claude_code_position = 'float'
let g:claude_code_float_width = 0.85
let g:claude_code_float_height = 0.85
let g:claude_code_float_border = 'double'| Variable | Default | Description |
|---|---|---|
g:claude_code_command |
'claude' |
CLI executable |
g:claude_code_position |
'right' |
Window layout |
g:claude_code_split_ratio |
0.4 |
Terminal size (0.0–1.0) |
g:claude_code_enter_insert |
1 |
Auto-enter Terminal mode on focus |
g:claude_code_hide_numbers |
1 |
Hide line numbers in terminal |
g:claude_code_hide_signcolumn |
1 |
Hide sign column in terminal |
g:claude_code_use_git_root |
1 |
Start Claude at git root |
g:claude_code_multi_instance |
1 |
Separate session per git repo |
g:claude_code_map_keys |
1 |
Register default toggle keymaps |
g:claude_code_map_extended_keys |
1 |
Register <Leader>c* keymaps |
g:claude_code_map_toggle |
'<C-\>' |
Toggle key |
g:claude_code_map_continue |
'<Leader>cC' |
Continue key |
g:claude_code_map_verbose |
'<Leader>cV' |
Verbose key |
g:claude_code_refresh_enable |
1 |
Auto-reload changed buffers |
g:claude_code_refresh_interval |
1000 |
Polling interval (ms) |
g:claude_code_refresh_notify |
1 |
Notify on buffer reload |
g:claude_code_float_width |
0.8 |
Popup width fraction |
g:claude_code_float_height |
0.8 |
Popup height fraction |
g:claude_code_float_border |
'rounded' |
Border style |
g:claude_code_model |
'' |
Claude model override |
g:claude_code_debug |
0 |
Enable debug logging to message area |
g:claude_code_terminal_start_delay |
300 |
Delay (ms) before attaching to Claude terminal |
Buffer-local b:claude_code_* overrides take precedence over g: variables.
vim-claude-code/
├── plugin/
│ └── claude_code.vim # Entry point: command + keymaps
├── autoload/
│ └── claude_code/
│ ├── config.vim # Configuration defaults + get/set
│ ├── terminal.vim # Terminal lifecycle (create/toggle/close)
│ ├── terminal_bridge.vim # Terminal lookup and prompt dispatch
│ ├── window.vim # Window layout utilities
│ ├── git.vim # Git root detection with caching
│ ├── keymaps.vim # Terminal-local keymaps
│ ├── refresh.vim # File change detection and reload
│ ├── util.vim # Shared helpers (selection, context, error, debug)
│ ├── commands.vim # explain, fix, refactor, test, doc
│ ├── git_commands.vim # commit, review, pr
│ ├── arch_commands.vim # plan, analyze
│ ├── workflow_commands.vim # rename, optimize, debug, apply
│ └── meta_commands.vim # chat, context, model, version, doctor
├── test/
│ ├── vimrc # Minimal vimrc for test runner
│ └── test_dispatch.vader # Vader test suite
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI (Vim 8 + Vim 9)
└── doc/
└── claude_code.txt # :help documentation
:help claude-codeRun the health check first:
:Claude doctorThis reports [OK] / [FAIL] for each dependency and tells you exactly what to fix.
E117: Unknown function — Run :helptags ALL then restart Vim. Ensure the
plugin directory is on your runtimepath.
Terminal does not open — Verify vim --version | grep +terminal. The plugin
requires Vim compiled with +terminal. Run :Claude doctor to confirm.
Claude not found — Ensure claude is in $PATH: which claude. Run
:Claude doctor to confirm.
File changes not detected — Check g:claude_code_refresh_enable is 1 and
that autoread is not globally disabled in your vimrc.
Debug logging — Enable verbose output to diagnose issues:
let g:claude_code_debug = 1All internal events (dispatch, terminal launch, git calls, refresh) will be
printed to the message area. Disable again with let g:claude_code_debug = 0.
- UX improvements and workflow refinements
- Add more intelligent
:Claudesubcommands - Improve diagnostics and configuration options
- Official Neovim support
- Improved terminal/window handling
- Floating window UI (Neovim)
MIT — see LICENSE.
See CHANGELOG.md for full details.
