claude-code-emacs

Claude Code Emacs

Run Claude Code AI coding sessions directly in Emacs with powerful MCP integration.

Quick Start

;; Add to your init.el
(add-to-list 'load-path "/path/to/claude-code")
(require 'claude-code)
(global-set-key (kbd "C-c c") 'claude-code-transient)

# Install MCP server globally
npm install -g claude-code-mcp-server

# Configure Claude Code to use MCP
claude mcp add-json emacs '{
  "type": "stdio",
  "command": "claude-code-mcp"
}'

Now run M-x claude-code-run to start a session!

Key Features

🚀 Core Features

• Project-isolated sessions - Each project gets its own Claude Code buffer
• Smart file completion - Type @ in prompts to reference project files
• Transient menus - Press C-c c for the main menu with all commands
• Custom commands - Define reusable commands in .claude/commands/*.md
• Project prompts - .claude-code.prompt.md file per project for persistent context

🔌 MCP Integration

Claude Code can directly interact with your Emacs environment:

• Buffer operations - List/read open buffers, get selected text
• LSP integration - Get diagnostics, find definitions/references, describe symbols
• Diff tools - Compare files, view git changes, apply patches
• Real-time events - Buffer changes and diagnostics sent to Claude Code automatically
• Automatic reconnection - If Emacs restarts, running sessions (including background agents) re-register themselves and reconnect automatically

⌨️ Key Bindings

Global

Key	Action
C-c c	Open main transient menu
C-u M-x claude-code-run	Start with options (model, resume, etc.)

In Claude Code Session (vterm mode)

Key	Action
C-c C-q	Close Claude Code window
C-c C-k	Send Escape key
C-c C-o	Send Ctrl+O (toggle expand)
C-c C-e	Send Ctrl+E (toggle expand more)
C-c C-d	Send Ctrl+T (toggle TODO display)
C-c C-n	Send Tab (toggle thinking mode)
C-c RET	Send Return key
C-c TAB	Send Shift+Tab (toggle auto-accept)
C-c C-t	Open transient menu
C-c C-s	Toggle scroll mode (for fullscreen mode)
C-c C-a	Open agents view and enable agent view mode

In Agent View Mode (claude-code-vterm-agent-mode)

A minor mode for operating the Claude Code agents view. Press C-c C-a in a Claude Code session to send Left (which opens the agents view) and enable this mode.

The mode stays deliberately minimal so its keymap is free for user extensions. Everything not listed below passes through to the terminal: typing reaches the agents view's text input, and the TUI's own control keys (C-r rename, C-s switch view, C-t pin, arrows, RET, ESC) work as in a plain vterm.

Key	Action
C-n / C-p	Select next / previous agent
C-c C-a	Command menu (transient) with every operation

The transient menu bundles all agents view operations: select (n/p), rename via minibuffer (r), pin to top (t), stop with confirmation (k), switch view (v), open (RET, 1) and quit (q). Opening or quitting from the menu also turns the mode off.

Every operation is also available as a plain command, so you can bind your own keys in claude-code-vterm-agent-mode-map.

In Scroll Mode (claude-code-vterm-scroll-mode)

A minor mode for scrolling the Claude Code fullscreen view. Toggle on/off with C-c C-s while in a Claude Code session.

Key	Action
<prior> (PageUp)	Scroll up one page
<next> (PageDown)	Scroll down one page
S-<up> (Shift+Up)	Scroll up one line
S-<down> (Shift+Down)	Scroll down one line
C-<end>	Jump to the bottom
q / C-c C-s	Exit scroll mode

Required Claude Code keybindings configuration

S-<up> / S-<down> (line scroll) do not work out of the box because Claude Code does not bind shift+up / shift+down to scroll actions by default. Add the following to ~/.claude/keybindings.json so Claude Code treats those keys as line-scroll actions in its fullscreen view:

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "Scroll",
      "bindings": {
        "shift+up": "scroll:lineUp",
        "shift+down": "scroll:lineDown"
      }
    }
  ]
}

<prior> / <next> / C-<end> use Claude Code's default bindings and need no extra configuration.

In Prompt Buffer

Key	Action
C-c C-s	Send section at point
C-c C-r	Send selected region
C-c C-o	Open Claude Code session
C-c C-t	Open prompt transient menu
@	File completion

In Transient Menu (C-c c)

Key	Action
1/y	Send 1 (yes)
2	Send 2
3	Send 3
k	Send Escape
e	Send Ctrl+E (toggle expand more)
o	Send Ctrl+O (toggle expand)
t	Send Ctrl+T (toggle TODO display)
h	Send Tab (toggle thinking mode)
g	Git & GitHub menu
/	Slash commands menu

Common Workflows

Project Prompts

Each project gets a .claude-code.prompt.md file at the project root. When you open this file, it automatically positions at the end for quick prompt entry:

# Claude Code Prompts for my-project

This file contains prompts for Claude Code sessions.

## Example Prompts

Fix the bug in @src/utils.js where the parser fails on empty strings

---

Add unit tests for @src/api/auth.js

Open with M-x claude-code-open-prompt-file or p in transient menu.

Fix LSP Errors

M-x claude-code-fix-diagnostic
;; or press 'f' in transient menu

Custom Commands

Create .claude/commands/refactor.md:

Refactor the following code: $ARGUMENTS

Execute with x in transient menu → select "refactor"

Git Operations

Press g in main menu for git commands:

• g - commit
• p - push
• r - review changes
• c - PR comments

Requirements

• Emacs 28.1+
• Claude Code CLI installed
• Node.js 16+ (for MCP)
• Required packages: projectile, vterm, transient, markdown-mode
• Optional packages:
  • lsp-mode (9.0.0+): For LSP diagnostic fixing and MCP tools integration
  • websocket (1.15+): For MCP server WebSocket communication
  • alert: For desktop notifications

Installation Details

MCP Server Installation

Option 1: Global Installation (Recommended)

# Install globally from npm
npm install -g claude-code-mcp-server

# Configure Claude Code
claude mcp add-json emacs '{
  "type": "stdio",
  "command": "claude-code-mcp"
}'

Option 2: Using npx (No Installation Required)

# Configure Claude Code to use npx
# npx will download and run the package on demand
claude mcp add-json emacs '{
  "type": "stdio",
  "command": "npx",
  "args": ["claude-code-mcp-server"]
}'

Option 3: Build from Source

# If you cloned the repository
cd /path/to/claude-code/mcp-server
npm install
npm run build

# Configure Claude Code
claude mcp add-json emacs '{
  "type": "stdio",
  "command": "node",
  "args": ["/path/to/claude-code/mcp-server/dist/index.js"]
}'

See docs/MCP-SETUP.md for detailed MCP configuration.

Architecture

• Modular design - Separate modules for buffer management, commands, UI, MCP
• Per-session WebSocket - Each Claude Code session (agent) maintains its own MCP connection, so multiple agents can run in the same project simultaneously
• Automatic reconnection - MCP connection health monitoring with ping/pong
• Event batching - Efficient real-time notifications with debouncing

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Run make test to ensure all tests pass
5. Submit a pull request

Development Commands

# Compile with all dependencies (including optional ones)
make compile

# Compile without optional dependencies (websocket, lsp-mode)
# Useful for testing MELPA compatibility
make compile-minimal

# Run tests
make test

# Run package-lint
make lint

Release Process

Releases are automated using GitHub Actions:

Creating a New Release

Option 1: Using GitHub CLI (Recommended)

# Create a draft release
./scripts/create-release.sh 0.2.0

# Or create and publish immediately
./scripts/create-release.sh 0.2.0 --publish

Option 2: Using GitHub Actions

1. Go to Actions → Create Release Draft → Run workflow
2. Enter version number (e.g., 0.2.0)

Final Steps

1. Review the auto-generated release notes

2. Edit if needed

3. Click "Publish release" (if using draft)

4. Automated Steps (After publishing):

   • Git tag is created automatically
   • Version numbers are updated in:
     • claude-code.el
     • mcp-server/package.json
   • MCP server is published to npm
   • MELPA recipe is generated

Manual Version Update

For local version updates:

./scripts/update-version.sh 0.2.0

License

GPL-3.0-or-later