NeovimをAI IDEに変える：claudecode.nvimの完全ガイド

みなさまこんにちは！株式会社エアークローゼットのBillyです。

この記事は株式会社エアークローゼット Advent Calendar 2025 8日目の記事です。

はじめに

claudecode.nvim は coder/claudecode.nvim が提供する公式プラグインで、WebSocketを通じてNeovimとClaude Code CLIを接続します。このプラグインは Model Context Protocol (MCP) を実装しており、AnthropicのVS CodeやJetBrains拡張機能と同じプロトコルを使用しています。

なぜclaudecode.nvimが必要なのか？

ターミナルでClaude Codeを使用する場合：

• コマンドを入力してコード提案を受け取れる
• しかしClaude Codeはエディタでどのファイルを開いているか分からない

claudecode.nvimを使用すると：

• Claude CodeがNeovimで開いているファイルを認識
• 選択中のコードをリアルタイムで追跡
• 変更を自動的にバッファに適用
• 承認前に差分を表示してレビュー可能

システム要件

• Neovim ≥ 0.8.0
• Claude Code CLIがインストール済み（claudeコマンドが使用可能）
• folke/snacks.nvim（ターミナルサポート用）
• nvim-lua/plenary.nvim

インストール

lazy.nvimを使用

-- ~/.config/nvim/lua/plugins/claudecode.lua
return {
  "coder/claudecode.nvim",
  lazy = false,
  dependencies = {
    "nvim-lua/plenary.nvim",
    "folke/snacks.nvim",
  },
  config = function()
    require("claudecode").setup({})
  end,
}

キーマップ付き設定

return {
  "coder/claudecode.nvim",
  lazy = false,
  dependencies = {
    "nvim-lua/plenary.nvim",
    "folke/snacks.nvim",
  },
  config = function()
    require("claudecode").setup({})
  end,
  keys = {
    { "<leader>ac", "<cmd>ClaudeCode<cr>", desc = "Claude Codeを切り替え" },
    { "<leader>af", "<cmd>ClaudeCodeFocus<cr>", desc = "Claudeにフォーカス" },
    { "<leader>ar", "<cmd>ClaudeCode --resume<cr>", desc = "セッションを再開" },
    { "<leader>as", "<cmd>ClaudeCodeSend<cr>", desc = "選択範囲を送信", mode = "v" },
  },
}

WebSocketの仕組み

接続アーキテクチャ

