manzaltu/claude-code-ide.el: Claude Code IDE integration for Emacs

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.

• 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

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.

Claude Code automatically knows which file you’re currently viewing in Emacs

Claude Code can access and work with selected text in your buffers

Integrated ediff view for code changes, with Claude Code able to directly access diagnostic data (errors, warnings, etc.) from opened files

Automatically mention and reference selected text in Claude conversations

Resume previous Claude Code conversations with the –resume flag

• Emacs 28.1 or higher
• Claude Code CLI installed and available in PATH
• vterm or eat package (for terminal support)

Follow the installation instructions at Claude Code Documentation.

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

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.

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.

• 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

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)

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.

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.

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.

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)

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*")))

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).

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).

To enable debug mode for Claude Code CLI (passes the -d flag):

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

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

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]*).

Claude Code IDE includes built-in MCP tools that expose Emacs functionality to Claude, enabling powerful code navigation and analysis capabilities:

• 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.)

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?”

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.

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")))

(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"))))

This project is licensed under the GNU General Public License v3.0 or later. See the LICENSE file for details.