claude-code.el

一个用于 Claude Code CLI 的 Emacs 界面，提供 Emacs 与 Claude AI 之间的集成，以实现编码辅助。

特性

• 无缝的 Emacs 集成：无需离开 Emacs 即可启动、管理并与 Claude 交互
• 保持在当前缓冲区：在不分散注意力的情况下，将代码、区域或命令发送给 Claude
• 即时修复错误：指向 flycheck/flymake 报告的错误，并请求 Claude 进行修复
• 多实例支持：为不同项目或任务运行独立的 Claude 会话
• 快速响应：通过按键（//1/2/3）直接回复 Claude，无需切换缓冲区
• 智能上下文：可选地在向 Claude 发送命令时包含文件路径和行号
• 瞬态菜单：通过瞬态菜单访问所有命令和斜杠命令
• 继续对话：恢复之前的会话或回溯到之前的某个点
• 只读模式：切换到只读模式后，仍可使用常规的 Emacs 命令和快捷键选择并复制文本
• 模式循环切换：在默认模式、自动接受修改模式和计划模式之间快速切换
• 桌面通知：当 Claude 完成处理时收到通知
• 终端选择：兼容 eat 和 vterm 后端
• 完全可定制：自定义快捷键、通知和显示偏好设置

安装

先决条件

