emacs-config/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a modular Emacs configuration with 33+ configuration modules in the lisp/ directory. The configuration is designed for software development with support for multiple languages, LSP, version control, and various productivity tools.

Core Commands

Configuration Management

M-x reload-emacs-config        ; Non-blocking reload (won't freeze UI)
M-x reload-emacs-config-blocking ; Original blocking reload
M-x reload-emacs-config-fast  ; Fast reload using byte-compiled files
M-x reload-emacs-config-smart ; Smart reload (only changed files)
M-x reload-current-file       ; Reload only current .el file
M-x byte-compile-config       ; Byte-compile all config files for faster loading
M-x clean-byte-compiled-files ; Remove all .elc files
M-x byte-compile-init-files   ; Compile only lisp/ directory files

;; Keybindings:
C-c C-r   ; Non-blocking reload (default)
C-u C-c C-r ; Blocking reload (old behavior)
C-c r     ; Reload current file only
C-c R     ; Fast reload (byte-compiled)

Emergency Fixes

M-x fix-editing-now            ; Emergency restore editing capability
M-x diagnose-editing-issue     ; Diagnose why editing is disabled
M-x diagnose-cua-selection     ; Debug CUA mode and selection issues
M-x diagnose-key-conflicts     ; Debug keybinding conflicts
C-c C-!                        ; Quick emergency fix keybinding
C-c C-?                        ; Quick diagnosis keybinding

Package Management

M-x package-refresh-without-proxy  ; Refresh packages bypassing proxy
M-x package-install-without-proxy  ; Install package bypassing proxy
M-x install-dev-packages           ; Install common development packages
M-x toggle-proxy                   ; Toggle proxy settings on/off

Development Modes

M-x enable-dev-mode-modern    ; Enable Eglot-based development mode
M-x enable-dev-mode           ; Enable LSP-mode based development (legacy)
M-x disable-eslint-in-buffer  ; Disable ESLint in current buffer

Architecture

Module Loading Order (init.el)

1. Emergency fixes (init-emergency-fix) - Loaded first to ensure editing works
2. Core modules - Package management, completion, UI, editor settings
3. Development tools - Project management, VCS, LSP, treesitter
4. Optional configs - Loaded conditionally if files exist

Key Configuration Modules

Core System:

• init-core.el - Package management with use-package
• init-completion.el - Company mode for auto-completion (replaced Corfu)
• init-ui.el - CUA mode configuration, themes, display settings
• init-editor.el - Selection keybindings, shift-selection fixes

Development:

• init-eglot.el - Built-in LSP client configuration (auto-enables for programming modes)
• init-treesitter.el - Tree-sitter support for Emacs 29+
• emacs-dev-config-modern.el - Additional dev tools (yasnippet, origami, etc.) via M-x enable-dev-mode-modern

Fix Modules:

• init-emergency-fix.el - Emergency editing restoration
• init-eslint-fix.el - ESLint configuration handling
• init-seq-fix.el - Seq library compatibility fixes

Applications:

• elfeed-config.el - RSS reader with CUA mode fixes
• portfolio-tracker-v2.el - Investment portfolio tracking
• mu4e-config.el - Email client configuration

CUA Mode and Keybinding Architecture

The configuration uses CUA mode for standard copy/paste (C-c, C-v, C-x) but disables it in special modes where single-key commands are needed:

• Elfeed buffers
• Magit
• Dired
• Portfolio tracker

C-Shift-Arrow word selection is specially configured to work with CUA mode through custom functions in init-editor.el.

Completion System

Uses Company mode with:

• Auto-completion after 2 characters
• 0.2 second delay
• Tab/Shift-Tab navigation
• Multiple backends configured

Custom Keybindings

• C-c C-r - Reload configuration
• C-c C-d c - Diagnose CUA/selection
• C-c C-d k - Diagnose key conflicts
• C-x w - Open Elfeed RSS reader
• C-c $ - Open portfolio tracker

Important Notes

• The configuration automatically disables CUA mode in special modes to preserve single-key commands
• ESLint is automatically disabled if no configuration file is found in the project
• Proxy settings can be toggled for package installation (default: eudewerepo001:3128)
• Byte-compilation is recommended for faster startup (M-x byte-compile-config)
• Emergency fix functions are available if editing becomes disabled