Claude Code 登陆 Emacs 编辑器

Claude Code IDE for Emacs 通过 Model Context Protocol (MCP) 提供了与 Claude Code CLI 的原生集成。与简单的终端包装器不同，该包创建了 Claude 和 Emacs 之间的双向桥接，使 Claude 能够理解并利用 Emacs 的强大功能——从 LSP 和项目管理到自定义 Elisp 函数。这将 Claude 转变为真正的 Emacs 感知 AI 助手，可在现有工作流中工作并与整个 Emacs 生态系统交互。

自动项目检测和会话管理

使用 vterm、eat 或 ghostel 的终端集成，完整色彩支持

IDE 集成的 MCP 协议实现

文件操作、编辑器状态和工作区信息的工具支持

可扩展的 MCP 工具服务器，用于访问 Emacs 命令（xrefs、tree-sitter、项目信息等）

Flycheck 和 Flymake 诊断集成

带 ediff 集成的高级 diff 视图（在应用建议前修改）

Tab-bar 支持，确保正确的上下文切换

选区和缓冲区追踪，增强上下文感知

Emacs 工具集成

该包使 Claude Code 能够通过 MCP 工具集成利用 Emacs 的全部功能。Claude 可以直接访问和利用 Emacs 的能力，包括：

Language Server Protocol (LSP) 集成，通过 xref 命令进行智能代码导航（eglot、lsp-mode 等）

Tree-sitter 用于语法树分析和在 AST 级别理解代码结构

Imenu 用于文件内的结构化符号列表和导航

项目集成用于项目感知的操作

任何 Emacs 命令或函数都可以作为 MCP 工具公开，允许 Claude：

• 执行项目范围的搜索和重构
• 访问专业模式及其功能
• 执行量身定制的自定义 Elisp 函数以适应工作流

这种深度集成意味着 Claude Code 理解你的项目上下文，可以利用 Emacs 广泛的生态系统提供更智能和上下文感知的协助。

活跃文件感知

Claude Code 自动识别你在 Emacs 中当前查看的文件

代码选区上下文

Claude Code 可以访问和处理缓冲区中的选定文本

带诊断的高级 Diff 视图

集成的 ediff 视图用于代码更改，Claude Code 能够直接访问已打开文件的诊断数据（错误、警告等）

自动文本提及

自动在 Claude 对话中提及和引用选定的文本

使用 –resume 标志恢复之前的 Claude Code 对话

需求

• Claude Code CLI 已安装并在 PATH 中可用
• vterm、eat 或 ghostel 包（用于终端支持）

安装 Claude Code CLI

按照 Claude Code 文档 的安装说明操作。

安装 Emacs 包

当前该包还在早期开发阶段。

若要使用 emacs-version >= 30 和带 vc 绑定的 use-package 安装：

(use-package claude-code-ide
  :vc (:url "https://github.com/manzaltu/claude-code-ide.el" :rev :newest)
  :bind ("C-c C-'" . claude-code-ide-menu) ; Set your favorite keybinding
  :config
  (claude-code-ide-emacs-tools-setup)) ; Optionally enable Emacs MCP tools

若要使用 use-package 和 straight.el 安装：

(use-package claude-code-ide
  :straight (:type git :host github :repo "manzaltu/claude-code-ide.el")
  :bind ("C-c C-'" . claude-code-ide-menu) ; Set your favorite keybinding
  :config
  (claude-code-ide-emacs-tools-setup)) ; Optionally enable Emacs MCP tools

Doom Emacs

(package! claude-code-ide
  :recipe (:host github :repo "manzaltu/claude-code-ide.el"))

(use-package! claude-code-ide
  :bind ("C-c C-'" . claude-code-ide-menu) ; Set your favorite keybinding
  :config
  (claude-code-ide-emacs-tools-setup)) ; Optionally enable Emacs MCP tools

保存上述内容后，在终端中运行：doom sync。

与 Claude Code IDE 交互的最简单方式是通过瞬态菜单界面，它提供对所有可用命令的可视化访问。只需运行 M-x claude-code-ide-menu 打开交互式菜单。

