Claude Code IDE for Emacs
Overview
Claude Code IDE for Emacs provides native integration with Claude Code CLI through the Model Context Protocol (MCP). Unlike simple terminal wrappers, this package creates a bidirectional bridge between Claude and Emacs, enabling Claude to understand and leverage Emacs’ powerful features—from LSP and project management to custom Elisp functions. This transforms Claude into a true Emacs-aware AI assistant that works within your existing workflow and can interact with your entire Emacs ecosystem.
Features
Automatic project detection and session management
Terminal integration with full color support using vterm or eat
or MCP protocol implementation for IDE integration
Tool support for file operations, editor state, and workspace info
Extensible MCP tools server for accessing Emacs commands (xrefs, tree-sitter, project info, e.g.)
Diagnostic integration with Flycheck and Flymake
Advanced diff view with ediff integration
Tab-bar support for proper context switching
Selection and buffer tracking for better context awareness
Emacs Tool Integration
This package enables Claude Code to leverage the full power of Emacs through MCP tools integration. Claude can directly access and utilize Emacs capabilities including:
Language Server Protocol (LSP) integration through xref commands for intelligent code navigation (eglot, lsp-mode and others)
integration through xref commands for intelligent code navigation (eglot, lsp-mode and others) Tree-sitter for syntax tree analysis and understanding code structure at the AST level
for syntax tree analysis and understanding code structure at the AST level Imenu for structured symbol listing and navigation within files
for structured symbol listing and navigation within files Project integration for project-aware operations
integration for project-aware operations Any Emacs command or function can be exposed as an MCP tool, allowing Claude to: Perform project-wide searches and refactoring Access specialized modes and their features Execute custom Elisp functions tailored to your workflow
can be exposed as an MCP tool, allowing Claude to:
This deep integration means Claude Code understands your project context and can leverage Emacs’ extensive ecosystem to provide more intelligent and context-aware assistance.
Screenshots
Active File Awareness
Claude Code automatically knows which file you’re currently viewing in Emacs
Code Selection Context
Claude Code can access and work with selected text in your buffers
Advanced Diff View with Diagnostics
Integrated ediff view for code changes, with Claude Code able to directly access diagnostic data (errors, warnings, etc.) from opened files
Automatic Text Mentions
Automatically mention and reference selected text in Claude conversations
Session Restoration
Resume previous Claude Code conversations with the –resume flag
Installation
Prerequisites
Emacs 28.1 or higher
Claude Code CLI installed and available in PATH
vterm or eat package (for terminal support)
Installing Claude Code CLI
Follow the installation instructions at Claude Code Documentation.
Installing the Emacs Package
Currently, this package is in early development. To install using use-package and 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
Usage
Basic Commands
The easiest way to interact with Claude Code IDE is through the transient menu interface, which provides visual access to all available commands. Simply run M-x claude-code-ide-menu to open the interactive menu.
Command Description M-x claude-code-ide-menu Open transient menu with all Claude Code commands M-x claude-code-ide-emacs-tools-setup Set up built-in MCP tools (e.g. xref, project) M-x claude-code-ide Start Claude Code for the current project M-x claude-code-ide-send-prompt Send prompt to Claude from minibuffer input M-x claude-code-ide-continue Continue most recent conversation in directory M-x claude-code-ide-resume Resume Claude Code with previous conversation M-x claude-code-ide-stop Stop Claude Code for the current project M-x claude-code-ide-switch-to-buffer Switch to project’s Claude buffer M-x claude-code-ide-list-sessions List all active Claude Code sessions and switch M-x claude-code-ide-check-status Check if Claude Code CLI is installed and working M-x claude-code-ide-insert-at-mentioned Send selected text to Claude prompt M-x claude-code-ide-send-escape Send escape key to Claude terminal M-x claude-code-ide-insert-newline Insert newline in Claude prompt (sends \ + Enter) M-x claude-code-ide-toggle Toggle visibility of Claude Code window M-x claude-code-ide-show-debug Show the debug buffer with WebSocket messages M-x claude-code-ide-clear-debug Clear the debug buffer
Multi-Project Support
Claude Code IDE automatically detects your project using Emacs’ built-in project.el . Each project gets its own Claude Code instance with a unique buffer name like *claude-code[project-name]* .
You can run multiple Claude Code instances simultaneously for different projects. Use claude-code-ide-list-sessions to see all active sessions and switch between them.
Window Management
Running claude-code-ide when a session is already active will toggle the window visibility
when a session is already active will toggle the window visibility The window can be closed with standard Emacs window commands ( C-x 0 ) without stopping Claude
Configuration
Configuration Variables
Variable Description Default claude-code-ide-cli-path Path to Claude Code CLI "claude" claude-code-ide-buffer-name-function Function for buffer naming claude-code-ide--default-buffer-name claude-code-ide-cli-debug Enable CLI debug mode (-d flag) nil claude-code-ide-cli-extra-flags Additional CLI flags (e.g. “–model”) "" claude-code-ide-debug Enable debug logging nil claude-code-ide-terminal-backend Terminal backend (vterm or eat) 'vterm claude-code-ide-log-with-context Include session context in log messages t claude-code-ide-debug-buffer Buffer name for debug output "*claude-code-ide-debug*" claude-code-ide-use-side-window Use side window vs regular buffer t claude-code-ide-window-side Side for Claude window 'right claude-code-ide-window-width Width for side windows (left/right) 90 claude-code-ide-window-height Height for side windows (top/bottom) 20 claude-code-ide-focus-on-open Focus Claude window when opened t claude-code-ide-focus-claude-after-ediff Focus Claude window after opening ediff t claude-code-ide-show-claude-window-in-ediff Show Claude window during ediff t claude-code-ide-system-prompt Custom system prompt to append nil claude-code-ide-enable-mcp-server Enable MCP tools server nil claude-code-ide-mcp-server-port Port for MCP tools server nil (auto-select) claude-code-ide-mcp-server-tools Alist of exposed Emacs functions nil claude-code-ide-diagnostics-backend Diagnostics backend (auto/flycheck/flymake) 'auto claude-code-ide-prevent-reflow-glitch Prevent terminal reflow glitch (bug #1422) t
Side Window Configuration
Claude Code buffers open in a side window by default. You can customize the placement:
; ; 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 )
Or, if you’d prefer to use a regular window:
; ; Use regular window instead of side window ( setq claude-code-ide-use-side-window nil )
Terminal Backend Configuration
Claude Code IDE supports both vterm and eat as terminal backends. By default, it uses vterm , but you can switch to eat if preferred:
; ; Use eat instead of vterm ( setq claude-code-ide-terminal-backend 'eat ) ; ; Or switch back to vterm (default) ( setq claude-code-ide-terminal-backend 'vterm )
The eat backend is a pure Elisp terminal emulator that may work better in some environments where vterm compilation is problematic. Both backends provide full terminal functionality including color support and special key handling.
Terminal Keybindings
Claude Code IDE adds custom keybindings to the terminal for easier interaction:
Keybinding Command Description M-RET claude-code-ide-insert-newline Insert a newline in the prompt C- claude-code-ide-send-escape Send escape key to cancel operations
These keybindings are automatically set up for both vterm and eat backends and only apply within Claude Code terminal buffers.
Terminal Reflow Glitch Prevention (Temporary)
Claude Code IDE includes a temporary workaround for a known Claude Code bug (#1422) where terminal reflows during window resizes can cause uncontrollable scrolling. This workaround is enabled by default but can be disabled if needed:
; ; Disable the terminal reflow glitch prevention (not recommended until bug is fixed) ( setq claude-code-ide-prevent-reflow-glitch nil )
The workaround will be removed once the upstream bug is fixed.
Diagnostics Configuration
Claude Code IDE supports both Flycheck and Flymake for code diagnostics. By default, it will automatically detect which one is active:
; ; 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 )
Custom Buffer Naming
You can customize how Claude Code buffers are named:
( setq claude-code-ide-buffer-name-function ( lambda ( directory ) ( if directory ( format " *Claude: %s * " ( file-name-nondirectory ( directory-file-name directory))) " *Claude:Global* " )))
Custom CLI Flags
You can pass additional flags to the 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
Note: These flags are appended to the Claude command after any built-in flags like -d (debug) or -r (resume).
Custom System Prompt
You can append a custom system prompt to Claude’s default prompt, allowing you to customize Claude’s behavior for specific projects or contexts:
; ; 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
When set, this adds the --append-system-prompt flag to the Claude command. Set to nil to disable (default).
Debugging
Claude CLI Debug Mode
To enable debug mode for Claude Code CLI (passes the -d flag):
( setq claude-code-ide-cli-debug t )
Emacs Debug Logging
To enable debug logging within Emacs (logs WebSocket messages and JSON-RPC communication):
( setq claude-code-ide-debug t )
Then view debug logs with:
M-x claude-code-ide-show-debug - Show the debug buffer
- Show the debug buffer M-x claude-code-ide-clear-debug - Clear the debug buffer
The debug buffer shows:
WebSocket connection events
All JSON-RPC messages (requests/responses)
Error messages and diagnostics
General debug information with session context
Multiple Claude Code Instances on One Project
Using git worktrees is the recommended way for running multiple Claude Code instances on different branches of the same project. This allows you to develop features or fix bugs in parallel:
# 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
Each worktree is treated as a separate project by project.el , allowing you to have independent Claude Code sessions with their own buffers (e.g., *claude-code[myproject]* and *claude-code[myproject-worktree]* ).
Emacs MCP Tools
Claude Code IDE includes built-in MCP tools that expose Emacs functionality to Claude, enabling powerful code navigation and analysis capabilities:
Built-in Tools
xref-find-references - Find all references to a symbol throughout the project
- Find all references to a symbol throughout the project xref-find-apropos - Find symbols matching a pattern across the entire project
- Find symbols matching a pattern across the entire project treesit-info - Get tree-sitter syntax tree information for deep code structure analysis
- Get tree-sitter syntax tree information for deep code structure analysis imenu-list-symbols - List all symbols (functions, classes, variables) in a file using imenu
- List all symbols (functions, classes, variables) in a file using imenu project-info - Get information about the current project (directory, files, etc.)
Enabling MCP Tools
To enable these tools, add to your configuration:
; ; Set up the built-in Emacs tools (claude-code-ide-emacs-tools-setup)
Once enabled, Claude can use these tools to navigate your codebase. For example:
“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?”
Creating Custom MCP Tools
You can expose your own Emacs functions to Claude through the MCP tools system. This allows Claude to interact with specialized Emacs features, custom commands, or domain-specific functionality.
Tool Definition Format
Each tool definition in claude-code-ide-mcp-server-tools follows this format:
'(function-name :description " Human-readable description for Claude " :parameters (( :name " param1 " :type " string " :required t :description " What this parameter does " ) ( :name " param2 " :type " number " :required nil :description " Optional parameter " )))
Context-Aware Tool Example
( 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))) ( add-to-list 'claude-code-ide-mcp-server-tools '(my-project-grep :description " Search for pattern in project files " :parameters (( :name " pattern " :type " string " :required t :description " Pattern to search for " ))))
License
This project is licensed under the GNU General Public License v3.0 or later. See the LICENSE file for details.