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
• 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)
• Tree-sitter for syntax tree analysis and understanding code structure at the AST level
• Imenu for structured symbol listing and navigation within files
• Project 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

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.

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
• The window can be closed with standard Emacs window commands (C-x 0) without stopping Claude

Configuration

Configuration Variables

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:

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
• 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
• xref-find-apropos - Find symbols matching a pattern across the entire project
• treesit-info - 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
• 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.

Related Projects

• Claude Code CLI
• Claude Code VS Code Extension
• claudecode.nvim - Neovim integration