多项目支持

Claude Code IDE 使用 Emacs 内置的 project.el 自动检测你的项目。每个项目都获得自己的 Claude Code 实例，缓冲区名称为 *claude-code[project-name]*。

你可以同时为不同项目运行多个 Claude Code 实例。使用 claude-code-ide-list-sessions 查看所有活跃会话并在它们之间切换。

当会话已活跃时运行 claude-code-ide 将切换窗口可见性

窗口可以通过标准 Emacs 窗口命令（C-x 0）关闭而无需停止 Claude

使用 claude-code-ide-toggle-recent 从任何地方切换最近的 Claude 窗口，无论你当前的项目上下文如何。当你在项目目录之外但想快速隐藏/显示 Claude 时，这很有用。

使用 Ediff 进行 Diff 查看

当启用 claude-code-ide-use-ide-diff（默认）时，Claude 的代码建议使用 Emacs 强大的 ediff 界面显示。这提供了两个关键优势：

可视化 diff 比较 — 通过并排或统一 diff 视图查看 Claude 确切想要更改的内容

交互式编辑 — 你可以在应用建议前修改 Claude 的建议

当 Claude 建议代码更改时，ediff 会自动打开

ediff 控制缓冲区变为活跃（一个带有 ediff 命令的小窗口）

缓冲区 A 显示当前代码，缓冲区 B 显示 Claude 的建议

你可以修改缓冲区 B 来改进 Claude 的建议更改

在 ediff 控制缓冲区中按 q 退出

出现提示时，选择是否接受更改（y 或 n）

如果接受（y），缓冲区 B 的任何更改将被发送回 Claude 以应用到原始文件

这允许你在应用前改进 Claude 的建议，确保最终代码符合你的确切要求。

配置变量

侧窗口配置

Claude Code 缓冲区默认在侧窗口中打开。你可以自定义放置位置：