┌─────────────────┐         WebSocket          ┌─────────────────┐
│                 │◄─────────────────────────► │                 │
│     Neovim      │    ~/.claude/ide/*.lock    │   Claude Code   │
│  (claudecode.   │                            │      CLI        │
│     nvim)       │                            │                 │
└─────────────────┘                            └─────────────────┘
        │                                              │
        │  1. プラグイン起動                             │
        │  2. WebSocketサーバー作成（ランダムポート）       │
        │  3. ポート情報をlockファイルに書き込み            │
        │                                              │
        │                                              │
        │              4. Claude Codeがlockファイルを読む │
        │              5. WebSocket接続                 │
        │◄─────────────────────────────────────────────│
        │                                              │
        │  6. コンテキスト送信（ファイル、選択範囲等）        │
        │─────────────────────────────────────────────►│
        │                                              │
        │              7. Claudeから変更を受信            │
        │◄─────────────────────────────────────────────│

接続プロセスの詳細

1. プラグイン起動: Neovimがロードされると、claudecode.nvimが自動的に開始
2. WebSocketサーバー作成: プラグインはvim.loop（libuv）を使用してランダムポートでサーバーを作成
3. lockファイル書き込み: 接続情報が~/.claude/ide/[port].lockに書き込まれる
4. 検出: Claude Codeで/ideを実行すると、~/.claude/ide/ディレクトリをスキャンしてlockファイルを検索
5. 接続: Claude Codeはlockファイルからポートを読み取り、WebSocket接続を確立
6. MCPプロトコル: 双方がModel Context Protocolで通信

接続の確認

# 現在のlockファイルを確認
ls -la ~/.claude/ide/

# lockファイルの内容（JSON形式）
cat ~/.claude/ide/*.lock

詳細設定

完全な設定

require("claudecode").setup({
  -- ターミナル設定
  terminal_cmd = nil, -- nil = デフォルトの"claude"を使用
                      -- または "~/.claude/local/claude"（ローカルインストール用）

  -- ターミナルプロバイダー
  provider = "snacks", -- "snacks" | "native" | "external"

  -- ウィンドウ設定
  split_side = "right",           -- "left" | "right"
  split_width_percentage = 0.30,  -- 幅30%

  -- 動作設定
  auto_close = true,              -- アクション後にターミナルを自動的に閉じる
  focus_after_send = false,       -- 送信後にClaudeにフォーカス
  track_selection = true,         -- ビジュアル選択を追跡

  -- 作業ディレクトリ
  git_repo_cwd = true,            -- gitルートをcwdとして使用
  -- cwd = "/path/to/project",    -- 静的パス
  -- cwd_provider = function(ctx) -- カスタム関数
  --   return vim.fn.getcwd()
  -- end,
})

フローティングウィンドウ設定

require("claudecode").setup({
  provider = "snacks",
  snacks_win_opts = {
    position = "float",
    width = 0.8,
    height = 0.8,
    border = "rounded",
    title = " Claude Code ",
    title_pos = "center",
  },
})

利用可能なコマンド

コマンド	説明
:ClaudeCode	Claude Codeターミナルを切り替え
:ClaudeCodeFocus	Claudeにフォーカス（スマート切り替え）
:ClaudeCode --resume	前のセッションを再開
:ClaudeCode --continue	会話を続ける
:ClaudeCodeSend	ビジュアル選択をClaudeに送信
:ClaudeCodeAdd <file>	ファイルをコンテキストに追加
:ClaudeCodeSelectModel	Claudeモデルを選択
:ClaudeCodeDiffAccept	提案された変更を承認
:ClaudeCodeDiffDeny	提案された変更を拒否

ワークフロー

1. 基本的な起動

1. プロジェクト内でNeovimを開く
2. プラグインが自動的にWebSocketサーバーを起動
3. :ClaudeCode または <leader>ac を入力
4. Claude Codeターミナルが開く（接続済み）
5. Claudeとのチャットを開始

2. コード選択の送信

1. 質問したいコードをビジュアル選択
2. :ClaudeCodeSend または <leader>as を入力
3. コードがコンテキストと共にClaudeに送信される
4. Claudeがコードを認識して分析可能

3. 変更のレビューと適用

Claudeがコード変更を提案した場合：

1. Neovimがネイティブの差分ビューを開く
2. 左側：現在のコード
3. 右側：Claudeが提案したコード
4. 変更をレビュー
5. :ClaudeCodeDiffAccept で適用
   または :ClaudeCodeDiffDeny で拒否
6. 承認前に編集可能

4. /ideコマンドの使用

別のターミナルからClaude Codeを実行する場合：

# ターミナル1: Neovim
nvim .

# ターミナル2: Claude Code
claude
> /ide        # ClaudeがNeovimを検出して接続
> 今開いているファイルは？
# Claudeが開いているファイルを正確に回答

他のプラグインとの統合

nvim-tree / neo-treeとの連携

プラグインは自動的にファイルブラウザの選択を検出：

-- nvim-treeでの選択も追跡される
-- Claudeがホバー中のファイルを認識

Telescopeとの連携

-- Telescopeを使用してコンテキストに追加するファイルを選択
vim.keymap.set("n", "<leader>aF", function()
  require("telescope.builtin").find_files({
    attach_mappings = function(_, map)
      map("i", "<CR>", function(prompt_bufnr)
        local selection = require("telescope.actions.state").get_selected_entry()
        require("telescope.actions").close(prompt_bufnr)
        vim.cmd("ClaudeCodeAdd " .. selection.path)
      end)
      return true
    end,
  })
end, { desc = "Claudeコンテキストにファイルを追加" })

トラブルシューティング

Claude CodeがNeovimを検出できない

# lockファイルの存在を確認
ls ~/.claude/ide/

# ない場合、Neovimを再起動
# プラグインがlockファイルを再作成する

WebSocket接続に失敗

-- 固定ポートを指定してみる
require("claudecode").setup({
  port = 12345, -- 固定ポート
})

ターミナルが開かない

-- snacks.nvimがインストールされていることを確認
-- またはネイティブターミナルを使用
require("claudecode").setup({
  provider = "native",
})

lockファイルの権限エラー

# 権限を修正
chmod 755 ~/.claude/ide/
chmod 644 ~/.claude/ide/*.lock

他のプラグインとの比較

機能	claudecode.nvim	greggh/claude-code.nvim	codecompanion.nvim
公式MCP	✅	❌	❌
WebSocket	✅	❌	❌
選択追跡	✅	✅	✅
差分ビュー	✅ ネイティブ	✅	✅
マルチプロバイダー	❌ Claudeのみ	❌ Claudeのみ	✅
依存関係	最小限	最小限	多め

ヒントとベストプラクティス

1. 常にgitリポジトリを使用: git_repo_cwd = trueを設定してClaudeがプロジェクトコンテキストを理解できるようにする

2. 適切なキーマップ: すべてのClaudeコマンドに<leader>aプレフィックスを設定

3. 承認前にレビュー: 変更を適用する前に必ず差分ビューを確認

4. Copilotとの併用: claudecode.nvimとcopilot.vimは独立して動作し、両方を使用可能

5. セッション管理: 長い会話を続けるには--resumeを使用

まとめ

claudecode.nvimは、WebSocket経由でClaude Codeと直接接続することで、Neovimを本格的なAI搭載IDEに変えます。MCPプロトコルにより、Claudeは以下のことが可能になります：

• エディタからリアルタイムのコンテキストを認識
• 差分ビューで変更を提案
• ファイルシステムと対話

これは現在、VS CodeやCursorと同様のClaude Code体験を求めるNeovimユーザーにとって最良のソリューションです。

---

参考資料

• coder/claudecode.nvim - GitHub
• greggh/claude-code.nvim - GitHub
• Top 4 Claude Neovim Plugins 2025
• Replacing Cursor With Neovim and Claude Code - Daniel Miessler
• Claude Code Neovim Ghostty Integration - Daniel Miessler