claude-code.el

claude-code.el allows running multiple Claude instances simultaneously, each associated with a specific directory (project root, file directory, or current directory). This enables separate conversations for different workflows (e.g., one instance for 'tests' and another for 'refactor') within the same project.

Key Concepts

• Instance Naming: The first instance in a directory is the "default". Subsequent instances require a custom name.
• Buffer Naming: Buffers follow the pattern *claude:/path/to/directory:instance-name*.
• Instance Selection: If multiple instances exist for a project, commands like claude-send-command or claude-code-kill will prompt you to select the target instance.
• Cross-Project Usage: You can select an instance running in a different project to analyze dependent files or sibling directories.
• Persistence: The package remembers which buffers are associated with which instances to minimize repetitive prompts.

## 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

For users of straight.el, use the following configuration. This setup includes the necessary dependencies and terminal backends. It uses :depth 1 for the claude-code installation to reduce download size.

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

You can control how the Claude Code buffer is displayed using two primary methods:

1. Using claude-code-display-window-fn

Provide a function that accepts the buffer as an argument. This allows for custom logic, such as using popwin or specific display-buffer parameters.

2. Using display-buffer-alist

Use standard Emacs display-buffer-alist entries to target Claude buffers (which typically match the regex ^\*claude). This is useful for forcing Claude into persistent side windows.

;; Method 1: Custom display function
(defun my-claude-display-right (buffer)
  "Display Claude buffer in right side window."
  (display-buffer buffer '((display-buffer-in-side-window)
                           (side . right)
                           (window-width . 90))))
(setq claude-code-display-window-fn #'my-claude-display-right

;; Method 2: display-buffer-alist
(add-to-list 'display-buffer-alist
              '(^\*claude
                (display-buffer-in-side-window)
                (side . right)
                (window-width . 90)))

To install claude-code.el on Emacs 30+, you must first ensure the inheritenv dependency is installed via :vc. You should also install a terminal backend package (eat, vterm, or ghostel) depending on your preference.

Note: If you are not using a :vc install for eat, you must add the NonGNU ELPA archive to your configuration.

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