;; Open Claude on the left side
(setq claude-code-ide-window-side 'left)

;; Open Claude at the bottom with custom height
(setq claude-code-ide-window-side 'bottom
      claude-code-ide-window-height 30)

;; Open Claude on the right with custom width
(setq claude-code-ide-window-side 'right
      claude-code-ide-window-width 100)

;; Don't automatically focus the Claude window
(setq claude-code-ide-focus-on-open nil)

;; Keep focus on ediff control window when opening diffs
(setq claude-code-ide-focus-claude-after-ediff nil)

;; Hide Claude window during ediff for more screen space
(setq claude-code-ide-show-claude-window-in-ediff nil)

;; Disable IDE diff viewer to show diffs in terminal instead
(setq claude-code-ide-use-ide-diff nil)

或者，如果你更愿意使用常规窗口：

;; Use regular window instead of side window
(setq claude-code-ide-use-side-window nil)

终端后端配置

Claude Code IDE 支持 vterm、eat 和 ghostel 作为终端后端，默认使用 vterm。

注意：在可用的后端中，ghostel 提供了最顺畅的体验：其渲染基本上不受 vterm 和 eat 容易出现的闪烁、滚动故障和显示伪影的影响，因此如果你的设置中有 ghostel，建议选择它。

要切换到另一个后端：

;; Use eat instead of vterm
(setq claude-code-ide-terminal-backend 'eat)

;; Use ghostel instead of vterm
(setq claude-code-ide-terminal-backend 'ghostel)

;; Or switch back to vterm (default)
(setq claude-code-ide-terminal-backend 'vterm)

eat 后端是一个纯 Elisp 终端模拟器，在某些 vterm 编译有问题的环境中可能工作更好。ghostel 后端使用 Ghostel 的终端集成，需要提供 ghostel-exec 的版本。所有后端都提供完整的终端功能，包括色彩支持和特殊按键处理。

Claude Code 包含一个实验性替代终端渲染器，可以消除闪烁。要启用它：

(setq claude-code-ide-no-flicker t)

注意，使用此渲染器，普通的 Emacs 缓冲区滚动和搜索（C-s、C-r）将在终端缓冲区中不起作用。而是使用 Claude Code 的内置按键绑定：

C-o j / C-o k - 通过记录向上/向下滚动

C-o / - 搜索记录

Claude Code IDE 为 vterm 终端包含智能闪烁缩减，以提供更平滑的视觉输出：

;; Enable/disable vterm anti-flicker optimization (enabled by default)
(setq claude-code-ide-vterm-anti-flicker t)

;; Adjust the render delay for batching updates (default is 0.005 seconds)
(setq claude-code-ide-vterm-render-delay 0.01)  ; Increase for smoother but less responsive

这种优化检测快速终端重绘序列（例如 Claude 扩展文本区域时）并将其批处理以获得更平滑的渲染。5ms 默认延迟在不易察觉的延迟下提供最佳视觉质量。

Claude Code IDE 在启动终端时包含简短的初始化延迟，以确保正确的布局渲染：

;; Adjust the terminal initialization delay (default is 0.1 seconds)
(setq claude-code-ide-terminal-initialization-delay 0.15)

;; Or disable it entirely (may cause visual glitches)
(setq claude-code-ide-terminal-initialization-delay 0)

这个延迟防止了终端模拟初始化时可能发生的显示伪影，如提示不对齐和光标定位错误。默认 100ms 的延迟基本上不易察觉，但确保可靠的终端启动。

Claude Code IDE 为终端添加了自定义按键绑定，以便更容易交互：

这些按键绑定自动为 vterm、eat 和 ghostel 后端设置，仅在 Claude Code 终端缓冲区内适用。

Claude Code IDE 包含针对已知 Claude Code bug (#1422) 的临时解决方案，其中窗口调整大小期间的终端回流可能导致不可控的滚动。此解决方案默认启用，但如需可以禁用：

;; Disable the terminal reflow glitch prevention (not recommended until bug is fixed)
(setq claude-code-ide-prevent-reflow-glitch nil)

一旦上游 bug 修复，解决方案将被删除。

诊断配置

Claude Code IDE 支持 Flycheck 和 Flymake 用于代码诊断。默认情况下，它将自动检测哪一个是活跃的：

;; Let Claude Code automatically detect the active diagnostics backend
(setq claude-code-ide-diagnostics-backend 'auto) ; default

;; Or force a specific backend
(setq claude-code-ide-diagnostics-backend 'flycheck)
(setq claude-code-ide-diagnostics-backend 'flymake)

Claude Code 可以通过 executeCode MCP 工具直接在你运行的 Emacs 会话中评估 Elisp 表达式。这默认启用。

(setq claude-code-ide-enable-execute-code nil)

你可以自定义 Claude Code 缓冲区的命名方式：

(setq claude-code-ide-buffer-name-function
      (lambda (directory)
        (if directory
            (format "*Claude:%s*" (file-name-nondirectory (directory-file-name directory)))
          "*Claude:Global*")))

你可以向 Claude Code CLI 传递额外的标志：

;; Use a specific model
(setq claude-code-ide-cli-extra-flags "--model opus")

;; Pass multiple flags
(setq claude-code-ide-cli-extra-flags "--model opus --no-cache")

;; Flags are added to all Claude Code sessions

注意：这些标志被附加到 Claude 命令后，在任何内置标志（如 -d（调试）或 -r（恢复））之后。

你可以在 Claude 的默认 prompt 后附加自定义系统 prompt，允许你为特定项目或上下文自定义 Claude 的行为：

;; Set a custom system prompt
(setq claude-code-ide-system-prompt "You are an expert in Elisp and Emacs development.")

;; Or configure it per-project using dir-locals.el
;; In .dir-locals.el:
((nil . ((claude-code-ide-system-prompt . "Focus on functional programming patterns and avoid mutations."))))

;; Set via the transient menu: M-x claude-code-ide-menu → Configuration → Set system prompt

设置后，这会将 --append-system-prompt 标志添加到 Claude 命令。设置为 nil 以禁用（默认）。

要为 Claude Code CLI 启用调试模式（传递 -d 标志）：

(setq claude-code-ide-cli-debug t)

要启用 Emacs 内的调试日志记录（记录 WebSocket 消息和 JSON-RPC 通信）：

(setq claude-code-ide-debug t)

然后使用以下方式查看调试日志：

M-x claude-code-ide-show-debug - 显示调试缓冲区

M-x claude-code-ide-clear-debug - 清除调试缓冲区

调试缓冲区显示：

WebSocket 连接事件

所有 JSON-RPC 消息（请求/响应）

错误消息和诊断

带有会话上下文的常规调试信息

在一个项目上运行多个 Claude Code 实例

使用 git worktrees 是在同一项目的不同分支上运行多个 Claude Code 实例的推荐方式。这允许你并行开发功能或修复错误：

# Create a new worktree for a feature branch
git worktree add ../myproject-worktree feature-branch

;; Start Claude Code in the main project
find-file /path/to/myproject
M-x claude-code-ide

;; Start another Claude Code instance in the worktree
find-file /path/to/myproject-worktree
M-x claude-code-ide

每个 worktree 由 project.el 视为单独的项目，允许你具有独立的 Claude Code 会话及其自己的缓冲区（例如 *claude-code[myproject]* 和 *claude-code[myproject-worktree]*）。

内置 MCP 工具

Claude Code IDE 包含内置的 MCP 工具，将 Emacs 功能公开给 Claude，启用强大的代码导航和分析能力：

xref-find-references - 在整个项目中查找符号的所有引用

xref-find-apropos - 在整个项目中查找与模式匹配的符号

treesit-info - 获取 tree-sitter 语法树信息以进行深层代码结构分析

imenu-list-symbols - 使用 imenu 列出文件中的所有符号（函数、类、变量）

project-info - 获取当前项目的信息（目录、文件等）

要启用这些工具，添加到你的配置中：

;; Set up the built-in Emacs tools
(claude-code-ide-emacs-tools-setup)

启用后，Claude 可以使用这些工具导航你的代码库。例如：

"Find the definition of function foo"

"Show me all places where this variable is used"

"What type of AST node is under the cursor?"

"Analyze the parse tree of this entire file"

"List all functions and variables in this file"

"How many files are in this project?"

创建自定义 MCP 工具

你可以通过 MCP 工具系统将自己的 Emacs 函数公开给 Claude。这允许 Claude 与专业 Emacs 功能、自定义命令或特定领域功能交互。

工具定义格式

使用 claude-code-ide-make-tool 函数定义工具：

(claude-code-ide-make-tool
 :function #'function-name     ; The Emacs function to call
 :name "tool_name"             ; Name for Claude to use (snake_case recommended)
 :description "..."            ; Human-readable description
 :args '((:name "param1"       ; List of argument specifications
          :type string         ; Type: string, number, integer, boolean, etc.
          :description "..."   ; What this parameter does
          :optional t)))       ; Optional parameters marked with :optional t

可用的参数类型：string、number、integer、boolean、array、object、null

上下文感知工具示例

;; Define a context-aware function that operates in the session's project
(defun my-project-grep (pattern)
  "Search for PATTERN in the current session's project."
  (claude-code-ide-mcp-server-with-session-context nil
    ;; This executes with the session's project directory as default-directory
    (let* ((project-dir default-directory)
           (results (shell-command-to-string
                    (format "rg -n '%s' %s" pattern project-dir))))
      results)))

;; Define and register the tool (automatically added to claude-code-ide-mcp-server-tools)
(claude-code-ide-make-tool
 :function #'my-project-grep
 :name "my_project_grep"
 :description "Search for pattern in project files"
 :args '((:name "pattern"
          :type string
          :description "Pattern to search for")))

;; Enable Emacs tool MCP server
(claude-code-ide-emacs-tools-setup)

claude-code-ide-mcp-server-with-session-context 宏确保你的工具在正确的项目上下文中执行。

许可证

该项目在 GNU General Public License v3.0 或更高版本下获得许可。详见 LICENSE 文件。

Claude® 是 Anthropic, PBC 的注册商标。Claude Code 是由 Anthropic, PBC 开发的应用程序。

相关资源

Claude Code VS Code Extension

claudecode.nvim - Neovim 集成