GitHub Emacs Lisp Weekly Trending

rust-lang/rust-mode

Emacs configuration for Rust

rust-mode

Table of Contents

rust-mode

Introduction

rust-mode makes editing Rust code with Emacs enjoyable. It requires Emacs 25 or later, and is included in both Emacs Prelude and Spacemacs by default.

This mode provides:

Syntax highlighting (for Font Lock Mode)
Indentation
Integration with Cargo, clippy and rustfmt

This mode does not provide auto completion, or jumping to function / trait definitions. See Auto-completion below for tips on how to enable this.

If you are missing features in rust-mode, please check out rustic before you open a feature request. It depends on rust-mode and provides additional features. This allows us to keep rust-mode light-weight for users that are happy with basic functionality.

Known issues

rust-syntax-propertize and adaptive-wrap-prefix-mode can lead to severe lag when editing larger files (https://github.com/brotzeit/rustic/issues/107)

Installation

Melpa

The package is available on MELPA. Add this to your init.el.

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)
(package-refresh-contents)

Now you can install rust-mode with:

M-x package-install rust-mode

And put this in your config to load rust-mode automatically:

(require 'rust-mode)

NonGNU ELPA

NonGNU ELPA can be used out of the box in emacs28.

For older versions you need to add something like the following to your init file:

(with-eval-after-load 'package (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")))

Manual installation

Clone this repository locally, and add this to your init.el:

(add-to-list 'load-path "/path/to/rust-mode/")
(autoload 'rust-mode "rust-mode" nil t)
(add-to-list 'auto-mode-alist '("\\.rs\\'" . rust-mode))

Feature guide

Indentation

Commands like TAB should indent correctly.

The Rust style guide recommends spaces rather than tabs for indentation; to follow the recommendation add this to your init.el, which forces indentation to always use spaces.

(add-hook 'rust-mode-hook
          (lambda () (setq indent-tabs-mode nil)))

Since Emacs ≥ 24.4, electric-indent-mode is turned on by default. If you do not like it, call (electric-indent-mode 0) in rust-mode-hook.

Code formatting

The rust-format-buffer function will format your code with rustfmt if installed. By default, this is bound to C-c C-f.

The variable rust-format-on-save enables automatic formatting on save. For example, add the following in your init.el to enable format on save:

(setq rust-format-on-save t)

Prettifying

You can toggle prettification of your code by running M-x prettify-symbols-mode. If you'd like to automatically enable this for all rust files, add the following to your init.el.

(add-hook 'rust-mode-hook
          (lambda () (prettify-symbols-mode)))

You can add your own prettifications to rust-prettify-symbols-alist. For example, to display x.add(y) as x∔(y), simply add to your init file (push '(".add" . ?∔) rust-prettify-symbols-alist).

Running / testing / compiling code

The rust-run, rust-test, rust-compile and rust-check functions shell out to Cargo to run, test, build and check your code. Under the hood, these use the standard Emacs compile function.

By default these are bound to:

C-c C-c C-u rust-compile
C-c C-c C-k rust-check
C-c C-c C-t rust-test
C-c C-c C-r rust-run

To run programs requiring user input use universal argument when invoking rust-run (C-u C-c C-c C-r).

Clippy

rust-run-clippy runs Clippy, a linter. By default, this is bound to C-c C-c C-l.

Easy insertion of dbg!

rust-dbg-wrap-or-unwrap either wraps or unwraps the current region in dbg!. This can be useful for easily adding debug lines to your program.

This is bound to C-c C-d by default.

More commands

rust-toggle-mutability toggle mut for var defined at current line

tree-sitter

You can try the new native treesitter mode rust-ts-mode with:

(use-package rust-mode
  :init
  (setq rust-mode-treesitter-derive t))

In case you want to use treesitter but can't use Emacs 29.1, you can take a look at tree-sitter. When the dependencies are installed you can activate the feature with:

(use-package tree-sitter
  :config
  (require 'tree-sitter-langs)
  (global-tree-sitter-mode)
  (add-hook 'tree-sitter-after-on-hook #'tree-sitter-hl-mode))

LSP

eglot

A lightweight lsp client.

(add-hook 'rust-mode-hook 'eglot-ensure)

lsp-mode

Provides more features and you can enhance the functionality by using additional packages. You can find more information in the lsp-mode wiki.

(add-hook 'rust-mode-hook #'lsp)

Auto-completion

You can either use a lsp client or racer with emacs-racer.

Note that racer and rls are considered deprecated. You should use rust-analyzer instead.

Other recommended packages

flycheck

flycheck allows highlighting compile errors and Clippy lints inline.

cargo.el

cargo.el provides a minor mode for integration with Cargo, Rust's package manager.

cargo-mode

cargo-mode is an Emacs minor mode which allows to dynamically select a Cargo command. The reasons behind this package can be found in the post.

rustic

rustic is based on rust-mode, extending it with other features such as integration with LSP and with flycheck.

Optional features

The features of the following files can be disabled with rust-load-optional-libraries.

rust-cargo.el
rust-compile.el
rust-playpen.el
rust-rustfmt.el

They are disabled by default when you use rustic as it has its own implementations for those features.

Customization

rust-cargo-default-arguments set additional cargo args used for check,compile,run,test

For package maintainers

Tests

Run elisp tests:

make test

Contributing

Contributions are very welcome. We are also looking for additional maintainers.

NixOS/nix-mode

An Emacs major mode for editing Nix expressions.

nix-mode

An Emacs major mode for editing Nix expressions. There is also a manual available at nix-mode.org.

Submodes

A quick list of what is provided.

nix-mode.el

This is the main usage of nix-mode. This provides basic handling of .nix files. Syntax highlighting and indentation support using SMIE are provided. nix-mode can be used with the following snippet:

(require 'nix-mode)
(add-to-list 'auto-mode-alist '("\\.nix\\'" . nix-mode))

or with use-package:

(use-package nix-mode
  :mode "\\.nix\\'")

nix.el

nix.el contains some miscellaneous tools for Nix developers. Interactive functions include:

nix-unpack - unpack source of a Nix attribute.

To use this just type:

M-x nix-unpack

Followed by your Nix path & attribute path.
nix-build - build a Nix derivation.

This is meant to work similarly to M-x compile. It will use your current directory & build it if there is a default.nix there.

nix.el also provides some basic functions for interfacing with Nix. Some variables are provided to point to the Nix binaries that can be used in Lisp code:

nix-executable
nix-build-executable
nix-instantiate-executable
nix-store-executable
nix-shell-executable

Other useful functions for Lisp scripts are provided:

nix-system - Get the current system, detected by Nix

nix-flake.el

nix-flake.el provides support for flake commands. These commands are experimental as of Nix 2.4.

It uses transient.el to provide a magit-like interface. To run a command on the current flake, type:

M-x nix-flake

You can also initialize a flake from a template:

M-x nix-flake-init

nix-repl.el

nix-repl.el has two purposes.

First, it provides an interface for completion, used by nix-company.el.

Second, it provides an interactive function to open a repl. You can open this with:

M-x nix-repl

nix-store.el

This file provides a command M-x nix-store-show-path. The command displays an overview of a store path. The information it shows is the realisation status, the hash and the size of the store path. Also it shows lists of derivers, references, referrers and requisites of the respective path.

You can change the order in which that information is shown. See the documentation of the function nix-store-show-path for more information.

When viewing a store buffer, the command M-x nix-store-show-log opens a local log file associated with a derivation.

nix-prettify-mode.el

When nix-prettify-mode is enabled, hash-parts of the Nix store file names are prettified, i.e. displayed as nix-prettify-char character (… by default.).

This is based on a similar mode for Guix: Prettify Mode (Emacs-Guix Reference Manual).

Origins

This repository is based off of the nix-mode.el file originally located in the Nix repository at misc/emacs/nix-mode.el. Please see the CHANGELOG file for a list of changes.

Other Emacs packages

@shlevy has an excellent package for integrating nix-shell into emacs. It is available at shlevy/nix-buffer.

@travisbhartwell also has some package dealing with Nix. They are available at travisbhartwell/nix-emacs.

manzaltu/claude-code-ide.el

Claude Code IDE integration for Emacs

#+TITLE: Claude Code IDE for Emacs #+AUTHOR: Yoav Orot #+EMAIL: orot.yoav@gmail.com #+DESCRIPTION: Claude Code integration for Emacs #+KEYWORDS: emacs, claude, ai, code-assistant #+OPTIONS: toc:t num:nil

[[https://github.com/manzaltu/claude-code-ide.el/actions/workflows/test.yml][file:https://github.com/manzaltu/claude-code-ide.el/workflows/CI/badge.svg]] [[https://www.gnu.org/software/emacs/][file:https://img.shields.io/badge/GNU Emacs-28--30-blueviolet.svg]] [[https://www.gnu.org/licenses/gpl-3.0][file:https://img.shields.io/badge/License-GPL v3-blue.svg]]

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 (modify suggestions before applying)
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 #+CAPTION: Claude Code automatically knows which file you're currently viewing in Emacs #+html: #+html:

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

*** Code Selection Context #+CAPTION: Claude Code can access and work with selected text in your buffers #+html: #+html:

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

*** Advanced Diff View with Diagnostics #+CAPTION: Integrated ediff view for code changes, with Claude Code able to directly access diagnostic data (errors, warnings, etc.) from opened files #+html: #+html:

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

*** Automatic Text Mentions #+CAPTION: Automatically mention and reference selected text in Claude conversations #+html: #+html:

Automatically mention and reference selected text in Claude conversations

*** Session Restoration #+CAPTION: Resume previous Claude Code conversations with the --resume flag #+html: #+html:

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 [[https://docs.anthropic.com/en/docs/claude-code][Claude Code Documentation]].

** Installing the Emacs Package

Currently, this package is in early development.

To install using =emacs-version= >= 30 and =use-package= with the =vc= binding:

#+begin_src elisp (use-package claude-code-ide :vc (:url "https://github.com/manzaltu/claude-code-ide.el" :rev :newest) :bind ("C-c C-'" . claude-code-ide-menu) ; Set your favorite keybinding :config (claude-code-ide-emacs-tools-setup)) ; Optionally enable Emacs MCP tools #+end_src

To install using =use-package= and [[https://github.com/raxod502/straight.el][straight.el]]:

#+begin_src emacs-lisp (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 #+end_src

*** Doom Emacs

In =packages.el=:

#+begin_src emacs-lisp (package! claude-code-ide :recipe (:host github :repo "manzaltu/claude-code-ide.el")) #+end_src

In =config.el=: #+begin_src emacs-lisp (use-package! claude-code-ide :bind ("C-c C-'" . claude-code-ide-menu) ; Set your favorite keybinding :config (claude-code-ide-emacs-tools-setup)) ; Optionally enable Emacs MCP tools #+end_src

After saving the above, run: =doom sync= in the terminal.

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.

| Command | Description | |-----------------------------------------+---------------------------------------------------| | =M-x claude-code-ide-menu= | Open transient menu with all Claude Code commands | | =M-x claude-code-ide-emacs-tools-setup= | Set up built-in MCP tools (e.g. xref, project) | | =M-x claude-code-ide= | Start Claude Code for the current project | | =M-x claude-code-ide-send-prompt= | Send prompt to Claude from minibuffer input | | =M-x claude-code-ide-continue= | Continue most recent conversation in directory | | =M-x claude-code-ide-resume= | Resume Claude Code with previous conversation | | =M-x claude-code-ide-stop= | Stop Claude Code for the current project | | =M-x claude-code-ide-switch-to-buffer= | Switch to project's Claude buffer | | =M-x claude-code-ide-list-sessions= | List all active Claude Code sessions and switch | | =M-x claude-code-ide-check-status= | Check if Claude Code CLI is installed and working | | =M-x claude-code-ide-insert-at-mentioned= | Send selected text to Claude prompt | | =M-x claude-code-ide-send-escape= | Send escape key to Claude terminal | | =M-x claude-code-ide-insert-newline= | Insert newline in Claude prompt (sends \ + Enter) | | =M-x claude-code-ide-toggle= | Toggle visibility of Claude Code window | | =M-x claude-code-ide-toggle-recent= | Toggle most recent Claude window globally | | =M-x claude-code-ide-show-debug= | Show the debug buffer with WebSocket messages | | =M-x claude-code-ide-clear-debug= | Clear the debug buffer |

** 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
Use =claude-code-ide-toggle-recent= to toggle the most recent Claude window from anywhere, regardless of your current project context. This is useful when you're outside a project directory but want to quickly hide/show Claude

** Diff Viewing with Ediff

When =claude-code-ide-use-ide-diff= is enabled (default), Claude's code suggestions are displayed using Emacs' powerful =ediff= interface. This provides two key advantages:

Visual diff comparison - See exactly what Claude wants to change with side-by-side or unified diff views
Interactive editing - You can modify Claude's suggestions before applying them

*** How to use ediff:

When Claude suggests code changes, =ediff= opens automatically
The ediff control buffer becomes active (a small window with ediff commands)
Buffer A shows the current code, Buffer B shows Claude's suggestion
You can modify Buffer B to refine Claude's proposed changes
Press =q= in the ediff control buffer to quit
When prompted, choose whether to accept the changes (=y= or =n=)
If you accept (=y=), any changes from Buffer B will be sent back to Claude to be applied on the original file

This allows you to refine Claude's suggestions before they're applied, ensuring the final code meets your exact requirements.

** Configuration

*** Configuration Variables

| Variable | Description | Default | |-----------------------------------------------+---------------------------------------------+--------------------------------------| | ~claude-code-ide-cli-path~ | Path to Claude Code CLI | ~"claude"~ | | ~claude-code-ide-buffer-name-function~ | Function for buffer naming | ~claude-code-ide--default-buffer-name~ | | ~claude-code-ide-cli-debug~ | Enable CLI debug mode (-d flag) | ~nil~ | | ~claude-code-ide-cli-extra-flags~ | Additional CLI flags (e.g. "--model") | ~""~ | | ~claude-code-ide-debug~ | Enable debug logging | ~nil~ | | ~claude-code-ide-terminal-backend~ | Terminal backend (vterm or eat) | ~'vterm~ | | ~claude-code-ide-vterm-anti-flicker~ | Enable vterm flicker reduction | ~t~ | | ~claude-code-ide-vterm-render-delay~ | vterm render batching delay (seconds) | ~0.005~ | | ~claude-code-ide-terminal-initialization-delay~ | Initialization delay for terminals | ~0.1~ | | ~claude-code-ide-log-with-context~ | Include session context in log messages | ~t~ | | ~claude-code-ide-debug-buffer~ | Buffer name for debug output | ~"claude-code-ide-debug"~ | | ~claude-code-ide-use-side-window~ | Use side window vs regular buffer | ~t~ | | ~claude-code-ide-window-side~ | Side for Claude window | ~'right~ | | ~claude-code-ide-window-width~ | Body width for side windows (left/right) | ~100~ | | ~claude-code-ide-window-height~ | Height for side windows (top/bottom) | ~20~ | | ~claude-code-ide-focus-on-open~ | Focus Claude window when opened | ~t~ | | ~claude-code-ide-focus-claude-after-ediff~ | Focus Claude window after opening ediff | ~t~ | | ~claude-code-ide-show-claude-window-in-ediff~ | Show Claude window during ediff | ~t~ | | ~claude-code-ide-use-ide-diff~ | Use IDE diff viewer instead of terminal | ~t~ | | ~claude-code-ide-switch-tab-on-ediff~ | Switch to Claude's tab when opening ediff | ~t~ | | ~claude-code-ide-system-prompt~ | Custom system prompt to append | ~nil~ | | ~claude-code-ide-enable-mcp-server~ | Enable MCP tools server | ~nil~ | | ~claude-code-ide-mcp-server-port~ | Port for MCP tools server | ~nil~ (auto-select) | | ~claude-code-ide-mcp-server-tools~ | Alist of exposed Emacs functions | ~nil~ | | ~claude-code-ide-diagnostics-backend~ | Diagnostics backend (auto/flycheck/flymake) | ~'auto~ | | ~claude-code-ide-no-flicker~ | Enable flicker-free terminal renderer | ~nil~ | | ~claude-code-ide-prevent-reflow-glitch~ | Prevent terminal reflow glitch (bug #1422) | ~t~ | | ~claude-code-ide-enable-execute-code~ | Allow model to evaluate Elisp in Emacs | ~t~ |

*** Side Window Configuration

Claude Code buffers open in a side window by default. You can customize the placement:

#+begin_src emacs-lisp ;; 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)

;; Disable IDE diff viewer to show diffs in terminal instead (setq claude-code-ide-use-ide-diff nil) #+end_src

Or, if you'd prefer to use a regular window:

#+begin_src emacs-lisp ;; Use regular window instead of side window (setq claude-code-ide-use-side-window nil) #+end_src

*** 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:

#+begin_src emacs-lisp ;; 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) #+end_src

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.

**** Flicker-Free Renderer (Experimental)

Claude Code includes an experimental alternative terminal renderer that eliminates flickering. To enable it:

#+begin_src emacs-lisp (setq claude-code-ide-no-flicker t) #+end_src

Note that with this renderer, normal Emacs buffer scrolling and search (=C-s=, =C-r=) will not work in the terminal buffer. Instead, use Claude Code's built-in keybindings:

=C-o j= / =C-o k= - Scroll up/down through the transcript
=C-o /= - Search the transcript

**** vterm Rendering Optimization

Claude Code IDE includes intelligent flicker reduction for vterm terminals to provide smoother visual output:

#+begin_src emacs-lisp ;; Enable/disable vterm anti-flicker optimization (enabled by default) (setq claude-code-ide-vterm-anti-flicker t)

;; Adjust the render delay for batching updates (default is 0.005 seconds) (setq claude-code-ide-vterm-render-delay 0.01) ; Increase for smoother but less responsive #+end_src

This optimization detects rapid terminal redraw sequences (like when Claude expands text areas) and batches them for smoother rendering. The 5ms default delay provides optimal visual quality with imperceptible latency.

**** Terminal Initialization Delay

Claude Code IDE includes a brief initialization delay when launching terminals to ensure proper layout rendering:

#+begin_src emacs-lisp ;; Adjust the terminal initialization delay (default is 0.1 seconds) (setq claude-code-ide-terminal-initialization-delay 0.15)

;; Or disable it entirely (may cause visual glitches) (setq claude-code-ide-terminal-initialization-delay 0) #+end_src

This delay prevents display artifacts such as misaligned prompts and incorrect cursor positioning that can occur when terminal emulation is initializing. The default 100ms delay is imperceptible but ensures reliable terminal startup.

**** Terminal Keybindings

Claude Code IDE adds custom keybindings to the terminal for easier interaction:

| Keybinding | Command | Description | |------------+--------------------------------+--------------------------------------| | =M-RET= | =claude-code-ide-insert-newline= | Insert a newline in the prompt | | =C- = | =claude-code-ide-send-escape= | Send escape key to cancel operations |

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 ([[https://github.com/anthropics/claude-code/issues/1422][#1422]]) where terminal reflows during window resizes can cause uncontrollable scrolling. This workaround is enabled by default but can be disabled if needed:

#+begin_src emacs-lisp ;; Disable the terminal reflow glitch prevention (not recommended until bug is fixed) (setq claude-code-ide-prevent-reflow-glitch nil) #+end_src

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:

#+begin_src emacs-lisp ;; 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) #+end_src

*** Elisp Code Execution

Claude Code can evaluate Elisp expressions directly in your running Emacs session via the =executeCode= MCP tool. This is enabled by default.

To disable it:

#+begin_src emacs-lisp (setq claude-code-ide-enable-execute-code nil) #+end_src

*** Custom Buffer Naming

You can customize how Claude Code buffers are named:

#+begin_src emacs-lisp (setq claude-code-ide-buffer-name-function (lambda (directory) (if directory (format "Claude:%s" (file-name-nondirectory (directory-file-name directory))) "Claude:Global"))) #+end_src

*** Custom CLI Flags

You can pass additional flags to the Claude Code CLI:

#+begin_src emacs-lisp ;; 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 #+end_src

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:

#+begin_src emacs-lisp ;; 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 #+end_src

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

#+begin_src emacs-lisp (setq claude-code-ide-cli-debug t) #+end_src

**** Emacs Debug Logging

To enable debug logging within Emacs (logs WebSocket messages and JSON-RPC communication):

#+begin_src emacs-lisp (setq claude-code-ide-debug t) #+end_src

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:

#+begin_src bash

Create a new worktree for a feature branch

git worktree add ../myproject-worktree feature-branch #+end_src

#+begin_src elisp ;; 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 #+end_src

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:

#+begin_src emacs-lisp ;; Set up the built-in Emacs tools (claude-code-ide-emacs-tools-setup) #+end_src

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

Define tools using the =claude-code-ide-make-tool= function:

#+begin_src emacs-lisp (claude-code-ide-make-tool :function #'function-name ; The Emacs function to call :name "tool_name" ; Name for Claude to use (snake_case recommended) :description "..." ; Human-readable description :args '((:name "param1" ; List of argument specifications :type string ; Type: string, number, integer, boolean, etc. :description "..." ; What this parameter does :optional t))) ; Optional parameters marked with :optional t #+end_src

Available argument types: =string=, =number=, =integer=, =boolean=, =array=, =object=, =null=

*** Context-Aware Tool Example

#+begin_src emacs-lisp ;; Define a context-aware function that operates in the session's project (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)))

;; Define and register the tool (automatically added to claude-code-ide-mcp-server-tools) (claude-code-ide-make-tool :function #'my-project-grep :name "my_project_grep" :description "Search for pattern in project files" :args '((:name "pattern" :type string :description "Pattern to search for")))

;; Enable Emacs tool MCP server (claude-code-ide-emacs-tools-setup) #+end_src

The =claude-code-ide-mcp-server-with-session-context= macro ensures your tool executes in the correct project context.

License

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

Trademark Notice

Claude® is a registered trademark of Anthropic, PBC. Claude Code is an application developed by Anthropic, PBC.

Related Projects

[[https://docs.anthropic.com/en/docs/claude-code][Claude Code CLI]]
[[https://github.com/anthropics/claude-code][Claude Code VS Code Extension]]
[[https://github.com/coder/claudecode.nvim][claudecode.nvim]] - Neovim integration

xenodium/agent-shell

A native Emacs buffer to interact with LLM agents powered by ACP

#+TITLE: Emacs Agent Shell #+AUTHOR: Álvaro Ramírez

[[https://melpa.org/#/agent-shell][file:https://melpa.org/packages/agent-shell-badge.svg]]

👉 [[https://github.com/sponsors/xenodium][Support this work via GitHub Sponsors]] by [[https://github.com/xenodium][@xenodium]] (check out my [[https://xenodium.com][blog]])

[[file:agent-shell.png]]

This project needs your funding

As you pay for those useful LLM tokens, consider [[https://github.com/sponsors/xenodium][sponsoring]] development and maintenance of this project. With your help, I can make this effort more [[https://github.com/sponsors/xenodium][sustainable]].

Thank you!

[[https://xenodium.com/][Alvaro]]

agent-shell

A native Emacs shell to interact with LLM agents powered by ACP ([[https://agentclientprotocol.com][Agent Client Protocol]]).

With agent-shell, you can chat with the likes of Gemini CLI, Claude Agent, Auggie, Mistral Vibe, or any other ACP-driven agent.

[[https://www.youtube.com/watch?v=R2Ucr3amgGg][agent-shell - YouTube]]

[[https://www.youtube.com/watch?v=R2Ucr3amgGg][file:yt.png]]

[[https://www.youtube.com/watch?v=ymMlftdGx4I][agent-shell + Claude Skills - YouTube]]

[[https://www.youtube.com/watch?v=ymMlftdGx4I][https://img.youtube.com/vi/ymMlftdGx4I/0.jpg]]

[[https://www.youtube.com/watch?v=HJQ86HuSIJI][agent-shell + Claude Skills + Charts - YouTube]]

[[https://www.youtube.com/watch?v=HJQ86HuSIJI][https://img.youtube.com/vi/HJQ86HuSIJI/0.jpg]]

News

[[https://xenodium.com/agent-shell-0-47-1-updates][agent-shell 0.47 updates]].
[[https://xenodium.com/agent-shell-0-25-updates][agent-shell 0.25 updates]].
[[https://xenodium.com/agent-shell-016-improvements-melpa][agent-shell 0.17 improvements + MELPA]].
[[https://xenodium.com/agent-shell-0-5-improvements][agent-shell 0.5 improvements]].
[[https://xenodium.com/introducing-agent-shell][Introducing Emacs agent-shell (powered by ACP)]].
[[https://xenodium.com/introducing-acpel][Introducing acp.el]].

Related projects

=agent-shell= relies on [[https://github.com/xenodium/acp.el][acp.el]] to communicate with agents via ACP ([[https://agentclientprotocol.com/][Agent Client Protocol]]).

We now have a handful of additional packages to extend the =agent-shell= experience:

[[https://github.com/xenodium/emacs-skills][emacs-skills]]: Claude Agent skills for Emacs.
[[https://github.com/ElleNajt/agent-shell-to-go][agent-shell-to-go]]: Interact with =agent-shell= sessions from your mobile or any other device via Slack.
[[https://github.com/Embedded-Focus/agent-circus][agent-circus]]: Run AI coding agents in sandboxed Docker containers.
[[https://github.com/cmacrae/agent-shell-sidebar][agent-shell-sidebar]]: A sidebar add-on for =agent-shell=.
[[https://github.com/dcluna/agent-shell-bookmark][agent-shell-bookmark]]: Bookmark support for agent-shell sessions.
[[https://github.com/gveres/agent-shell-workspace][agent-shell-workspace]]: Dedicated tab-bar workspace for managing multiple =agent-shell= sessions.
[[https://github.com/jethrokuan/agent-shell-manager][agent-shell-manager]]: Tabulated view and management of =agent-shell= buffers.
[[https://github.com/nineluj/agent-review][agent-review]]: Code review interface for =agent-shell=.
[[https://github.com/ultronozm/agent-shell-attention.el][agent-shell-attention.el]]: Mode-line attention tracker for =agent-shell=.
[[https://github.com/xenodium/agent-shell-knockknock][agent-shell-knockknock]]: Notifications for =agent-shell= via [[https://github.com/konrad1977/knockknock][knockknock.el]].
[[https://github.com/zackattackz/agent-shell-notifications][agent-shell-notifications]]: Desktop notifications for =agent-shell= events.
[[https://github.com/ElleNajt/meta-agent-shell][meta-agent-shell]]: Multi-agent coordination system for =agent-shell= with inter-agent communication, task tracking, and project-level dispatching.
[[https://github.com/cxa/agent-shell-macext][agent-shell-macext]]: macOS-specific enhancements for =agent-shell=.
[[https://github.com/lllShamanlll/agent-shell-org-transcript][agent-shell-org-transcript]]: Org-mode transcripts for =agent-shell= sessions, with org-roam integration.
[[https://github.com/eddof13/ob-agent-shell][ob-agent-shell]]: Org Babel backend for executing =agent-shell= source blocks.
[[https://github.com/Marx-A00/agent-recall][agent-recall]]: Search, browse, and resume =agent-shell= conversation transcripts.
[[https://github.com/lgmoneda/agent-shell-pet][agent-shell-pet]]: Codex-like pets that broadcast agent-shell session states.

Articles

20Y: [[https://20y.hu/~slink/journal/agent-shell/index.html][Agentic development workflow in Emacs]]
Skye: [[https://skyefreeman.com/blog/2026/04/15/how-im-using-llms-with-emacs][How I'm using LLM's via Emacs]].
sincebyte: [[https://neoemacs.com/posts/agent-shell-cursor-agent-cli/][Agent Shell Cursor Agent Cli]].
Naputo: [[https://blog.n-daisuke897.com/posts/2026-03-01-agent-shell-session-selection/][How to Select Sessions When Starting the agent-shell ACP Client Running on Emacs]]
vandee: [[https://www.vandee.art/blog/2026-01-23-my-agent-practice-with-opencode-in-emacs.html][My Agent Practice with OpenCode in Emacs]].

Icons

Thanks to [[https://github.com/lobehub/lobe-icons][Lobe Icons]] for the lovely icons.

Setup

** External dependencies

*** Claude Agent SDK

For Anthropic's [[https://code.claude.com/docs/en/overview][Claude Agent]] (formerly known as the Claude Code), follow [[https://github.com/agentclientprotocol/claude-agent-acp][claude-agent-acp instructions]], typically something like:

#+begin_src bash npm install -g @agentclientprotocol/claude-agent-acp #+end_src

Note: The =-g= flag is required to install the binary globally so it's available in your PATH. After installation, verify it's available by running =which claude-agent-acp= in your terminal.

Optionally: You may also need [[https://code.claude.com/docs/en/overview][Claude Agent]] itself if you want to use a Claude subscription (run the CLI outside of Emacs at least once to log in to your subscription and then use =agent-shell= from Emacs). Follow Claude Agent's [[https://code.claude.com/docs/en/overview#get-started][get started]] for installation.

*** Codex

For OpenAI's Codex, install [[https://github.com/zed-industries/codex-acp][zed/codex-acp]] and ensure the codex-acp executable is in PATH.

*** Gemini CLI

For Google's [[https://github.com/google-gemini/gemini-cli][Gemini CLI]], be sure to get a recent release supporting the =--experimental-acp= flag.

*** Goose

For Goose CLI, install [[https://block.github.io/goose/docs/getting-started/installation][goose]] and ensure the goose executable is in PATH.

*** Cursor

For Cursor agent, install with:

#+begin_src bash npm install -g @blowmage/cursor-agent-acp #+end_src

See https://github.com/blowmage/cursor-agent-acp-npm for details.

*** Kimi Code CLI

For Kimi Code CLI, install with:

#+begin_src bash curl -L code.kimi.com/install.sh | bash #+end_src

See https://www.kimi.com/code for details.

*** Kiro CLI

For Kiro CLI, install with:

#+begin_src bash curl -fsSL https://cli.kiro.dev/install | bash #+end_src

See https://kiro.dev/docs/cli/acp/ for details.

*** Qwen Code

For Qwen Code, install with:

#+begin_src bash npm install -g @qwen-code/qwen-code@latest #+end_src

See https://github.com/QwenLM/qwen-code for details.

*** Auggie

For Auggie CLI, install with:

#+begin_src bash npm install -g @augmentcode/auggie #+end_src

See https://docs.augmentcode.com/cli/overview for details. *** Mistral Vibe

For Mistral Vibe, install with:

#+begin_src bash uv tool install mistral-vibe #+end_src

See https://github.com/mistralai/mistral-vibe for details.

*** Factory Droid

For Factory Droid, install Droid:

#+begin_src bash curl -fsSL https://app.factory.ai/cli | sh #+end_src

See https://factory.ai for details.

*** Pi

For Pi coding agent, install the =pi-acp= adapter:

#+begin_src bash npm install -g pi-acp #+end_src

See https://github.com/svkozak/pi-acp for details.

** Installation

=agent-shell= is powered by built-in =comint-shell=, via [[https://github.com/xenodium/shell-maker][shell-maker]], available on [[https://melpa.org/#/shell-maker][MELPA]].

Both [[https://melpa.org/#/agent-shell][agent-shell]] and its dependency [[https://melpa.org/#/acp][acp.el]] are now available on MELPA.

You can install via:

#+begin_src emacs-lisp (use-package agent-shell :ensure t :ensure-system-package ;; Add agent installation configs here ((claude . "brew install claude-code") (claude-agent-acp . "npm install -g @agentclientprotocol/claude-agent-acp"))) #+end_src

This will automatically install the required dependencies ([[https://melpa.org/#/acp][acp.el]] and [[https://melpa.org/#/shell-maker][shell-maker]]).

*** Doom Emacs

If you are using Doom Emacs and would like to use the =package!= macro:

#+begin_src emacs-lisp (package! shell-maker) (package! acp) (package! agent-shell) #+end_src

Run =doom sync= and restart.

Include =require= before configuration:

#+begin_src emacs-lisp (require 'acp) (require 'agent-shell) ;; rest of config... #+end_src

** Configuration

Configure authentication for the agent providers you want to use.

*** Environment variables

Pass environment variables to the spawned agent process by customizing the agent-shell-*-environment variable with agent-shell-make-environment-variables. The helper accepts key/value pairs and exports them when the agent starts.

#+begin_src emacs-lisp (setq agent-shell-anthropic-claude-environment (agent-shell-make-environment-variables "ANTHROPIC_API_KEY" (auth-source-pass-get 'secret "anthropic-api-key") "HTTPS_PROXY" "http://proxy.example.com:8080")) #+end_src

**** Inheriting environment variables

By default, the agent process starts with a minimal environment. To inherit environment variables from the parent Emacs process, use the :inherit-env t parameter in agent-shell-make-environment-variables:

#+begin_src emacs-lisp (setenv "ANTHROPIC_API_KEY" (auth-source-pass-get 'secret "anthropic-api-key"))

(setq agent-shell-anthropic-claude-environment (agent-shell-make-environment-variables :inherit-env t)) #+end_src

This ensures that environment variables like PATH, HOME, and others from your Emacs session are available to the agent process, while still allowing you to override or add specific variables.

**** Loading environment variables from files

You can load environment variables from .env files using the :load-env parameter. This supports both single and multiple files:

#+begin_src emacs-lisp ;; Load from a single .env file (setq agent-shell-anthropic-claude-environment (agent-shell-make-environment-variables :load-env "~/.env" "CUSTOM_VAR" "custom_value"))

;; Load from multiple .env files (setq agent-shell-anthropic-claude-environment (agent-shell-make-environment-variables :load-env '("~/.env" ".env.local") :inherit-env t)) #+end_src

The .env files should contain variables in the format KEY=value, with one variable per line. Comments (lines starting with #) and empty lines are ignored.

*** Anthropic Claude

For login-based authentication (default):

#+begin_src emacs-lisp (setq agent-shell-anthropic-authentication (agent-shell-anthropic-make-authentication :login t)) #+end_src

For API key authentication:

#+begin_src emacs-lisp ;; With string (setq agent-shell-anthropic-authentication (agent-shell-anthropic-make-authentication :api-key "your-anthropic-api-key-here"))

;; With function (setq agent-shell-anthropic-authentication (agent-shell-anthropic-make-authentication :api-key (lambda () (auth-source-pass-get 'secret "anthropic-api-key")))) #+end_src

For OAuth token authentication (the =CLAUDE_CODE_OAUTH_TOKEN= we get from =claude setup-token=):

#+begin_src emacs-lisp ;; With string (setq agent-shell-anthropic-authentication (agent-shell-anthropic-make-authentication :oauth "your-oauth-token-here"))

;; With function (setq agent-shell-anthropic-authentication (agent-shell-anthropic-make-authentication :oauth (lambda () (auth-source-pass-get "secret" "anthropic-oauth-token")))) #+end_src

For alternative Anthropic-compatible API endpoints, configure via environment variables:

#+begin_src emacs-lisp (setq agent-shell-anthropic-claude-environment (agent-shell-make-environment-variables "ANTHROPIC_BASE_URL" "https://api.moonshot.cn/anthropic" "ANTHROPIC_MODEL" "kimi-k2-turbo-preview" "ANTHROPIC_SMALL_FAST_MODEL" "kimi-k2-turbo-preview")) #+end_src

*** Google Gemini

For login-based authentication (default):

#+begin_src emacs-lisp (setq agent-shell-google-authentication (agent-shell-google-make-authentication :login t)) #+end_src

For API key authentication:

#+begin_src emacs-lisp ;; With string (setq agent-shell-google-authentication (agent-shell-google-make-authentication :api-key "your-google-api-key-here"))

;; With function (setq agent-shell-google-authentication (agent-shell-google-make-authentication :api-key (lambda () (auth-source-pass-get 'secret "google-api-key")))) #+end_src

For Vertex AI authentication:

#+begin_src emacs-lisp (setq agent-shell-google-authentication (agent-shell-google-make-authentication :vertex-ai t)) #+end_src

*** OpenAI Codex

For login-based authentication (default):

#+begin_src emacs-lisp (setq agent-shell-openai-authentication (agent-shell-openai-make-authentication :login t)) #+end_src

For API key authentication:

#+begin_src emacs-lisp ;; With string (setq agent-shell-openai-authentication (agent-shell-openai-make-authentication :api-key "your-openai-api-key-here"))

;; With function (setq agent-shell-openai-authentication (agent-shell-openai-make-authentication :api-key (lambda () (auth-source-pass-get 'secret "openai-api-key")))) #+end_src

*** Goose

For OpenAI API key authentication:

#+begin_src emacs-lisp ;; With string (setq agent-shell-goose-authentication (agent-shell-make-goose-authentication :openai-api-key "your-openai-api-key-here"))

;; With function (setq agent-shell-goose-authentication (agent-shell-make-goose-authentication :openai-api-key (lambda () (auth-source-pass-get 'secret "openai-api-key")))) #+end_src

*** Qwen Code

For OAuth login-based authentication:

#+begin_src emacs-lisp (setq agent-shell-qwen-authentication (agent-shell-qwen-make-authentication :login t)) #+end_src

*** Auggie

For login-based authentication (default):

#+begin_src emacs-lisp (setq agent-shell-auggie-authentication (agent-shell-make-auggie-authentication :login t)) #+end_src

For no authentication (when using alternative authentication methods):

#+begin_src emacs-lisp (setq agent-shell-auggie-authentication (agent-shell-make-auggie-authentication :none t)) #+end_src

*** Mistral Vibe

For API key authentication:

#+begin_src emacs-lisp ;; With string (setq agent-shell-mistral-authentication (agent-shell-mistral-make-authentication :api-key "your-mistral-api-key-here"))

;; With function (reusing the API key configured in vibe) (setq agent-shell-mistral-authentication (agent-shell-mistral-make-authentication :api-key (lambda () (string-trim (shell-command-to-string "source ~/.vibe/.env; echo $MISTRAL_API_KEY"))))) #+end_src

*** Customizing Available Agents

By default, =agent-shell= includes configurations for all supported agents (Claude Agent, Gemini CLI, Codex, Goose, Qwen Code, and Auggie). You can customize which agents are available through the =agent-shell-agent-configs= variable.

** Usage

*** Quick Start

=M-x agent-shell= - Start or reuse any of the known agents.

You can select and start any of the known agent shells (see =agent-shell-agent-configs=) via the =agent-shell= interactive command and enables reusing existing shells when available. With a prefix argument (=C-u M-x agent-shell=), it forces starting a new shell session, thus instantiating multiple agent shells.

*** Specific Agent Commands

Start a specific agent shell session directly:

=M-x agent-shell-anthropic-start-claude-code= - Start a Claude Agent session
=M-x agent-shell-auggie-start-agent= - Start an Auggie agent session
=M-x agent-shell-openai-start-codex= - Start a Codex agent session
=M-x agent-shell-google-start-gemini= - Start a Gemini agent session
=M-x agent-shell-goose-start-agent= - Start a Goose agent session
=M-x agent-shell-cursor-start-agent= - Start a Cursor agent session
=M-x agent-shell-kiro-start-agent= - Start a Kiro CLI agent session
=M-x agent-shell-mistral-start-vibe= - Start a Mistral Vibe agent session
=M-x agent-shell-qwen-start= - Start a Qwen Code agent session
=M-x agent-shell-droid-start-agent= - Start a Factory Droid agent session
=M-x agent-shell-pi-start-agent= - Start a Pi coding agent session

*** Setting a default agent for all new shells

You can set a default agent to use for all new shells started via =agent-shell= like so:

#+begin_src emacs-lisp (setq agent-shell-preferred-agent-config (agent-shell-anthropic-make-claude-code-config)) #+end_src

*** Configuring MCP servers

You can configure MCP servers directly via =agent-shell=. This allows you to avoid having to repeat configurations across every agent that you use.

#+begin_src emacs-lisp (setq agent-shell-mcp-servers '(((name . "notion") (type . "http") (headers . []) (url . "https://mcp.notion.com/mcp")))) #+end_src

** Running agents in Devcontainers / Docker containers (Experimental)

=agent-shell= provides rudimentary support for running agents and shell commands in containers.

Use =agent-shell-command-prefix= to prefix the command that starts the agent, or a shell command that should be run so it is executed inside the container.

*** Static command list

#+begin_src emacs-lisp (setq agent-shell-command-prefix '("devcontainer" "exec" "--workspace-folder" ".")) #+end_src

*** Function-based configuration

For dynamic per-agent containers, provide a function that takes the current agent-shell buffer and returns the command list:

#+begin_src emacs-lisp (setq agent-shell-command-prefix (lambda (buffer) (let ((config (agent-shell-get-config buffer))) (pcase (map-elt config :identifier) ('claude-code '("docker" "exec" "claude-dev" "--")) ('gemini-cli '("docker" "exec" "gemini-dev" "--")) (_ '("devcontainer" "exec" ".")))))) #+end_src

*** Per-session containers

You can use different containers for different shell sessions, even of the same agent type:

#+begin_src emacs-lisp (setq agent-shell-command-prefix (lambda (buffer) ;; Different container based on project (if (string-match "project-a" (buffer-name buffer)) '("docker" "exec" "project-a-dev" "--") '("docker" "exec" "project-b-dev" "--")))) #+end_src

Note that any =:environment-variables= you may have passed to =acp-make-client= will not apply to the agent process running inside the container. It's expected to inject environment variables by means of your devcontainer configuration / Dockerfile.

Next, set an =agent-shell-path-resolver-function= that resolves container paths in the local working directory, and vice versa. Agent shell provides the =agent-shell-devcontainer-resolve-path= function for use with devcontainers specifically: it reads the =workspaceFolder= specified in =.devcontainer/devcontainer.json=, or uses the default value of =/workspaces/ = otherwise.

#+begin_src emacs-lisp (setq agent-shell-path-resolver-function #'agent-shell-devcontainer-resolve-path) #+end_src

Note that this allows the agent to access files on your local file-system. While care has been taken to restrict access to files in the local working directory, it's probably possible for a malicious agent to circumvent this restriction.

Optional: to prevent the agent running inside the container to access your local file-system altogether and to have it read/modify files inside the container directly, in addition to setting the resolver function, disable the "read/write text file" client capabilities:

#+begin_src emacs-lisp (setq agent-shell-text-file-capabilities nil) #+end_src

*** Data storage location

By default, agent-shell stores per-project data (transcripts, screenshots, etc.) under a =.agent-shell/= directory in the project root, and automatically adds that directory to =.gitignore= the first time it is created. This is a one-time operation: removing the entry from =.gitignore= will not cause it to be re-added.

You can change where this data is stored by setting =agent-shell-dot-subdir-function= to a custom function. The function receives one argument, SUBDIR (e.g. ="screenshots"=), and must return the absolute path to that subdirectory (without creating it).

For example, to store data under =user-emacs-directory= instead of the project tree, flattening the project path into a directory name:

#+begin_src emacs-lisp (defun my/agent-shell-dot-subdir (subdir) (let* ((cwd (string-remove-suffix "/" (agent-shell-cwd))) (sanitized (replace-regexp-in-string "/" "-" (string-remove-prefix "/" cwd)))) (expand-file-name subdir (locate-user-emacs-file (concat "agent-shell/" sanitized)))))

(setopt agent-shell-dot-subdir-function #'my/agent-shell-dot-subdir) #+end_src

This stores data at a path like =~/.emacs.d/agent-shell/home-user-src-myproject/screenshots/=.

*** Screenshots from clipboard

You can send a screenshot from your clipboard to your shell with =agent-shell-send-clipboard-image=. Call with =C-u= to =agent-shell-send-clipboard-image-to= to select from your shells. agent-shell relies on external programs to write an image from clipboard to file as configured in =agent-shell-clipboard-image-handlers=. Preconfigured handlers are

=wl-paste= for Wayland desktops,
=xclip= for Xorg,
=pngpaste= for MacOS.
=powershell= for Windows.

*** Inhibiting minor modes during file writes

Some minor modes (for example, =aggressive-indent-mode=) can interfere with an agent's edits. Agent Shell can temporarily disable selected per-buffer minor modes while applying edits.

#+begin_src emacs-lisp (setopt agent-shell-write-inhibit-minor-modes '(aggressive-indent-mode)) #+end_src

All of the above settings can be applied on a per-project basis using [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html][directory-local variables]].

** Key bindings

=RET= - Submits prompt.
=M-J= - Iserts newline.
=C-c C-c= - Interrupt current agent operation
=TAB and Shift-TAB= - Navigate interactive elements

To customize =RET= binding behaviour, you can use something like:

#+begin_src emacs-lisp :lexical no (use-package agent-shell :bind (:map agent-shell-mode-map ("RET" . newline) ("M-RET" . shell-maker-submit))) #+end_src

Or if you prefer C-c C-c to send and C-c C-k to interrupt, use the following:

#+begin_src emacs-lisp :lexical no (use-package agent-shell :bind (:map agent-shell-mode-map ("RET" . newline) ("C-c C-c" . shell-maker-submit) ("C-c C-k" . agent-shell-interrupt))) #+end_src

*** Evil Evil users may want to rebind ~RET~ for inserting a new line in =insert mode= and sending the prompt in =normal mode=.

Also, when viewing diffs (before accepting changes) it may be annoying having to enter =insert mode= to send keys (~y/n/p/q/etc~). If this is your case, you can make these buffers start in Emacs mode (you can always go to Evil modes if you need to with ~C-z~). #+begin_src emacs-lisp (use-package agent-shell :config ;; Evil state-specific RET behavior: insert mode = newline, normal mode = send (evil-define-key 'insert agent-shell-mode-map (kbd "RET") #'newline) (evil-define-key 'normal agent-shell-mode-map (kbd "RET") #'comint-send-input)

;; Configure *agent-shell-diff* buffers to start in Emacs state
(add-hook 'diff-mode-hook
    (lambda ()
      (when (string-match-p "\\*agent-shell-diff\\*" (buffer-name))
	(evil-emacs-state)))))

#+end_src

Customizations

#+BEGIN_SRC emacs-lisp :results table :colnames '("Custom variable" "Description") :exports results (let ((rows)) (mapatoms (lambda (symbol) (when (and (string-match "^agent-shell" (symbol-name symbol)) (custom-variable-p symbol)) (push `(,symbol ,(car (split-string (or (documentation-property symbol 'variable-documentation) (get (indirect-variable symbol) 'variable-documentation) (get symbol 'variable-documentation) "") "\n"))) rows)))) (sort rows (lambda (a b) (string< (symbol-name (car a)) (symbol-name (car b)))))) #+END_SRC

#+RESULTS: | Custom variable | Description | |-----------------------------------------------+---------------------------------------------------------------------------------| | agent-shell-agent-configs | The list of known agent configurations. | | agent-shell-anthropic-authentication | Configuration for Anthropic authentication. | | agent-shell-anthropic-claude-acp-command | Command and parameters for the Anthropic Claude client. | | agent-shell-anthropic-claude-command | Command and parameters for the Anthropic Claude client. | | agent-shell-anthropic-claude-environment | Environment variables for the Anthropic Claude client. | | agent-shell-anthropic-default-model-id | Default Anthropic model ID. | | agent-shell-anthropic-default-session-mode-id | Default Anthropic session mode ID. | | agent-shell-auggie-acp-command | Command and parameters for the Auggie client. | | agent-shell-auggie-authentication | Configuration for Auggie authentication. | | agent-shell-auggie-environment | Environment variables for the Auggie client. | | agent-shell-buffer-name-format | Format to use when generating agent shell buffer names. | | agent-shell-busy-indicator-frames | Frames for the busy indicator animation. | | agent-shell-clipboard-image-handlers | Handlers for saving clipboard images to a file. | | agent-shell-completion-mode-hook | Hook run after entering or leaving ‘agent-shell-completion-mode’. | | agent-shell-command-prefix | Command prefix for executing commands in a container. | | agent-shell-context-sources | Sources to consider when determining M-x agent-shell automatic context. | | agent-shell-cursor-acp-command | Command and parameters for the Cursor agent client. | | agent-shell-cursor-environment | Environment variables for the Cursor agent client. | | agent-shell-display-action | Display action for agent shell buffers. | | agent-shell-droid-acp-command | Command and parameters for the Factory Droid ACP client. | | agent-shell-droid-authentication | Configuration for Factory Droid authentication. | | agent-shell-droid-environment | Environment variables for the Factory Droid ACP client. | | agent-shell-embed-file-size-limit | Maximum file size in bytes for embedding with ContentBlock::Resource. | | agent-shell-file-completion-enabled | Non-nil automatically enables file completion when starting shells. | | agent-shell-github-acp-command | Command and parameters for the GitHub Copilot agent client. | | agent-shell-github-default-model-id | Default GitHub Copilot model ID. | | agent-shell-github-default-session-mode-id | Default GitHub Copilot session mode ID. | | agent-shell-github-environment | Environment variables for the GitHub Copilot agent client. | | agent-shell-google-authentication | Configuration for Google authentication. | | agent-shell-google-gemini-acp-command | Command and parameters for the Gemini client. | | agent-shell-google-gemini-environment | Environment variables for the Google Gemini client. | | agent-shell-goose-acp-command | Command and parameters for the Goose client. | | agent-shell-goose-authentication | Configuration for Goose authentication. | | agent-shell-goose-environment | Environment variables for the Goose client. | | agent-shell-header-style | Style for agent shell buffer headers. | | agent-shell-highlight-blocks | Whether or not to highlight source blocks. | | agent-shell-mcp-servers | List of MCP servers to initialize when creating a new session. | | agent-shell-mistral-acp-command | Command and parameters for the Mistral Vibe client. | | agent-shell-mistral-authentication | Configuration for Mistral AI authentication. | | agent-shell-mistral-default-model-id | Default Mistral AI model ID. | | agent-shell-mistral-default-session-mode-id | Default Mistral AI session mode ID. | | agent-shell-mistral-environment | Environment variables for the Mistral Vibe client. | | agent-shell-openai-authentication | Configuration for OpenAI authentication. | | agent-shell-openai-codex-acp-command | Command and parameters for the OpenAI Codex client. | | agent-shell-openai-codex-environment | Environment variables for the OpenAI Codex client. | | agent-shell-openai-default-model-id | Default Codex model ID. | | agent-shell-openai-default-session-mode-id | Default Codex session mode ID. | | agent-shell-opencode-acp-command | Command and parameters for the OpenCode client. | | agent-shell-opencode-authentication | Configuration for OpenCode authentication. | | agent-shell-opencode-default-model-id | Default OpenCode model ID. | | agent-shell-opencode-default-session-mode-id | Default OpenCode session mode ID. | | agent-shell-opencode-environment | Environment variables for the OpenCode client. | | agent-shell-path-resolver-function | Function for resolving remote paths on the local file-system, and vice versa. | | agent-shell-permission-icon | Icon displayed when shell commands require permission to execute. | | agent-shell-pi-acp-command | Command and parameters for the Pi ACP client. | | agent-shell-pi-environment | Environment variables for the Pi client. | | agent-shell-prefer-session-resume | Prefer ACP session resume over session load when both are available. | | agent-shell-prefer-viewport-interaction | Non-nil makes ‘agent-shell’ prefer viewport interaction over shell interaction. | | agent-shell-preferred-agent-config | Default agent to use for all new shells. | | agent-shell-qwen-acp-command | Command and parameters for the Qwen Code client. | | agent-shell-qwen-authentication | Configuration for Qwen Code authentication. | | agent-shell-qwen-environment | Environment variables for the Qwen Code client. | | agent-shell-screenshot-command | The program to use for capturing screenshots. | | agent-shell-section-functions | Abnormal hook run after overlays are applied (experimental). | | agent-shell-session-strategy | How to handle sessions when starting a new shell. | | agent-shell-show-busy-indicator | Non-nil to show the busy indicator animation in the header and mode line. | | agent-shell-show-config-icons | Whether to show icons in agent config selection. | | agent-shell-show-context-usage-indicator | Non-nil to show the context usage indicator in the header and mode line. | | agent-shell-show-usage-at-turn-end | Whether to display usage information when agent turn ends. | | agent-shell-show-welcome-message | Non-nil to show welcome message. | | agent-shell-text-file-capabilities | Whether agents are initialized with read/write text file capabilities. | | agent-shell-thought-process-expand-by-default | Whether thought process sections should be expanded by default. | | agent-shell-thought-process-icon | Icon displayed during the AI’s thought process. | | agent-shell-tool-use-expand-by-default | Whether tool use sections should be expanded by default. | | agent-shell-transcript-file-path-function | Function to generate the full transcript file path. | | agent-shell-ui-mode-hook | Hook run after entering or leaving ‘agent-shell-ui-mode’. | | agent-shell-user-message-expand-by-default | Whether user message sections should be expanded by default. | | agent-shell-write-inhibit-minor-modes | List of minor mode commands to inhibit during ‘fs/write_text_file’ edits. |

Commands #+BEGIN_SRC emacs-lisp :results table :colnames '("Binding" "Command" "Description") :exports results (let ((rows)) (mapatoms (lambda (symbol) (when (and (string-match "^agent-shell" (symbol-name symbol)) (commandp symbol)) (push `(,(string-join (seq-filter (lambda (symbol) (not (string-match "menu" symbol))) (mapcar (lambda (keys) (key-description keys)) (or (where-is-internal (symbol-function symbol) comint-mode-map nil nil (command-remapping 'comint-next-input)) (where-is-internal symbol agent-shell-mode-map nil nil (command-remapping symbol)) (where-is-internal (symbol-function symbol) agent-shell-mode-map nil nil (command-remapping symbol))))) " or ") ,(symbol-name symbol) ,(car (split-string (or (documentation symbol t) "") "\n"))) rows)))) (sort rows (lambda (a b) (string< (cadr a) (cadr b))))) #+END_SRC

#+RESULTS: | Binding | Command | Description | |-----------------+---------------------------------------------------------+-------------------------------------------------------------------------------| | | agent-shell | Start or reuse an existing agent shell. | | | agent-shell--display-buffer | Toggle agent SHELL-BUFFER display. | | | agent-shell-anthropic-start-claude-code | Start an interactive Claude Agent shell. | | | agent-shell-auggie-start-agent | Start an interactive Auggie agent shell. | | | agent-shell-clear-buffer | Clear the current shell buffer. | | | agent-shell-completion-mode | Toggle agent shell completion with @ or / prefix. | | | agent-shell-cursor-start-agent | Start an interactive Cursor agent shell. | | C- | agent-shell-cycle-session-mode | Cycle through available session modes for the current agent-shell' session. | | | agent-shell-delete-interaction-at-point | Delete interaction (request and response) at point. | | | agent-shell-droid-start-agent | Start an interactive Factory Droid agent shell. | | | agent-shell-fakes-load-session | Load and replay a traffic session from file. | | | agent-shell-github-start-copilot | Start an interactive GitHub Copilot agent shell. | | | agent-shell-google-start-gemini | Start an interactive Gemini CLI agent shell. | | | agent-shell-goose-start-agent | Start an interactive Goose agent shell. | | | agent-shell-help-menu | Transient menu for agent-shell' commands. | | | agent-shell-insert-file | Insert a file into agent-shell'. | | | agent-shell-insert-shell-command-output | Execute a shell command and insert output as a code block. | | C-c C-c | agent-shell-interrupt | Interrupt in-progress request and reject all pending permissions. | | | agent-shell-jump-to-latest-permission-button-row | Jump to the latest permission button row. | | | agent-shell-mistral-start-vibe | Start an interactive Mistral Vibe agent shell. | | | agent-shell-mode | Major mode for agent shell. | | | agent-shell-new-shell | Start a new agent shell. | | S-<return> | agent-shell-newline | Insert a newline, and move to left margin of the new line. | | C-<down> or M-n | agent-shell-next-input | Cycle forwards through input history. | | n or TAB | agent-shell-next-item | Go to next item. | | | agent-shell-next-permission-button | Jump to the next button. | | | agent-shell-open-transcript | Open the transcript file for the current agent-shell' buffer. | | | agent-shell-openai-start-codex | Start an interactive Codex agent shell. | | | agent-shell-opencode-start-agent | Start an interactive OpenCode agent shell. | | C-c C-o | agent-shell-other-buffer | Switch to other associated buffer (viewport vs shell). | | C- or M-p | agent-shell-previous-input | Cycle backwards through input history, saving input. | | p or | agent-shell-previous-item | Go to previous item. | | | agent-shell-previous-permission-button | Jump to the previous button. | | | agent-shell-prompt-compose | Compose an agent-shell' prompt in a dedicated buffer. | | | agent-shell-queue-request | Queue or immediately send a request depending on shell busy state. | | | agent-shell-qwen-start | Start an interactive Qwen Code CLI agent shell. | | | agent-shell-remove-pending-request | Remove all pending requests or a specific request by REMOVE-INDEX. | | C-x x r | agent-shell-rename-buffer | Rename current shell buffer. | | | agent-shell-reset-logs | Reset all log buffers. | | | agent-shell-resume-pending-requests | Resume processing pending requests in the queue. | | | agent-shell-run-all-tests | Run all agent-shell tests in batch mode. | | M-r | agent-shell-search-history | Search previous input history. | | | agent-shell-send-current-file | Insert a file into agent-shell'. | | | agent-shell-send-dwim | Send region or error at point to last accessed shell buffer in project. | | | agent-shell-send-file | Insert a file into agent-shell'. | | | agent-shell-send-other-file | Prompt to send a file into agent-shell'. | | | agent-shell-send-region | Send region to last accessed shell buffer in project. | | | agent-shell-send-screenshot | Capture a screenshot and insert it into agent-shell'. | | C-c RET | agent-shell-set-session-mode | Set session mode (if any available). | | C-c C-v | agent-shell-set-session-model | Set session model. | | RET | agent-shell-submit | Submit current input. | | | agent-shell-toggle | Toggle agent shell display. | | | agent-shell-toggle-logging | Toggle logging. | | | agent-shell-ui-backward-block | Jump to the previous block. | | | agent-shell-ui-forward-block | Jump to the next block. | | | agent-shell-ui-mode | Minor mode for SUI block navigation. | | | agent-shell-ui-toggle-fragment-at-point | Toggle visibility of fragment body at point. | | | agent-shell-version | Show agent-shell' mode version. | | | agent-shell-view-acp-logs | View agent shell ACP logs buffer. | | | agent-shell-view-traffic | View agent shell traffic buffer. | | | agent-shell-viewport-compose-cancel | Cancel prompt composition. | | | agent-shell-viewport-compose-send | Send the viewport composed prompt to the agent shell. | | | agent-shell-viewport-compose-send-and-kill | Send the viewport composed prompt to the agent shell and kill compose buffer. | | | agent-shell-viewport-compose-send-and-wait-for-response | Send the viewport composed prompt and display response in viewport. | | | agent-shell-viewport-cycle-session-mode | Cycle through available session modes. | | | agent-shell-viewport-edit-mode | Major mode for composing agent shell prompts. | | | agent-shell-viewport-interrupt | Interrupt active agent shell request. | | | agent-shell-viewport-next-item | Go to next item. | | | agent-shell-viewport-next-page | Show next interaction (request / response). | | | agent-shell-viewport-previous-item | Go to previous item. | | | agent-shell-viewport-previous-page | Show previous interaction (request / response). | | | agent-shell-viewport-refresh | Refresh viewport buffer content with current item from shell. | | | agent-shell-viewport-reply | Reply as a follow-up and compose another prompt/query. | | | agent-shell-viewport-set-session-mode | Set session mode. | | | agent-shell-viewport-set-session-model | Set session model. | | | agent-shell-viewport-view-last | Display the last request/response interaction. | | | agent-shell-viewport-view-mode | Major mode for viewing agent shell prompts (read-only). |

Filing issues When filing an issue, please keep the checkboxes from the [[https://github.com/xenodium/agent-shell/blob/main/.github/ISSUE_TEMPLATE/issue.md][issue template]] and check them off as applicable. They help ensure I have enough information to help.

Please read through this section before filing issues or feature requests. I won't be able to help unless I have enough information to help. This section shows how to get the details I need.

Versions: What version of =agent-shell=, =acp.el=, the ACP package (e.g. =claude-code-acp=), and the agent CLI (e.g. =claude=, =gemini=) are you running?
Steps to reproduce: What exact steps lead to the issue? Be specific about what you did and in what order.
ACP traffic: See [[https://github.com/xenodium/agent-shell?tab=readme-ov-file#how-do-i-viewget-agent-client-protocol-traffic][how to get ACP traffic]] above. This is the most useful piece of information for diagnosing issues.
Screenshots: A screenshot helps correlate what you see with the protocol data.
Your agent-shell config: Share any relevant =agent-shell= variable settings from your Emacs config.
Profiling data (for performance issues): Use =M-x profiler-start=, reproduce the issue, then =M-x profiler-report= (and =M-x profiler-stop=). Share the report.

** Why doesn't =agent-shell= offer all slash commands/skills available in CLI agent?

=agent-shell= can only offer the slash commands/skills advertised by the agent via [[https://agentclientprotocol.com][Agent Client Protocol]]. To view what's exposed by your agent, expand the "Available /commands" section. Is the command you're after missing? Please consider filing a feature-request with the respective agent (ie. Gemini CLI) or their ACP layer (claude-code-acp).

[[file:slash-commands.png]]

** Can you add support for another agent?

Does the agent support ACP ([[https://agentclientprotocol.com][Agent Client Protocol]])? If so, =agent-shell= can likely support this agent. Some agents have ACP support built-in (like [[https://github.com/google-gemini/gemini-cli][gemini-cli]]). Others require a separate ACP package (like [[https://github.com/zed-industries/claude-code-acp][claude-code-acp]] for [[https://github.com/anthropics/claude-code][claude-code]]). When filing a feature request to add a new agent, please include a link to the project supporting [[https://agentclientprotocol.com][Agent Client Protocol]] (built-in or otherwise).

Agents without ACP support are out of scope for integrating with =agent-shell=. Having said that, if you do build an ACP layer like =claude-agent-acp=, then =agent-shell= can work with it.

** =agent-shell= not behaving as expected?

Could be the agent itself missing an [[https://agentclientprotocol.com][Agent Client Protocol]] feature, =agent-shell= missing the feature, or both 😃 So which one is it? It's hard to tell unless we look at [[https://agentclientprotocol.com][Agent Client Protocol]] traffic between the two.

** Is shx supported? No. There are reports that [[https://github.com/xenodium/agent-shell/issues/543][it does not work]] with agent-shell. ** How do I view/get [[https://agentclientprotocol.com][Agent Client Protocol]] traffic?

=M-x agent-shell-toggle-logging= (make sure logging is ON).
Reproduce the issue
=M-x agent-shell-view-traffic=

Browse through traffic and see if you can spot the issue. For example, if you see a request sent by the agent asking for user permission, but =agent-shell= isn't surfacing this permission, it looks like perhaps =agent-shell= is missing a feature.

For example, here's what a [[https://agentclientprotocol.com/protocol/schema#session%2Frequest-permission][session/request_permission]] request would look like from the traffic viewer.

[[file:traffic.png]]

Sometimes including a traffic screenshot in an issue is enough. Other times including the full traffic is needed. From the traffic viewer, you can =M-x acp-traffic-save-to= to save as =.traffic=.

** Where should I file bug or feature request?

*** Agent issues or feature requests

If you're able to determine the agent is missing a feature (or a bug is present) in their [[https://agentclientprotocol.com][Agent Client Protocol]] implementation, please file an issue directly with the agent folks. For example:

[[https://github.com/agentclientprotocol/claude-agent-acp][claude-agent-acp]]: For Claude Agent.
[[https://github.com/zed-industries/codex-acp][codex-acp]]: For Codex.
[[https://github.com/google-gemini/gemini-cli][Gemini CLI]].
[[https://block.github.io/goose/docs/getting-started/installation][Goose]].
[[https://github.com/QwenLM/qwen-code][Qwen Code]].

*** =agent-shell= issues or feature requests

Alternatively, if you noticed =agent-shell= is missing a feature (or has a bug), please [[https://github.com/xenodium/agent-shell/issues][file an agent-shell issue]].

*** Not sure where to file an issue?

File [[https://github.com/xenodium/agent-shell/issues][in agent-shell]], but please try to provide details, so I can determine whether =agent-shell= or the agent itself needs work. Traffic data would be very useful here. Provide a screenshot or a .traffic file if you think it'll help. See [[https://github.com/xenodium/agent-shell?tab=readme-ov-file#how-do-i-viewget-agent-client-protocol-traffic][how to get ACP traffic]].

Contributing

See [[file:CONTRIBUTING.org][CONTRIBUTING.org]].

Contributors

#+HTML: #+HTML: #+HTML:

Made with [[https://contrib.rocks][contrib.rocks]].

eval-exec/neomacs

NEO Emacs (WIP): A GPU-powered Emacs written in Rust with a modern display engine. Aiming for modern design/multi-threaded Elisp, 10x performance and 100% Emacs compatibility. 🚀 Inline 4K images/4K videos/WPEWebKit using GPU acceleration, DMA-BUF, ZERO-COPY. Rich animation effects support.

"I started Neomacs because I love Emacs, I respect Emacs, and I want to evolve the legendary Emacs into the ultimate modern powerhouse." — Eval Exec

✨ "While other editors can save your files, only Emacs can save your soul." ✨

❤️ Sponsor Neomacs

Neomacs is a long-term project that takes significant ongoing work to build, test, and maintain. If you want to support its development, please consider sponsoring it on ❤️ GitHub Sponsors.

Note: Neomacs is in active alpha development. Expect rough edges, breaking changes, and missing features. Contributions and bug reports are very welcome!

Fork notice: Neomacs is a hard fork of GNU Emacs, forked from commit 705c0e3729. The changes are too invasive to ever be accepted upstream, so we did not preserve the original git history to keep the repository lightweight. If you need the full Emacs git history for reference, open an issue, and we can re-add it.

Why a fork, not from scratch? Neomacs aims for 100% compatibility with official GNU Emacs — every config, package, and workflow should just work. By forking, we keep the original Emacs C code as a reference and test oracle: we can verifying that each Rust rewrite produces identical behavior, ensuring nothing breaks as subsystems are replaced one by one.

The Problem

Emacs is a 40-year-old C codebase that hasn't kept up with modern hardware or software engineering:

Display engine — ~50,000 lines of C in xdisp.c, designed for text terminals in the 1980s. CPU-only rendering, no GPU acceleration, no native video/animations, no smooth visual effects
- Large images — rendering slows down significantly
- Video playback — not natively supported
- Modern animations — no smooth cursor movement, buffer transitions, or visual effects
- Web content — limited browser integration
- GPU utilization — everything runs on CPU while your GPU sits idle
Elisp performance — no inline caching, stop-the-world GC, dynamic dispatch overhead. Even with native-comp (AOT), Elisp lacks runtime JIT optimization, speculative inlining, and concurrent GC — leaving significant performance on the table
Unsafe C codebase — ~300,000 lines of unsafe C with manual memory management, monolithic architecture (runtime and editor entangled), single-threaded design that prevents real concurrency

The Solution

Throw it all away and start fresh.

Neomacs is rewriting Emacs from the ground up in Rust — starting with the display engine and expanding to the core:

GPU display engine (done) — ~4,000 lines of Rust replacing ~50,000 lines of legacy C, powered by wgpu (Vulkan/Metal/DX12/OpenGL)
Rust layout engine (done) — bypasses xdisp.c entirely, reads buffer text via FFI and computes layout in Rust
Inline video/images/WebKit (done) — 4K video, GPU-decoded images, and WPE WebKit browser views embedded directly in buffers
21 scroll effects, 8 cursor modes, 10 buffer transitions (done) — GPU-accelerated animations running on the render thread at display refresh rate
Zero-copy DMA-BUF (done) — efficient GPU texture sharing (Linux)
Rewrite entire Emacs core in Rust (in progress) — replacing all ~300,000 lines of C with safe, modern Rust: Elisp runtime, evaluator, bytecode VM, GC, buffer/window/frame subsystems, and all editor internals
True multi-threaded Elisp (planned) — real concurrency for the Lisp machine, not just cooperative threading
10x performance, and 100% Emacs compatibility. (planned) — Rust-optimized Lisp machine with JIT compilation and inline caching

Showcase

🎬 Neomacs youtube video

Animations (Cursor, Buffer Switch, Scroll)

https://github.com/user-attachments/assets/85b7ee7b-3f4a-4cd2-a84f-86a91d052f11

GPU Text with Rounded Box Faces

Inline 4K Images

GPU-decoded directly — no CPU cost, won't block Emacs main thread.

Inline Web Browser (WPE WebKit)

GPU backend, DMA-BUF zero-copy.

Inline Terminal (Alacritty)

GPU-backed terminal emulator embedded in Emacs buffer.

Inline 4K Video Playback

DMA-BUF zero-copy, GPU backend — no CPU cost.

https://github.com/user-attachments/assets/275c6d9a-fced-44f6-8f43-3bbd2984d672

Features

Working Now

Feature	Description
GPU Text Rendering	Hardware-accelerated text via wgpu (Vulkan/Metal/DX12/OpenGL)
Video Playback	GStreamer + VA-API hardware decode with DMA-BUF zero-copy
Cursor Animations	8 modes with 7 movement styles and configurable spring trail
Scroll Animations	21 scroll effects with 5 easing functions
Buffer Transitions	10 buffer-switch effects (crossfade, slide, page-curl, etc.)
DMA-BUF Zero-Copy	GPU-to-GPU texture sharing via Vulkan HAL (no CPU readback)
Inline Images	GPU-accelerated image rendering in buffers
Inline WebKit	WPE WebKit browser views embedded in buffers

Animations

All animations run on the GPU render thread at display refresh rate, independent of the Emacs redisplay. Configure everything from Elisp.

Cursor

8 particle/visual modes (Neovide-inspired):

Mode	Description
`none`	No animation, instant movement
`smooth`	Smooth interpolated movement (default)
`railgun`	Particles shoot backward from cursor
`torpedo`	Comet-like trail follows cursor
`pixiedust`	Sparkly particles scatter around cursor
`sonicboom`	Shockwave ring expands from cursor
`ripple`	Concentric rings emanate outward
`wireframe`	Animated outline glow

7 movement styles controlling how the cursor interpolates between positions:

Style	Description
`exponential`	Smooth deceleration, no fixed duration (uses speed param)
`spring`	Critically-damped spring, Neovide-like feel (default)
`ease-out-quad`	Gentle deceleration curve
`ease-out-cubic`	Stronger deceleration curve
`ease-out-expo`	Sharp deceleration curve
`ease-in-out-cubic`	Smooth S-curve
`linear`	Constant speed

The spring style also supports a 4-corner trail effect where leading corners snap ahead and trailing corners stretch behind, controlled by a trail-size parameter (0.0-1.0).

Buffer Switch (Crossfade/Transition)

10 buffer-switch effects triggered when the visible buffer changes:

Effect	Description
`none`	Instant switch
`crossfade`	Alpha blend between old and new (default)
`slide-left/right/up/down`	Directional slide transitions
`scale-fade`	Scale and fade
`push`	New buffer pushes old buffer out
`blur`	Blur transition
`page-curl`	3D page-turning effect

Scroll

21 scroll animation effects organized into categories:

#	Effect	Category	Description
0	`slide`	2D	Content slides in scroll direction (default)
1	`crossfade`	2D	Alpha blend between old and new positions
2	`scale-zoom`	2D	Destination zooms from 95% to 100%
3	`fade-edges`	2D	Lines fade at viewport edges
4	`cascade`	2D	Lines drop in with stagger delay
5	`parallax`	2D	Layers scroll at different speeds
6	`tilt`	3D	Subtle 3D perspective tilt
7	`page-curl`	3D	Page turning effect
8	`card-flip`	3D	Card flips around X-axis
9	`cylinder-roll`	3D	Content wraps around cylinder
10	`wobbly`	Deformation	Jelly-like deformation
11	`wave`	Deformation	Sine-wave distortion
12	`per-line-spring`	Deformation	Each line springs independently
13	`liquid`	Deformation	Noise-based fluid distortion
14	`motion-blur`	Post-process	Vertical blur during scroll
15	`chromatic-aberration`	Post-process	RGB channel separation
16	`ghost-trails`	Post-process	Semi-transparent afterimages
17	`color-temperature`	Post-process	Warm/cool tint by direction
18	`crt-scanlines`	Post-process	Retro scanline overlay
19	`depth-of-field`	Post-process	Center sharp, edges dim
20	`typewriter-reveal`	Creative	Lines appear left-to-right

5 scroll easing functions:

#	Easing	Description
0	`ease-out-quad`	Standard deceleration (default)
1	`ease-out-cubic`	Stronger deceleration
2	`spring`	Critically damped spring with overshoot
3	`linear`	Constant speed
4	`ease-in-out-cubic`	Smooth S-curve

Configuration

;; All-in-one configuration:
;; (neomacs-set-animation-config
;;   CURSOR-ENABLED CURSOR-SPEED CURSOR-STYLE CURSOR-DURATION
;;   CROSSFADE-ENABLED CROSSFADE-DURATION
;;   SCROLL-ENABLED SCROLL-DURATION
;;   &optional SCROLL-EFFECT SCROLL-EASING TRAIL-SIZE)

;; Example: spring cursor, crossfade buffer switch, page-curl scroll with spring easing
(neomacs-set-animation-config t 15.0 'spring 150 t 200 t 150 7 2 0.7)

;; Example: fast linear cursor, no crossfade, wobbly scroll
(neomacs-set-animation-config t 20.0 'linear 100 nil 200 t 200 10 0 0.0)

The Ambitious Vision

Neomacs aims to be the most capable and beautiful Emacs ever built, rewriting its internals in Rust:

Rich media — 4K video, PDF rendering, image manipulation directly in buffers
GPU-native — hardware-accelerated rendering, shader effects, 120fps animations
GPU terminal — Rust-based terminal emulator replacing slow term.el/ansi-term/vterm
Cross-platform — Linux (Vulkan), macOS (Metal), Windows (Vulkan/DX12)
Rust core — rewrite Emacs C internals in Rust for memory safety and performance
Multi-threaded Elisp — true concurrency for the Lisp machine, enabling parallel Elisp execution
10x faster Elisp — Rust-optimized Lisp interpreter/compiler to dramatically speed up Elisp

The goal: Make Emacs as powerful and beautiful as it deserves to be.

Architecture

Neomacs is rewriting Emacs from C to Rust with clean module boundaries. The goal is a layered architecture where the Elisp runtime is a self-contained core, editor subsystems are independent modules communicating through defined APIs, and the rendering engine runs on a separate GPU thread.

Current State

The rendering engine and layout engine are already in Rust. The Emacs C core still runs the Elisp evaluator, GC, and editor subsystems — connected to Rust via FFI channels.

Target Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Neomacs (Rust)                          │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                  Elisp Runtime Core                      │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │   │
│  │  │ Evaluator   │  │ Bytecode VM │  │ GC/Allocator│       │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘       │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │   │
│  │  │ LispObject  │  │Symbol Table │  │ Type System │       │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘       │   │
│  └──────────────────────────────────────────────────────────┘   │
│                             │                                   │
│                             ▼                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                       Runtime API                        │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │   │
│  │  │register_type│  │register_root│  │define_func  │       │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘       │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │   │
│  │  │  run_hook   │  │  specbind   │  │signal_error │       │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘       │   │
│  └──────────────────────────────────────────────────────────┘   │
│                             │                                   │
│                             ▼                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                     Editor Modules                        │  │
│  │  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐  ┌───────┐│  │
│  │  │ Buffer │  │ Window │  │ Frame  │  │Keyboard│  │Process││  │
│  │  └────────┘  └────────┘  └────────┘  └────────┘  └───────┘│  │
│  │  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐  ┌───────┐│  │
│  │  │ Font   │  │ Image  │  │File IO │  │ Reader │  │ Data  ││  │
│  │  └────────┘  └────────┘  └────────┘  └────────┘  └───────┘│  │
│  └───────────────────────────────────────────────────────────┘  │
│                             │                                   │
│                             ▼                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    Rendering Engine                       │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │  │
│  │  │Layout Engine│  │wgpu Renderer│  │ Animations  │        │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘        │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │  │
│  │  │    winit    │  │   WebKit    │  │ GStreamer   │        │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘        │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                      Threading                            │  │
│  │   ┌────────────┐                       ┌────────────┐     │  │
│  │   │EmacsThread │                       │RenderThread│     │  │
│  │   └────────────┘                       └────────────┘     │  │
│  │      │                                      ▲             │  │
│  │      ├── FrameGlyphBuffer (crossbeam) ──────┘             │  │
│  │      └── InputEvent (crossbeam) ────────────────────┐     │  │
│  │                                                     │     │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                       Backends                            │  │
│  │   ┌──────────┐         ┌──────────┐       ┌──────────┐    │  │
│  │   │  Vulkan  │         │  Metal   │       │ DX12/GL  │    │  │
│  │   └──────────┘         └──────────┘       └──────────┘    │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Design principles:

Elisp Runtime Core is a self-contained Rust crate. It owns LispObject, the evaluator, bytecode VM, GC, specpdl, and symbol table. It does NOT know about buffers, windows, frames, or any editor concept.
Runtime API is a trait-based interface. Editor modules register their types (with GC trace descriptors), roots, and primitives. The GC traces registered types generically — no hardcoded mark_kboards() or mark_terminals().
Editor Modules are independent. Each owns its data structures and exposes them to Lisp through the Runtime API. Modules do not reach into each other's internals.
Rendering Engine runs on a separate GPU thread, communicating via crossbeam channels (FrameGlyphBuffer down, InputEvent up). Already implemented.

Why Rust?

Memory safety without garbage collection
Zero-cost abstractions for high-performance rendering
Excellent FFI with C (Emacs core)
Modern tooling (Cargo, async, traits)
Growing ecosystem for graphics (wgpu, winit, cosmic-text)

Why wgpu?

Cross-platform — single API for Vulkan, Metal, DX12, and OpenGL
Safe Rust API — no unsafe Vulkan/Metal code in application
WebGPU standard — future-proof API design
Active development — used by Firefox, Bevy, and many others

For an in-depth analysis of the current Emacs C architecture, why it's hard to rewrite, and why Elisp is slow, see docs/elisp-core-analysis.md.

Building

Prerequisites

Rust (stable, 1.93+)
GStreamer (optional, for video playback)
WPE WebKit (optional, for inline browser, Linux only)
VA-API (optional, for hardware video decode on Linux)
GNU Emacs (optional, for pre-compiling .el files — speeds up bootstrap ~17x)

Build commands in this README are run from the repository root.

Quick Start

# Optional (recommended): use the repo dev shell (handles all dependencies)
nix develop --accept-flake-config

# Build Neomacs (compiles Rust, bootstraps Elisp, generates pdump)
cargo xtask fresh-build --release

# Run
./target/release/neomacs

Linux (Arch Linux)

# Install dependencies
sudo pacman -S --needed \
  base-devel autoconf automake texinfo clang git pkg-config \
  gtk4 glib2 cairo \
  gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad \
  wpewebkit wpebackend-fdo \
  wayland wayland-protocols \
  mesa libva \
  libjpeg-turbo libtiff giflib libpng librsvg libwebp \
  ncurses gnutls libxml2 sqlite jansson tree-sitter \
  gmp acl libxpm \
  libgccjit

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build Neomacs (compiles Rust, bootstraps Elisp, generates pdump)
cargo xtask fresh-build --release

# Run
./target/release/neomacs

macOS (Experimental)

macOS support is experimental — see issue #22 for status.

# Install dependencies (Homebrew)
brew install pkgconf \
  glib cairo \
  gstreamer gst-plugins-base gst-plugins-good \
  jpeg-turbo libtiff giflib libpng librsvg webp \
  gnutls libxml2 sqlite jansson tree-sitter gmp

# gmp-mpfr-sys is built with system GMP support. Its build script probes
# GMP with the C compiler directly, so Homebrew's keg must be visible to
# both the C compiler and linker.
export CPATH="$(brew --prefix gmp)/include${CPATH:+:$CPATH}"
export LIBRARY_PATH="$(brew --prefix gmp)/lib${LIBRARY_PATH:+:$LIBRARY_PATH}"

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build Neomacs
cargo xtask fresh-build --release

# Run
./target/release/neomacs

NixOS / Nix

Neomacs uses nix-wpe-webkit for the WPE WebKit dependency. Pre-built binaries are available via Cachix (~60MB download instead of ~1 hour build).

The flake.nix includes nixConfig for the Cachix cache. Pass --accept-flake-config to use it automatically, or configure it system-wide:

NixOS — add to your configuration (e.g., /etc/nixos/configuration.nix):

{
  nix.settings.substituters = [ "https://nix-wpe-webkit.cachix.org" ];
  nix.settings.trusted-public-keys = [ "nix-wpe-webkit.cachix.org-1:ItCjHkz1Y5QcwqI9cTGNWHzcox4EqcXqKvOygxpwYHE=" ];
}

Non-NixOS — add to ~/.config/nix/nix.conf:

extra-substituters = https://nix-wpe-webkit.cachix.org
extra-trusted-public-keys = nix-wpe-webkit.cachix.org-1:ItCjHkz1Y5QcwqI9cTGNWHzcox4EqcXqKvOygxpwYHE=

Build with Nix

Option 1 — Trust the nixConfig in flake.nix (simplest):

nix build --accept-flake-config

# Or enter development shell
nix develop --accept-flake-config

Option 2 — Pass Cachix flags directly:

nix build \
  --extra-substituters "https://nix-wpe-webkit.cachix.org" \
  --extra-trusted-public-keys "nix-wpe-webkit.cachix.org-1:ItCjHkz1Y5QcwqI9cTGNWHzcox4EqcXqKvOygxpwYHE="

Note: Both options require your user to be in trusted-users in /etc/nix/nix.conf (e.g., trusted-users = root @wheel your-username), or configure the cache system-wide as shown above.

Manual build (inside dev shell)

cargo xtask fresh-build --release

Platform Support

Linux – primary supported platform. The steps above document a validated Arch Linux workflow, but other distributions should follow similar dependency installation with their package manager.
macOS – experimental. See issue #22 for status.
Windows – planned.
Mobile (Android/iOS) – planned.
WebAssembly (WASM) – planned.

Roadmap

The Rust display engine rewrite is complete — the Rust layout engine is now the only rendering path, bypassing xdisp.c entirely. See docs/rust-display-engine.md for the design document.

Completed:

GPU text rendering, face resolution, syntax highlighting
Display properties, overlays, invisible text, line numbers
Mode-line, header-line, tab-line
Variable-width fonts, BiDi text layout
Word-wrap, truncation, fringes, margins
Images, video, WebKit embedding

In progress:

Rewriting the entire Emacs C core in Rust (Elisp runtime, evaluator, bytecode VM, GC, buffer/window/frame subsystems)
macOS and cross-platform support
TUI (terminal) renderer

Planned:

True multi-threaded Elisp
JIT compilation and inline caching for 10x Elisp performance

Contributing

Contributions welcome! Areas where help is needed:

Graphics programmers — shader effects, rendering optimizations
Rust developers — architecture, performance, safety
Emacs hackers — Lisp API design, integration testing
Documentation — tutorials, API docs, examples

Acknowledgments

Built with:

wgpu — Cross-platform GPU rendering (Vulkan/Metal/DX12/GL)
winit — Cross-platform window management
cosmic-text — Pure Rust text shaping
GStreamer — Video playback with VA-API
ash — Vulkan bindings for DMA-BUF import
Inspired by Neovide cursor animations

License

GNU General Public License v3.0 (same as Emacs)

Star History

doomemacs/doomemacs

An Emacs framework for the stubborn martian hacker

Doom Emacs

Install • Documentation • FAQ • Screenshots • Contribute

Introduction

It is a story as old as time. A stubborn, shell-dwelling, and melodramatic vimmer—envious of the features of modern text editors—spirals into despair before he succumbs to the dark side. This is his config.

Doom is a configuration framework for GNU Emacs tailored for Emacs bankruptcy veterans who want less framework in their frameworks, a modicum of stability (and reproducibility) from their package manager, and the performance of a hand rolled config (or better). It can be a foundation for your own config or a resource for Emacs enthusiasts to learn more about our favorite operating system.

Its design is guided by these mantras:

Gotta go fast. Startup and run-time performance are priorities. Doom goes beyond by modifying packages to be snappier and load lazier.
Close to metal. There's less between you and vanilla Emacs by design. That's less to grok and less to work around when you tinker. Internals ought to be written as if reading them were part of Doom's UX, and it is!
Opinionated, but not stubborn. Doom is about reasonable defaults and curated opinions, but use as little or as much of it as you like.
Your system, your rules. You know better. At least, Doom hopes so! It won't automatically install system dependencies (and will force plugins not to either). Rely on doom doctor to tell you what's missing.
Nix/Guix is a great idea! The Emacs ecosystem is temperamental. Things break and they break often. Disaster recovery should be a priority! Doom's package management should be declarative and your private config reproducible, and comes with a means to roll back releases and updates (still a WIP).

Check out the FAQ for answers to common questions about the project.

Features

Minimalistic good looks inspired by modern editors.
Curated and sane defaults for many packages, (major) OSes, and Emacs itself.
A modular organizational structure for separating concerns in your config.
A standard library designed to simplify your elisp bike shedding.
A declarative package management system (powered by straight.el) with a command line interface. Install packages from anywhere, not just (M)ELPA, and pin them to any commit.
Optional vim emulation powered by evil-mode, including ports of popular vim plugins like vim-sneak, vim-easymotion, vim-unimpaired and more!
Opt-in LSP integration for many languages, using lsp-mode or eglot
Support for many programming languages. Includes syntax highlighting, linters/checker integration, inline code evaluation, code completion (where possible), REPLs, documentation lookups, snippets, and more!
Support for many tools, like docker, pass, ansible, terraform, and more.
A Spacemacs-esque keybinding scheme, centered around leader and localleader prefix keys (SPC and SPCm for evil users, C-c and C-c l for vanilla users).
A rule-based popup manager to control how temporary buffers are displayed (and disposed of).
Per-file indentation style detection and editorconfig integration. Let someone else argue about tabs vs spaces.
Project-management tools and framework-specific minor modes with their own snippets libraries.
Project search (and replace) utilities, powered by ripgrep and ivy or helm.
Isolated and persistent workspaces (also substitutes for vim tabs).
Support for Chinese and Japanese input systems.
Save a snapshot of your shell environment to a file for Emacs to load at startup. No more struggling to get Emacs to inherit your PATH, among other things.

Prerequisites

Required:
- GNU Emacs 27.1–30.2 (30.2 is recommended)
  - If only using Doom's core, 27.1+ is required.
  - If using Doom's modules (especially tree-sitter support), 29.1+ is required.
- Git >= 2.23
- ripgrep >= 11.0
Optional, but recommended:
- fd 7.3.0+ (used to improve file indexing performance)
- GNU variants of find, ls, and tar (on MacOS and BSD *nix)
- Symbola font (Emacs' fallback font for glyphs it can't display)

Warning

Avoid unstable and pre-release builds of Emacs. These end in .50, .60, or .9X (e.g. 28.1.91). Doom should generally work on Emacs HEAD (the maintainer dogfoods it), but support lags behind the bleeding edge by at least a month or so.

Important

Doom is comprised of ~150 optional modules, some of which may have additional dependencies. Visit their documentation or run bin/doom doctor to check for any that you may have missed.

Install

git clone --depth 1 https://github.com/doomemacs/doomemacs ~/.config/emacs
~/.config/emacs/bin/doom install

Then read our Getting Started guide to be walked through installing, configuring and maintaining Doom Emacs.

It's a good idea to add ~/.config/emacs/bin to your PATH! Other bin/doom commands you should know about:

doom sync to synchronize your private config with Doom by installing missing packages, removing orphaned packages, and regenerating caches. Run this whenever you modify your private init.el or packages.el, or install/remove an Emacs package through your OS package manager (e.g. mu4e or agda).
doom upgrade to update Doom to the latest release & all installed packages.
doom doctor to diagnose common issues with your system and config.
doom env to dump a snapshot of your shell environment to a file that Doom will load at startup. This allows Emacs to inherit your PATH, among other things.

Roadmap

Doom is an active and ongoing project. To make that development more transparent, its roadmap (and other concerns) are published across three github project boards and a newsletter:

Development Roadmap
Packages under review: lists plugins we are watching and considering for inclusion, and what their status for inclusion is. Please consult this list before requesting new packages/features.

Upstream bugs: lists issues that originate from elsewhere, and whether or not we have local workarounds or temporary fixes for them.
~~Doom's newsletter~~ (not finished) will contain changelogs in between releases.

Getting help

Emacs is no journey of a mere thousand miles. You will run into problems and mysterious errors. When you do, here are some places you can look for help:

Our documentation covers many use cases.
- The Configuration section covers how to configure Doom and its packages.
- The Package Management section covers how to install and disable packages.
- This section explains the bin/doom script's most important commands.
- This section lists some common configuration mistakes new users make, when migrating a config from another distro or their own.
- This answer shows you how to add your own themes to your private config.
- This answer shows you how to change the default font.
- Your issue may be documented in the FAQ.
With Emacs built-in help system documentation is a keystroke away:
- For functions: SPC h f or C-h f
- For variables: SPC h v or C-h v
- For a keybind: SPC h k or C-h k
- To search available keybinds: SPC h b b or C-h b b
Run bin/doom doctor to detect common issues with your development environment and private config.
Check out the FAQ or Community FAQs, in case your question has already been answered.
Search Doom's issue tracker in case your issue was already reported.
Hop on our Discord server; it's active and friendly! Keep an eye on the #announcements channel, where I announce breaking updates and releases.

Contribute

Doom is a labor of love and incurable madness, but I'm only one guy. Doom wouldn't be where it is today without your help. I welcome contributions of any kind!

I ❤️ pull requests and bug reports (see the Contributing Guidelines)!
Don't hesitate to tell me my Elisp-fu sucks, but please tell me why.
Hop on our Discord server and say hi! Help others, hang out or talk to me about Emacs, gamedev, programming, physics, pixel art, anime, gaming -- anything you like. Nourish this lonely soul.
If you'd like to support my work financially, buy me a drink through liberapay or paypal. My work contends with studies, adventures in indie gamedev and freelance work. Donations help me allocate more time to my Emacs and OSS capers.

google-coral/coralnpu

A machine learning accelerator core designed for energy-efficient AI at the edge.

Coral NPU

Coral NPU is a hardware accelerator for ML inferencing. Coral NPU is an Open Source IP designed by Google Research and is freely available for integration into ultra-low-power System-on-Chips (SoCs) targeting wearable devices such as hearables, augmented reality (AR) glasses and smart watches.

Coral NPU is a neural processing unit (NPU), also known as an AI accelerator or deep-learning processor. Coral NPU is based on the 32-bit RISC-V Instruction Set Architecture (ISA).

Coral NPU includes three distinct processor components that work together: matrix, vector (SIMD), and scalar.

Coral NPU Architecture Datasheet

Coral NPU Features

Coral NPU offers the following top-level feature set:

RV32IMF_Zve32x RISC-V instruction set (specifically rv32imf_zve32x_zicsr_zifencei_zbb)
32-bit address space for applications and operating system kernels
Four-stage processor, in-order dispatch, out-of-order retire
Four-way scalar, two-way vector dispatch
128-bit SIMD, 256-bit (future) pipeline
8 KB ITCM memory (tightly-coupled memory for instructions)
32 KB DTCM memory (tightly-coupled memory for data)
Both memories are single-cycle-latency SRAM, more efficient than cache memory
AXI4 bus interfaces, functioning as both manager and subordinate, to interact with external memory and allow external CPUs to configure Coral NPU

System Requirements

Bazel 7.4.1
Python 3.9-3.12 (3.13 support is in progress)
SRecord

Quick Start

# Ensure that test suite passes
bazel run //tests/cocotb:core_mini_axi_sim_cocotb

# Build a binary
bazel build //examples:coralnpu_v2_hello_world_add_floats

# Build the Simulator (non-RVV for shorter build time):
bazel build //tests/verilator_sim:core_mini_axi_sim

# Run the binary on the simulator:
bazel-bin/tests/verilator_sim/core_mini_axi_sim --binary bazel-out/k8-fastbuild-ST-dd8dc713f32d/bin/examples/coralnpu_v2_hello_world_add_floats.elf

emacs-mirror/emacs

Mirror of GNU Emacs

This directory tree holds version 32.0.50 of GNU Emacs, the extensible, customizable, self-documenting real-time display editor.

The file INSTALL in this directory says how to build and install GNU Emacs on various systems, once you have unpacked or checked out the entire Emacs file tree.

See the file etc/NEWS for information on new features and other user-visible changes in recent versions of Emacs.

The file etc/PROBLEMS contains information on many common problems that occur in building, installing and running Emacs.

The file CONTRIBUTE contains information on contributing to Emacs as a developer.

You may encounter bugs in this release. If you do, please report them; your bug reports are valuable contributions to the FSF, since they allow us to notice and fix problems on machines we don't have, or in code we don't use often. Please send bug reports to the mailing list bug-gnu-emacs@gnu.org. If possible, use M-x report-emacs-bug.

See the "Bugs" section of the Emacs manual for more information on how to report bugs. (The file 'BUGS' in this directory explains how you can find and read that section using the Info files that come with Emacs.) For a list of mailing lists related to Emacs, see https://savannah.gnu.org/mail/?group=emacs. For the complete list of GNU mailing lists, see https://lists.gnu.org/.

The 'etc' subdirectory contains several other files, named in capital letters, which you might consider looking at when installing GNU Emacs.

The file 'configure' is a shell script to acclimate Emacs to the oddities of your processor and operating system. It creates the file 'Makefile' (a script for the 'make' program), which automates the process of building and installing Emacs. See INSTALL for more detailed information.

The file 'configure.ac' is the input used by the autoconf program to construct the 'configure' script.

The shell script 'autogen.sh' generates 'configure' and other files by running Autoconf (which in turn uses GNU m4), and configures files in the .git subdirectory if you are using Git. If you want to use it, you will need to install recent versions of these build tools. This should be needed only if you edit files like 'configure.ac' that specify Emacs's autobuild procedure.

The file 'Makefile.in' is a template used by 'configure' to create 'Makefile'.

The file 'make-dist' is a shell script to build a distribution tar file from the current Emacs tree, containing only those files appropriate for distribution. If you make extensive changes to Emacs, this script will help you distribute your version to others.

There are several subdirectories:

'src' holds the C code for Emacs (the Emacs Lisp interpreter and its primitives, the redisplay code, and some basic editing functions). 'lisp' holds the Emacs Lisp code for Emacs (most everything else). 'leim' holds the original source files for the generated files in lisp/leim. These form the library of Emacs input methods, required to type international characters that can't be directly produced by your keyboard. 'lib' holds source code for libraries used by Emacs and its utilities 'lib-src' holds the source code for some utility programs for use by or with Emacs, like movemail and etags. 'lwlib' holds the sources of the Lucid Widget Library used on X. 'oldXMenu' source files from X11R2 XMenu library, used in non-toolkit builds. 'etc' holds miscellaneous architecture-independent data files Emacs uses, like the tutorial text and tool bar images. The contents of the 'lisp', 'leim', 'info', and 'doc' subdirectories are architecture-independent too. 'info' holds the Info documentation tree for Emacs. 'doc/emacs' holds the source code for the Emacs Manual. If you modify the manual sources, you will need the 'makeinfo' program to produce an updated manual. 'makeinfo' is part of the GNU Texinfo package; you need a suitably recent version of Texinfo. 'doc/lispref' holds the source code for the Emacs Lisp reference manual. 'doc/lispintro' holds the source code for the Introduction to Programming in Emacs Lisp manual. 'msdos' holds configuration files for compiling Emacs under MS-DOS. 'nextstep' holds instructions and some other files for compiling the Nextstep port of Emacs, for GNUstep and macOS Cocoa. 'nt' holds code and documentation for building Emacs on MS-Windows. 'test' holds tests for various aspects of Emacs's functionality. 'modules' holds the modhelp.py helper script. 'admin' holds files used by Emacs developers, and Unicode data files. 'build-aux' holds auxiliary files used during the build. 'm4' holds Autoconf macros used for generating the configure script. 'java' holds the Java code for the Emacs port to Android. 'cross' holds Makefiles and an additional copy of gnulib used to build Emacs for Android devices. 'exec' holds the source code to several helper executables used to run user-installed programs on Android.

Building Emacs on non-Posix platforms requires tools that aren't part of the standard distribution of the OS. The platform-specific README files and installation instructions should list the required tools.

NOTE ON COPYRIGHT YEARS

In copyright notices where the copyright holder is the Free Software Foundation, then where a range of years appears, this is an inclusive range that applies to every year in the range. For example: 2005-2008 represents the years 2005, 2006, 2007, and 2008.

This file is part of GNU Emacs.

GNU Emacs is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

GNU Emacs is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with GNU Emacs. If not, see https://www.gnu.org/licenses/.

emacs-lsp/lsp-ui

UI integrations for lsp-mode

lsp-ui

Table of Contents

lsp-ui

Intro

This package contains all the higher level UI modules of lsp-mode, like flycheck support and code lenses.

By default, lsp-mode automatically activates lsp-ui unless lsp-auto-configure is set to nil.

You only have to put (use-package lsp-ui) in your config and the package will work out of the box. (use-package)

Or use the builtin package manager.

M-x package-install [RET] lsp-ui [RET]

lsp-ui-sideline:

Show informations of the symbols on the current line. It also show flycheck diagnostics and LSP code actions

Customization:

lsp-ui-sideline-show-diagnostics show diagnostics messages in sideline
lsp-ui-sideline-show-hover show hover messages in sideline
lsp-ui-sideline-show-code-actions show code actions in sideline
lsp-ui-sideline-update-mode When set to 'line' the information will be updated when user changes current line otherwise the information will be updated when user changes current point
lsp-ui-sideline-delay seconds to wait before showing sideline
lsp-ui-sideline-diagnostic-max-lines default to showing only the first line of diagnostic messages, increase for more verbose messages, decrease if flickering occurs

lsp-ui-peek:

Add peek feature

You may remap xref-find-{definitions,references} (bound to M-. M-? by default):

(define-key lsp-ui-mode-map [remap xref-find-definitions] #'lsp-ui-peek-find-definitions)
(define-key lsp-ui-mode-map [remap xref-find-references] #'lsp-ui-peek-find-references)

There is a window-local jump list dedicated to cross references:

(lsp-ui-peek-jump-backward)
(lsp-ui-peek-jump-forward)

Other cross references:

(lsp-ui-peek-find-workspace-symbol "pattern 0")
;; If the server supports custom cross references
(lsp-ui-peek-find-custom 'base "$cquery/base")

Customization:

lsp-ui-peek-enable enable ‘lsp-ui-peek’
lsp-ui-peek-show-directory show the directory of files

lsp-ui-doc

Show object documentation at point in a child frame.

Show documentation in a WebKit widget

Focus into lsp-ui-doc-frame

Customization:

lsp-ui-doc-enable Enable lsp-ui-doc
lsp-ui-doc-position Where to display the doc (top, bottom or at-point)
lsp-ui-doc-side Where to display the doc (left or right)
lsp-ui-doc-delay Number of seconds before showing the doc
lsp-ui-doc-show-with-cursor When non-nil, move the cursor over a symbol to show the doc
lsp-ui-doc-show-with-mouse When non-nil, move the mouse pointer over a symbol to show the doc

lsp-ui-imenu

Show imenu entries.

Customization:

lsp-ui-imenu-kind-position place to show entries kind
lsp-ui-imenu-buffer-position place to show the buffer window
lsp-ui-imenu-window-width set window width
lsp-ui-imenu-window-fix-width when non-nil, the window will not be resizable (eg. unaffected by balance-windows)
lsp-ui-imenu--custom-mode-line-format mode line format
lsp-ui-imenu-auto-refresh auto refresh when necessary
lsp-ui-imenu-refresh-delay delay to refresh imenu

Contributing

Any kind of help is appreciated. If you want to help us maintaining this package, leave a note.

qjcg/awesome-typst

Awesome Typst Links

English | 简体中文

Awesome Typst

Curated collection of useful links for Typst users.

Contributions are welcome!

Official Project Links

typst.app - The Typst web app
Typst Documentation
GitHub
Blog
Social - Discord Instagram LinkedIn Mastodon Bluesky

Typst Community Links

#typst:matrix.org - Matrix room for Typst.
Typst Examples Book - An online book with Typst snippets, including extended tutorial and useful hacks.
Typst Japanese Community - Typst Japanese community docs and resources.
Typst-telegram-russian-chat - Chat about Typst in Telegram in russian
best-of-typst - A ranked list of awesome projects related to Typst.
Typst Reddit Commuity - An English speaking subreddit about Typst
Nonsense - Funny and visually stunning generator of random fake math papers.

Integrations & Tools

Browser Extensions

(FireFox) bib-kit - Retrieve website information to create citations in the hayagriva format
(FireFox) yank - Yank URL and title of current tab, format to a chosen markup language, and copy to clipboard (supports typst link format)

Chatbots

typst-bot - A discord bot to render Typst code
typst-bot-telegram - A telegram bot to render Typst code
typst-telegram-bot - A telegram bot with focus in rendering math expression in Typst.

CI/CD

gitlab-ci-typst - Build Typst documents using GitLab CI pipelines
setup-typst - 📑 Install Typst for use in GitHub Actions
typst-action - Build Typst documents using GitHub actions

CLI Tools

em-dee-pdf - Markdown to PDF converter with 18 built-in themes, LaTeX math, syntax highlighting, and table of contents.
typstyle - Opinionated typst code formatter focusing on aesthetic, convergence and correctness.
typst-live - Hot reloading of pdf in web browser
typst-pandoc - Typst custom reader and writer for Pandoc
Tylax - A bidirectional LaTeX-Typst converter based on AST parsing, with support for TikZ graphics.
utpm - Package manager for local and remote Typst packages.
Tyler - Package compiler for the ease of packaging and publishing Typst libraries and templates.
textlint-plugin-typst - textlint plugin to lint Typst

Editors

Katvan - A bare-bones editor for Typst files, with a bias for Right-to-Left editing.
Typstwriter - An integrated desktop editor for typst projects.
BeauTyXT - A private, secure, minimalistic Text, Markdown, and Typst editor for Android
AcademicID - A self-hosted academic-focused AI chatbot and research workspace with a Typst, Markdown, and Text editor.
TypstEdit - A native MacOS Typst editor
Typesetter - A minimalist, local-first Typst editor for Linux
typos - A Typst-native note-taking system powered by Rust and Tauri with typed metadata, cross-references, backlinks, and knowledge graph visualization.

Editor Integrations

SeniorMars/tree-sitter-typst - A TreeSitter parser for the Typst File Format
Tinymist VS Code Extension - A vscode extension for Tinymist integration
Tinymist - A language server for typst with integrations for Emacs, Helix, NeoVim, Sublime Text, VsCode/VsCodium, and Zed
Typst Sync - A vscode extension for Typst local packages management and synchronization.
frozolotl/tree-sitter-typst - A tree-sitter grammar with a focus on correctness.
inktyp - An Inkscape plugin to insert and edit Typst equations
obsidian-typst - Renders typst code blocks in Obsidian into images using Typst through the power of WASM!
org-typst-preview - Typst preview in org-mode
typstar - Neovim plugin providing autosnippets, excalidraw integration and [standalone] Anki flashcard export
typst-conceal.vim - Vim/Nvim plugin for replacing long typst symbol names with unicode characters
typst-math - A VS Code extension to simplify math writing in Typst
typst-sympy-calculator - VS Code extension for Typst math calculating, includes Arithmetic, Calculus, Matrix, Custom Variances and Functions by yourself
typst-ts-mode - Typst tree sitter major mode for Emacs
typst.nvim - WIP. Goals: Treesitter highlighting, snippets, and a smooth integration with neovim
typst.vim - Vim plugin for Typst
typstd - Yet another Typst language server.
uben0/tree-sitter-typst - A TreeSitter grammar for the Typst language, used by Helix
zeta - A language server for Zettelkasten-style note-taking, featuring fast navigation, and a graph view.

Online Tools

Detypify - Typst symbol classifier
online-typst-editor - A serverless (client-side) typst editor powered by WebAssembly (typst.ts)
excel-to-typst - A tool that convert Excel tables to Typst table, can work in uploading .xlsx file or pasting.

Office

pptypst - Bring the power of Typst to PowerPoint

Programming

Typix - Deterministic Typst compilation with Nix
Typstry.jl - The Julia to Typst interface
leetcode.typ - Solving Leetcode problems in Typst
mpl-typst - A Typst backend for Matplotlib.
pypst - Declarative Typst in Python with Pandas data frame support.
typst-py - Python binding to typst
typst-rb - Ruby binding to typst
typst.ts - JavaScript binding to typst

Typst As A Service

typst-http-api - An simple docker containing an API to compile typst markup
typst-telegram-bot - A plain and simple HTTP API for rendering math with Typst.

Templates & Libraries

Official

typst/templates - The templates that ship with the Typst web app

General

Data Thinking Report Template - a template for artificial intelligence whitepapers with collaborative bibliographies using Zotero
HSOS-PTP-Typst-Template - A German template for writing papers, overfitted for the Osnabrück University of Applied Scien
INSA Typst Template - A template for INSA (Institut National des Sciences Appliquées), a french public engineering school.
LaPreprint - Beautiful preprints for Typst
Mantys - A template for writing manuals for Typst packages.
Project-Report-Typst - A simple template for college or university level project report.
SimplePaper - A Chinese template for writing simple paper
Typst-Paper-Template - Typst template for Working Paper
aiaa-typst-template - A template for AIAA (American Institute of Aeronautics and Astronautics) papers.
bubble-template - A simple and colorful template for reports
french-association-status - A Template to write status for french associations.
gloss-awe - Automatically Generated Glossary Page (renamed from typst-glossary)
in-dexter - Automatically Generated Index Page (renamed from typst-index)
mcm-icm-typst-template - A template for Mathematical Contest in Modeling (MCM) and the Interdisciplinary Contest in Modeling(ICM).
simple-typst-thesis - A template useful for writing simple thesis in Typst
thesis-template-typst - Technical University of Munich thesis Template with cover, titlepage, tables, figures, appendix, etc.
tufte-typst - A Tufte-inspired template for Typst
tufte-memo - A memo document template inspired by the design of Edward Tufte's books.
typst-bioinfo-thesis - Flexible section headers and page numbers; pretty outlines and a wrapfig
klirr - Zero-maintenance and smart FOSS generating beautiful invoices for services and expenses.
typst-invoice - Generate invoices from TOML files
typst-mla9-template - An MLA 9th edition template
typst-orange-template - A Typst book template inspired by The Legrand Orange Book
typst-palettes - A library of color palettes for Typst
typst-templates - A templates collection for major venues in machine learning and AI.
typst-templates - Templates for Typst
typst-templates - My typst templates
typst-uwthesis - A typst template for writing thesis, featuring a working abbreviation lists.
typstry - A Tapestry of Typst Templates & Examples
writable-gm-screen-inserts - Writable Game Master Screen Insertsces

Assignments

OpenBoard - Easily build clean assessments in the style of the College Board.
assignment-template - A simple assignment template
sheetstorm - A template for assignment sheets
typst-assignment-template - Yet another simple assignment template
typst-assignment-template - Yet another simple assignment template with a cover and several useful math symbols.
typst-homework-template - A simple homework template inspired by the LaTeX homework template by Adam Blank
typst-teacher-template - A collection of typst templates. Mainly used to create worksheets and exams for my classes.
tinyset - A lightweight and opinionated problem set package designed with pure math proofs in mind.

CV

Examples

bare-bones-cv – A single-page minimalistic CV comprising essentials only.
cv.typ - A no-frills curriculum vitae (CV) template for Typst that uses a YAML file for data input in order to version control CV data easily.
chicv - A minimal and fully-customizable CV template.

Templates

NNJR - A resume template inspired by Jake's Resume LaTeX template. Uses Typst and YAML.
alta-typst - A simple Typst CV template, inspired by AltaCV by LianTze Lim
attractive-typst-resume - A modern looking, attractive CV/Resume template by Harkunwar Kochar
billryan-typst - A simple and minimalist resume template, inspired by Resume by Billryan.
brilliant-CV - Another CV template for your job application, yet powered by Typst and more
caidan - A clean and minimal food menu template.
cv.typ - A no-frills curriculum vitae (CV) template using Typst and YAML to version control CV data.
friggeri-cv - A slightly modified version of the Friggeri CV, originally created by Adrien Friggeri in LaTeX, ported to Typst.
modern-cv - A modern resume and coverletter template based on Awesome CV
modern-typst-template - A modern resume/CV template.
moderncv.typst - A CV template inspired by LaTeX's moderncv
resume.typ - Simple and ergonomic template to generate resume and CV
typst-academic-cv - Typst Template for Academic CV
typst-blue-header-cv - Customizable Typst two-columns CV template with a top header.
typst-cv-miku - A simple, elegant, academic style CV template for typst. Support for English and Chinese (and more)
typst-cv-resume - A CV template with Sans font inspired by LaTeX Deedy-Resume
typst-cv-template1 - A CV template inspired by Alessandro Plasmati's Graduate CV LaTex template
typst-cv-template - A CV template inspired by LaTeX's Awesome CV
typst-cv-template - Chi CV Template (For Typst)
typst-mixed-resume - A casual and elegant resume template inspired by multiple templates.
typst-neat-cv - A Typst template for modern, minimal and elegant CVs, inspired by mintyfrankie's Brilliant CV
typst-resume-sans - A sleek and unadorned sans-serif resume template.
typst-resume-template - Aesthetic style inspired by the Awesome-CV project
typst-resume-template - A pretty resume template designed using typst.
typst-twentysecondcv - A CV template inspired by LaTeX's Twenty Seconds Resume/CV
typst-yaml-cv - A simple cv template designed using typst and yaml.
vercanard - A colorful resume template for Typst
typst-resume-template - Modern, minimalist resume design with Typst

Calendar / Timetable

typst-timetable - A template for timetables
october - A simple printable month calendar

Footnotes & Endnotes

notes.typ - A library for notes with deduplication and customizability.

Formatting

metro - A typst package to add typsetting to units!
ruby-typ - A library to add ruby text
showybox - A Typst package for creating colorful and customizable boxes.
simple-poem-typst - An application of the measure function to set Arabic poetry.
syntastica-typst - Tree-sitter syntax highlighting for code blocks.
term - A Typst package for creating figures that emulate terminal screenshots.
typst-ansi_render - A library to render text with ANSI escape sequences
typst-boxes - A library to draw colorful boxes.
typst-codelst - A Typst package to render source code.
typst-diagbox - A library for diagonal line dividers in Typst tables
typst-gentle-clues - A typst package to simply add admonitions.
typst-tablem - Write markdown-like tables easily.
typst-tablex - More powerful and customizable tables in Typst!

Graphics

CeTZ - CeTZ (CeTZ, ein Typst Zeichenpacket) is a library for drawing with Typst with an API inspired by TikZ and Processing. It comes with modules for drawing plots, graphs and charts.
typst-raytracer - raytracer in typst

Letters

typst-letter-pro - DIN 5008 letter template for Typst
typst-letter - A typst letter template inspired by the DIN 5008 norm
typst-letter-template - A customizable typst letter template with different presets (DIN 5008, Swiss C5)

Linguistics

eggs - Linguistics examples and glosses with minimalist syntax
leipzig-gloss - A library that provides primitives for creating glossing rules according to Leipzig.
typst-ipa - 🔄 ASCII / IPA conversion for Typst
tyipa - Write phonetic transcriptions using the IPA, in a typsty style.
typst-dictionary-template - 📕 a template for lexical dictionary/glossary in Typst
arborly - A library for producing beautiful syntax tree graphs
typst-syntree - Syntax trees for typst
linphon - Set phonological feature matrices, linear rewrite rules, and more

Music

conchord - Typst package to easily write lyrics with chords and generate colorful fretboard diagrams
typst-chords - A library to write song lyrics with chord diagrams in Typst

Plotting

typst-cd - Proof of Concept for tikz-like commutative diagrams
typst-plot - A library for plotting line charts (deprecated in favor of CeTZ)
typst-plotting - A library for drawing a variety of charts and plots like line charts, histograms, and pie charts

Posters

typst-poster - An academic poster template
peace-of-posters - A package for creating academic posters in block style

Science, Technology, Engineering & Math (STEM)

Chemistry

alchemist - Render skeletal formulas in a human-readable format using cetz.
typsium - Typeset chemical formulas and reactions.

Engineering

circuitypst - A library for drawing electronic circuit schematics
typst-bytefield - A library for drawing (network) protocol headers
tids - A TI-style datasheet template for electronic component

Mathematics

commute - A library for creating commutative diagrams
typst-algorithms - A library for writing algorithms
typst-himcm-template - An HiMCM template for Typst
typst-math-template - A simple math template that allows for numbered, referenceable theorems and compilation of subfiles that use references.
typst-pf3 - A small package for creating "structured proofs." Essentially a port of Leslie Lamport's pf2.sty
typst-theorems - A library for creating numbered theorem environments
typst-undergradmath - A Typst port of undergradmath

Physics

physica - A library for usual physics notations, e.g. vectors and vector fields, matrices, differentials, derivatives, Dirac brackets, tensors, isotopes, and digital signal sequences.

Conferences

aiaa-typst - A template for creating conference papers in the style of the American Institute of Aeronautics and Astronautics.
cogsci-conference - Official template for the Cognitive Science Society (CogSci) Conference Proceedings.
ieee-conference-typst-template A template to write IEEE Conference in Typst.
ieee-typst-template - A template to write IEEE Papers in Typst
ifacconf-typst - A template for creating conference papers in the style of the International Federation of Automatic Control

Journals

ieee-trans-typst - A template that mimic LaTeX IEEE Transaction template (ieee-trans.cls)

Grants/Proposals

typst-nsf-templates - National Science Foundation (NSF) general template and outlines for popular proposal types.

Scripting

typst-oxifmt - Convenient Rust-like string formatting in Typst
typst-tools4typst - Tools for package and template authors.

Slides

diapo - A minimal and simplistic presentation template.
polylux - Create presentation slides in Typst
clean-polylux-typst - A clean and dynamic polylux presentation slide template
pinit - Pin things as you like, especially useful for creating slides in typst.
touying - A powerful package for creating presentation slides in Typst

purcell/exec-path-from-shell

Make Emacs use the $PATH set up by the user's shell

exec-path-from-shell

A GNU Emacs library to ensure environment variables inside Emacs look the same as in the user's shell.

Motivation

Ever find that a command works in your shell, but not in Emacs?

This happens a lot on OS X, where an Emacs instance launched as a GUI app inherits a default minimal set of environment variables that are probably not the ones you see in a terminal window. Similarly, if you start Emacs as a daemon from systemd or launchd, it will run with a default set of environment variables.

This library solves this problem by copying important environment variables from the user's shell: it works by asking your shell to print out the variables of interest, then copying them into the Emacs environment.

Compatibility

Supported shells:

zsh
bash
tcsh
fish
nu

Note that shell variables which have not been exported as environment variables (e.g. using the "export" keyword) may not be visible to exec-path-from-shell.

If you experience issues, enable the variable exec-path-from-shell-debug before runnin functions from the package: this will produce detailed logging in *Messages* about the shell command line and output.

Installation

Installable packages are available via MELPA: do M-x package-install RET exec-path-from-shell RET.

Alternatively, download the latest release or clone the repository, and install exec-path-from-shell.el with M-x package-install-file.

Usage

Add the following to your init.el (after calling package-initialize):

(when (memq window-system '(mac ns x))
  (exec-path-from-shell-initialize))

This sets $MANPATH, $PATH and exec-path from your shell, but only when executed in a GUI frame on OS X and Linux.

If you launch Emacs as a daemon from systemd or similar, you might like to use the following snippet:

(when (daemonp)
  (exec-path-from-shell-initialize))

You can copy values of other environment variables by customizing exec-path-from-shell-variables before invoking exec-path-from-shell-initialize, or by calling exec-path-from-shell-copy-env, e.g.:

(exec-path-from-shell-copy-env "PYTHONPATH")

This function may also be called interactively.

The author uses the following configuration snippet before calling exec-path-from-shell-initialize:

(require 'exec-path-from-shell)
(dolist (var '("SSH_AUTH_SOCK" "SSH_AGENT_PID" "GPG_AGENT_INFO" "LANG" "LC_CTYPE" "NIX_SSL_CERT_FILE" "NIX_PATH"))
  (add-to-list 'exec-path-from-shell-variables var))

Setting up your shell startup files correctly

Note that your shell will inherit Emacs's environment variables when it is run by exec-path-from-shell -- to avoid surprises your config files should therefore set the environment variables to their exact desired final values, i.e. don't do this:

export PATH=/usr/local/bin:$PATH

but instead do this:

export PATH=/usr/local/bin:/usr/bin:/bin

To be safe, exec-path-from-shell starts an interactive (and login) shell by default, but this can be much slower than necessary. Interactive shells often have fancy features enabled that are only helpful when one interacts directly with the shell, and this can frequently cause startup time to exceed 750ms. This can be avoided:

Follow best practice by setting your environment variables so that they are available to both interactive and non-interactive shells. In practical terms, for most people this means setting them in ~/.profile, ~/.bash_profile, ~/.zshenv instead of ~/.bashrc and ~/.zshrc.
Once a non-interactive shell sets your environment variables correctly, adjust exec-path-from-shell-arguments appropriately (often to nil) before calling exec-path-from-shell-initialize so that it will start a non-interactive shell.

To learn more about how popular shells load start-up files, read this helpful article.

Making `exec-path-from-shell` faster

If evaluation takes more than exec-path-from-shell-warn-duration-millis (500ms by default) then exec-path-from-shell will print a warning.

Non-interactive shells start up faster. Follow the steps in the section above so that you can run your shell without -i and still get the right environment variable settings. When "-i" is then removed from exec-path-from-shell-arguments, this package becomes more efficient.
Invoking the shell has a non-trivial overhead in any case. Don't call exec-path-from-shell-copy-env repeatedly, since each invocation starts a shell. Instead, set exec-path-from-shell-variables to the full list of vars you want, and call exec-path-from-shell-initialize once.

Further help

C-h f exec-path-from-shell-initialize
C-h f exec-path-from-shell-copy-env

💝 Support this project and my other Open Source work via Patreon

💼 LinkedIn profile

✍ sanityinc.com

dominikh/go-mode.el

Emacs mode for the Go programming language

This is go-mode, the Emacs mode for editing Go code.

It is a complete rewrite of the go-mode that shipped with Go 1.0.3 and before, and was part of Go 1.1 until Go 1.3. Beginning with Go 1.4, editor integration will not be part of the Go distribution anymore, making this repository the canonical place for go-mode.

Features

In addition to normal features, such as fontification and indentation, and close integration with familiar Emacs functionality (for example syntax-based navigation like beginning-of-defun), go-mode comes with the following extra features to provide an improved experience:

Integration with gofmt by providing a command of the same name, and gofmt-before-save, which can be used in a hook to format Go buffers before saving them.
- Setting the gofmt-command variable also allows using goimports.
- Setting the gofmt-args variable with a list of arguments allows using e.g. gofmt -s.
Integration with godoc via the functions godoc and godoc-at-point.
Integration with the Playground
- go-play-buffer and go-play-region to send code to the Playground
- go-download-play to download a Playground entry into a new buffer
Managing imports
- A function for jumping to the file's imports (go-goto-imports - C-c C-f i)
- A function for adding imports, including tab completion (go-import-add, bound to C-c C-a)
- It is recommended that you use goimports or the organize-imports feature of gopls to manage adding/removing/organizing imports automatically.
Integration with godef
- godef-describe (C-c C-d) to describe expressions
- godef-jump (C-c C-j) and godef-jump-other-window (C-x 4 C-c C-j) to jump to declarations
- This requires you to install godef via go install github.com/rogpeppe/godef@latest.
Basic support for imenu (functions and variables)
Built-in support for displaying code coverage as calculated by go test (go-coverage)
Several functions for jumping to and manipulating the individual parts of function signatures. These functions support anonymous functions, but are smart enough to skip them when required (e.g. when jumping to a method receiver or docstring.)
- Jump to the argument list (go-goto-arguments - C-c C-f a)
- Jump to the docstring, create it if it does not exist yet (go-goto-docstring - C-c C-f d).
- Jump to the function keyword (go-goto-function - C-c C-f f)
- Jump to the function name (go-goto-function-name - C-c C-f n)
- Jump to the return values (go-goto-return-values - C-c C-f r)
- Jump to the method receiver, adding a pair of parentheses if no method receiver exists (go-goto-method-receiver - C-c C-f m).
All of these functions accept a prefix argument (C-u), causing them to skip anonymous functions.

Installation

MELPA

The recommended way of installing go-mode is via ELPA, the Emacs package manager, and the MELPA Stable repository, which provides an up-to-date version of go-mode.

If you're not familiar with ELPA yet, consider reading this guide.

Manual

To install go-mode manually, check out the go-mode.el repository in a directory of your choice, add it to your load path and configure Emacs to automatically load it when opening a .go file:

(add-to-list 'load-path "/place/where/you/put/it/")
(autoload 'go-mode "go-mode" nil t)
(add-to-list 'auto-mode-alist '("\\.go\\'" . go-mode))

Either evaluate the statements with C-x C-e, or restart Emacs.

Other extensions

There are several third party extensions that can enhance the Go experience in Emacs.

Gopls integration

Gopls is the official language server protocol (lsp) implementation provided by the Go team. It is intended to replace the existing third party tools for code formatting (gofmt), automatic imports (goimports), code navigation (godef/guru), type and function descriptions (godoc/godef), error checking, auto completion (gocode), variable and type renaming (rename), and more. Once gopls is stable the older tools will no longer be supported.

Gopls is a supported backend for lsp-mode. It will be used automatically by lsp-mode if gopls is found in your PATH. You can install gopls via: go install golang.org/x/tools/gopls@latest. To enable lsp-mode for go buffers:

(add-hook 'go-mode-hook 'lsp-deferred)

Syntax/error checking

There are two ways of using flymake with Go:

goflymake, which internally uses go build to capture all errors that a regular compilation would also produce
flymake-go for a more lightweight solution that only uses gofmt and as such is only able to catch syntax errors. Unlike goflymake, however, it does not require an additional executable.

Additionally, there is flycheck, a modern replacement for flymake, which comes with built-in support for Go. In addition to using go build or gofmt, it also has support for go vet, golint and errcheck.

Auto completion

For auto completion, take a look at gocode.

eldoc

https://github.com/syohex/emacs-go-eldoc provides eldoc functionality for go-mode.

Snippets

I maintain a set of YASnippet snippets for go-mode at https://github.com/dominikh/yasnippet-go

Integration with errcheck

https://github.com/dominikh/go-errcheck.el provides integration with errcheck.

Stability

go-mode.el has regular, tagged releases and is part of the MELPA Stable repository. These tagged releases are intended to provide a stable experience. APIs added in tagged releases will usually not be removed or changed in future releases.

Changes made on the master branch, which is tracked by the normal MELPA repository, however, are under active development. New APIs are experimental and may be changed or removed before the next release. Furthermore, there is a higher chance for bugs.

If you want a stable experience, use MELPA Stable. If you want cutting edge features, or "beta-test" future releases, use MELPA or the master branch.

emacs-lsp/lsp-mode

Emacs client/library for the Language Server Protocol

title: LSP Mode - Language Server Protocol support for Emacs description: Language Server Protocol support with multiple languages support for Emacs root_file: README.md

Language Server Protocol Support for Emacs

homepage • installation • languages • settings • tutorials • troubleshooting • screenshots • FAQ

Why?

❤️ Community Driven
💎 Fully featured - supports all features in Language Server Protocol v3.14.
🚀 Fast - see performance section.
🌟 Flexible - choose between full-blown IDE with flashy UI or minimal distraction free.
⚙️ Easy to configure - works out of the box and automatically upgrades if additional packages are present.

Overview

Client for Language Server Protocol (v3.14). lsp-mode aims to provide IDE-like experience by providing optional integration with the most popular Emacs packages like company, flycheck and projectile.

Non-blocking asynchronous calls
Real-time Diagnostics/linting via flycheck (recommended) or flymake when Emacs > 26 (requires flymake>=1.0.5)
Code completion - company-capf / completion-at-point (note that company-lsp is no longer supported).
Hovers - using lsp-ui
Code actions - via lsp-execute-code-action, modeline (recommended) or lsp-ui sideline.
Code outline - using builtin imenu or helm-imenu
Code navigation - using builtin xref, lsp-treemacs tree views or lsp-ui peek functions.
Code lens
Symbol highlights
Formatting
Project errors on modeline
Debugger - dap-mode
Breadcrumb on headerline
Helm integration - helm-lsp
Ivy integration - lsp-ivy
Consult integration - consult-lsp
Treemacs integration - lsp-treemacs
Semantic tokens as defined by LSP 3.17 (compatible language servers include recent development builds of clangd and rust-analyzer)
which-key integration for better discovery
iedit
dired
ido

Presentations/demos

System Crafters channel Emacs IDE Videos
skybert's emacsconf presentation (Java)
thatwist's ScalaUA Conference presentation (Scala)

Contributions

Contributions are very much welcome!

NOTE Documentation for clients is generated from doc comments in the clients themselves (see lsp-doc.el) and some metadata (see lsp-clients.json) so please submit corrections accordingly.

Support the project

The emacs-lsp organization has more than 20,000 lines of code, to keep all of this working, we need to implement new features and help the community on a lot of issues.

You can help us keep going and improving it by supporting the project

Members

Here is a list of the current lsp-mode members and what they are primarily working on/responsible for.

_totbwf F#	_brotzeit Rust	_dsyzling Scala	_kurnevsky Scala \| Rust	_seagle0128 Go \| Python MS
_{sebastiansturm} lsp-mode core \| C++	_vibhavp lsp-mode core	_yyoncho lsp-mode core \| Java	_ericdallo Dart/Flutter \| Clojure	_danielmartin C++ \| Swift
_kiennq completions \| pwsh	_nbfalcon lsp-mode core \| iedit	_psibi Terraform \| Nix	_razzmatazz C# \| F#	_jcs090218 lsp-mode core

justbur/emacs-which-key

Emacs package that displays available keybindings in popup

which-key [[https://elpa.gnu.org/packages/which-key.html][https://elpa.gnu.org/packages/which-key.svg]] [[http://melpa.org/#/which-key][http://melpa.org/packages/which-key-badge.svg]] [[http://stable.melpa.org/#/which-key][file:http://stable.melpa.org/packages/which-key-badge.svg]]

** ARCHIVE NOTICE

which-key is now included in the master branch of Emacs and will likely be released with Emacs v30. Bug reports and contributions to which-key will now be considered through standard Emacs channels, and this repository is being archived.

** Introduction =which-key= is a minor mode for Emacs that displays the key bindings following your currently entered incomplete command (a prefix) in a popup. For example, after enabling the minor mode if you enter =C-x= and wait for the default of 1 second the minibuffer will expand with all of the available key bindings that follow =C-x= (or as many as space allows given your settings). This includes prefixes like =C-x 8= which are shown in a different face. Screenshots of what the popup will look like are included below. =which-key= started as a rewrite of [[https://github.com/kai2nenobu/guide-key][guide-key-mode]], but the feature sets have diverged to a certain extent.

** Table of Contents :TOC_3:

[[#which-key][which-key]]
- [[#archive-notice][ARCHIVE NOTICE]]
- [[#introduction][Introduction]]
- [[#install][Install]]
  - [[#melpa][MELPA]]
  - [[#manually][Manually]]
- [[#initial-setup][Initial Setup]]
  - [[#side-window-bottom-option][Side Window Bottom Option]]
  - [[#side-window-right-option][Side Window Right Option]]
  - [[#side-window-right-then-bottom][Side Window Right then Bottom]]
  - [[#minibuffer-option][Minibuffer Option]]
- [[#manual-activation][Manual Activation]]
- [[#additional-commands][Additional Commands]]
- [[#special-features-and-configuration-options][Special Features and Configuration Options]]
  - [[#popup-type-options][Popup Type Options]]
  - [[#custom-string-replacement-options][Custom String Replacement Options]]
  - [[#sorting-options][Sorting Options]]
  - [[#paging-options][Paging Options]]
  - [[#face-customization-options][Face Customization Options]]
  - [[#other-options][Other Options]]
- [[#support-for-third-party-libraries][Support for Third-Party Libraries]]
  - [[#key-chord][Key-chord]]
  - [[#evil-operators][Evil operators]]
  - [[#god-mode][God-mode]]
- [[#more-examples][More Examples]]
  - [[#nice-display-with-split-frame][Nice Display with Split Frame]]
- [[#known-issues][Known Issues]]
- [[#thanks][Thanks]]

** Install *** MELPA After setting up [[http://melpa.org][MELPA]] as a repository, use =M-x package-install which-key= or your preferred method. You will need to call =which-key-mode= to enable the minor mode of course.

*** Manually Add which-key.el to your =load-path= and require. Something like #+BEGIN_SRC emacs-lisp (add-to-list 'load-path "path/to/which-key.el") (require 'which-key) (which-key-mode) #+END_SRC

** Initial Setup No further setup is required if you are happy with the default setup. To try other options, there are 3 choices of default configs that are preconfigured (then customize to your liking). The main choice is where you want the which-key buffer to display. Screenshots of the default options are shown in the next sections.

In each case, we show as many key bindings as we can fit in the buffer within the constraints. The constraints are determined by several factors, including your Emacs settings, the size of the current Emacs frame, and the which-key settings, most of which are described below.

There are many substitution abilities included, which are quite flexible (ability to use regexp for example). This makes which-key very customizable.

*** Side Window Bottom Option Popup side window on bottom. This is the current default. To restore this setup use

#+BEGIN_SRC emacs-lisp

(which-key-setup-side-window-bottom) #+END_SRC

[[./img/which-key-bottom.png]]

*** Side Window Right Option Popup side window on right. For defaults use

#+BEGIN_SRC emacs-lisp

(which-key-setup-side-window-right) #+END_SRC

Note the defaults are fairly conservative and will tend to not display on
narrower frames. If you get a message saying which-key can't display the
keys, try making your frame wider or adjusting the defaults related to the
maximum width (see =M-x customize-group which-key=).

[[./img/which-key-right.png]]

*** Side Window Right then Bottom This is a combination of the previous two choices. It will try to use the right side, but if there is no room it will switch to using the bottom, which is usually easier to fit keys into. This setting can be helpful if the size of the Emacs frame changes frequently, which might be the case if you are using a dynamic/tiling window manager.

#+BEGIN_SRC emacs-lisp
(which-key-setup-side-window-right-bottom)
#+END_SRC

*** Minibuffer Option Take over the minibuffer. For the recommended configuration use

#+BEGIN_SRC emacs-lisp
(which-key-setup-minibuffer)
#+END_SRC

[[./img/which-key-minibuffer.png]]

Note the maximum height of the minibuffer is controlled through the built-in
variable =max-mini-window-height=. Also, the paging commands do not work
reliably with the minibuffer option. Use the side window on the bottom
option if you need paging.

** Manual Activation #+NAME: #manual-activation If you only want the =which-key= popup when you need it, you can try a setup along the following lines

#+BEGIN_SRC emacs-lisp ;; Allow C-h to trigger which-key before it is done automatically (setq which-key-show-early-on-C-h t) ;; make sure which-key doesn't show normally but refreshes quickly after it is ;; triggered. (setq which-key-idle-delay 10000) (setq which-key-idle-secondary-delay 0.05) (which-key-mode) #+END_SRC

This will prevent which-key from showing automatically, and allow you to use =C-h= in the middle of a key sequence to show the =which-key= buffer and keep it open for the remainder of the key sequence.

** Additional Commands

=which-key-show-top-level= will show most key bindings without a prefix. It is most and not all, because many are probably not interesting to most users.
=which-key-show-major-mode= will show the currently active major-mode bindings. It's similar to =C-h m= but in a which-key format. It is also aware of evil commands defined using =evil-define-key=.
=which-key-show-next-page-cycle= / =which-key-show-previous-page-cycle= will flip pages in a circle.
=which-key-show-next-page-no-cycle= / =which-key-show-previous-page-no-cycle= will flip pages and stop at first/last page.
=which-key-undo= can be used to undo the last keypress when in the middle of a key sequence.

** Special Features and Configuration Options There are more options than the ones described here. All of the configurable variables are available through =M-x customize-group which-key=. *** Popup Type Options There are three different popup types that which-key can use by default to display the available keys. The variable =which-key-popup-type= decides which one is used. **** minibuffer #+BEGIN_SRC emacs-lisp (setq which-key-popup-type 'minibuffer) #+END_SRC Show keys in the minibuffer. **** side window #+BEGIN_SRC emacs-lisp (setq which-key-popup-type 'side-window) #+END_SRC Show keys in a side window. This popup type has further options: #+BEGIN_SRC emacs-lisp ;; location of which-key window. valid values: top, bottom, left, right, ;; or a list of any of the two. If it's a list, which-key will always try ;; the first location first. It will go to the second location if there is ;; not enough room to display any keys in the first location (setq which-key-side-window-location 'bottom)

 ;; max width of which-key window, when displayed at left or right.
 ;; valid values: number of columns (integer), or percentage out of current
 ;; frame's width (float larger than 0 and smaller than 1)
 (setq which-key-side-window-max-width 0.33)

 ;; max height of which-key window, when displayed at top or bottom.
 ;; valid values: number of lines (integer), or percentage out of current
 ;; frame's height (float larger than 0 and smaller than 1)
 (setq which-key-side-window-max-height 0.25)
 #+END_SRC

**** frame

 #+BEGIN_SRC emacs-lisp
 (setq which-key-popup-type 'frame)
 #+END_SRC
 Show keys in a popup frame. This popup won't work very well in a terminal,
 where only one frame can be shown at any given moment. This popup type has
 further options:
 #+BEGIN_SRC emacs-lisp
 ;; max width of which-key frame: number of columns (an integer)
 (setq which-key-frame-max-width 60)

 ;; max height of which-key frame: number of lines (an integer)
 (setq which-key-frame-max-height 20)
 #+END_SRC

**** custom Write your own display functions! This requires you to write three functions, =which-key-custom-popup-max-dimensions-function=, =which-key-custom-show-popup-function=, and =which-key-custom-hide-popup-function=. Refer to the documentation for those variables for more information, but here is a working example (this is the current implementation of side-window bottom).

 #+BEGIN_SRC emacs-lisp
   (setq which-key-popup-type 'custom)
   (defun which-key-custom-popup-max-dimensions-function (ignore)
     (cons
      (which-key-height-or-percentage-to-height
       which-key-side-window-max-height)
      (frame-width)))
   (defun fit-horizonatally ()
     (let ((fit-window-to-buffer-horizontally t))
       (fit-window-to-buffer)))
   (defun which-key-custom-show-popup-function (act-popup-dim)
     (let* ((alist '((window-width . fit-horizontally)
                     (window-height . fit-window-to-buffer))))
       (if (get-buffer-window which-key--buffer)
           (display-buffer-reuse-window which-key--buffer alist)
         (display-buffer-in-major-side-window which-key--buffer
                                              'bottom 0 alist))))
   (defun which-key-custom-hide-popup-function ()
     (when (buffer-live-p which-key--buffer)
       (quit-windows-on which-key--buffer)))
 #+END_SRC

*** Custom String Replacement Options #+NAME: #custom-string-replacement-options You can customize the way the keys show in the buffer using three different replacement methods. The first, keymap-based replacement, is preferred and will take precedence over the others. The remaining methods are still available, because they pre-date the first and are more flexible in what they can accomplish.

**** Keymap-based replacement Using this method, which-key can display a custom string for a key definition in some keymap. There are two ways to define a keymap-based replacement. The preferred way is to use =define-key= (or a command that uses =define-key= internally) with a cons cell as the definition. For example,

 #+BEGIN_SRC emacs-lisp
   (define-key some-map "f" '("foo" . command-foo))
   (define-key some-map "b" '("bar-prefix" . (keymap)))
   (setq my-map (make-sparse-keymap))
   (define-key some-map "b" (cons "bar-prefix" my-map))
 #+END_SRC

 binds =command-foo= to =f= in =some-map=, but also stores the string "foo"
 which which-key will extract to use to describe this command. The second
 example binds an empty keymap to =b= in =some-map= and uses "bar-prefix" to
 describe it. The last two lines replicate the functionality of the second
 line, while assigning the new keymap to the symbol =my-map= (note the use
 of =cons= to ensure that =my-map= is evaluated for =define-key=). These
 bindings are accepted by =define-key= natively (i.e., with or without
 which-key being loaded). Since many key-binding utilities use =define-key=
 internally, this functionality should be available with your favorite
 method of defining keys as well.

 The second method is to use =which-key-add-keymap-based-replacements=. The
 statement

 #+BEGIN_SRC emacs-lisp
   (define-key some-map "f" 'long-command-name-foo)
   (define-key some-map "b" some-prefix-map)
   (which-key-add-keymap-based-replacements some-map
     "f" '("foo" . long-command-name-foo)
     "b" '("bar-prefix" . (keymap)))
 #+END_SRC

 uses =define-key= to add two bindings and tells which-key to use the string
 "foo" in place of "command-foo" and the string "bar-prefix" for an empty
 prefix map. =which-key-add-keymap-based-replacements= just uses
 =define-key= to bind (or rebind) the command.

 There are other methods of telling which-key to replace command names,
 which are described next. The keymap-based replacements should be the most
 performant since they use built-in functionality of emacs. However, the
 alternatives can be more flexible in telling which-key how and when to
 replace text. They can be used simultaneously, but which-key will give
 precedence to the keymap-based replacement when it exists.

**** Key-Based replacement Using this method, the description of a key is replaced using a string that you provide. Here's an example

 #+BEGIN_SRC emacs-lisp
 (which-key-add-key-based-replacements
   "C-x C-f" "find files")
 #+END_SRC

 where the first string is the key combination whose description you want to
 replace, in a form suitable for =kbd=. For that key combination, which-key
 overwrites the description with the second string, "find files". In the
 second type of entry you can restrict the replacements to a major-mode. For
 example,

 #+BEGIN_SRC emacs-lisp
 (which-key-add-major-mode-key-based-replacements 'org-mode
   "C-c C-c" "Org C-c C-c"
   "C-c C-a" "Org Attach")
 #+END_SRC

 Here the first entry is the major-mode followed by a list of the first type
 of entries. In case the same key combination is listed under a major-mode
 and by itself, the major-mode version takes precedence.

**** Key and Description replacement

 The second and third methods target the text used for the keys and the
 descriptions directly. The relevant variable is
 =which-key-replacement-alist=.  Here's an example of one of the default key
 replacements

 #+BEGIN_SRC emacs-lisp
 (push '(("<\\([[:alnum:]-]+\\)>" . nil) . ("\\1" . nil))
       which-key-replacement-alist)
 #+END_SRC

 Each element of the outer cons cell is a cons cell of the form =(KEY
 . BINDING)=. The =car= of the outer cons determines how to match key
 bindings while the =cdr= determines how those matches are replaced. See the
 docstring of =which-key-replacement-alist= for more information.

 The next example shows how to replace the description.

 #+BEGIN_SRC emacs-lisp
 (push '((nil . "left") . (nil . "lft")) which-key-replacement-alist)
 #+END_SRC

 Here is an example of using key replacement to include Unicode characters
 in the results. Unfortunately, using Unicode characters may upset the
 alignment of the which-key buffer, because Unicode characters can have
 different widths even in a monospace font and alignment is based on
 character width.

 #+BEGIN_SRC emacs-lisp
 (add-to-list 'which-key-replacement-alist '(("TAB" . nil) . ("↹" . nil)))
 (add-to-list 'which-key-replacement-alist '(("RET" . nil) . ("⏎" . nil)))
 (add-to-list 'which-key-replacement-alist '(("DEL" . nil) . ("⇤" . nil)))
 (add-to-list 'which-key-replacement-alist '(("SPC" . nil) . ("␣" . nil)))
 #+END_SRC

 The =cdr= may also be a function that receives a =cons= of the form =(KEY
 . BINDING)= and produces a =cons= of the same form. This allows for
 interesting ideas like this one suggested by [[https://github.com/pdcawley][@pdcawley]] in [[https://github.com/justbur/emacs-which-key/pull/147][PR #147]].

 #+BEGIN_SRC emacs-lisp
 (push (cons '(nil . "paredit-mode")
             (lambda (kb)
               (cons (car kb)
                     (if paredit-mode
                         "[x] paredit-mode"
                       "[ ] paredit-mode"))))
       which-key-replacement-alist)
 #+END_SRC

 The box will be checked if =paredit-mode= is currently active.

*** Sorting Options By default the output is sorted by the key in a custom order. The default order is to sort lexicographically within each "class" of key, where the classes and their order are

=Special (SPC, TAB, ...) < Single Character (ASCII) (a, ...) < Modifier (C-, M-, ...) < Other=

You can control the order by setting this variable. This also shows the
other available options.

#+BEGIN_SRC emacs-lisp
;; default
(setq which-key-sort-order 'which-key-key-order)
;; same as default, except single characters are sorted alphabetically
;; (setq which-key-sort-order 'which-key-key-order-alpha)
;; same as default, except all prefix keys are grouped together at the end
;; (setq which-key-sort-order 'which-key-prefix-then-key-order)
;; same as default, except all keys from local maps shown first
;; (setq which-key-sort-order 'which-key-local-then-key-order)
;; sort based on the key description ignoring case
;; (setq which-key-sort-order 'which-key-description-order)
#+END_SRC

*** Paging Options

There are at least several prefixes that have many keys bound to them, like
=C-x=. which-key displays as many keys as it can given your settings, but
for these prefixes this may not be enough. The paging feature gives you the
ability to bind a key to the function =which-key-C-h-dispatch= which will
allow you to cycle through the pages without changing the key sequence you
were in the middle of typing. There are two slightly different ways of doing
this.

**** Method 1 (default): Using C-h (or =help-char=) This is the easiest way, and is turned on by default. Use #+BEGIN_SRC emacs-lisp (setq which-key-use-C-h-commands nil) #+END_SRC to disable the behavior (this will only take effect after toggling which-key-mode if it is already enabled). =C-h= can be used with any prefix to switch pages when there are multiple pages of keys. This changes the default behavior of Emacs which is to show a list of key bindings that apply to a prefix. For example, if you were to type =C-x C-h= you would get a list of commands that follow =C-x=. This uses which-key instead to show those keys, and unlike the Emacs default saves the incomplete prefix that you just entered so that the next keystroke can complete the command.

 The commands are:
 - Cycle through the pages forward with =n= (or =C-n=)
 - Cycle backwards with =p= (or =C-p=)
 - Undo the last entered key (!) with =u= (or =C-u=)
 - Call the default command bound to =C-h=, usually
   =describe-prefix-bindings=, with =h= (or =C-h=)

This is especially useful for those who like =helm-descbinds= but also want to use =C-h= as their which-key paging key.

Note =C-h= is by default equivalent to =?= in this context.

Note also that using =C-h= will not work with the =C-h= prefix, unless you make further adjustments. See Issues [[https://github.com/justbur/emacs-which-key/issues/93][#93]] and [[https://github.com/justbur/emacs-which-key/issues/175][#175]] for example.

**** Method 2: Bind your own keys

 Essentially, all you need to do for a prefix like =C-x= is the following
 which will bind =<f5>= to the relevant command.

 #+BEGIN_SRC emacs-lisp

(define-key which-key-mode-map (kbd "C-x ") 'which-key-C-h-dispatch) #+END_SRC

 This is completely equivalent to

 #+BEGIN_SRC emacs-lisp

(setq which-key-paging-prefixes '("C-x")) (setq which-key-paging-key " ") #+END_SRC

 where the latter are provided for convenience if you have a lot of
 prefixes.

*** Face Customization Options The faces that which-key uses are | Face | Applied To | Default Definition | |----------------------------------------+-------------------------------+-------------------------------------------------------------| | =which-key-key-face= | Every key sequence | =:inherit font-lock-constant-face= | | =which-key-separator-face= | The separator (→) | =:inherit font-lock-comment-face= | | =which-key-note-face= | Hints and notes | =:inherit which-key-separator-face= | | =which-key-special-key-face= | User-defined special keys | =:inherit which-key-key-face :inverse-video t :weight bold= | | =which-key-group-description-face= | Command groups (i.e, keymaps) | =:inherit font-lock-keyword-face= | | =which-key-command-description-face= | Commands not in local-map | =:inherit font-lock-function-name-face= | | =which-key-local-map-description-face= | Commands in local-map | =:inherit which-key-command-description-face= |

The last two deserve some explanation. A command lives in one of many possible
keymaps. You can distinguish between local maps, which depend on the buffer you
are in, which modes are active, etc., and the global map which applies
everywhere. It might be useful for you to distinguish between the two. One way
to do this is to remove the default face from
=which-key-command-description-face= like this

#+BEGIN_SRC emacs-lisp

(set-face-attribute 'which-key-command-description-face nil :inherit nil) #+END_SRC

another is to make the local map keys appear in bold

#+BEGIN_SRC emacs-lisp

(set-face-attribute 'which-key-local-map-description-face nil :weight 'bold) #+END_SRC

You can also use =M-x customize-face= to customize any of the above faces to
your liking.

*** Other Options #+NAME: #other-options The options below are also available through customize. Their defaults are shown.

#+BEGIN_SRC emacs-lisp
  ;; Set the time delay (in seconds) for the which-key popup to appear. A value of
  ;; zero might cause issues so a non-zero value is recommended.
  (setq which-key-idle-delay 1.0)

  ;; Set the maximum length (in characters) for key descriptions (commands or
  ;; prefixes). Descriptions that are longer are truncated and have ".." added.
  ;; This can also be a float (fraction of available width) or a function.
  (setq which-key-max-description-length 27)

  ;; Use additional padding between columns of keys. This variable specifies the
  ;; number of spaces to add to the left of each column.
  (setq which-key-add-column-padding 0)

  ;; The maximum number of columns to display in the which-key buffer. nil means
  ;; don't impose a maximum.
  (setq which-key-max-display-columns nil)

  ;; Set the separator used between keys and descriptions. Change this setting to
  ;; an ASCII character if your font does not show the default arrow. The second
  ;; setting here allows for extra padding for Unicode characters. which-key uses
  ;; characters as a means of width measurement, so wide Unicode characters can
  ;; throw off the calculation.
  (setq which-key-separator " → " )
  (setq which-key-unicode-correction 3)

  ;; Set the prefix string that will be inserted in front of prefix commands
  ;; (i.e., commands that represent a sub-map).
  (setq which-key-prefix-prefix "+" )

  ;; Set the special keys. These are automatically truncated to one character and
  ;; have which-key-special-key-face applied. Disabled by default. An example
  ;; setting is
  ;; (setq which-key-special-keys '("SPC" "TAB" "RET" "ESC" "DEL"))
  (setq which-key-special-keys nil)

  ;; Show the key prefix on the left, top, or bottom (nil means hide the prefix).
  ;; The prefix consists of the keys you have typed so far. which-key also shows
  ;; the page information along with the prefix.
  (setq which-key-show-prefix 'left)

  ;; Set to t to show the count of keys shown vs. total keys in the mode line.
  (setq which-key-show-remaining-keys nil)
#+END_SRC

** Support for Third-Party Libraries Some support is provided for third-party libraries which don't use standard methods of looking up commands. Some of these need to be enabled explicitly. This code includes some hacks, so please report any problems. *** Key-chord Enabled by default. *** Evil operators Evil motions and text objects following an operator like =d= are not all looked up in a standard way. Support is controlled through =which-key-allow-evil-operators= which should be non-nil if evil is loaded before which-key and through =which-key-show-operator-state-maps= which needs to be enabled explicitly because it is more of a hack. The former allows for the inner and outer text object maps to show, while the latter shows motions as well. *** God-mode Call =(which-key-enable-god-mode-support)= after loading god-mode to enable support for god-mode key sequences. This is new and experimental, so please report any issues. ** More Examples *** Nice Display with Split Frame Unlike guide-key, which-key looks good even if the frame is split into several windows. #+CAPTION: which-key in a frame with 3 horizontal splits [[./img/which-key-right-split.png]]

#+CAPTION: which-key in a frame with 2 vertical splits
[[./img/which-key-bottom-split.png]]

** Known Issues

A few users have reported crashes related to which-key popups when quitting a key sequence with =C-g=. A possible fix is discussed in [[https://github.com/justbur/emacs-which-key/issues/130][this issue]]. ** Thanks Special thanks to
[[https://github.com/bmag][@bmag]] for helping with the initial development and finding many bugs.
[[https://github/iqbalansari][@iqbalansari]] who among other things adapted the code to make =which-key-show-top-level= possible.

doomemacs/themes

A megapack of themes for GNU Emacs.

Doom Emacs' Theme Pack

A theme megapack for GNU Emacs, inspired by community favorites. Special attention is given for Doom Emacs and solaire-mode support, but will work fine anywhere else.

See the screenshots.

Install

Doom Emacs

The built-in :ui doom module installs and configures doom-themes for you, and loads doom-one by default. To change the theme, change doom-theme:

;; in ~/.doom.d/config.el
(setq doom-theme 'doom-city-lights)

Manually + `use-package`

doom-themes is available on MELPA. Here is an example configuration with some common defaults laid out:

(use-package doom-themes
  :ensure t
  :custom
  ;; Global settings (defaults)
  (doom-themes-enable-bold t)   ; if nil, bold is universally disabled
  (doom-themes-enable-italic t) ; if nil, italics is universally disabled
  ;; for treemacs users
  (doom-themes-treemacs-theme "doom-atom") ; use "doom-colors" for less minimal icon theme
  :config
  (load-theme 'doom-one t)

  ;; Enable flashing mode-line on errors
  (doom-themes-visual-bell-config)
  ;; Enable custom neotree theme (nerd-icons must be installed!)
  (doom-themes-neotree-config)
  ;; or for treemacs users
  (doom-themes-treemacs-config)
  ;; Corrects (and improves) org-mode's native fontification.
  (doom-themes-org-config))

Theme list

This megapack's first and flagship theme is doom-one (inspired by Atom One Dark), but also includes 67 themes submitted to us by the Emacs community. We welcome PRs to help us maintain and address inconsistencies in them.

Name	Source	Description
doom-1337	link	ported from VSCode's 1337 theme (ported by @ccmywish)
doom-acario-dark	original	an original dark theme (ported by @gagbo)
doom-acario-light	original	an original light theme (ported by @gagbo)
doom-ayu-dark	link	inspired by Ayu Dark (ported by @ashton)
doom-ayu-light	link	inspirted by Ayu Light (ported by @LoveSponge)
doom-ayu-mirage	link	inspired by Ayu Mirage (ported by @LoveSponge)
doom-badger	link	inspired by cann's Badger colorscheme (ported by @jsoa)
doom-bluloco-dark	link	ported from VSCode's Bluloco Dark (ported by @RazikSF)
doom-bluloco-light	link	ported from VSCode's Bluloco Light (ported by @RazikSF)
doom-challenger-deep	link	inspired by Vim's Challenger Deep theme (ported by @fuxialexander)
doom-city-lights	link	inspired by Atom's City Lights theme (ported by @fuxialexander)
doom-dark+	n/a	ported from equinusocio's VSCode Theme, dark+ (ported by @ema2159)
doom-dracula	link	inspired by the popular Dracula theme (ported by @fuxialexander)
doom-earl-grey	original	a gentle color scheme, for code (ported by @JuneKelly)
doom-ephemeral	link	inspired by the Ephemeral Theme from elenapan's dotfiles (ported by @karetsu)
doom-fairy-floss	link	a candy colored theme by sailorhg (ported by @ema2159)
doom-feather-dark	original	a candy colored theme by sailorhg (ported by @Plunne)
doom-feather-light	original	a candy colored theme by sailorhg (ported by @Plunne)
doom-flatwhite	link	inspired by Atom's Flatwhite Syntax theme (ported by @JuneKelly)
doom-gruvbox	link	inspired by morhetz's Gruvbox (ported by @JongW)
doom-gruvbox-light	link	inspired by morhetz's Gruvbox (light) (ported by @jsoa)
doom-henna	link	based on VSCode's Henna theme (ported by @jsoa)
doom-homage-black	original	a minimalistic, colorless theme inspired by eziam, tao, and jbeans (ported by @mskorzhinskiy)
doom-homage-white	original	minimal white theme inspired by editors from 2000s (ported by @mskorzhinskiy)
doom-horizon	link	ported from VSCode Horizon (ported by @karetsu)
doom-Iosvkem	link	ported from the default dark theme for Adobe Brackets (ported by @neutaaaaan)
doom-ir-black	link	ported from Vim's ir_black colorscheme (ported by @legendre6891)
doom-lantern	link	based on Gitleptune's Lantern theme (ported by @paladhammika)
doom-laserwave	link	a clean synthwave/outrun theme inspired by VSCode's Laserwave (ported by @hyakt)
doom-manegarm	original	an original autumn-inspired dark theme (ported by @kenranunderscore)
doom-material	link	adapted from equinusocio's Material themes (ported by @tam5)
doom-material-dark	link	inspired by Material Theme by xrei (ported by @trev-dev)
doom-meltbus	link	a dark (mostly) monochromatic theme (ported by @spacefrogg)
doom-miramare	link	a port of Franbach's Miramare theme; a variant of Grubox (ported by @sagittaros)
doom-molokai	link	inspired by Tomas Restrepo's Molokai (ported by @hlissner)
doom-monokai-classic	link	port of Monokai Classic (ported by @ema2159)
doom-monokai-machine	link	port of Monokai Classic (ported by @minikN)
doom-monokai-octagon	link	port of Monokai Octagon (ported by @minikN)
doom-monokai-pro	link	Port of Monokai Pro (ported by @minikN)
doom-monokai-ristretto	link	Port of Monokai Ristretto (ported by @minikN)
doom-monokai-spectrum	link	port of Monokai Spectrum (ported by @minikN)
doom-moonlight	link	inspired by VS code's Moonlight (ported by @Brettm12345)
doom-nord	link	dark variant of Nord (ported by @fuxialexander)
doom-nord-aurora	link	a light variant of Nord (ported by @MoskitoHero)
doom-nord-light	link	light variant of Nord (ported by @fuxialexander)
doom-nova	link	inspired by Trevord Miller's Nova (ported by @bigardone)
doom-oceanic-next	link	inspired by Oceanic Next (ported by @juanwolf)
doom-oksolar-dark	link	an OKLab variant of Solarized dark (ported by logc)
doom-oksolar-light	link	an OKLab variant of Solarized light (ported by logc)
doom-old-hope	link	inspired by An Old Hope, in a galaxy far far away (ported by @teesloane)
doom-one	link	inspired by Atom One Dark (ported by @hlissner)
doom-one-light	link	inspired by Atom One Light (ported by @ztlevi)
doom-opera	original	an original light theme (ported by @jwintz)
doom-opera-light	original	an original light theme (ported by @jwintz)
doom-outrun-electric	link	a high contrast, neon theme inspired by Outrun Electric on VSCode (ported by @ema2159)
doom-palenight	link	adapted from equinusocio's Material themes (ported by @Brettm12345)
doom-peacock	link	inspired by daylerees' Peacock (ported by @teesloane)
doom-pine	link	a green-tinged Gruvbox (by @RomanHargrave)
doom-plain	link	inspired by gko's plain theme for VSCode (ported by @das-s)
doom-plain-dark	link	inspired by gko's plain theme for VSCode (ported by @das-s)
doom-rouge	link	ported from VSCode's Rouge Theme (ported by @das-s)
doom-shades-of-purple	link	a port of VSCode's Shades of Purple (ported by @jwbaldwin)
doom-snazzy	link	inspired by Hyper Snazzy (ported by @ar1a)
doom-solarized-dark	link	a dark variant of Solarized (ported by @ema2159)
doom-solarized-dark-high-contrast	link	a high-contrast variant of Solarized Dark (ported by @jmorag)
doom-solarized-light	link	a light variant of Solarized (ported by @fuxialexander)
doom-sourcerer	link	a port of xero's Sourcerer (ported by @fm0xb)
doom-spacegrey	link	I'm sure you've heard of it (ported by @teesloane)
doom-tokyo-night	link	inspired by VSCode's Tokyo Night theme (ported by @FosterHangdaan)
doom-tomorrow-day	link	a light variant of Tomorrow (ported by @emacswatcher)
doom-tomorrow-night	link	One of the dark variants of Tomorrow (ported by @hlissner)
doom-vibrant	doom-one	a more vibrant variant of doom-one (ported by @hlissner)
doom-wilmersdorf	link	port of Ian Pan's Wilmersdorf (ported by @ema2159)
doom-xcode	Xcode.app	based off of Apple's Xcode Dark Theme (ported by @kadenbarlow)
doom-zenburn	link	port of the popular Zenburn theme (ported by @jsoa)

Extensions

Check out the wiki for details on customizing our neotree/treemacs/etc extensions.

(doom-themes-visual-bell-config): flash the mode-line when the Emacs bell rings (i.e. an error occurs). May not be compatible with all mode line plugins.
(doom-themes-neotree-config): a neotree theme that takes after Atom's file drawer; a more minimalistic icon theme plus variable pitch file/directory labels, as seen in the doom-one screenshot.

(This requires nerd-icons' fonts to be installed: M-x nerd-icons-install-fonts)
(doom-themes-treemacs-config): two treemacs icon themes, one that takes after Atom's, and a second more colorful implementation.
(doom-themes-org-config): corrects and improves some of org-mode's native fontification issues.
- Re-set org-todo & org-headline-done faces to make them respect underlying faces (i.e. don't override the :height or :background of underlying faces).
- Make statistic cookies respect underlying faces.
- Fontify item bullets (make them stand out)
- Fontify item checkboxes (and when they're marked done), like TODOs that are marked done.
- Fontify dividers/separators (5+ dashes)
- Fontify #hashtags and @at-tags, for personal convenience; see doom-org-special-tags to disable this.

Complementary plugins

The following plugins complement our themes:

To get dimmed sidebars and brighter source buffers (like in the screenshots), see solaire-mode.
AnthonyDiGirolamo added doom-one (screenshot) and doom-molokai (screenshot) skins to airline-themes.
The modeline in the screenshots is doom-modeline.

Customization

There are three ways to customize themes in this package:

Explore the available variables provided by our themes, starting with the ones provided for all packages:
- doom-themes-enable-bold (default: t): if nil, disables bolding as much as possible (only affects faces that our theme supports; it won't catch them all).
- doom-themes-enable-italic (default: t): if nil, disables italicization as much as possible (only affects faces that our theme supports; it won't catch them all).
- doom-themes-padded-modeline (default: nil): if t, pad the mode-line in 4px on each side. Can also be set to an integer to specify the exact padding. or M-x customize-group RET doom-themes to explore them.

Use the custom-set-faces macro (Doom users should use custom-set-faces! instead) to customize any face. e.g.

;; Must be used *after* the theme is loaded
(custom-set-faces
  `(mode-line ((t (:background ,(doom-color 'dark-violet)))))
  `(font-lock-comment-face ((t (:foreground ,(doom-color 'base6))))))

Copy your favorite theme into your custom-theme-directory (normally ~/.emacs.d/, or ~/.doom.d/themes for Doom users), and tweak it there.

Contribute

PRs are welcome to maintain our themes, including additional theme and plugin support.

dgutov/diff-hl

Emacs package for highlighting uncommitted changes

About

diff-hl-mode highlights uncommitted changes on the side of the window, allows you to jump between and revert them selectively.

This feature is also known as "source control gutter indicators".

In buffers controlled by Git, you can stage and unstage the changes.

For the usage instructions and the list of commands, see the Commentary section inside the file.

Tested with Git, Mercurial, Bazaar and SVN. May work with other VC backends, too.

The package also contains auxiliary modes:

diff-hl-dired-mode provides similar functionality in Dired.
diff-hl-margin-mode changes the highlighting function to use the margin instead of the fringe.
But if you use a non-graphical terminal, the package will fall back to using the margins anyway, as long as diff-hl-fallback-to-margin is non-nil and the margin width is non-zero.
diff-hl-amend-mode sets the reference revision to the one before recent one. Also, you could use diff-hl-set-reference-rev to set it to any revision, see its docstring for details.
diff-hl-flydiff-mode implements highlighting changes on the fly.
diff-hl-show-hunk-mouse-mode makes fringe and margin react to mouse clicks to show the corresponding hunk. That's the alternative to using diff-hl-show-hunk and friends.

Usage

Put this into your init script:

(global-diff-hl-mode)

You must also ensure that VC is enabled (e.g. vc-handled-backends is not nil).

Check out the Commentary section in each file for more detailed usage instructions.

Screenshots

diff-hl-mode

Top window: a buffer in this minor mode, bottom window: the corresponding diff.

diff-hl-dired-mode

diff-hl-margin-mode

Requirements

Emacs 26.1+.

Notes

By default diff-hl-mode only updates the display when the buffer is in saved state. For a different tradeoff, also enable diff-hl-flydiff-mode, which makes the updates happen on a timer.
To use an alternative diff algorithm with Git, add a corresponding argument to vc-git-diff-switches, e.g. (setq vc-git-diff-switches '("--histogram")). Using the diff.algorithm option doesn't work because vc-git-diff calls git diff-index. diff-hl-flydiff-mode does not support alternative algorithms, because it uses the external diff program.
We conflict with other modes when they put indicators on the fringe, such as Flycheck. This is rarely a significant problem, since if you're using such a mode, you'd usually want to fix all errors and warnings before continuing, and then the conflicting indicators go away.
There's no fringe when Emacs is running in the console, but the navigation and revert commands still work. Consider turning diff-hl-margin-mode on, to show the indicators in the margin instead. It also helps avoid the conflict with Flycheck/Flymake even on graphical frames.
Frame-local and buffer-local values of line-spacing are not supported.
Fringe width up to 16 works best (because we can't define a bitmap with width above that number).

Integration

If you're using some package other than vc to commit changes, it might not run vc-checkin-hook after commits. In that case, you'll need to either add diff-hl-update to the hook it does run, or advise some function that's called in the buffer after its state has changed.

psvn

(advice-add 'svn-status-update-modeline :after #'diff-hl-update)

Magit

If you're using a version before 2.4.0, it defines magit-revert-buffer-hook (or magit-not-reverted-hook), which we use.

When using Magit 2.4 or newer, add this to your init script:

(add-hook 'magit-post-refresh-hook 'diff-hl-magit-post-refresh)

Tramp

diff-hl should just work with Tramp. But slow or high latency connections can cause performance problems. If you experience such issues, customize diff-hl-disable-on-remote to t. This will change the behavior of both turn-on-diff-hl-mode and global-diff-hl-mode (whichever you prefer to use).

_totbwf F#	_brotzeit Rust	_dsyzling Scala	_kurnevsky Scala \| Rust	_seagle0128 Go \| Python MS
_{sebastiansturm} lsp-mode core \| C++	_vibhavp lsp-mode core	_yyoncho lsp-mode core \| Java	_ericdallo Dart/Flutter \| Clojure	_danielmartin C++ \| Swift
_kiennq completions \| pwsh	_nbfalcon lsp-mode core \| iedit	_psibi Terraform \| Nix	_razzmatazz C# \| F#	_jcs090218 lsp-mode core