vim-claude-code

AI-powered coding, inside Vim. No context switching.

vim-claude-code brings Claude Code directly into your editor. Fix bugs, write tests, review diffs, generate commits, and refactor code — all without leaving Vim.

One keypress opens Claude in a split panel. Another hides it. Your session persists across toggles. Claude edits your files; your buffers reload automatically. You stay in flow.

Why vim-claude-code?

Most AI coding tools pull you out of your editor — into a browser, a chat window, or a separate terminal. vim-claude-code keeps everything inside Vim:

• No copy-pasting — commands automatically capture your visual selection or current function
• No tab switching — Claude runs in a managed split, toggled with a single key
• No blind edits — every file change Claude proposes shows up as a reviewable diff before anything is written to disk
• No workflow interruption — buffers reload automatically when Claude modifies files

Demos

Toggle, fix bugs, generate tests, explain code, git workflows, diff preview, terminal zoom, and more — all from within Vim. See DEMO.md for individual feature walkthroughs.

Features at a Glance

Stay in Flow

• One-key toggle — <C-\> opens and hides Claude. Session persists across toggles.
• Terminal Zoom — Maximize Claude to full-screen with <C-w>z, tmux-style. Restore your split instantly.
• Auto file refresh — Buffers reload when Claude edits your files. No manual :e needed.
• Multiple layouts — Right split (default), bottom, top, left, floating popup, or dedicated tab.

Context-Aware Commands

• Selection-aware — Commands use your visual selection when active, otherwise detect the current function automatically.
• 22 sub-commands — Explain, fix, refactor, test, document, commit, review, rename, optimize, debug, and more. All tab-completable.
• Git-aware — Claude starts at your repo root. Separate sessions per repository.

Review Before Claude Writes

• Diff preview — Every file edit Claude proposes opens a side-by-side diff tab. Review what changes, then accept or reject. You stay in control.

Full Git Workflow

• Commit messages — Generated from your staged diff, with conventional commit support.
• Code review — Claude reviews your current diff with configurable strictness and security checks.
• PR descriptions — Generated from your branch changes without leaving the editor.

Requirements

• Vim 8+ compiled with +terminal
• Claude Code CLI installed and in $PATH
• Optional: +popupwin for floating window mode
• Optional: python3 for diff preview (:Claude preview)
  • Note: In Windows, there is a default python3 that redirects to the Windows Store. Run Claude doctor to check if you have a valid python3 installation. If you have Python 3, but your installation uses python.exe as the executable, create a python3 symlink.

Installation

Stable release — v1.4.1 Pin to the latest stable release using the examples below, or omit the tag to always track main.

vim-plug

" Always track latest
Plug 'rishi-opensource/vim-claude-code'

" Pin to stable release
Plug 'rishi-opensource/vim-claude-code', { 'tag': 'v1.4.1' }

Vundle

Plugin 'rishi-opensource/vim-claude-code'

Vundle does not support tag pinning. To pin manually after install:

copy

cd ~/.vim/bundle/vim-claude-code && git checkout v1.4.1

pathogen

git clone --branch v1.4.1 https://github.com/rishi-opensource/vim-claude-code.git ~/.vim/bundle/vim-claude-code

Native packages (Vim 8+)

mkdir -p ~/.vim/pack/plugins/start
git clone --branch v1.4.1 https://github.com/rishi-opensource/vim-claude-code.git ~/.vim/pack/plugins/start/vim-claude-code

Quick Start

1. Open Claude:

:Claude
" or press <C-\>

2. Run a health check:

:Claude doctor

This reports [OK] / [FAIL] for every dependency and tells you exactly what to fix.

3. Explore commands with tab completion:

:Claude <Tab>

The Claude session persists — toggling with <C-\> hides and restores the same session.

Commands

Terminal

Open, hide, and manage the Claude terminal session.

Code Intelligence

Commands work on your visual selection when active, or auto-detect the current function.

Git Workflow

From staged diff to commit message to PR description — without opening a browser.

Architecture & Planning

Think through larger problems with Claude before writing code.

Workflow Utilities

Direct in-editor actions — apply suggestions, debug errors, rename symbols, or zoom the terminal.

Meta

Utility

Reviewing Claude's Edits — Diff Preview

When Claude proposes changes to a file, a side-by-side diff tab opens automatically before anything is written to disk:

  [current file]    │    [proposed changes]

Review exactly what Claude wants to change, then use these keys in the diff tab:

Enable diff preview for your project:

:Claude preview install

This registers Claude Code hooks in .claude/settings.local.json. To auto-enable on every Vim startup:

let g:claude_code_diff_preview = 1

Diff preview commands:

Requires python3. Uses Vim +clientserver for instant diffs when available, falls back to polling.

Full-Screen Focus — Terminal Zoom

Working through a complex problem? Press <C-w>z inside the Claude terminal to maximize it full-screen — just like tmux's zoom. Press again to restore your split layout.

This is especially useful when Claude is generating a long response and you want to read it without distractions.

" Customize the zoom key
let g:claude_code_map_zoom = '<C-w>z'

Keymaps

Default keymaps

Extended keymaps (g:claude_code_map_extended_prefix + key)

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 = 0

Window Layouts

Set g:claude_code_position to match your preferred workflow:

" Bottom split at 30%
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'

Configuration

Buffer-local b:claude_code_* overrides take precedence over g: variables.

Troubleshooting

Run the health check first:

:Claude doctor

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

Claude not found — Ensure claude is in $PATH: which claude.

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 = 1

All internal events (dispatch, terminal launch, git calls, refresh) will be printed to the message area.

For full in-editor documentation, run :help claude-code.

License

MIT — see LICENSE.

Changelog

See CHANGELOG.md for full details. This project uses semantic-release for automated versioning. See doc/RELEASING.md for details.