claude-code.el

An Emacs interface for Claude Code CLI, providing integration between Emacs and Claude AI for coding assistance.

Features

• Seamless Emacs Integration - Start, manage, and interact with Claude without leaving Emacs
• Stay in Your Buffer - Send code, regions, or commands to Claude while keeping your focus
• Fix Errors Instantly - Point at a flycheck/flymake error and ask Claude to fix it
• Multiple Instances - Run separate Claude sessions for different projects or tasks
• Quick Responses - Answer Claude with a keystroke (<return>/<escape>/1/2/3) without switching buffers
• Smart Context - Optionally include file paths and line numbers when sending commands to Claude
• Transient Menu - Access all commands and slash commands through a transient menu
• Continue Conversations - Resume previous sessions or fork to earlier points
• Read-Only Mode - Toggle to select and copy text with normal Emacs commands and keybindings
• Mode Cycling - Quick switch between default, auto-accept edits, and plan modes
• Desktop Notifications - Get notified when Claude finishes processing
• Terminal Choice - Works with eat, vterm, and ghostel (libghostty) backends
• Fully Customizable - Configure keybindings, notifications, and display preferences

Installation

Prerequisites

• Emacs 30.0 or higher
• Claude Code CLI installed and configured
• Required: transient (0.7.5+) inheritenv (0.2)
• Optional: eat (0.9.2+) for eat backend, vterm for vterm backend, ghostel for ghostel backend
  • Note: If not using a :vc install, the eat package requires NonGNU ELPA:

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

• Optional but recommended: Monet for IDE integration

Using builtin use-package (Emacs 30+)

;; add melpa to package archives (vterm and ghostel are on melpa):
(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)

;; install required inheritenv dependency:
(use-package inheritenv
  :vc (:url "https://github.com/purcell/inheritenv" :rev :newest))

;; for eat terminal backend:
(use-package eat :ensure t)

;; for vterm terminal backend:
(use-package vterm :ensure t)

;; for ghostel terminal backend (libghostty):
(use-package ghostel
  :vc (:url "https://github.com/dakra/ghostel" :rev :newest))

;; install claude-code.el
(use-package claude-code :ensure t
  :vc (:url "https://github.com/stevemolitor/claude-code.el" :rev :newest)
  :config
  ;; optional IDE integration with 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)

  ;; Optionally define a repeat map so that "M" will cycle thru Claude auto-accept/plan/confirm modes after invoking claude-code-cycle-mode / C-c M.
  :bind
  (:repeat-map my-claude-code-map ("M" . claude-code-cycle-mode)))

Using straight.el

;; install required inheritenv dependency:
(use-package inheritenv
  :straight (:type git :host github :repo "purcell/inheritenv"))

;; for eat terminal backend:
(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"))))

;; for vterm terminal backend:
(use-package vterm :straight t)

;; for ghostel terminal backend (libghostty):
(use-package ghostel
  :straight (:type git :host github :repo "dakra/ghostel"))

;; install claude-code.el, using :depth 1 to reduce download size:
(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) ;; or your preferred key
  ;; Optionally define a repeat map so that "M" will cycle thru Claude auto-accept/plan/confirm modes after invoking claude-code-cycle-mode / C-c M.
  :bind
  (:repeat-map my-claude-code-map ("M" . claude-code-cycle-mode))
  :config
  ;; optional IDE integration with Monet
  (add-hook 'claude-code-process-environment-functions #'monet-start-server-function)
  (monet-mode 1)

  (claude-code-mode))

Basic Usage

Setting Prefix Key

You need to set your own key binding for the Claude Code command map, as described in the Installation section. The examples in this README use C-c c as the prefix key.

Picking a Terminal Backend

claude-code.el supports three terminal backends:

• eat (default) — pure Elisp terminal emulator, no external dependencies beyond its own Emacs package.
• vterm — libvterm-based terminal; generally snappier than eat but requires compiling a native module.
• ghostel — libghostty-based terminal; typically faster than vterm and renders the Claude TUI most faithfully. Requires the ghostel package.

Switch backends by customizing claude-code-terminal-backend:

