Claude Code を Neovim で使う｜claudecode.nvim 導入と設定

claudecode.nvim とは何か

coder/claudecode.nvim は、Anthropic が VS Code と JetBrains 向けにのみ公式提供している Claude Code IDE 拡張を、Neovim 向けに再実装したコミュニティプラグインです。

公式拡張と同じ Model Context Protocol(MCP) を WebSocket で実装しており、Claude Code CLI がエディタ内のファイルコンテキストを認識する仕組みは公式と同等です。「Neovim をそのまま AI IDE に昇格させる」という設計思想で、ターミナル操作・キーバインド・Vim モーション――これまで慣れ親しんだ操作体系を一切変えずに Claude Code を呼び出せます。

純 Lua 実装であるため、Python ブリッジや Node.js 依存が一切なく、Neovim ネイティブのランタイムだけで完結します。

動作要件と前提準備

インストール前に以下 3 点を確認してください。

1. Neovim 0.8.0 以上 がインストール済みであること
2. Claude Code CLI がインストール済みで claude コマンドが PATH に通っていること
3. folke/snacks.nvim がプラグインマネージャーに登録されていること

Claude Code CLI をローカルインストーラー(claude migrate-installer)で管理している場合、実行パスが ~/.claude/local/claude になります。その場合は後述の terminal_cmd 設定で対応します。

Claude Code CLI のインストールは npm 経由が最も確実です。

npm install -g @anthropic-ai/claude-code
claude --version  # バージョン確認

claudecode.nvim のインストール(lazy.nvim)

lazy.nvim を使っている場合、以下の設定ブロックをプラグイン設定ファイルに追加します(出典: GitHub README)。

{
  "coder/claudecode.nvim",
  dependencies = {
    "folke/snacks.nvim",
  },
  config = true,
  cmd = {
    "ClaudeCode",
    "ClaudeCodeFocus",
    "ClaudeCodeSend",
    "ClaudeCodeAdd",
    "ClaudeCodeDiffAccept",
    "ClaudeCodeDiffDeny",
  },
}

config = true と書くだけでデフォルト設定が適用されます。カスタマイズが必要な場合は opts = { ... } で上書きします。

Neovim を再起動後、:ClaudeCode を実行して Claude Code のターミナルウィンドウが右ペインに現れれば導入成功です。

基本設定オプション

デフォルトから変更したい場合は opts テーブルで上書きします(出典: GitHub)。

opts = {
  -- WebSocket ポートの探索範囲
  port_range = { min = 10000, max = 65535 },
  -- Neovim 起動時に自動で Claude サーバーを立ち上げるか
  auto_start = true,
  -- ログ出力レベル ("info" / "debug" / "warn" / "error")
  log_level = "info",
  -- ローカルインストール時はここに実行パスを指定
  terminal_cmd = nil,  -- 例: "~/.claude/local/claude"
  -- :ClaudeCodeSend 後にフォーカスを Claude 側に移すか
  focus_after_send = false,
  -- カーソル位置・選択範囲を Claude に自動送信するか
  track_selection = true,
  -- ターミナルペインの設定
  terminal = {
    split_side = "right",         -- "left" も選択可
    split_width_percentage = 0.30, -- 画面幅の 30% を Claude ペインに割り当て
    provider = "auto",             -- "snacks" / "native" / "external" / "none"
  },
}

track_selection = true(デフォルト)の状態では、ビジュアルモードで選択した範囲が Claude のコンテキストに自動的に反映されます。「このコードを説明して」と話しかければ選択済みの関数や変数をそのまま対象にできます。

主要コマンド一覧

claudecode.nvim が提供するコマンドは以下の通りです。

:ClaudeCodeAdd は行番号も指定できます。ClaudeCodeAdd path/to/file.lua 10 30 と書くと 10〜30 行目だけをコンテキストに渡せます。

キーマップの設定

毎回 :ClaudeCode とタイプするのは煩雑です。keys テーブルにショートカットを追加しましょう(出典: Zenn)。