• Emacs 30.0 或更高版本
• 已安装并配置好 Claude Code CLI
• 必需：transient (0.7.5+) inheritenv (0.2)
• 可选：eat (0.9.2+) 用于 eat 后端，vterm 用于 vterm 后端
  • 注意：如果未使用 :vc 安装方式，eat 包需要 NonGNU ELPA：

    (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/"))
    

• 可选但推荐：Monet 用于 IDE 集成

使用内置 use-package（Emacs 30+）

;; 将 melpa 添加到包源中，因为 vterm 在 melpa 上：
(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)

;; 安装必需的 inheritenv 依赖：
(use-package inheritenv
  :vc (:url "https://github.com/purcell/inheritenv" :rev :newest))

;; 对于 eat 终端后端：
(use-package eat :ensure t)

;; 对于 vterm 终端后端：
(use-package vterm :ensure t)

;; 安装 claude-code.el
(use-package claude-code :ensure t
  :vc (:url "https://github.com/stevemolitor/claude-code.el" :rev :newest)
  :config
  ;; 可选的 IDE 集成，使用 Monet
  (add-hook 'claude-code-process-environment-functions #'monet-start-server-function)
  (monet-mode 1)

  (claude-code-mode)
  :bind-keymap ("C-c c" . claude-code-command-map)

  ;; 可选地定义重复映射，以便在调用 claude-code-cycle-mode / C-c M 后，“M”键可以循环切换 Claude 的自动接受/计划/确认模式。
  :bind
  (:repeat-map my-claude-code-map ("M" . claude-code-cycle-mode)))

使用 straight.el

;; 安装必需的 inheritenv 依赖：
(use-package inheritenv
  :straight (:type git :host github :repo "purcell/inheritenv"))

;; 对于 eat 终端后端：
(use-package eat
  :straight (:type git
                   :host codeberg
                   :repo "akib/emacs-eat"
                   :files ("*.el" ("term" "term/*.el") "*.texi"
                           "*.ti" ("terminfo/e" "terminfo/e/*")
                           ("terminfo/65" "terminfo/65/*")
                           ("integration" "integration/*")
                           (:exclude ".dir-locals.el" "*-tests.el"))))

;; 对于 vterm 终端后端：
(use-package vterm :straight t)

;; 安装 claude-code.el，使用 :depth 1 以减少下载大小：
(use-package claude-code
  :straight (:type git :host github :repo "stevemolitor/claude-code.el" :branch "main" :depth 1
                   :files ("*.el" (:exclude "images/*")))
  :bind-keymap
  ("C-c c" . claude-code-command-map) ;; 或您喜欢的键
  ;; 可选地定义重复映射，以便在调用 claude-code-cycle-mode / C-c M 后，“M”键可以循环切换 Claude 的自动接受/计划/确认模式。
  :bind
  (:repeat-map my-claude-code-map ("M" . claude-code-cycle-mode))
  :config
  ;; 可选的 IDE 集成，使用 Monet
  (add-hook 'claude-code-process-environment-functions #'monet-start-server-function)
  (monet-mode 1)

  (claude-code-mode))

基本使用

设置前缀键

您需要按照 安装 部分的说明，为 Claude Code 命令映射设置您自己的快捷键。本 README 中的示例使用 C-c c 作为前缀键。

选择 eat 或 vterm

默认情况下，claude-code.el 使用 eat 后端。如果您更喜欢 vterm，请自定义 claude-code-terminal-backend：

(setq claude-code-terminal-backend 'vterm)

瞬态菜单

您可以通过调用瞬态菜单 claude-code-transient (C-c c m) 来查看重要命令列表：

启动和停止 Claude

要启动 Claude，请运行 claude-code (C-c c c)。这将在缓冲区文件所在项目的根目录下启动一个新的 Claude 实例；如果不在任何项目中，则会在当前目录下启动。Claude-code.el 使用 Emacs 内置的 project.el，它适用于大多数版本控制系统。

要在特定目录下启动 Claude，请使用 claude-code-start-in-directory (C-c c d)。系统会提示您输入目录。

claude-code-continue 命令将继续之前的对话，而 claude-code-resume 允许您从之前的会话列表中进行选择。

要终止 Claude 进程并关闭其窗口，请使用 claude-code-kill (C-c c k)。

向 Claude 发送命令

Claude 启动后，您可以切换到 Claude 缓冲区并开始输入提示。或者，您也可以通过 claude-code-send-command（C-c c s）使用 minibuffer 向 Claude 发送提示。claude-code-send-command-with-context（C-c c x）还会将当前文件名和行号发送给 Claude。这在询问“这段代码是做什么的？”或“修复这段代码中的错误”时非常有用。

使用 claude-code-send-region（C-c c r）命令可以将选中的区域发送给 Claude；如果没有选择区域，则会发送整个缓冲区。此命令适用于在普通 Emacs 缓冲区中编写提示并将其发送给 Claude 的场景。如果使用单个前缀参数（C-u C-c c r），它会在发送区域之前提示您提供额外的上下文信息。

您还可以直接将文件发送给 Claude，使用 claude-code-send-file 按路径发送任意文件，或使用 claude-code-send-buffer-file（C-c c o）发送与当前缓冲区关联的文件。claude-code-send-buffer-file 命令支持与 claude-code-send-region 类似的前缀参数——使用单个前缀参数时会提示您输入说明，而使用双前缀参数时还会切换到 Claude 缓冲区。

如果您将光标置于 flymake 或 flycheck 错误上，可以通过 claude-code-fix-error-at-point（C-c c e）请求 Claude 修复该错误。

要显示或隐藏 Claude 缓冲区，请使用 claude-code-toggle（C-c c t）。要跳转到 Claude 缓冲区，请使用 claude-code-switch-to-buffer（C-c c b）。如果缓冲区处于隐藏状态，此命令会将其打开。

管理 Claude 窗口

claude-code-toggle（C-c c t）用于显示或隐藏 Claude 窗口。即使窗口被隐藏，您也可以使用 claude-code-switch-to-buffer（C-c c b）命令切换到 Claude 窗口。

要在 Claude 缓冲区进入只读模式，请使用 claude-code-toggle-read-only-mode（C-c c z）。在此模式下，您可以选择和复制文本，并使用常规的 Emacs 键绑定。再次调用 claude-code-toggle-read-only-mode 即可退出只读模式。

快速回复

有时您希望在不切换到 Claude 缓冲区的情况下快速回复 Claude。以下命令允许您在不离开当前编辑缓冲区的情况下回答 Claude 的问题：

• claude-code-send-return（C-c c y）：向 Claude 发送回车键，通常用于对 Claude 的问题回答“是”。
• claude-code-send-escape（C-c c n）：向 Claude 发送 Esc 键，表示“否”或取消正在执行的 Claude 操作。
• claude-code-send-1（C-c c 1）：向 Claude 发送数字“1”，以响应 Claude 查询并选择选项“1”。
• claude-code-send-2（C-c c 2）：向 Claude 发送数字“2”。
• claude-code-send-3（C-c c 3）：向 Claude 发送数字“3”。

使用 Monet 进行 IDE 集成

您可以选择使用 Monet 进行 IDE 集成。要将 Monet 与 Claude 集成，请执行以下操作（或使用上述等效的 use-package 声明）：

(add-hook 'claude-code-process-environment-functions #'monet-start-server-function)
(monet-mode 1)

当 Claude 启动新实例时，它会自动启动一个 Monet WebSocket 服务器，用于监听并发送 IDE 注释到 Claude 或从 Claude 接收注释。当前选中的内容会自动发送给 Claude，Claude 会在 Emacs 中显示差异、使用 Emacs Monet 工具打开文件、获取诊断信息等。更多详细信息请参阅 Monet 的文档。

多个 Claude 实例的使用

claude-code.el 支持在不同项目和目录中运行多个 Claude 实例。每个 Claude 实例都与特定的目录相关联（项目根目录、文件所在目录或当前目录）。

实例管理

• 当您使用 claude-code 启动 Claude 时，它会为当前目录创建一个实例。
• 如果该目录已经存在 Claude 实例，系统会提示您为新实例命名（例如，“tests”、“docs”）。
• 您也可以使用 claude-code-new-instance 显式创建具有自定义名称的新实例。
• 缓冲区名称遵循以下格式：
  • *claude:/path/to/directory:instance-name*（例如，*claude:/home/user/project:tests*）。
• 如果您所在的目录没有 Claude 实例，但其他目录中已有实例运行，系统会提示您选择一个实例。
• 系统会记住您对该目录的选择，因此后续不会再提示您。

实例选择

针对某个实例的操作命令（如 claude-send-command、claude-code-switch-to-buffer、claude-code-kill 等）会在当前缓冲区所属项目有多个 Claude 实例时提示您选择要使用的实例。

如果缓冲区文件未与任何正在运行的 Claude 实例关联，您可以选择其他项目中正在运行的实例。这在您希望 Claude 分析依赖项目或位于兄弟目录中的文件时非常有用。

Claude-code.el 会记住哪些缓冲区与哪些 Claude 实例相关联，因此您不会反复收到提示。这种关联也有助于 Claude-code.el 在终止 Claude 进程并删除其关联缓冲区时做出正确的处理。

每个目录的多个实例

您可以为同一目录运行多个 Claude 实例，以支持不同的工作流程：

• 目录中的第一个实例是“默认”实例。
• 其他实例在创建时需要命名（例如，“tests”、“docs”、“refactor”）。
• 当一个目录存在多个实例时，与 Claude 交互的命令会提示您选择要使用的实例。
• 使用 C-u claude-code-switch-to-buffer 可以查看所有目录中的所有 Claude 实例（而不仅仅是当前目录）。
• 使用 claude-code-select-buffer 作为专用命令，始终显示所有目录中的所有 Claude 实例。

这样，您可以在同一个项目中为工作的不同方面进行独立的 Claude 对话，例如一个实例用于编写代码，另一个实例用于编写测试。

在 Claude 缓冲区中工作

Claude-code.el 旨在支持在 Emacs 中使用 minibuffer 和常规 Emacs 缓冲区来操作 Claude Code，同时保持正常的键绑定和完整的 Emacs 编辑功能。然而，Claude-code.el 还为在 Claude Code 终端缓冲区中工作添加了一些便利功能：

您可以按 C-g 作为 Esc 键的替代。此外，Claude-code.el 还支持多种在 Claude Code 会话中输入换行的方式：

• 默认（Shift+Return 插入换行）：按 Shift+Return 插入换行，按 Return 发送消息。
• Alt+Return 风格：按 Alt+Return 插入换行，按 Return 发送。
• Shift+Return 发送：按 Return 插入换行，按 Shift+Return 发送。
• Super+Return 发送：按 Return 插入换行，按 Command+Return（macOS）发送。

您可以通过自定义 claude-code-newline-keybinding-style 来更改此行为（参见自定义部分）。

命令参考

• claude-code-transient (C-c c m) - 显示所有命令（瞬态菜单）

• claude-code (C-c c c) - 启动 Claude。使用前缀参数 (C-u) 时，创建后会切换到 Claude 缓冲区。使用双重前缀 (C-u C-u) 时，会提示输入项目目录。

• claude-code-start-in-directory (C-c c d) - 提示输入目录并在该目录下启动 Claude。使用前缀参数 (C-u) 时，创建后会切换到 Claude 缓冲区。

• claude-code-continue (C-c c C) - 启动 Claude 并继续之前的对话。使用前缀参数 (C-u) 时，创建后会切换到 Claude 缓冲区。使用双重前缀 (C-u C-u) 时，会提示输入项目目录。

• claude-code-resume (C-c c R) - 从交互式列表中恢复特定的 Claude 会话。使用前缀参数 (C-u) 时，创建后会切换到 Claude 缓冲区。使用双重前缀 (C-u C-u) 时，会提示输入项目目录。

• claude-code-new-instance (C-c c i) - 创建具有自定义名称的新 Claude 实例。始终提示输入实例名称，而 claude-code 在没有实例存在时会使用“default”。使用前缀参数 (C-u) 时，创建后会切换到 Claude 缓冲区。使用双重前缀 (C-u C-u) 时，会提示输入项目目录。

• claude-code-kill (C-c c k) - 杀死当前的 Claude 会话。

• claude-code-kill-all (C-c c K) - 杀死所有目录下的所有 Claude 实例。

• claude-code-send-command (C-c c s) - 向 Claude 发送命令。使用前缀参数 (C-u) 时，发送后会切换到 Claude 缓冲区。

• claude-code-send-command-with-context (C-c c x) - 带有当前文件和行上下文的命令发送。使用前缀参数 (C-u) 时，发送后会切换到 Claude 缓冲区。

• claude-code-send-region (C-c c r) - 将当前区域或缓冲区发送给 Claude。使用前缀参数 (C-u) 时，会提示添加到文本中的指令。使用双重前缀 (C-u C-u) 时，会添加指令并切换到 Claude 缓冲区。

• claude-code-send-file - 将指定文件发送给 Claude。会提示输入文件路径。

• claude-code-send-buffer-file (C-c c o) - 将当前缓冲区关联的文件发送给 Claude。使用前缀参数 (C-u) 时，会提示添加到文件中的指令。使用双重前缀 (C-u C-u) 时，会添加指令并切换到 Claude 缓冲区。

• claude-code-fix-error-at-point (C-c c e) - 请求 Claude 修复当前光标位置的错误（适用于 flycheck、flymake 及任何实现 help-at-pt 的系统）。使用前缀参数 (C-u) 时，发送后会切换到 Claude 缓冲区。

• claude-code-fork (C-c c f) - 分叉对话（通过向 Claude 发送 escape-escape 跳转到之前的对话）。

• claude-code-slash-commands (C-c c /) - 访问 Claude 斜杠命令菜单。

• claude-code-toggle (C-c c t) - 切换 Claude 窗口的显示状态。

• claude-code-switch-to-buffer (C-c c b) - 切换到 Claude 缓冲区。使用前缀参数 (C-u) 时，会显示所有目录下的所有 Claude 实例。

• claude-code-select-buffer (C-c c B) - 从所有项目和目录下的运行实例中选择并切换到一个 Claude 缓冲区。

• claude-code-toggle-read-only-mode (C-c c z) - 在 Claude 缓冲区中切换只读模式与正常模式（便于选择和复制文本）。

• claude-code-cycle-mode (C-c c M) - 向 Claude 发送 Shift-Tab，以在默认模式、自动接受编辑模式和计划模式之间循环切换。请参阅上方的安装部分，配置重复映射，以便在首次调用后使用 “M” 键即可循环切换模式。

• claude-code-send-return (C-c c y) - 向 Claude 发送回车键（用于在不切换到 Claude REPL 缓冲区的情况下确认操作，例如对 Claude 的“是”做出回应）。

• claude-code-send-escape (C-c c n) - 向 Claude 发送 Esc 键（用于在 Claude 请求确认时说“否”，且无需切换到 Claude REPL 缓冲区）。

• claude-code-send-1 (C-c c 1) - 向 Claude 发送数字“1”（用于在 Claude 提供编号菜单时选择第一个选项）。

• claude-code-send-2 (C-c c 2) - 向 Claude 发送数字“2”（用于在 Claude 提供编号菜单时选择第二个选项）。

• claude-code-send-3 (C-c c 3) - 向 Claude 发送数字“3”（用于在 Claude 提供编号菜单时选择第三个选项）。

桌面通知

claude-code.el 会在 Claude 完成处理并等待输入时通知您。默认情况下，它会在 minibuffer 中显示消息，并使 modeline 脉动以提供视觉反馈。

macOS 原生通知

若要使用带有声音的 macOS 原生通知，请在您的配置中添加以下内容：

(defun my-claude-notify (title message)
  "显示带有声音的 macOS 通知。"
  (call-process "osascript" nil nil nil
                "-e" (format "display notification \"%s\" with title \"%s\" sound name \"Glass\""
                             message title)))

(setq claude-code-notification-function #'my-claude-notify)

这将在 Claude 准备就绪时显示带有“Glass”音效的系统通知。您可以将音效名称更改为任何系统音效（如“Ping”、“Hero”、“Morse”等），或移除 sound name 部分以获得无声通知。

Linux 原生通知

对于 Linux 桌面通知，您可以使用 notify-send（GNOME/Unity）或 kdialog（KDE）：

;; 对于 GNOME/Unity 桌面
(defun my-claude-notify (title message)
  "使用 notify-send 显示 Linux 通知。"
  (if (executable-find "notify-send")
      (call-process "notify-send" nil nil nil title message)
    (message "%s: %s" title message)))

(setq claude-code-notification-function #'my-claude-notify)

要在 Linux 上添加声音：

(defun my-claude-notify-with-sound (title message)
  "显示带有声音的 Linux 通知。"
  (when (executable-find "notify-send")
    (call-process "notify-send" nil nil nil title message))
  ;; 如果 paplay 可用，则播放声音
  (when (executable-find "paplay")
    (call-process "paplay" nil nil nil "/usr/share/sounds/freedesktop/stereo/message.oga")))

(setq claude-code-notification-function #'my-claude-notify-with-sound)

Windows 原生通知

在 Windows 上，你可以使用 PowerShell 创建 Toast 通知：

(defun my-claude-notify (title message)
  "使用 PowerShell 显示 Windows 通知。"
  (call-process "powershell" nil nil nil
                "-NoProfile" "-Command"
                (concat "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null; "
                        "$template = '<toast><visual><binding template=\"ToastGeneric\"><text>" title "</text><text>" message "</text></binding></visual></toast>'; "
                        "$xml = New-Object Windows.Data.Xml.Dom.XmlDocument; "
                        "$xml.LoadXml($template); "
                        "$toast = [Windows.UI.Notifications.ToastNotification]::new($xml); "
                        "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Emacs').Show($toast)")))

(setq claude-code-notification-function #'my-claude-notify)

注意：Linux 和 Windows 的示例尚未经过测试。欢迎提供反馈和改进！

Claude Code 钩子集成

claude-code.el 提供了通过 emacsclient 从 Claude Code CLI 接收钩子事件的功能。

有关钩子监听器和设置函数的全面示例，请参阅 examples/hooks/claude-code-hook-examples.el。

钩子 API

• claude-code-event-hook - 当 Claude Code CLI 触发事件时运行的 Emacs 钩子
• claude-code-handle-hook - 所有 Claude Code CLI 钩子的 统一入口点。请在你的 CLI 钩子中使用 (type buffer-name &rest args) 调用此函数，并将 JSON 数据作为 emacsclient 的额外参数传递。

JSON 响应系统

钩子可以返回结构化的 JSON 数据，以使用 run-hook-with-args-until-success 控制 Claude Code 的行为：

1. 多个处理程序：在 claude-code-event-hook 上注册多个函数
2. 顺序执行：函数按顺序调用，并传递消息数据
3. 首个响应获胜：当某个函数返回非空 JSON 时，执行停止
4. 双向通信：JSON 响应会发送回 Claude Code CLI

这使得交互式工作流成为可能，例如权限提示，其中钩子可以影响 Claude 的行为。

设置步骤

1. 将 bin 目录添加到 PATH 中（这是钩子包装脚本所必需的）：

   export PATH="/path/to/claude-code.el/bin:$PATH"
   

   请将其添加到你的 Bash 配置文件（如 ~/.bashrc、~/.bash_profile 等），因为 Claude Code 需要在 Bash 环境中访问该路径。

2. 启动 Emacs 服务器，以便 emacsclient 可以与你的 Emacs 实例通信：

   ;; 启动 Emacs 服务器（添加到你的 init.el 文件中）
   (start-server)
   
   ;; 使用标准 Emacs 函数添加你的钩子监听器
   (add-hook 'claude-code-event-hook 'my-claude-hook-listener)
   

自定义钩子监听器

钩子监听器会接收到一个包含以下键的消息 plist：

• :type - 钩子类型（例如 'notification、'stop、'pre-tool-use、'post-tool-use）
• :buffer-name - 来自 $CLAUDE_BUFFER_NAME 的 Claude 缓冲区名称
• :json-data - 来自 Claude CLI 的 JSON 负载
• :args - 额外参数列表（在使用扩展配置时）

;; 定义你自己的钩子监听器函数
(defun my-claude-hook-listener (message)
  "Claude Code 钩子的自定义监听器。
MESSAGE 是一个包含 :type、:buffer-name、:json-data 和 :args 键的 plist。"
  (let ((hook-type (plist-get message :type))
        (buffer-name (plist-get message :buffer-name))
        (json-data (plist-get message :json-data))
        (args (plist-get message :args)))
    (cond 
     ((eq hook-type 'notification)
      (message "Claude 已就绪于 %s！JSON：%s" buffer-name json-data))
     ((eq hook-type 'stop)  
      (message "Claude 已完成于 %s！JSON：%s" buffer-name json-data))
     (t
      (message "Claude 钩子：%s，附带 JSON：%s" hook-type json-data)))))

;; 使用标准 Emacs 钩子函数添加钩子监听器
(add-hook 'claude-code-event-hook 'my-claude-hook-listener)

完整的监听器示例可在示例文件中找到，展示了通知、日志记录、Org 模式集成以及如何使用 :args 字段中的额外参数。

Claude Code CLI 配置

配置 Claude Code CLI 钩子，使其通过 emacsclient 调用 claude-code-handle-hook，并将 JSON 数据作为附加参数传递：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "emacsclient --eval \"(claude-code-handle-hook 'notification \\\"$CLAUDE_BUFFER_NAME\\\")\" \"$(cat)\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "emacsclient --eval \"(claude-code-handle-hook 'stop \\\"$CLAUDE_BUFFER_NAME\\\")\" \"$(cat)\""
          }
        ]
      }
    ]
  }
}

命令模式如下：

emacsclient --eval "(claude-code-handle-hook 'notification \"$CLAUDE_BUFFER_NAME\")" "$(cat)" "ARG1" "ARG2" "ARG3"

其中：

• "$(cat)" - 来自标准输入的 JSON 数据（始终必需）
• ARG1 是 "$PWD" - 当前工作目录
• ARG2 是 "$(date -Iseconds)" - 时间戳
• ARG3 是 "$$" - 进程 ID

claude-code-handle-hook 会创建一个发送给监听器的消息 plist：

(list :type 'notification 
      :buffer-name "$CLAUDE_BUFFER_NAME"
      :json-data "$(cat)" 
      :args '("ARG1" "ARG2" "ARG3"))

有关 CLI 钩子设置的详细信息，请参阅 Claude Code 钩子文档。

小贴士与技巧

• 粘贴图片：使用 C-v 将图片粘贴到 Claude 窗口中。请注意，在 macOS 上，应使用 Control-v 而不是 Command-v。
• 粘贴文本：使用 C-y（即 yank）将文本粘贴到 Claude 窗口中。
• 发送命令前保存文件：Claude 直接从磁盘读取文件内容，而不是从 Emacs 缓冲区中读取。在发送引用文件内容的命令之前，请务必先保存文件（C-x C-s）。可以启用 global-auto-revert-mode，以便自动将 Emacs 缓冲区与 Claude 所做的文件更改同步：

  (global-auto-revert-mode 1)
  ;; 如果文件在 Claude 修改后无法可靠地自动重新加载，
  ;; 可以禁用文件通知功能，改用轮询方式：
  (setq auto-revert-use-notify nil)
  

• 通过钩子实现自动重新加载：若需更精细地控制缓冲区的重新加载，可使用监听 Claude 文件编辑的自动重新加载钩子示例：

  ;; 加载自动重新加载钩子
  (load-file "examples/hooks/claude-code-auto-revert-hook.el")
  ;; 设置自动重新加载模式（任选其一）：
  (setup-claude-auto-revert)           ; 安全模式 - 跳过已修改的缓冲区
  (setup-claude-auto-revert-aggressive) ; 提示是否重新加载已修改的缓冲区
  (setup-claude-auto-revert-org)       ; 对 Org 文件进行特殊处理
  

  随后，在你的 ~/.claude/settings.json 中配置 PostToolUse 钩子（参见 examples/hooks/auto-revert-settings.json）。

自定义设置

;; 设置命令映射的快捷键。
(global-set-key (kbd "C-c C-a") claude-code-command-map)

;; 设置 Claude 终端模拟的终端类型（默认为 "xterm-256color"）。
;; 这决定了终端的功能，例如颜色支持等。
;; 更多信息请参阅 eat-term-name 的文档。
(setq claude-code-term-name "xterm-256color")

;; 更改 Claude 可执行文件的路径（默认为 "claude"）。
;; 如果 Claude 不在你的 PATH 中，或你希望使用特定版本时，此设置非常有用。
(setq claude-code-program "/usr/local/bin/claude")

;; 设置 Claude 的命令行参数
;; 例如，启用详细输出
(setq claude-code-program-switches '("--verbose"))

;; 添加在 Claude 启动后运行的钩子
(add-hook 'claude-code-start-hook 'my-claude-setup-function)

;; 调整初始化延迟（默认为 0.1 秒）
;; 这有助于防止在缓冲区显示时，Claude 尚未完全准备好而导致的终端布局问题。
(setq claude-code-startup-delay 0.2)

;; 配置缓冲区大小阈值，用于触发确认提示（默认为 100000 字符）。
;; 如果缓冲区超过此阈值，claude-code-send-region 会在将整个缓冲区发送给 Claude 之前请求确认。
(setq claude-code-large-buffer-threshold 100000)

;; 配置在 Claude 缓冲区中输入换行和发送消息的按键绑定风格。
;; 可选风格如下：
;;   'newline-on-shift-return - S-return 插入换行，RET 发送消息（默认）
;;   'newline-on-alt-return   - M-return 插入换行，RET 发送消息
;;   'shift-return-to-send    - RET 插入换行，S-return 发送消息
;;   'super-return-to-send    - RET 插入换行，s-return 发送消息（macOS 上为 Command+Return）
(setq claude-code-newline-keybinding-style 'newline-on-shift-return)

;; 启用或禁用 Claude 完成任务并等待输入时的通知功能（默认为 t）。
(setq claude-code-enable-notifications t)

;; 自定义通知函数（默认为 claude-code--default-notification）。
;; 该函数应接受两个参数：标题和消息。
;; 默认函数会显示一条消息，并使模型线闪烁以提供视觉反馈。
(setq claude-code-notification-function 'claude-code--default-notification)

;; 示例：使用自定义通知函数
(defun my-claude-notification (title message)
  "Claude Code 的自定义通知函数。"
  ;; 在此处添加你的自定义通知逻辑
  (message "[%s] %s" title message))
(setq claude-code-notification-function 'my-claude-notification)

;; 配置杀掉实例时的确认行为（默认为 t）。
;; 当为 t 时，claude-code-kill 会在终止实例前提示确认。
;; 当为 nil 时，直接终止 Claude 实例而不进行确认。
(setq claude-code-confirm-kill t)

;; 启用或禁用窗口大小调整优化功能（默认为 t）。
;; 启用后，只有当窗口宽度发生变化时才会触发终端重排，
;; 而不会因高度变化而重新绘制。这可以避免在垂直分割窗口时不必要的重绘，
;; 从而提升性能并减少视觉瑕疵。
;; 如果调整窗口大小后出现终端显示问题，可将其设置为 nil。
(setq claude-code-optimize-window-resize t)

;; 启用或禁用 no-delete-other-windows 参数（默认为 nil）。
;; 启用后，Claude Code 窗口将设置 no-delete-other-windows 参数，
;; 从而防止在执行 delete-other-windows 或类似命令时关闭 Claude 窗口，
;; 保持 Claude 缓冲区始终可见且可访问。
(setq claude-code-no-delete-other-windows t)

;; 切换显示 Claude 缓冲区时自动选择该缓冲区（默认为 nil）。
;; 当设置为 t 时，claude-code-toggle 在显示 Claude 缓冲区后会将焦点切换到该缓冲区。
;; 当为 nil 时，缓冲区虽被显示，但焦点仍保留在当前缓冲区。
(setq claude-code-toggle-auto-select t)

自定义窗口位置

使用 display-window 函数

你可以通过设置 claude-code-display-window-fn 来自定义 Claude Code 窗口的显示方式。该函数接收 Claude 缓冲区作为参数，并应以适当的方式显示它：

;; 使用带有自定义配置的 display-buffer
(setq claude-code-display-window-fn #'display-buffer)

;; 示例：使用 popwin 在侧边窗口显示
(setq claude-code-display-window-fn #'display-buffer)
(let ((buffer-regexp "^\\*claude:.+:.+\\*$"))
  (push `(,buffer-regexp :regexp t :width 78 :position left :stick t :noselect nil :dedicated nil)
        popwin:special-display-config))

;; 示例：始终在右侧侧边窗口显示
(defun my-claude-display-right (buffer)
  "将 Claude 缓冲区显示在右侧侧边窗口。"
  (display-buffer buffer '((display-buffer-in-side-window)
                           (side . right)
                           (window-width . 90))))
(setq claude-code-display-window-fn #'my-claude-display-right)

使用 display-buffer-alist

你还可以通过 Emacs 的 display-buffer-alist 控制 Claude Code 窗口的显示方式。例如，让 Claude 窗口始终出现在屏幕右侧的固定侧边窗口中，窗口宽度为 90 个字符：

(add-to-list 'display-buffer-alist
                 '("^\\*claude"
                   (display-buffer-in-side-window)
                   (side . right)
                   (window-width . 90)))

这种布局最适合宽屏显示器。

字体设置

Claude Code 使用了大量的特殊 Unicode 字符，而大多数常见的编程字体并不包含所有这些字符。为了确保 Emacs 能够正确渲染 Claude 的特殊字符，你需要使用一个对 Unicode 支持非常全面的字体，或者为 Emacs 设置回退字体，以便在你首选的字体缺少某个字符时使用。

使用系统字体作为回退

如果你不想安装任何新字体，可以直接使用系统中已有的字体作为回退。以下是在 macOS 上的一个良好配置，假设你的默认首选字体是“Maple Mono”。请将“Maple Mono”替换为你实际使用的默认字体，并将其添加到你的 init.el 文件中：

;; 重要：告诉 Emacs 使用我们的字体集设置
(setq use-default-font-for-symbols nil)

;; 先添加最不常用的字体，最后添加最常用的字体
(set-fontset-font t 'symbol "STIX Two Math" nil 'prepend)
(set-fontset-font t 'symbol "Zapf Dingbats" nil 'prepend)
(set-fontset-font t 'symbol "Menlo" nil 'prepend)

;; 最后添加你的默认首选字体
(set-fontset-font t 'symbol "Maple Mono" nil 'prepend)

在 Linux 或 Windows 上的配置则取决于你系统中可用的字体。要测试你的系统是否安装了某种字体，可以评估以下表达式：

(find-font (font-spec :family "DejaVu Sans Mono"))

在 Linux 上，配置可能如下所示：

(setq use-default-font-for-symbols nil)
(set-fontset-font t 'symbol "DejaVu Sans Mono" nil 'prepend)

;; 你的首选默认字体：
(set-fontset-font t 'symbol "Maple Mono" nil 'prepend)

使用 JuliaMono 作为回退

一种跨平台的方法是安装一款具有出色 Unicode 符号支持的等宽字体。JuliaMono 对 Unicode 符号的支持非常优秀。为了让 Claude Code 缓冲区在渲染 Unicode 字符时使用 Julia Mono，同时在显示 ASCII 字符时仍使用你的默认字体，可以添加以下 Elisp 代码：

(setq use-default-font-for-symbols nil)
(set-fontset-font t 'unicode (font-spec :family "JuliaMono"))

;; 你的首选默认字体：
(set-fontset-font t 'symbol "Maple Mono" nil 'prepend)

自定义 Claude Code 字体

如果你希望仅为 Claude Code REPL 使用特定字体，而在其他地方使用不同的字体，则可以自定义 claude-code-repl-face：

(custom-set-faces
   '(claude-code-repl-face ((t (:family "JuliaMono")))))

（如果将 Claude Code 的字体设置为“JuliaMono”，则可以跳过上述所有的字体集回退配置。）

减少窗口布局变化时的闪烁

为了减少窗口布局变化时 Claude 缓冲区的闪烁，可以在钩子中调整 eat 延迟相关变量。这样做会以增加一些延迟为代价来减少闪烁：

  ;; 减少闪烁
  (add-hook 'claude-code-start-hook
            (lambda ()
              (setq-local eat-minimum-latency 0.033
                          eat-maximum-latency 0.1)))

注意：最近对 claude-code.el 的更新已经修复了闪烁问题，因此现在对这些延迟值进行自定义的需求已经大大降低。

修复竖线之间的空格

如果在 Claude 的输出中看到竖线之间有空格，可以通过调整 line-spacing 值来解决。例如：

;; 设置行间距以减少竖线之间的间隙
(setq line-spacing 0.1)

或者仅针对 Claude 缓冲区应用：

(add-hook 'claude-code-start-hook
          (lambda ()
            ;; 减小行间距以修复竖线间隙
            (setq-local line-spacing 0.1))) 

演示

GIF 演示

这个 演示 展示了 claude-code.el 的实际运行效果，包括访问临时菜单、带文件上下文发送命令以及错误修复等功能。

视频演示

请观看这个 视频演示，它展示了 claude-code.el 插件的功能。该视频由一位插件用户友好地制作并分享。

eat 特定的自定义设置

当使用 eat 终端后端时，还有一些额外的自定义选项可供使用：

;; 自定义只读模式下的光标样式（默认为 '(box nil nil)）
;; 格式为 (CURSOR-ON BLINKING-FREQUENCY CURSOR-OFF)
;; 光标样式选项：'box, 'hollow, 'bar, 'hbar, 或 nil
(setq claude-code-eat-read-only-mode-cursor-type '(bar nil nil))

;; 控制 eat 的滚动缓冲区大小，以支持更长时间的对话
;; 默认值为 131072 个字符，通常已足够
;; 对于非常长的 Claude 会话，你可能需要增大此值
;; 警告：将此值设置为 nil（无限）并不推荐用于 Claude Code，
;; 因为这可能导致长时间会话时出现严重的性能问题。
(setq eat-term-scrollback-size 500000)  ; 增加至 50 万个字符

Vterm 特定的自定义设置

当使用 vterm 终端后端时，还有一些额外的自定义选项可供使用：

;; 启用/禁用缓冲以防止多行输入时的闪烁（默认为 t）
;; 启用后，vterm 输出中看起来像是重绘多行输入框的内容
;; 会短暂地被缓冲，并以单批方式处理
;; 这可以防止 Claude 在扩展其输入框时出现闪烁
(setq claude-code-vterm-buffer-multiline-output t)

;; 控制缓冲的 vterm 输出开始处理之前的延迟时间（默认为 0.01）
;; 这是 vterm 等待收集输出突发的时间，单位为秒
;; 延迟时间越长，闪烁现象可能会越少，但响应速度可能会变慢
;; 默认的 0.01 秒（10 毫秒）是一个较好的平衡点
(setq claude-code-vterm-multiline-delay 0.01)

Vterm 回滚配置

Vterm 有自己的回滚限制，这与 claude-code.el 的设置是分开的。默认情况下，vterm 将回滚限制为 1000 行。为了能够滚动到长时间 Claude 对话的顶部，您可以增加 vterm-max-scrollback：

;; 将 vterm 回滚限制增加到 100000 行（允许的最大值）
;; 注意：这会增加内存使用量
(setq vterm-max-scrollback 100000)

如果您不想全局设置此值，也可以仅针对 Claude 缓冲区使用钩子进行设置：

(add-hook 'claude-code-start-hook
          (lambda ()
            ;; 只对 vterm 后端增加回滚限制
            (when (eq claude-code-terminal-backend 'vterm)
              (setq-local vterm-max-scrollback 100000))))

这样可以确保只有 Claude 缓冲区具有更大的回滚限制，而其他 vterm 缓冲区则保持默认限制。

Vterm 窗口宽度配置

Vterm 有一个最小窗口宽度设置，它会影响文本换行的方式。默认情况下，vterm-min-window-width 被设置为 80 列。如果您将 Claude 窗口调整得比这个限制更窄，Claude 输入框可能会错误地换行，从而导致显示问题。

如果您希望在较窄的窗口中使用 Claude（例如在侧边窗口中），可以调整 vterm-min-window-width。请注意，这必须作为自定义变量设置，可以通过 custom-set-variables 或 setopt 来完成，setq 是不起作用的：

;; 允许 vterm 窗口的宽度低至 40 列
(setopt vterm-min-window-width 40)

这在您喜欢将 Claude 放在狭窄的侧边窗口中，同时在主窗口中编写代码时特别有用。

Vterm 定时器延迟

vterm-timer-delay 变量控制 vterm 在接收数据时刷新其缓冲区的频率。这个延迟时间（以秒为单位）有助于在处理大量输出时管理性能。将其设置为 nil 会完全禁用延迟。

默认值 0.1 秒对于 Claude Code 来说效果很好。由于 Claude 在生成代码或解释时经常会发送大量的数据，因此降低此延迟或将其禁用（设置为 nil）会显著降低性能。除非您遇到特定的显示问题，否则请坚持使用默认值，或者稍微提高一点。

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 Apache License 2.0 许可证——详情请参阅 LICENSE 文件。

claude-code.el 快速上手指南

claude-code.el 是一个 Emacs 插件，旨在将 Claude Code CLI 无缝集成到 Emacs 编辑器中，让你无需离开编辑器即可与 Claude AI 进行代码协作、错误修复和对话。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• Emacs 版本：需要 Emacs 30.0 或更高版本。
• 核心依赖：必须安装并配置好 Claude Code CLI。
• Emacs 包依赖：
  • transient (版本 0.7.5+)
  • inheritenv (版本 0.2)
• 终端后端（二选一）：
  • 推荐：eat (版本 0.9.2+)。若通过非 :vc 方式安装，需添加 NonGNU ELPA 源：

    (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/"))
    

  • 备选：vterm (需从 MELPA 安装)。
• 可选增强：Monet，用于更深层的 IDE 集成（如自动发送选中代码、显示 Diff 等）。

安装步骤

推荐使用 Emacs 30+ 内置的 use-package 进行安装。请将以下配置添加到你的 Emacs 配置文件（如 init.el）中。

1. 配置包归档源

确保已添加 MELPA 源（用于获取 vterm）：

(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)

2. 安装依赖与插件

复制以下代码块到你的配置文件中。该配置会自动安装 inheritenv、终端后端以及 claude-code.el 本身。

;; 安装必需依赖 inheritenv
(use-package inheritenv
  :vc (:url "https://github.com/purcell/inheritenv" :rev :newest))

;; 选择终端后端：推荐使用 eat
(use-package eat :ensure t)
;; 如果偏好 vterm，请使用下面这行代替上面那行：
;; (use-package vterm :ensure t)

;; 安装 claude-code.el
(use-package claude-code :ensure t
  :vc (:url "https://github.com/stevemolitor/claude-code.el" :rev :newest)
  :config
  ;; 可选：启用 Monet IDE 集成
  ;; (add-hook 'claude-code-process-environment-functions #'monet-start-server-function)
  ;; (monet-mode 1)

  (claude-code-mode)
  :bind-keymap ("C-c c" . claude-code-command-map)

  ;; 可选：定义重复映射，方便快速切换模式
  :bind
  (:repeat-map my-claude-code-map ("M" . claude-code-cycle-mode)))

注意：如果你使用 straight.el 管理包，请参考原文 README 中的 straight.el 配置段落进行调整。

基本使用

安装完成后，重启 Emacs 或重新加载配置文件即可开始使用。默认前缀键为 C-c c。

1. 启动 Claude

在项目根目录或当前文件所在目录下，按下 C-c c c (claude-code) 启动一个新的 Claude 会话。

• 若需在特定目录启动，使用 C-c c d。
• 若要恢复之前的会话，使用 C-c c 后选择 continue 或 resume。

2. 发送指令与代码

你可以通过多种方式与 Claude 交互：

• 发送当前文件或区域：
  • C-c c r (claude-code-send-region)：发送选中的代码区域（若无选中则发送整个缓冲区）。
  • C-c c o (claude-code-send-buffer-file)：发送当前文件。
  • C-c c x (claude-code-send-command-with-context)：发送命令并附带当前文件名和行号上下文（适合询问“这段代码做了什么”或“修复此处的 bug"）。
• 直接输入命令：
  • C-c c s (claude-code-send-command)：在 minibuffer 中输入提示词发送给 Claude。
• 快速修复错误：
  • 将光标移至 flycheck 或 flymake 报错处，按下 C-c c e (claude-code-fix-error-at-point) 让 Claude 自动修复。

3. 窗口管理与交互

• 显示/隐藏窗口：C-c c t (claude-code-toggle)。
• 切换焦点：C-c c b (claude-code-switch-to-buffer)。
• 只读模式：C-c c z。在此模式下可使用标准 Emacs 快捷键选择和复制文本。
• 快速响应：无需切换窗口即可回复 Claude 的确认请求：
  • C-c c y：发送回车（确认/Yes）。
  • C-c c n：发送 Esc（取消/No）。
  • C-c c 1 / 2 / 3：发送对应数字选项。

4. 调用菜单

按下 C-c c m (claude-code-transient) 可弹出完整的功能菜单，浏览所有可用命令和斜杠命令。