;; Use vterm:
(setq claude-code-terminal-backend 'vterm)

;; Use ghostel (libghostty-powered terminal emulator):
(setq claude-code-terminal-backend 'ghostel)

Transient Menu

You can see a menu of the important commands by invoking the transient, claude-code-transient (C-c c m):

Starting and Stopping Claude

To start Claude, run claude-code (C-c c c). This will start a new Claude instance in the root project directory of the buffer file, or the current directory if outside of a project. Claude-code.el uses Emacs built-in project.el which works with most version control systems.

To start Claude in a specific directory use claude-code-start-in-directory (C-c c d). It will prompt you for the directory.

The claude-code-continue command will continue the previous conversation, and claude-code-resume will let you pick from a list of previous sessions.

To kill the Claude process and close its window use claude-code-kill (C-c c k).

Sending Commands to Claude

Once Claude has started, you can switch to the Claude buffer and start entering prompts. Alternately, you can send prompts to Claude using the minibuffer via claude-code-send-command (C-c c s). claude-code-send-command-with-context (C-c c x) will also send the current file name and line number to Claude. This is useful for asking things like "what does this code do?", or "fix the bug in this code".

Use the claude-code-send-region (C-c c r) command to send the selected region to Claude, or the entire buffer if no region is selected. This command is useful for writing a prompt in a regular Emacs buffer and sending it to Claude. With a single prefix arg (C-u C-c c r) it will prompt for extra context before sending the region to Claude.

You can also send files directly to Claude using claude-code-send-file to send any file by path, or claude-code-send-buffer-file (C-c c o) to send the file associated with the current buffer. The claude-code-send-buffer-file command supports prefix arguments similar to claude-code-send-region - with a single prefix arg it prompts for instructions, and with double prefix it also switches to the Claude buffer.

If you put your cursor over a flymake or flycheck error, you can ask Claude to fix it via claude-code-fix-error-at-point (C-c c e).

To show and hide the Claude buffer use claude-code-toggle (C-c c t). To jump to the Claude buffer use claude-code-switch-to-buffer (C-c c b). This will open the buffer if hidden.

Managing Claude Windows

The claude-code-toggle (C-c c t) will show and hide the Claude window. Use the claude-code-switch-to-buffer (C-c c b) command to switch to the Claude window even if it is hidden.

To enter read-only mode in the Claude buffer use claude-code-toggle-read-only-mode (C-c c z). In this mode you can select and copy text, and use regular Emacs keybindings. To exit read-only mode invoke claude-code-toggle-read-only-mode again.

Quick Responses

Sometimes you want to send a quick response to Claude without switching to the Claude buffer. The following commands let you answer a query from Claude without leaving your current editing buffer:

• claude-code-send-return (C-c c y) - send the return or enter key to Claude, commonly used to respond with "Yes" to Claude queriesy
• claude-code-send-escape (C-c c n) - send the escape key, to say "No" to Claude or to cancel a running Claude action
• claude-code-send-1 (C-c c 1) - send "1" to Claude, to choose option "1" in response to a Claude query
• claude-code-send-2 (C-c c 2) - send "2" to Claude
• claude-code-send-3 (C-c c 3) - send "3" to Claude

IDE Integration with Monet

You can optionally use Monet for IDE integration. To integrate Monet with Claude do this (or the equivalent use-package declaration shown above):

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

When Claude starts a new instance it will automatically start a Monet websocket server to listen to and send IDE comments to/from Claude. Current selection will automatically be sent to Claude, and Claude will show diffs in Emacs, use Emacs Monet tools to open files, get diagnostics, etc. See the Monet documentation for more details.

Community Extensions

• claude-code-extras by @lsy83971 — adds a dedicated input buffer for composing multi-line prompts (with send history), an instance manager dashboard (tabulated-list-mode), same-window display advice, copy/paste support for the vterm backend, and a spinner glyph fix. Worth a look if any of those features fit your workflow.

Working with Multiple Claude Instances

claude-code.el supports running multiple Claude instances across different projects and directories. Each Claude instance is associated with a specific directory (project root, file directory, or current directory).

Instance Management

• When you start Claude with claude-code, it creates an instance for the current directory
• If a Claude instance already exists for the directory, you'll be prompted to name the new instance (e.g., "tests", "docs")
• You can also use claude-code-new-instance to explicitly create a new instance with a custom name
• Buffer names follow the format:
  • *claude:/path/to/directory:instance-name* (e.g., *claude:/home/user/project:tests*)
• If you're in a directory without a Claude instance but have instances running in other directories, you'll be prompted to select one
• Your selection is remembered for that directory, so you won't be prompted again

Instance Selection

Commands that operate on an instance (claude-send-command, claude-code-switch-to-buffer, claude-code-kill, etc.) will prompt you for the Claude instance if there is more than one instance associated with the current buffer's project.

If the buffer file is not associated with a running Claude instance, you can select an instance running in a different project. This is useful when you want Claude to analyze dependent projects or files that you have checked out in sibling directories.

Claude-code.el remembers which buffers are associated with which Claude instances, so you won't be repeatedly prompted. This association also helps claude-code.el "do the right thing" when killing a Claude process and deleting its associated buffer.

Multiple Instances Per Directory

You can run multiple Claude instances for the same directory to support different workflows:

• The first instance in a directory is the "default" instance
• Additional instances require a name when created (e.g., "tests", "docs", "refactor")
• When multiple instances exist for a directory, commands that interact with Claude will prompt you to select which instance to use
• Use C-u claude-code-switch-to-buffer to see all Claude instances across all directories (not just the current directory)
• Use claude-code-select-buffer as a dedicated command to always show all Claude instances across all directories

This allows you to have separate Claude conversations for different aspects of your work within the same project, such as one instance for writing code and another for writing tests.

Working in the Claude Buffer

claude-code.el is designed to support using Claude Code in Emacs using the minibuffer and regular Emacs buffers, with normal keybindings and full Emacs editing facilities. However, claude-code.el also adds a few niceties for working in the Claude Code terminal buffer:

You can type C-g as an alternative to escape. Also claude-code.el supports several options for entering newlines in the Claude Code session:

• Default (newline-on-shift-return): Press Shift-Return to insert a newline, Return to send your message
• Alt-return style: Press Alt-Return to insert a newline, Return to send
• Shift-return to send: Press Return to insert a newline, Shift-Return to send
• Super-return to send: Press Return to insert a newline, Command-Return (macOS) to send

You can change this behavior by customizing claude-code-newline-keybinding-style (see Customization).

Command Reference

• claude-code-transient (C-c c m) - Show all commands (transient menu)
• claude-code (C-c c c) - Start Claude. With prefix arg (C-u), switches to the Claude buffer after creating. With double prefix (C-u C-u), prompts for the project directory
• claude-code-start-in-directory (C-c c d) - Prompt for a directory and start Claude there. With prefix arg (C-u), switches to the Claude buffer after creating
• claude-code-continue (C-c c C) - Start Claude and continue the previous conversation. With prefix arg (C-u), switches to the Claude buffer after creating. With double prefix (C-u C-u), prompts for the project directory
• claude-code-resume (C-c c R) - Resume a specific Claude session from an interactive list. With prefix arg (C-u), switches to the Claude buffer after creating. With double prefix (C-u C-u), prompts for the project directory
• claude-code-new-instance (C-c c i) - Create a new Claude instance w