{
  "coder/claudecode.nvim",
  dependencies = { "folke/snacks.nvim" },
  config = true,
  keys = {
    -- Claude ターミナルを開く/閉じる
    { "<leader>ac", "<cmd>ClaudeCode<cr>",      desc = "Claude Code 開閉" },
    -- Claude にフォーカスを移す
    { "<leader>af", "<cmd>ClaudeCodeFocus<cr>", desc = "Claude にフォーカス" },
    -- 選択テキストを Claude に送信(ビジュアルモード)
    { "<leader>as", "<cmd>ClaudeCodeSend<cr>",  desc = "Claude に送信",  mode = "v" },
    -- Diff を適用/却下
    { "<leader>ad", "<cmd>ClaudeCodeDiffAccept<cr>", desc = "変更を適用" },
    { "<leader>ax", "<cmd>ClaudeCodeDiffDeny<cr>",   desc = "変更を却下" },
  },
}

<leader> は自分の設定に合わせて読み替えてください。<Space>ac でトグル、ビジュアル選択後に <Space>as で送信、という流れが基本ワークフローになります。

Diff ワークフロー — 変更の確認・適用・却下

claudecode.nvim 最大の魅力が ネイティブ Diff ビューです。Claude がコードの変更を提案すると、Neovim の組み込み Diff 機能で「現在のコード」と「提案後のコード」が並列表示されます(出典: Qiita)。

基本的な流れは次のとおりです。

1. :ClaudeCode でターミナルを開き、変更依頼を入力する
2. Claude がコードを生成・変更すると Diff ビューが自動で立ち上がる
3. 左ペインが変更前、右ペインが変更後として表示される
4. 内容を確認したうえで :ClaudeCodeDiffAccept で適用、または :ClaudeCodeDiffDeny で却下する

承認は個別ファイルごとに行われるため、複数ファイルにまたがる変更も 1 ファイルずつ確認できます。「一括適用して後で問題に気づく」という事故を防ぐ設計です。

キーマップを設定してあれば <leader>ad / <leader>ax だけで操作が完結し、Diff ビューからターミナルに戻る手間もありません。

WebSocket 接続の仕組み

なぜ Neovim と Claude Code CLI が連携できるのか、内部の仕組みを簡単に把握しておくと設定トラブルに対処しやすくなります(出典: Zenn)。

claudecode.nvim は起動時にランダムポートで WebSocket サーバーを立ち上げ、接続情報を ~/.claude/ide/[port].lock ファイルに書き出します。Claude Code CLI がターミナルで起動されると、このロックファイルを読み込んで WebSocket 接続を確立します。

接続後は MCP プロトコルを通じて以下の情報がリアルタイムに同期されます。

• カーソル位置 — 現在どのファイルの何行目を見ているか
• ビジュアル選択範囲 — track_selection = true の場合
• ファイルコンテキスト — :ClaudeCodeAdd で追加したファイル内容
• Diff 操作結果 — 承認・却下のフィードバック

このアーキテクチャは VS Code / JetBrains 公式拡張と完全に同一であるため、将来的に Anthropic が拡張プロトコルを更新した場合も claudecode.nvim 側でキャッチアップしやすい構造になっています。

トラブルシューティング

:ClaudeCode を実行してもウィンドウが開かない

snacks.nvim が正しく読み込まれていない可能性があります。:checkhealth claudecode を実行して依存関係の状態を確認してください。

~/.claude/local/claude を使うローカルインストールで動作しない

opts に terminal_cmd = "~/.claude/local/claude" を追加します。デフォルトでは PATH 上の claude コマンドを探すため、ローカルインストール時は明示指定が必要です。

Diff ビューが表示されるが文字化けする

Neovim の encoding が utf-8 に設定されているか確認してください。set encoding=utf-8 を init.lua / init.vim に追加します。

ポートが競合してサーバーが起動しない

port_range を変更して競合しない範囲を指定します。{ min = 20000, max = 40000 } のように狭めることで探索時間も短縮できます。

Neovim 環境で Claude Code を使いこなしたい場合、claudecode.nvim は現時点で最も完成度の高い選択肢です。Lua ネイティブ・外部依存最小・公式プロトコル互換という 3 要素が揃っており、本番開発環境に組み込んでも安心して使えます。