GitHub Emacs Lisp Weekly Trending Repositories

syl20bnr/spacemacs

A community-driven Emacs distribution - The best editor is neither Emacs nor Vim, it's Emacs *and* Vim!

Quick Start

If you don't have an existing Emacs setup and want to run Spacemacs as your configuration, and if you have all prerequisites installed, you can install Spacemacs with one line:

shell:

git clone https://github.com/syl20bnr/spacemacs "${HOME}/.emacs.d"

Windows PowerShell:

git clone https://github.com/syl20bnr/spacemacs "${HOME}/.emacs.d"

If HOME is not set in environment or in registry:

git clone https://github.com/syl20bnr/spacemacs "${env:APPDATA}/.emacs.d"

If you do have an existing Emacs configuration, look at the full installation instructions for other options.

Introduction

Spacemacs is a new way of experiencing Emacs -- it's a sophisticated and polished set-up, focused on ergonomics, mnemonics and consistency.

Just clone and launch it, then press the space bar to explore the interactive list of carefully-chosen key bindings. You can also press the home buffer's [?] button for some great first key bindings to try.

Spacemacs can be used naturally by both Emacs and Vim users -- you can even mix the two editing styles. Being able to quickly switch between input styles, makes Spacemacs a great tool for pair-programming.

Spacemacs is currently in beta, and any contributions are very welcome.

Features

Great documentation: access the Spacemacs documentation with SPC h SPC.
Beautiful GUI: you'll love the distraction free UI and its functional mode-line.
Excellent ergonomics: all the key bindings are accessible by pressing the SPC or Alt-m.
Mnemonic key bindings: commands have mnemonic prefixes like SPC b for all the buffer commands or SPC p for the project commands.
Batteries included: discover hundreds of ready-to-use packages nicely organized in configuration layers following a set of conventions .

Documentation

Comprehensive documentation is available for each layer by pressing SPC h SPC.

You can also check the general documentation, quick start guide and the FAQ.

Getting Help

If you need help, ask your questions in the Gitter Chat and a member of the community will help you out.

If you prefer IRC, connect to the Gitter Chat IRC server and join the #syl20bnr/spacemacs channel.

Last but not least there are a lot of high class tutorials available on YouTube:

Jack of Some's Spacemacs tutorial videos.
GDQuest's Game Design oriented tutorials to Spacemacs.
Practicalli's Clojure tutorials based on Spacemacs.
Eivind Fonn's classic Spacemacs ABC.

Prerequisites

A package manager if the OS doesn't have one already.
Spacemacs is an extension of a popular text editor called Emacs. So you'll need Emacs installed first.

Spacemacs requires Emacs 28.2 or above. The development version of Emacs is not officially supported, but it should nevertheless be expected to work.
git is required to download and update Spacemacs.
Tar, in particular GNU Tar, is required to install and update Emacs packages used by Spacemacs.
(Optional) The default font used by Spacemacs is Source Code Pro. You may customize your own font settings and choose another font. If you want to use this default font, it must be installed.

Spacemacs also uses fallback fonts to ensure certain Unicode symbols it uses symbols appear correctly. The fonts used are determined by the OS:
- Linux: Nanum Gothic
- macOS: Arial Unicode MS
- Windows: MS Gothic and Lucida Sans Unicode
If the mode-line doesn't look similar to the picture at the top of this page, make sure you have the correct fallback font installed.
(Optional) Various commands in Spacemacs needs one of the following line searching program:
- ripgrep (rg)
- The silver searcher (ag)
- ack
- GNU Grep or BSD Grep
Grep is very slow but it's widely available on most systems and is used as an fallback option.

We strongly recommend ripgrep over other line searching programs, for its blazing fast speed. The following subsections helps you to install it.

Linux

Most Linux distribution ships a package manager already and if this is the case you are all set for this step.

If it doesn't, you may need to build the softwares mentioned below from their sources.
In most distributions, Emacs is installed via an emacs package from the package manager.

N.B. DO not install XEmacs because it's not supported by Spacemacs. XEmacs is an old fork of Emacs with various subtle differences.

N.B. Some Linux distributions support only Emacs versions older than 28.2. In this case you should build it from source instead.
Very likely Git is already installed on your system. Otherwise, you should be able to install git from your system's package manager.
Very likely Tar is already installed on your system. Otherwise, you should be able to install tar from your system's package manager.
(Optional) If Nerd Fonts and Nanum Gothic are available from your distribution's package manager, you should install it there.

Otherwise, the generic way to install it is:
1. Download the latest pre-built TTF font from https://github.com/adobe-fonts/source-code-pro/releases/latest and https://fonts.google.com/specimen/Nanum+Gothic.
2. Extract the archive and move the font files to ~/.fonts.
3. Refresh font cache with:
```
fc-cache -fv
```
(Optional) If your distribution is listed here, follow the instructions. Otherwise, you can download its pre-built binary or build it from source.

macOS

The most popular package manager on macOS is Homebrew, to install it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Several options exist for installing Emacs on macOS:
1. Emacs Plus features additional functionalities over base Emacs.
```
brew tap d12frosted/emacs-plus

# install latest stable release, with Spacemacs icon and native compilation
brew install emacs-plus --with-spacemacs-icon --with-native-comp
```
  You will require the latest version of Xcode Command Line tools, which can be downloaded from the Apple Developer Portal or by running the following command:
```
softwareupdate --all --install --force
```
2. Emacs Mac Port adds native GUI support to Emacs 28. And the full list of features is available here.
```
brew tap railwaycat/emacsmacport
brew install emacs-mac
```
3. Emacs for Mac OS X is the binary build of GNU Emacs, without any extra feature.
```
brew install --cask emacs
```
To install git:
```
brew install git
```
macOS ships with BSD Tar, but there are reports of weird issues so we require GNU Tar instead.
```
brew install gnu-tar
```
(Optional) To install Source Code Pro Font:
```
brew tap homebrew/cask-fonts
brew install --cask font-source-code-pro
```
Arial Unicode MS is shipped with macOS v10.5 and later so you don't need to install it manually.
(Optional) You can install ripgrep via Homebrew:
```
brew install ripgrep
```

Windows

We recommend using wsl2 with wslg support especially with a pgtk build of emacs and wayland. For the installation please refer to the linux installation section. When running emacs within your wsl2 environment emacs will be handled like any other windows application.

If this is not possible you can fallback to a native windows installation, however note that this will create a lot of subtle bugs especially with tls which we will most likely not be able to help with.

If you need to follow that path we recommend to at least use a package manager like Scoop to install the needed packages.

You can install Scoop via PowerShell:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # Optional: Needed to run a remote script the first time
irm get.scoop.sh | iex

Emacs can be installed in PowerShell:

scoop bucket add extras
scoop install emacs

To install git in PowerShell:

scoop bucket add main
scoop install git

Windows 10 build 17063 and later ships with BSD Tar, but it's required to install GNU Tar instead to avoid possible issues. Alternatively, if you are running an earlier version of Windows, Tar isn't installed. In either case, you can install GNU Tar via:
```
scoop bucket add main
scoop install tar
```
To install Source Code Pro Font in PowerShell:
```
scoop bucket add KnotUntied_scoop-fonts https://github.com/KnotUntied/scoop-fonts
scoop install sourcecodepro
```
MS Gothic and Lucida Sans Unicode are shipped with Windows 2003 and later so you don't need to install it manually.
(Optional) You can install ripgrep in PowerShell:
```
scoop bucket add main
scoop install ripgrep
```

Install

Default Install

The default installation downloads Spacemacs to the .emacs.d directory in your HOME directory.

But in the case of Windows, HOME is not set out-of-box. We recommend you to set it as an environment variable, with the same value as environment variable HOMEPATH, which usually looks like C:\Users\<username>.

Since Spacemacs will now be downloaded at "${HOME}/.emacs.d", if it already exists it'll be overridden.

Also, if you have either "${HOME}/.emacs.el" or "${HOME}/.emacs", they will appear before Spacemacs in Emacs's initialization steps. Thus they must be renamed in order for Spacemacs to load correctly.

To backup/rename the aforementioned files/directory, in shell:

[ -d "${HOME}/.emacs.d" ] && mv "${HOME}/.emacs.d" "${HOME}/.emacs.d.bak"
[ -f "${HOME}/.emacs.el" ] && mv "${HOME}/.emacs.el" "${HOME}/.emacs.el.bak"
[ -f "${HOME}/.emacs" ] && mv "${HOME}/.emacs" "${HOME}/.emacs.bak"

or in PowerShell:

if( Test-Path -Path "${HOME}/.emacs.d" )
{
    Rename-Item "${HOME}/.emacs.d" "${HOME}/.emacs.d.bak"
}
if( Test-Path -Path "${HOME}/.emacs.el" )
{
    Rename-Item "${HOME}/.emacs.el" "${HOME}/.emacs.el.bak"
}
if( Test-Path -Path "${HOME}/.emacs" )
{
    Rename-Item "${HOME}/.emacs" "${HOME}/.emacs.bak"
}

Now clone this repository with Git. The following work for both shell and PowerShell:
```
git clone https://github.com/syl20bnr/spacemacs "${HOME}/.emacs.d"
```
In case you have a limited internet connection or limited speed:
```
git clone --depth 1 https://github.com/syl20bnr/spacemacs ~/.emacs.d
```
Now you can launch Emacs and Spacemacs will be loaded.

Alternative Install Location

To install Spacemacs in a different location, we first need to introduce how Spacemacs is loaded:

When Emacs is started, it looks for the init file in a deterministic way. The default installation exploits it by occupying "${HOME}/.emacs.d/init.el" and let Emacs use it as its init file.

In other word, in default installation, Emacs find and load "${HOME}/.emacs.d/init.el", which is then responsible to load other files in "${HOME}/.emacs.d".

If you want to install Spacemacs to a different location, you need to make sure it's loaded by Emacs in one of its init file.

For example, if you've cloned Spacemacs to "${HOME}/Spacemacs", and if you use "${HOME}/.emacs.el" as Emacs init file, then the following lines in "${HOME}/.emacs.el":

;; load Spacemacs's initialization file, "~" is equivalent to "${HOME}"
(load-file "~/Spacemacs/init.el")

First Launch and Configuration

After cloning Spacemacs, the first time when you launch Emacs, Spacemacs will automatically install the essential packages it requires. This step is the bootstrap.
Once the bootstrap packages are installed, Spacemacs checks whether you have an customization file "${HOME}/.spacemacs", known as dotspacemacs:
- If it already exists, Spacemacs loads it as the configuration.
- Otherwise, you need to answer a few questions and Spacemacs will generate the dotspacemacs file for you.
If you are new to Emacs and/or Spacemacs, it's fine to just accept the default choices. They can be changed in the dotspacemacs file later.
Spacemacs will download and install remaining packages it will require, according to your dotspacemacs. When the all the packages have been installed, restart Emacs to complete the installation.
dotspacemacs is the configuration file for Spacemacs, it's self explanatory and is written in Emacs Lisp. Read general documentation and quick start guide for more information.
In case you want to store your dotspacemacs at another location, say under "${HOME}/.spacemacs.d":
- First set the environment variable SPACEMACSDIR to "${HOME}/.spacemacs.d".
- Move "${HOME}/.spacemacs" to "${HOME}/.spacemacs.d/init.el".
In other word, set SPACEMACSDIR to the parent directory of your dotspacemacs, and move dotspacemacs to the said directory.

Spacemacs logo

For Linux users, create spacemacs.desktop in ~/.local/share/applications/ using this .desktop file as a reference. Change the Name parameter to Name=Spacemacs and the Icon parameter to Icon=/PATH/TO/EMACSD/core/banners/img/spacemacs.png where PATH/TO/EMACSD is the path to your .emacs.d directory, by default ~/.emacs.d.

For macOS users, you need to download the .icns version of the logo and simply change the logo on the Dock.

Notes

Depending on the installed version of GnuTLS, securely installing Emacs packages may fail. If this happens to you please update your OS and Emacs. If you are behind a company proxy please trust the company firewall cert. We do not longer support disabling https due to security reasons.
(Windows) If the following error occurs after starting Emacs:
```
The directory ~/.emacs.d/server is unsafe
```
Fix it by changing the owner of the directory ~/.emacs.d/server:
- From Properties select the Tab “Security”,
- Select the button “Advanced”,
- Select the Tab “Owner”
- Change the owner to your account name
Source: Stack Overflow
(Windows) The period (dot) before a file or folder name means that it's a hidden file or folder. To show hidden files and folders:
- Press the Windows key
- Type File explorer options
- Select the View tab at the top
- Check Show hidden files, folders and drives
- Click OK

Update

Spacemacs relies solely on a rolling update scheme based on the latest changes available. To update Spacemacs, simply pull the latest changes from the develop branch:

Close Emacs and update the git repository:
```
git pull --rebase
```
Restart Emacs to complete the upgrade.

After updating Spacemacs, you should also check if any updates are available for your packages. On the Spacemacs Home Buffer SPC b h, click (press RET) on the [Update Packages] button, or use the convenient keybinding SPC f e U

Upgrading from the deprecated `master` branch

If you are still on the old master branch (i.e., if git branch --show-current shows master instead of develop), you need to upgrade to develop first.

Quotes

Quote by ashnur:

«I feel that spacemacs is an aircraft carrier and I am playing table tennis
on the deck as a freerider.»

Quote by deuill:

«I LOVE SPACEMACS AND MAGIT

 That is all»

Contributions

Spacemacs is a community-driven project, it needs you to keep it up to date and to propose great and useful configurations for all the things!

Before contributing, be sure to consult the contribution guidelines and conventions.

Communities

Spacemacs Everywhere

Once you've learned the Spacemacs key bindings, you can use them in other IDEs/tools, thanks to the following projects:

Intellimacs - Spacemacs' like key bindings for IntelliJ platform
Spaceclipse - Spacemacs’ like key bindings for Eclipse
SpaceVim - A community-driven modular vim distribution
VSpaceCode - Spacemacs’ like key bindings for Visual Studio Code

License

The license is GPLv3 for all parts specific to Spacemacs, this includes:

the initialization and core files
all the layer files
the documentation

For the packages shipped in this repository, you can refer to the files header.

Spacemacs logo by Nasser Alshammari released under a Creative Commons Attribution-ShareAlike 4.0 International License.

Supporting Spacemacs

The best way to support Spacemacs is to contribute to it either by reporting bugs, helping the community on the Gitter Chat or sending pull requests.

You can show your love for the project by getting cool Spacemacs t-shirts, mugs and more in the Spacemacs Shop.

If you want to show your support financially, then you can contribute to Bountysource, or buy a drink for the maintainer by clicking on the Paypal badge.

If you used Spacemacs in a project, and you want to show that fact, you can use the Spacemacs badge:

For Markdown:

[![Built with Spacemacs](https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg)](https://spacemacs.org)

For HTML:

<a href="https://spacemacs.org"><img alt="Built with Spacemacs" src="https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg" /></a>

For Org-mode:

[[https://spacemacs.org][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]]

Thank you!

karthink/gptel

A simple, extensible LLM client for Emacs

#+title: gptel: A simple LLM client for Emacs

[[https://elpa.nongnu.org/nongnu/gptel.html][file:https://elpa.nongnu.org/nongnu/gptel.svg]] [[https://elpa.nongnu.org/nongnu-devel/gptel.html][file:https://elpa.nongnu.org/nongnu-devel/gptel.svg]] [[https://stable.melpa.org/#/gptel][file:https://stable.melpa.org/packages/gptel-badge.svg]] [[https://melpa.org/#/gptel][file:https://melpa.org/packages/gptel-badge.svg]]

gptel is a simple Large Language Model chat client for Emacs, with support for multiple models and backends. It works in the spirit of Emacs, available at any time and uniformly in any buffer.

General usage: ([[https://www.youtube.com/watch?v=bsRnh_brggM][YouTube Demo]])

https://user-images.githubusercontent.com/8607532/230516812-86510a09-a2fb-4cbd-b53f-cc2522d05a13.mp4

https://user-images.githubusercontent.com/8607532/230516816-ae4a613a-4d01-4073-ad3f-b66fa73c6e45.mp4

In-place usage

#+html:

https://github.com/user-attachments/assets/cec11aec-52f6-412e-9e7a-9358e8b9b1bf #+html:

Tool use

#+html:

https://github.com/user-attachments/assets/5f993659-4cfd-49fa-b5cd-19c55766b9b2 #+html:

#+html:

https://github.com/user-attachments/assets/8f57c20b-e1b0-4d86-b972-f46fb90ae1e7 #+html:

See also [[https://youtu.be/g1VMGhC5gRU][this youtube demo (2 minutes)]] by Armin Darvish.

Media support

#+html:

https://github.com/user-attachments/assets/1fd947e1-226b-4be2-bc68-7b22b2e3215f

#+html:

Multi-LLM support demo:

https://github-production-user-asset-6210df.s3.amazonaws.com/8607532/278854024-ae1336c4-5b87-41f2-83e9-e415349d6a43.mp4

Interact with LLMs from anywhere in Emacs (any buffer, shell, minibuffer, wherever).
LLM responses are in Markdown or Org markup.
Supports multiple independent conversations, one-off ad hoc interactions and anything in between.
Supports tool-use to equip LLMs with agentic capabilities.
Supports Model Context Protocol (MCP) integration using [[https://github.com/lizqwerscott/mcp.el][mcp.el]].
Supports multi-modal input (include images, documents).
Supports "reasoning" content in LLM responses.
Save chats as regular Markdown/Org/Text files and resume them later.
Edit your previous prompts or LLM responses when continuing a conversation. These will be fed back to the model.
Supports introspection, so you can see /exactly/ what will be sent. Inspect and modify queries before sending them.
Pause multi-stage requests at an intermediate stage and resume them later.
Don't like gptel's workflow? Use it to create your own for any supported model/backend with a [[https://github.com/karthink/gptel/wiki/Defining-custom-gptel-commands][simple API]].

gptel uses Curl if available, but falls back to the built-in url-retrieve to work without external dependencies.

** Contents :toc:

[[#installation][Installation]]
- [[#straight][Straight]]
- [[#manual][Manual]]
- [[#doom-emacs][Doom Emacs]]
- [[#spacemacs][Spacemacs]]
[[#setup][Setup]]
- [[#openai][OpenAI]]
- [[#other-llm-backends][Other LLM backends]]
  - [[#optional-securing-api-keys-with-authinfo][(Optional) Securing API keys with =authinfo=]]
  - [[#optional-reading-api-keys-from-environment-variables][(Optional) Reading API keys from environment variables]]
  - [[#openai-chatgpt-pluspro-subscription][OpenAI (ChatGPT plus/pro subscription)]]
  - [[#azure][Azure]]
  - [[#gpt4all][GPT4All]]
  - [[#ollama][Ollama]]
  - [[#open-webui][Open WebUI]]
  - [[#gemini][Gemini]]
  - [[#llamacpp-or-llamafile][Llama.cpp or Llamafile]]
  - [[#kagi-fastgpt--summarizer][Kagi (FastGPT & Summarizer)]]
  - [[#togetherai][together.ai]]
  - [[#anyscale][Anyscale]]
  - [[#perplexity][Perplexity]]
  - [[#anthropic-claude][Anthropic (Claude)]]
  - [[#groq][Groq]]
  - [[#mistral-le-chat][Mistral Le Chat]]
  - [[#openrouter][OpenRouter]]
  - [[#privategpt][PrivateGPT]]
  - [[#deepseek][DeepSeek]]
  - [[#sambanova-deepseek][Sambanova (Deepseek)]]
  - [[#cerebras][Cerebras]]
  - [[#github-models][Github Models]]
  - [[#novita-ai][Novita AI]]
  - [[#xai][xAI]]
  - [[#aiml-api][AI/ML API]]
  - [[#github-copilotchat][GitHub CopilotChat]]
  - [[#aws-bedrock][AWS Bedrock]]
  - [[#moonshot-kimi][Moonshot (Kimi)]]
[[#usage][Usage]]
- [[#in-any-buffer][In any buffer:]]
- [[#in-a-dedicated-chat-buffer][In a dedicated chat buffer:]]
  - [[#including-media-images-documents-or-plain-text-files-with-requests][Including media (images, documents or plain-text files) with requests]]
  - [[#save-and-restore-your-chat-sessions][Save and restore your chat sessions]]
- [[#setting-options-backend-model-request-parameters-system-prompts-and-more][Setting options (backend, model, request parameters, system prompts and more)]]
- [[#include-more-context-with-requests][Include more context with requests]]
- [[#handle-reasoning-content][Handle "reasoning" content]]
- [[#tool-use][Tool use]]
  - [[#defining-gptel-tools][Defining gptel tools]]
  - [[#selecting-tools][Selecting tools]]
  - [[#llm-tool-collections][LLM tool collections]]
  - [[#model-context-protocol-mcp-integration][Model Context Protocol (MCP) integration]]
- [[#rewrite-refactor-or-fill-in-a-region][Rewrite, refactor or fill in a region]]
- [[#extra-org-mode-conveniences][Extra Org mode conveniences]]
- [[#introspection-examine-debug-or-modify-requests][Introspection (examine, debug or modify requests)]]
[[#faq][FAQ]]
- [[#chat-buffer-ui][Chat buffer UI]]
  - [[#i-want-the-window-to-scroll-automatically-as-the-response-is-inserted][I want the window to scroll automatically as the response is inserted]]
  - [[#i-want-the-cursor-to-move-to-the-next-prompt-after-the-response-is-inserted][I want the cursor to move to the next prompt after the response is inserted]]
  - [[#i-want-to-change-the-formatting-of-the-prompt-and-llm-response][I want to change the formatting of the prompt and LLM response]]
  - [[#how-does-gptel-distinguish-between-user-prompts-and-llm-responses][How does gptel distinguish between user prompts and LLM responses?]]
- [[#transient-menu-behavior][Transient menu behavior]]
  - [[#i-want-to-set-gptel-options-but-only-for-this-buffer][I want to set gptel options but only for this buffer]]
  - [[#i-want-the-transient-menu-options-to-be-saved-so-i-only-need-to-set-them-once][I want the transient menu options to be saved so I only need to set them once]]
  - [[#using-the-transient-menu-leaves-behind-extra-windows][Using the transient menu leaves behind extra windows]]
  - [[#can-i-change-the-transient-menu-key-bindings][Can I change the transient menu key bindings?]]
  - [[#doom-emacs-sending-a-query-from-the-gptel-menu-fails-because-of-a-key-conflict-with-org-mode][(Doom Emacs) Sending a query from the gptel menu fails because of a key conflict with Org mode]]
- [[#miscellaneous][Miscellaneous]]
  - [[#i-want-to-use-gptel-in-a-way-thats-not-supported-by-gptel-send-or-the-options-menu][I want to use gptel in a way that's not supported by =gptel-send= or the options menu]]
  - [[#chatgpt-i-get-the-error-http2-429-you-exceeded-your-current-quota][(ChatGPT) I get the error "(HTTP/2 429) You exceeded your current quota"]]
  - [[#why-another-llm-client][Why another LLM client?]]
[[#additional-configuration][Additional Configuration]]
- [[#option-presets][Option presets]]
  - [[#applying-presets-to-requests-automatically][Applying presets to requests automatically]]
[[#alternatives][Alternatives]]
- [[#packages-using-gptel][Packages using gptel]]
[[#acknowledgments][Acknowledgments]]

** Installation

Note: gptel requires Transient 0.7.8 or higher. Transient is a built-in package and Emacs does not update it by default. Ensure that =package-install-upgrade-built-in= is true, or update Transient manually.

Release version: =M-x package-install= ⏎ =gptel= in Emacs.
Development snapshot: Add MELPA or NonGNU-devel ELPA to your list of package sources, then install with =M-x package-install= ⏎ =gptel=.
Optional: Install =markdown-mode=.

#+html:

*** Straight #+html:

#+begin_src emacs-lisp (straight-use-package 'gptel) #+end_src #+html:

#+html:

*** Manual #+html:

Clone or download this repository and run =M-x package-install-file⏎= on the repository directory. #+html:

#+html:

*** Doom Emacs #+html:

In =packages.el=

#+begin_src emacs-lisp (package! gptel :recipe (:nonrecursive t)) #+end_src

In =config.el=

#+begin_src emacs-lisp (use-package! gptel :config (setq! gptel-api-key "your key")) #+end_src

"your key" can be the API key itself, or (safer) a function that returns the key. Setting =gptel-api-key= is optional, you will be asked for a key if it's not found.

Alternatively, Doom Emacs provides a built-in =:tools llm= [[https://github.com/doomemacs/modules/tree/main/modules/tools/llm][module]] powered by gptel. Enable it in your =init.el= in the =doom!= block:

#+begin_src emacs-lisp (doom! :tools llm) #+end_src

This installs gptel with preconfigured keybindings (= o l=), magit integration for generating commit messages (=M-g= in commit buffers), and packages =gptel-quick= and =gptel-magit=. Run =doom/help-modules= (= h d m=) and select =:tools llm= for full documentation.

#+html:

*** Spacemacs #+html:

In your =.spacemacs= file, add =llm-client= to =dotspacemacs-configuration-layers=.

#+begin_src emacs-lisp (llm-client :variables llm-client-enable-gptel t) #+end_src #+html:

** Setup

gptel supports a number of LLM providers:

#+html:

| LLM Backend | Requires | |----------------------+----------------------------| | OpenAI | [[ https://platform.openai.com/account/api-keys][API key]] | | OpenAI subscription | ChatGPT plus/pro sub | | Anthropic (Claude) | [[ https://www.anthropic.com/api][API key]] | | Gemini | [[ https://makersuite.google.com/app/apikey][API key]] | | Ollama | [[ https://ollama.ai/][Ollama running locally]] | | Open WebUI | [[ https://openwebui.com/][Open WebUI running locally]] | | Llama.cpp | [[ https://github.com/ggml-org/llama.cpp/tree/master/tools/server#quick-start][Llama.cpp running locally]] | | Llamafile | [[ https://github.com/Mozilla-Ocho/llamafile#quickstart][Local Llamafile server]] | | GPT4All | [[ https://gpt4all.io/index.html][GPT4All running locally]] | | Kagi FastGPT | [[ https://kagi.com/settings?p=api][API key]] | | Kagi Summarizer | [[ https://kagi.com/settings?p=api][API key]] | | Azure | Deployment and API key | | Groq | [[ https://console.groq.com/keys][API key]] | | Mistral Le Chat | [[ https://console.mistral.ai/api-keys][API key]] | | Perplexity | [[ https://docs.perplexity.ai/docs/getting-started][API key]] | | OpenRouter | [[ https://openrouter.ai/keys][API key]] | | AI/ML API | [[ https://aimlapi.com/app/?utm_source=gptel&utm_medium=github&utm_campaign=integration][API key]] | | together.ai | [[ https://api.together.xyz/settings/api-keys][API key]] | | Anyscale | [[ https://docs.endpoints.anyscale.com/][API key]] | | PrivateGPT | [[ https://github.com/zylon-ai/private-gpt#-documentation][PrivateGPT running locally]] | | DeepSeek | [[ https://platform.deepseek.com/api_keys][API key]] | | Sambanova (Deepseek) | [[ https://cloud.sambanova.ai/apis][API key]] | | Cerebras | [[ https://cloud.cerebras.ai/][API key]] | | Github Models | [[ https://github.com/settings/tokens][Token]] | | Novita AI | [[ https://novita.ai/model-api/product/llm-api?utm_source=github_gptel&utm_medium=github_readme&utm_campaign=link][Token]] | | xAI | [[ https://console.x.ai?utm_source=github_gptel&utm_medium=github_readme&utm_campaign=link][API key]] | | GitHub CopilotChat | GitHub account | | Bedrock | AWS credentials | | Moonshot (Kimi) | API key ([[ https://platform.moonshot.cn/console][CN]] or [[ https://platform.moonshot.ai/console][Global]]) | #+html:

*** OpenAI Procure an [[https://platform.openai.com/account/api-keys][OpenAI API key]].

Optional: Set =gptel-api-key= to the key. Alternatively, you may choose a more secure method such as:

Setting it to a custom function that returns the key.
Leaving it set to the default =gptel-api-key-from-auth-source= function which reads keys from =~/.authinfo=. (See [[#optional-securing-api-keys-with-authinfo][authinfo details]])

*** Other LLM backends

An OpenAI backend is configured out of the box. If you want to use other LLM backends (like Ollama, Claude/Anthropic or Gemini) you need to register and configure them first.

As an example, registering a backend typically looks like the following:

#+begin_src emacs-lisp (gptel-make-anthropic "Claude" :stream t :key gptel-api-key) #+end_src

Once this backend is registered, you'll see model names prefixed by "Claude:" appear in gptel's menu.

See below for details on your preferred LLM provider, including local LLMs.

#+html:

**** (Optional) Securing API keys with =authinfo= #+html:

You can use Emacs' built-in support for =authinfo= to store API keys required by gptel. Add your API keys to =~/.authinfo=, and leave =gptel-api-key= set to its default. By default, the API endpoint DNS name (e.g. "api.openai.com") is used as HOST and "apikey" as USER.

#+begin_src authinfo machine api.openai.com login apikey password sk-secret-openai-api-key-goes-here machine api.anthropic.com login apikey password sk-secret-anthropic-api-key-goes-here #+end_src

#+html:

**** (Optional) Reading API keys from environment variables #+html:

Alternatively, you can fetch API keys from variables in Emacs' environment (such as =OPENAI_API_KEY=) using a function like this:

#+begin_src emacs-lisp (defun gptel-api-key-from-environment (&optional var) (lambda () (getenv (or var ;provided key (thread-first ;or fall back to _API_KEY (type-of gptel-backend) (symbol-name) (substring 6) (upcase) (concat "_API_KEY")))))) #+end_src

Then set the =:key= when defining backend to the appropriate environment variable:

#+begin_src emacs-lisp (gptel-make-anthropic "My-Claude-backend" :key (gptel-api-key-from-environment "ANTHROPIC_API_KEY")) #+end_src

If no environment variable is provided:

#+begin_src emacs-lisp (gptel-make-gemini "My-Gemini-backend" :key (gptel-api-key-from-environment)) #+end_src

it will try to guess the key from the backend type, /i.e./ try to use =GEMINI_API_KEY= when using the Gemini backend, and so on.

#+html:

**** OpenAI (ChatGPT plus/pro subscription) #+html:

Includes access to OpenAI Codex models. Register a backend with

#+begin_src emacs-lisp (gptel-make-openai-oauth "OpenAI-sub") ;Any name of your choosing #+end_src

You will be prompted to log into OpenAI as required. (You can also log in manually with =M-x gptel-openai-oauth-login=.)

If you are using it through a proxy, you can specify the host name, protocol etc:

#+begin_src emacs-lisp (gptel-make-openai-oauth "OpenAI-sub" :host "my.openai-proxy.tld" :protocol "http") #+end_src

Refer to the documentation of =gptel-make-openai-oauth= to set more parameters.

You can pick this backend from the menu when using gptel. (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above:

#+begin_src emacs-lisp (setq gptel-model 'gpt-5.4-mini gptel-backend (gptel-make-openai-oauth "OpenAI-sub")) #+end_src

#+html:

**** Azure #+html:

#+begin_src emacs-lisp (gptel-make-azure "Azure-1" ;Name, whatever you'd like :protocol "https" ;Optional -- https is the default :host "YOUR_RESOURCE_NAME.openai.azure.com" :endpoint "/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2023-05-15" ;or equivalent :stream t ;Enable streaming responses :key #'gptel-api-key :models '(gpt-3.5-turbo gpt-4)) #+end_src

Refer to the documentation of =gptel-make-azure= to set more parameters.

You can pick this backend from the menu when using gptel. (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'gpt-3.5-turbo gptel-backend (gptel-make-azure "Azure-1" :protocol "https" :host "YOUR_RESOURCE_NAME.openai.azure.com" :endpoint "/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2023-05-15" :stream t :key #'gptel-api-key :models '(gpt-3.5-turbo gpt-4))) #+end_src

#+html:

**** GPT4All #+html:

#+begin_src emacs-lisp (gptel-make-gpt4all "GPT4All" ;Name of your choosing :protocol "http" :host "localhost:4891" ;Where it's running :models '(mistral-7b-openorca.Q4_0.gguf)) ;Available models #+end_src

These are the required parameters, refer to the documentation of =gptel-make-gpt4all= for more.

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above. Additionally you may want to increase the response token size since GPT4All uses very short (often truncated) responses by default.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-max-tokens 500 gptel-model 'mistral-7b-openorca.Q4_0.gguf gptel-backend (gptel-make-gpt4all "GPT4All" :protocol "http" :host "localhost:4891" :models '(mistral-7b-openorca.Q4_0.gguf))) #+end_src

#+html:

**** Ollama #+html:

Register a backend with #+begin_src emacs-lisp (gptel-make-ollama "Ollama" ;Any name of your choosing :host "localhost:11434" ;Where it's running :stream t ;Stream responses :models '(mistral:latest)) ;List of models #+end_src

These are the required parameters, refer to the documentation of =gptel-make-ollama= for more.

You can pick this backend from the menu when using gptel (see [[#usage][Usage]])

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'mistral:latest gptel-backend (gptel-make-ollama "Ollama" :host "localhost:11434" :stream t :models '(mistral:latest))) #+end_src

#+html:

**** Open WebUI #+html:

[[https://openwebui.com/][Open WebUI]] is an open source, self-hosted system which provides a multi-user web chat interface and an API endpoint for accessing LLMs, especially LLMs running locally on inference servers like Ollama.

Because it presents an OpenAI-compatible endpoint, you use ~gptel-make-openai~ to register it as a backend.

For instance, you can use this form to register a backend for a local instance of Open Web UI served via http on port 3000:

#+begin_src emacs-lisp (gptel-make-openai "OpenWebUI" :host "localhost:3000" :protocol "http" :key "KEY_FOR_ACCESSING_OPENWEBUI" :endpoint "/api/chat/completions" :stream t :models '("gemma3n:latest")) #+end_src

Or if you are running Open Web UI on another host on your local network (~box.local~), serving via https with self-signed certificates, this will work:

#+begin_src emacs-lisp (gptel-make-openai "OpenWebUI" :host "box.local" :curl-args '("--insecure") ; needed for self-signed certs :key "KEY_FOR_ACCESSING_OPENWEBUI" :endpoint "/api/chat/completions" :stream t :models '("gemma3n:latest")) #+end_src

To find your API key in Open WebUI, click the user name in the bottom left, Settings, Account, and then Show by API Keys section.

Refer to the documentation of =gptel-make-openai= for more configuration options.

You can pick this backend from the menu when using gptel (see [[#usage][Usage]])

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model "gemma3n:latest" gptel-backend (gptel-make-openai "OpenWebUI" :host "localhost:3000" :protocol "http" :key "KEY_FOR_ACCESSING_OPENWEBUI" :endpoint "/api/chat/completions" :stream t :models '("gemma3n:latest"))) #+end_src

#+html:

**** Gemini #+html:

#+begin_src emacs-lisp ;; :key can be a function that returns the API key. (gptel-make-gemini "Gemini" :key "YOUR_GEMINI_API_KEY" :stream t) #+end_src

These are the required parameters, refer to the documentation of =gptel-make-gemini= for more.

You can pick this backend from the menu when using gptel (see [[#usage][Usage]])

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'gemini-2.5-pro-exp-03-25 gptel-backend (gptel-make-gemini "Gemini" :key "YOUR_GEMINI_API_KEY" :stream t)) #+end_src

#+html:

**** Llama.cpp or Llamafile #+html:

(If using a llamafile, run a [[https://github.com/Mozilla-Ocho/llamafile#other-example-llamafiles][server llamafile]] instead of a "command-line llamafile", and a model that supports text generation.)

#+begin_src emacs-lisp ;; Llama.cpp offers an OpenAI compatible API (gptel-make-openai "llama-cpp" ;Any name :stream t ;Stream responses :protocol "http" :host "localhost:8000" ;Llama.cpp server location :models '(test)) ;Any names, doesn't matter for Llama #+end_src

These are the required parameters, refer to the documentation of =gptel-make-openai= for more.

You can pick this backend from the menu when using gptel (see [[#usage][Usage]])

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'test gptel-backend (gptel-make-openai "llama-cpp" :stream t :protocol "http" :host "localhost:8000" :models '(test))) #+end_src

#+html:

**** Kagi (FastGPT & Summarizer) #+html:

Kagi's FastGPT model and the Universal Summarizer are both supported. A couple of notes:

Universal Summarizer: If there is a URL at point, the summarizer will summarize the contents of the URL. Otherwise the context sent to the model is the same as always: the buffer text upto point, or the contents of the region if the region is active.
Kagi models do not support multi-turn conversations, interactions are "one-shot". They also do not support streaming responses.

#+begin_src emacs-lisp (gptel-make-kagi "Kagi" ;any name :key "YOUR_KAGI_API_KEY") ;can be a function that returns the key #+end_src

These are the required parameters, refer to the documentation of =gptel-make-kagi= for more.

You can pick this backend and the model (fastgpt/summarizer) from the transient menu when using gptel.

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'fastgpt gptel-backend (gptel-make-kagi "Kagi" :key "YOUR_KAGI_API_KEY")) #+end_src

The alternatives to =fastgpt= include =summarize:cecil=, =summarize:agnes=, =summarize:daphne= and =summarize:muriel=. The difference between the summarizer engines is [[https://help.kagi.com/kagi/api/summarizer.html#summarization-engines][documented here]].

#+html:

**** together.ai #+html:

#+begin_src emacs-lisp ;; Together.ai offers an OpenAI compatible API (gptel-make-openai "TogetherAI" ;Any name you want :host "api.together.xyz" :key "your-api-key" ;can be a function that returns the key :stream t :models '(;; has many more, check together.ai mistralai/Mixtral-8x7B-Instruct-v0.1 codellama/CodeLlama-13b-Instruct-hf codellama/CodeLlama-34b-Instruct-hf)) #+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]])

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'mistralai/Mixtral-8x7B-Instruct-v0.1 gptel-backend (gptel-make-openai "TogetherAI"
:host "api.together.xyz" :key "your-api-key"
:stream t :models '(;; has many more, check together.ai mistralai/Mixtral-8x7B-Instruct-v0.1 codellama/CodeLlama-13b-Instruct-hf codellama/CodeLlama-34b-Instruct-hf))) #+end_src

#+html:

**** Anyscale #+html:

#+begin_src emacs-lisp ;; Anyscale offers an OpenAI compatible API (gptel-make-openai "Anyscale" ;Any name you want :host "api.endpoints.anyscale.com" :key "your-api-key" ;can be a function that returns the key :models '(;; has many more, check anyscale mistralai/Mixtral-8x7B-Instruct-v0.1)) #+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]])

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'mistralai/Mixtral-8x7B-Instruct-v0.1 gptel-backend (gptel-make-openai "Anyscale" :host "api.endpoints.anyscale.com" :key "your-api-key" :models '(;; has many more, check anyscale mistralai/Mixtral-8x7B-Instruct-v0.1))) #+end_src

#+html:

**** Perplexity #+html:

#+begin_src emacs-lisp (gptel-make-perplexity "Perplexity" ;Any name you want :key "your-api-key" ;can be a function that returns the key :stream t) ;If you want responses to be streamed #+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]])

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'sonar gptel-backend (gptel-make-perplexity "Perplexity" :key "your-api-key" :stream t)) #+end_src

#+html:

**** Anthropic (Claude) #+html:

#+begin_src emacs-lisp (gptel-make-anthropic "Claude" ;Any name you want :stream t ;Streaming responses :key "your-api-key") #+end_src The =:key= can be a function that returns the key (more secure).

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'claude-3-sonnet-20240229 ; "claude-3-opus-20240229" also available gptel-backend (gptel-make-anthropic "Claude" :stream t :key "your-api-key")) #+end_src

***** (Optional) Interim support for Claude 3.7 Sonnet

To use Claude 3.7 Sonnet model in its "thinking" mode, you can define a second Claude backend and select it via the UI or elisp:

#+begin_src emacs-lisp (gptel-make-anthropic "Claude-thinking" ;Any name you want :key "your-API-key" :stream t :models '(claude-sonnet-4-20250514 claude-3-7-sonnet-20250219) :request-params '(:thinking (:type "enabled" :budget_tokens 2048) :max_tokens 4096)) #+end_src

You can set the reasoning budget tokens and max tokens for this usage via the =:budget_tokens= and =:max_tokens= keys here, respectively.

You can control whether/how the reasoning output is shown via gptel's menu or =gptel-include-reasoning=, see [[#handle-reasoning-content][handling reasoning content]].

#+html:

**** Groq #+html:

#+begin_src emacs-lisp ;; Groq offers an OpenAI compatible API (gptel-make-openai "Groq" ;Any name you want :host "api.groq.com" :endpoint "/openai/v1/chat/completions" :stream t :key "your-api-key" ;can be a function that returns the key :models '(gemma-7b-it llama3-8b-8192 mixtral-8x7b-32768 openai/gpt-oss-20b openai/gpt-oss-120b qwen/qwen3.6-27b)) #+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]). Note that Groq is fast enough that you could set =:stream nil= and still get near-instant responses.

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'mixtral-8x7b-32768 gptel-backend (gptel-make-openai "Groq" :host "api.groq.com" :endpoint "/openai/v1/chat/completions" :stream t :key "your-api-key" :models '(gemma-7b-it llama3-8b-8192 mixtral-8x7b-32768 openai/gpt-oss-20b openai/gpt-oss-120b qwen/qwen3.6-27b))) #+end_src

#+html:

**** Mistral Le Chat #+html:

#+begin_src emacs-lisp ;; Mistral offers an OpenAI compatible API (gptel-make-openai "MistralLeChat" ;Any name you want :host "api.mistral.ai" :endpoint "/v1/chat/completions" :protocol "https" :key "your-api-key" ;can be a function that returns the key :models '("mistral-small")) #+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'mistral-small gptel-backend (gptel-make-openai "MistralLeChat" ;Any name you want :host "api.mistral.ai" :endpoint "/v1/chat/completions" :protocol "https" :key "your-api-key" ;can be a function that returns the key :models '("mistral-small"))) #+end_src

#+html:

**** OpenRouter #+html:

#+begin_src emacs-lisp ;; OpenRouter offers an OpenAI compatible API (gptel-make-openai "OpenRouter" ;Any name you want :host "openrouter.ai" :endpoint "/api/v1/chat/completions" :stream t :key "your-api-key" ;can be a function that returns the key :models '(openai/gpt-3.5-turbo mistralai/mixtral-8x7b-instruct meta-llama/codellama-34b-instruct codellama/codellama-70b-instruct google/palm-2-codechat-bison-32k google/gemini-pro))

#+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'mixtral-8x7b-32768 gptel-backend (gptel-make-openai "OpenRouter" ;Any name you want :host "openrouter.ai" :endpoint "/api/v1/chat/completions" :stream t :key "your-api-key" ;can be a function that returns the key :models '(openai/gpt-3.5-turbo mistralai/mixtral-8x7b-instruct meta-llama/codellama-34b-instruct codellama/codellama-70b-instruct google/palm-2-codechat-bison-32k google/gemini-pro)))

#+end_src

#+html:

**** PrivateGPT #+html:

#+begin_src emacs-lisp (gptel-make-privategpt "privateGPT" ;Any name you want :protocol "http" :host "localhost:8001" :stream t :context t ;Use context provided by embeddings :sources t ;Return information about source documents :models '(private-gpt))

#+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'private-gpt gptel-backend (gptel-make-privategpt "privateGPT" ;Any name you want :protocol "http" :host "localhost:8001" :stream t :context t ;Use context provided by embeddings :sources t ;Return information about source documents :models '(private-gpt)))

#+end_src

#+html:

**** DeepSeek #+html:

#+begin_src emacs-lisp (gptel-make-deepseek "DeepSeek" ;Any name you want :stream t ;for streaming responses :key "your-api-key") ;can be a function that returns the key #+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'deepseek-reasoner gptel-backend (gptel-make-deepseek "DeepSeek" :stream t :key "your-api-key")) #+end_src

#+html:

**** Sambanova (Deepseek) #+html:

Sambanova offers various LLMs through their Samba Nova Cloud offering, with Deepseek-R1 being one of them. The token speed for Deepseek R1 via Sambanova is about 6 times faster than when accessed through deepseek.com

#+begin_src emacs-lisp (gptel-make-openai "Sambanova" ;Any name you want :host "api.sambanova.ai" :endpoint "/v1/chat/completions" :stream t ;for streaming responses :key "your-api-key" ;can be a function that returns the key :models '(DeepSeek-R1)) #+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend The code aboves makes the backend available for selection. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Add these two lines to your configuration:

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'DeepSeek-R1) (setq gptel-backend (gptel-get-backend "Sambanova")) #+end_src

#+html:

**** Cerebras #+html:

#+begin_src emacs-lisp ;; Cerebras offers an instant OpenAI compatible API (gptel-make-openai "Cerebras" :host "api.cerebras.ai" :endpoint "/v1/chat/completions" :stream t ;optionally nil as Cerebras is instant AI :key "your-api-key" ;can be a function that returns the key :models '(llama3.1-70b llama3.1-8b)) #+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'llama3.1-8b gptel-backend (gptel-make-openai "Cerebras" :host "api.cerebras.ai" :endpoint "/v1/chat/completions" :stream nil :key "your-api-key" :models '(llama3.1-70b llama3.1-8b))) #+end_src

#+html:

**** Github Models #+html:

NOTE: [[https://docs.github.com/en/github-models/about-github-models][GitHub Models]] is /not/ GitHub Copilot! If you want to use GitHub Copilot chat via gptel, look at the instructions for GitHub CopilotChat below instead.

#+begin_src emacs-lisp ;; Github Models offers an OpenAI compatible API (gptel-make-openai "Github Models" ;Any name you want :host "models.inference.ai.azure.com" :endpoint "/chat/completions?api-version=2024-05-01-preview" :stream t :key "your-github-token" :models '(gpt-4o)) #+end_src

You will need to create a github [[https://github.com/settings/personal-access-tokens][token]].

For all the available models, check the [[https://github.com/marketplace/models][marketplace]].

You can pick this backend from the menu when using (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'gpt-4o gptel-backend (gptel-make-openai "Github Models" ;Any name you want :host "models.inference.ai.azure.com" :endpoint "/chat/completions?api-version=2024-05-01-preview" :stream t :key "your-github-token" :models '(gpt-4o)) #+end_src

#+html:

**** Novita AI #+html:

#+begin_src emacs-lisp ;; Novita AI offers an OpenAI compatible API (gptel-make-openai "NovitaAI" ;Any name you want :host "api.novita.ai" :endpoint "/v3/openai" :key "your-api-key" ;can be a function that returns the key :stream t :models '(;; has many more, check https://novita.ai/llm-api gryphe/mythomax-l2-13b meta-llama/llama-3-70b-instruct meta-llama/llama-3.1-70b-instruct)) #+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]])

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'gryphe/mythomax-l2-13b gptel-backend (gptel-make-openai "NovitaAI"
:host "api.novita.ai" :endpoint "/v3/openai" :key "your-api-key"
:stream t :models '(;; has many more, check https://novita.ai/llm-api mistralai/Mixtral-8x7B-Instruct-v0.1 meta-llama/llama-3-70b-instruct meta-llama/llama-3.1-70b-instruct))) #+end_src

#+html:

**** xAI #+html:

#+begin_src emacs-lisp (gptel-make-xai "xAI" ; Any name you want :stream t :key "your-api-key") ; can be a function that returns the key #+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]])

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp (setq gptel-model 'grok-3-latest gptel-backend (gptel-make-xai "xAI" ; Any name you want :key "your-api-key" ; can be a function that returns the key :stream t)) #+end_src

#+html:

**** AI/ML API #+html:

AI/ML API provides 300+ AI models including Deepseek, Gemini, ChatGPT. The models run at enterprise-grade rate limits and uptimes.

#+begin_src emacs-lisp ;; AI/ML API offers an OpenAI compatible API (gptel-make-openai "AI/ML API" ;Any name you want :host "api.aimlapi.com" :endpoint "/v1/chat/completions" :stream t :key "your-api-key" ;can be a function that returns the key :models '(deepseek-chat gemini-pro gpt-4o)) #+end_src

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'gpt-4o gptel-backend (gptel-make-openai "AI/ML API" :host "api.aimlapi.com" :endpoint "/v1/chat/completions" :stream t :key "your-api-key" :models '(deepseek-chat gemini-pro gpt-4o))) #+end_src

#+html:

**** GitHub CopilotChat #+html:

#+begin_src emacs-lisp (gptel-make-gh-copilot "Copilot") #+end_src

Github copilot is configured to use the public endpoint =api.githubcopilot.com=. Depending on your plan, you may need to use a different host (see [[https://github.blog/changelog/2026-02-13-network-configuration-changes-for-copilot-coding-agent/#whats-changing][Copilot plan changes]]):

Copilot Business: =api.business.githubcopilot.com=
Copilot Enterprise: =api.enterprise.githubcopilot.com=
Copilot Pro and Pro+: =api.individual.githubcopilot.com=

You can do this as follows: #+begin_src emacs-lisp (gptel-make-gh-copilot "Copilot" :host "api.business.githubcopilot.com") #+end_src

You will be informed to login into =GitHub= as required. (You can also log in manually with =M-x gptel-gh-login=.)

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'claude-3.7-sonnet gptel-backend (gptel-make-gh-copilot "Copilot")) #+end_src

#+html:

**** AWS Bedrock #+html:

#+begin_src emacs-lisp (gptel-make-bedrock "AWS" ;; optionally enable streaming :stream t :region "ap-northeast-1" ;; subset of gptel--bedrock-models :models '(claude-sonnet-4-20250514) ;; Model region for cross-region inference profiles. Required for models such ;; as Claude without on-demand throughput support. One of 'apac, 'eu or 'us. ;; https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-use.html :model-region 'apac) #+end_src

AWS has numerous credential provisions; we follow this order precedence,

(argument) ~:aws-bearer-token~
(env. variable) ~AWS_BEARER_TOKEN_BEDROCK~
(argument) ~:aws-profile~ If this option is specified, the Bedrock-backend uses the shared AWS config and credentials files to obtain credentials based on the AWS Profile selected. If ~:aws-profile~ is set to the keyword ~:static~, the IAM credentials are imported without a profile argument.
(env. varible) ~AWS_PROFILE~
(env. varible) ~AWS_ACCESS_KEY_ID~, ~AWS_SECRET_ACCESS_KEY~ and ~AWS_SESSION_TOKEN~

NOTE: The Bedrock backend requires ~gptel-use-curl~ to be set to ~t~. When authenticating with an AWS profile or IAM credentials, =curl= computes a SigV4 signature and version 8.10 or newer is required (see [[https://github.com/curl/curl/issues/11794][curl issue #11794]]). Bearer token authentication does not have this requirement.

You can pick this backend from the menu when using gptel (see [[#usage][Usage]]).

***** (Optional) Set as the default gptel backend

The above code makes the backend available to select. If you want it to be the default backend for gptel, you can set this as the value of =gptel-backend=. Use this instead of the above.

#+begin_src emacs-lisp ;; OPTIONAL configuration (setq gptel-model 'claude-sonnet-4-20250514 gptel-backend (gptel-make-bedrock "AWS" ;; optionally enable streaming :stream t ;; optionally specify the aws profile ;; :profile :region "ap-northeast-1" ;; subset of gptel--bedrock-models :models '(claude-sonnet-4-20250514) ;; Model region for cross-region inference profiles. Required for models such ;; as Claude without on-demand throughput support. One of 'apac, 'eu or 'us. ;; https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-use.html :model-region 'apac)) #+end_src

#+html:

**** Moonshot (Kimi) #+html:

#+begin_src emacs-lisp (gptel-make-openai "Moonshot" :host "api.moonshot.cn" ;; or "api.moonshot.ai" for the global site :key "your-api-key" :stream t ;; optionally enable streaming :models '(kimi-latest kimi-k2-0711-preview)) #+end_src

See [[https://platform.moonshot.ai/docs/pricing/chat][Moonshot.ai document]] for a complete list of models.

***** (Optional) Use the builtin search tool

Moonshot supports a builtin search tool that does not requires the user to provide the tool implementation. To use that, you first need to define the tool and add to =gptel-tools= (while it does not requires the client to provide the search implementation, it does expects the client to reply a tool call message with its given argument, to be consistent with other tool calls):

#+begin_src emacs-lisp (setq gptel-tools (list (gptel-make-tool :name "$web_search" :function (lambda (&optional search_result) (json-serialize `(:search_result ,search_result))) :description "Moonshot builtin web search. Only usable by moonshot model (kimi), ignore this if you are not." :args '((:name "search_result" :type object :optional t)) :category "web"))) #+end_src

Then you also need to add the tool declaration via =:request-params= because it needs a special =builtin_function= type:

Now the chat should be able to automatically use search. Try "what's new today" and you should expect the up-to-date news in response.

#+html:

** Usage

gptel provides a few powerful, general purpose and flexible commands. You can dynamically tweak their behavior to the needs of your task with /directives/ (system prompts), redirection options and more. There is a [[https://www.youtube.com/watch?v=bsRnh_brggM][video demo]] showing various uses of gptel -- but =gptel-send= might be all you need.

|-------------------+---------------------------------------------------------------------------------------------------| | To send queries | Description | |-------------------+---------------------------------------------------------------------------------------------------| | =gptel-send= | Send all text up to =(point)=, or the selection if region is active. Works anywhere in Emacs. | | =gptel= | Create a new dedicated chat buffer. Not required to use gptel. | | =gptel-rewrite= | Rewrite, refactor or change the selected region. Can diff/ediff changes before merging/applying. | |-------------------+---------------------------------------------------------------------------------------------------|

|---------------------+---------------------------------------------------------------| | To tweak behavior | | |---------------------+---------------------------------------------------------------| | =C-u= =gptel-send= | Transient menu for preferences, input/output redirection etc. | | =gptel-menu= | /(Same)/ | |---------------------+---------------------------------------------------------------|

|------------------+--------------------------------------------------------------------------------------------------------| | To add context | | |------------------+--------------------------------------------------------------------------------------------------------| | =gptel-add= | Add/remove a region or buffer to gptel's context. In Dired, add/remove marked files. | | =gptel-add-file= | Add a file (text or supported media type) to gptel's context. Also available from the transient menu. | |------------------+--------------------------------------------------------------------------------------------------------|

|----------------------------+-----------------------------------------------------------------------------------------| | Org mode bonuses | | |----------------------------+-----------------------------------------------------------------------------------------| | =gptel-org-set-topic= | Limit conversation context to an Org heading. (For branching conversations see below.) | | =gptel-org-set-properties= | Write gptel configuration as Org properties, for per-heading chat configuration. | |----------------------------+-----------------------------------------------------------------------------------------|

|----------------------------+-------------------------------------------------------------------------------------------| | Oauth connections | | |----------------------------+-------------------------------------------------------------------------------------------| | =gptel-gh-login= | Authenticate with GitHub Copilot. (Automatically handled, but can be forced if required.) | | =gptel-openai-oauth-login= | Authenticate with OpenAI (Codex). (Automatically handled, but can be forced if required.) | |----------------------------+-------------------------------------------------------------------------------------------|

*** In any buffer:

Call =M-x gptel-send= to send the text up to the cursor. The response will be inserted below. Continue the conversation by typing below the response.
If a region is selected, the conversation will be limited to its contents.
Call =M-x gptel-send= with a prefix argument (~C-u~)
- to set chat parameters (model, backend, system message etc) for this buffer,
- include quick instructions for the next request only,
- to add additional context -- regions, buffers or files -- to gptel,
- to read the prompt from or redirect the response elsewhere,
- or to replace the prompt with the response.

#+html:

You can use =gptel-highlight-mode= to highlight LLM responses in different ways:

#+html:

You can also define a "preset" bundle of options that are applied together, see [[#option-presets][Option presets]] below.

*** In a dedicated chat buffer:

Note: gptel works anywhere in Emacs. The dedicated chat buffer only adds some conveniences.

Run =M-x gptel= to start or switch to the chat buffer. It will ask you for the key if you skipped the previous step. Run it with a prefix-arg (=C-u M-x gptel=) to start a new session.
In the gptel buffer, send your prompt with =M-x gptel-send=, bound to =C-c RET=.
Set chat parameters (LLM provider, model, system prompt etc) for the session by calling =gptel-send= with a prefix argument (=C-u C-c RET=):

#+html:

That's it. You can go back and edit previous prompts and responses if you want.

The default mode is =markdown-mode= if available, else =text-mode=. You can set =gptel-default-mode= to =org-mode= if desired.

You can use =gptel-highlight-mode= to highlight LLM responses in different ways.

You can also define a "preset" bundle of options that are applied together, see [[#option-presets][Option presets]] below.

#+html:

**** Including media (images, documents or plain-text files) with requests #+html:

gptel supports sending media in Markdown and Org chat buffers, but this feature is disabled by default.

You can enable it globally, for all models that support it, by setting =gptel-track-media=.
Or you can set it locally, just for the chat buffer, via the header line or gptel's transient menu:

#+html:

There are two ways to include media or plain-text files with requests:

Add files to gptel's context with =gptel-add-file=, described further below.
Include links to media in chat buffers. gptel will annotate the link to indicate that the linked files will be sent along with the prompt. If a link cannot be sent for some reason, that will be indicated too, and the reason will be shown in a tooltip:

#+html:

Most ways of specifying links to files/URLs are respected by gptel:

In Markdown mode:
- =[](file:///path/to/file.txt)= and ==
- =[Description](file:///path/to/file.txt)= and =Description=
- =<file:///path/to/file.txt>= "Plain" links of the form =file:///path/to/file.txt= will not be recognized.
In Org mode:
- =[[file:/path/to/file.txt]]=
- =[[file:/path/to/file.txt][Description]]=
- =<file:/path/to/file.txt>=
- =[[attachment:data.txt]]= "Plain" links of the form =file:/path/to/file.txt= will not be recognized.

Support for custom Org link types is planned.

#+html:

**** Save and restore your chat sessions #+html:

Saving the file will save the state of the conversation as well. To resume the chat, open the file and turn on =gptel-mode= before editing the buffer.

#+html:

*** Setting options (backend, model, request parameters, system prompts and more)

Most gptel options can be set from gptel's transient menu, available by calling =gptel-send= with a prefix-argument, or via =gptel-menu=. To change their default values in your configuration, see [[#additional-configuration][Additional Configuration]]. Chat buffer-specific options are also available via the header-line in chat buffers.

TODO Remove this when writing the manual.

Selecting a model and backend can be done interactively via the =-m= command of =gptel-menu=. Available registered models are prefixed by the name of their backend with a string like =ChatGPT:gpt-4o-mini=, where =ChatGPT= is the backend name you used to register it and =gpt-4o-mini= is the name of the model.

*** Include more context with requests :PROPERTIES: :CUSTOM_ID: include-context :END:

By default, gptel will query the LLM with the active region or the buffer contents up to the cursor. Often it can be helpful to provide the LLM with additional context from outside the current buffer. For example, when you're in a chat buffer but want to ask questions about a (possibly changing) code buffer and auxiliary project files.

You can include additional text regions, buffers or files with gptel's queries in two ways. The first is via links in chat buffers, as described above (see "Including media with requests").

The second is globally via dedicated context commands: you can add a selected region, buffer or file to gptel's context from the menu, or call =gptel-add=. To add a file use =gptel-add= in Dired, or use the dedicated =gptel-add-file= command. Directories will have their files added recursively after prompting for confirmation.

This additional context is "live" and not a snapshot. Once added, the regions, buffers or files are scanned and included at the time of each query. When using multi-modal models, added files can be of any supported type -- typically images.

You can examine the active context from the menu: #+html: <img src="https://github.com/karthink/gptel/assets/8607532/63cd7fc8-6b3e-42ae-b6ca-06ff935bae9c" align="center" alt="Image showing gptel's menu with the "inspect context" command.">

And then browse through or remove context from the context buffer: #+html:

By default, files in a version control system that are not project files ("gitignored" files) will not be added to the context. To be able to add these files, set =gptel-context-restrict-to-project-files= to =nil=. Note that remote files are always included, regardless of the value of =gptel-context-restrict-to-project-files=.

*** Handle "reasoning" content

Some LLMs include in their response a "thinking" or "reasoning" block. This text improves the quality of the LLM’s final output, but may not be interesting to you by itself. You can decide how you would like this "reasoning" content to be handled by gptel by setting the user option =gptel-include-reasoning=. You can include it in the LLM response (the default), omit it entirely, include it in the buffer but ignore it on subsequent conversation turns, or redirect it to another buffer. As with most options, you can specify this behavior from gptel's transient menu globally, buffer-locally or for the next request only.

When included with the response, reasoning content will be delimited by Org blocks or markdown backticks.

*** Tool use

gptel can provide the LLM with client-side elisp "tools", or function specifications, along with the request. If the LLM decides to run the tool, it supplies the tool call arguments, which gptel uses to run the tool in your Emacs session. The result is optionally returned to the LLM to complete the task.

This exchange can be used to equip the LLM with capabilities or knowledge beyond what is available out of the box -- for instance, you can get the LLM to control your Emacs frame, create or modify files and directories, or look up information relevant to your request via web search or in a local database. Here is a very simple example:

#+html:

https://github.com/user-attachments/assets/d1f8e2ac-62bb-49bc-850d-0a67aa0cd4c3 #+html:

To use tools in gptel, you need

a model that supports this usage. All the flagship models support tool use, as do many of the smaller open models.
Tool specifications that gptel understands. gptel does not currently include any tools out of the box.

#+html:

**** Defining gptel tools #+html:

Defining a gptel tool requires an elisp function and associated metadata. Here are two simple tool definitions:

To read the contents of an Emacs buffer:

#+begin_src emacs-lisp (gptel-make-tool :name "read_buffer" ; javascript-style snake_case name :function (lambda (buffer) ; the function that will run (unless (buffer-live-p (get-buffer buffer)) (error "error: buffer %s is not live." buffer)) (with-current-buffer buffer (buffer-substring-no-properties (point-min) (point-max)))) :description "return the contents of an emacs buffer" :args (list '(:name "buffer" :type string ; :type value must be a symbol :description "the name of the buffer whose contents are to be retrieved")) :category "emacs") ; An arbitrary label for grouping #+end_src

Besides the function itself, which can be named or anonymous (as above), the tool specification requires a =:name=, =:description= and a list of argument specifications in =:args=. Each argument specification is a plist with atleast the keys =:name=, =:type= and =:description=.

To create a text file:

#+begin_src emacs-lisp (gptel-make-tool :name "create_file" ; javascript-style snake_case name :function (lambda (path filename content) ; the function that runs (let ((full-path (expand-file-name filename path))) (with-temp-buffer (insert content) (write-file full-path)) (format "Created file %s in %s" filename path))) :description "Create a new file with the specified content" :args (list '(:name "path" ; a list of argument specifications :type string :description "The directory where to create the file") '(:name "filename" :type string :description "The name of the file to create") '(:name "content" :type string :description "The content to write to the file")) :category "filesystem") ; An arbitrary label for grouping #+end_src

With some prompting, you can get an LLM to write these tools for you.

Tools can also be asynchronous, use optional arguments and arguments with more structure (enums, arrays, objects etc). See =gptel-make-tool= for details.

#+html:

**** Selecting tools #+html:

Once defined, tools can be selected (globally, buffer-locally or for the next request only) from gptel's transient menu:

#+html:

From here you can also require confirmation for all tool calls, and decide if tool call results should be included in the LLM response.

Alternatively, you can add/remove tools via

Elisp, see [[#additional-configuration][Additional Configuration]].
gptel presets, see [[#option-presets][Option presets]].

#+html:

**** LLM tool collections #+html:

The following repositories provide collections of tools written by gptel users.

[[https://github.com/skissue/llm-tool-collection][llm-tool-collection]] :: A community collection of tools for use with LLM clients in Emacs. Includes LLM tools for interacting with files, Emacs buffers and running system commands.
[[https://github.com/karthink/gptel-agent][gptel-agent]] :: A collection of tools meant for agentic LLM use. Includes tools for filesystem access and manipulation, running Bash commands, Emacs introspection and Elisp evaluation, web search and YouTube.
[[https://github.com/ultronozm/codel.el][codel.el]] :: A collection of code editing tools.
[[https://codeberg.org/bajsicki/gptel-org-tools][gptel-org-tools]] :: Tools for interacting with Org files.
[[https://github.com/positron-solutions/ragmacs][ragmacs]] :: A collection of tools for Emacs introspection.
[[https://github.com/munen/emacs.d?tab=readme-ov-file#tool-use][Alain Lafon’s tool collection]]

Additionally, the [[https://github.com/karthink/gptel/wiki/Tools-collection][wiki has some examples]] of common tools. These are not maintained, but might serve instructional when writing custom tools.

#+html:

**** Model Context Protocol (MCP) integration #+html:

The [[https://modelcontextprotocol.io/introduction][Model Context Protocol]] (MCP) is a protocol for providing resources and tools to LLMs, and [[https://github.com/appcypher/awesome-mcp-servers][many MCP servers exist]] that provide LLM tools for file access, database connections, API integrations etc. The [[mcp.el]] package for Emacs can act as an MCP client and manage these tool calls for gptel.

To use MCP servers with gptel, you thus need three pieces:

The [[https://github.com/lizqwerscott/mcp.el][mcp.el]] package for Emacs, [[https://melpa.org/#/mcp][available on MELPA]].
MCP servers configured for and running via mcp.el.
gptel and access to an LLM

gptel includes =gptel-integrations=, a small library to make this more convenient. This library is not automatically loaded by gptel, so if you would like to use it you have to require it:

#+begin_src emacs-lisp (require 'gptel-integrations) #+end_src

Once loaded, you can run the =gptel-mcp-connect= and =gptel-mcp-disconnect= commands to register and unregister MCP-provided tools in gptel. These will also show up in the tools menu in gptel, accessed via =M-x gptel-menu= or =M-x gptel-tools=:

#+html:

MCP-provided tools can be used as normal with gptel. Here is a screencast of the process. (In this example the "github" MCP server is installed separately using npm.)

#+html:

https://github.com/user-attachments/assets/f3ea7ac0-a322-4a59-b5b2-b3f592554f8a #+html:

Here's an example of using these tools:

#+html:

https://github.com/user-attachments/assets/b48a6a24-a130-4da7-a2ee-6ea568e10c85 #+html:

#+html:

*** Rewrite, refactor or fill in a region

In any buffer: with a region selected, you can modify text, rewrite prose or refactor code with =gptel-rewrite=. Example with prose:

#+html:

https://github.com/user-attachments/assets/e3b436b3-9bde-4c1f-b2ce-3f7df1984933 #+html:

The result is previewed over the original text. By default, the buffer is not modified.

Pressing =RET= or clicking in the rewritten region should give you a list of options: you can iterate on, diff, ediff, merge or accept the replacement. Example with code:

#+html:

https://github.com/user-attachments/assets/4067fdb8-85d3-4264-9b64-d727353f68f9 #+html:

Acting on the LLM response:

If you would like one of these things to happen automatically, you can customize =gptel-rewrite-default-action=.

These options are also available from =gptel-rewrite=:

#+html:

And you can call them directly when the cursor is in the rewritten region:

#+html:

*** Extra Org mode conveniences

gptel offers a few extra conveniences in Org mode.

***** Limit conversation context to an Org heading

You can limit the conversation context to an Org heading with the command =gptel-org-set-topic=.

(This sets an Org property (=GPTEL_TOPIC=) under the heading. You can also add this property manually instead.)

***** Use branching context in Org mode (tree of conversations)

You can have branching conversations in Org mode, where each hierarchical outline path through the document is a separate conversation branch. This is also useful for limiting the context size of each query. See the variable =gptel-org-branching-context=.

If this variable is non-nil, you should probably edit =gptel-prompt-prefix-alist= and =gptel-response-prefix-alist= so that the prefix strings for org-mode are not Org headings, e.g.

#+begin_src emacs-lisp (setf (alist-get 'org-mode gptel-prompt-prefix-alist) "@user\n") (setf (alist-get 'org-mode gptel-response-prefix-alist) "@assistant\n") #+end_src

Otherwise, the default prompt prefix will make successive prompts sibling headings, and therefore on different conversation branches, which probably isn't what you want.

Note: using this option requires Org 9.7 or higher to be available. The [[https://github.com/ultronozm/ai-org-chat.el][ai-org-chat]] package uses gptel to provide this branching conversation behavior for older versions of Org.

***** Save gptel parameters to Org headings (reproducible chats)

You can declare the gptel model, backend, temperature, system message and other parameters as Org properties with the command =gptel-org-set-properties=. gptel queries under the corresponding heading will always use these settings, allowing you to create mostly reproducible LLM chat notebooks, and to have simultaneous chats with different models, model settings and directives (system prompts) under different Org headings.

*** Introspection (examine, debug or modify requests)

Set =gptel-expert-commands= to =t= to display additional options in gptel's transient menu. #+html:

Examining prompts: you can examine and edit gptel request payloads before sending them.

Pick one of the "dry run" options in the menu to produce a buffer containing the request payload.
You can edit this buffer as you would like and send the request.
You can also copy a Curl command corresponding to the request and invoke it from the shell.

Examining responses: You can turn on logging to examine the full response from an LLM.

Set =gptel-log-level= to =info= or =debug=.
Send a request.
Open the log buffer from gptel's transient menu, or switch to the =gptel-log= buffer.

** FAQ *** Chat buffer UI #+html:

**** I want the window to scroll automatically as the response is inserted #+html:

To be minimally annoying, gptel does not move the cursor by default. Add the following to your configuration to enable auto-scrolling.

#+begin_src emacs-lisp (add-hook 'gptel-post-stream-hook 'gptel-auto-scroll) #+end_src

#+html:

**** I want the cursor to move to the next prompt after the response is inserted #+html:

To be minimally annoying, gptel does not move the cursor by default. Add the following to your configuration to move the cursor:

#+begin_src emacs-lisp (add-hook 'gptel-post-response-functions 'gptel-end-of-response) #+end_src

You can also call =gptel-end-of-response= as a command at any time.

#+html:

**** I want to change the formatting of the prompt and LLM response #+html:

Anywhere in Emacs: Turn on =gptel-highlight-mode=. See its documentation for customization options.

In dedicated chat buffers: you can additionally customize =gptel-prompt-prefix-alist= and =gptel-response-prefix-alist=, which are prefixes inserted before the prompt and response. You can set a different pair for each major-mode.

For more custom formatting, use =gptel-pre-response-hook= and =gptel-post-response-functions=.

#+html:

**** How does gptel distinguish between user prompts and LLM responses? #+html:

gptel uses [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Text-Properties.html][text-properties]] to watermark LLM responses. Thus this text is interpreted as a response even if you copy it into another buffer. In regular buffers (buffers without =gptel-mode= enabled), you can turn off this tracking by unsetting =gptel-track-response=.

When restoring a chat state from a file on disk, gptel will apply these properties from saved metadata in the file when you turn on =gptel-mode=.

gptel does /not/ use any prefix or semantic/syntax element in the buffer (such as headings) to separate prompts and responses. The reason for this is that gptel aims to integrate as seamlessly as possible into your regular Emacs usage: LLM interaction is not the objective, it's just another tool at your disposal. So requiring a bunch of "user" and "assistant" tags in the buffer is noisy and restrictive. If you want these demarcations, you can customize =gptel-prompt-prefix-alist= and =gptel-response-prefix-alist=. Note that these prefixes are for your readability only and purely cosmetic.

#+html:

*** Transient menu behavior #+html:

**** I want to set gptel options but only for this buffer :PROPERTIES: :ID: 748cbc00-0c92-4705-8839-619b2c80e566 :END: #+html:

In every menu used to set options, gptel provides a "scope" option, bound to the ~=~ key:

#+html:

You can flip this switch before setting the option to =buffer= or =oneshot=. You only need to flip this switch once, it's a persistent setting. =buffer= sets the option buffer-locally, =oneshot= will set it for the next gptel request only. The default scope is global.

#+html:

**** I want the transient menu options to be saved so I only need to set them once #+html:

Any model options you set are saved according to the scope (see previous question). But the redirection options in the menu are set for the next query only:

#+html:

You can make them persistent across this Emacs session by pressing ~C-x C-s~:

#+html:

(You can also cycle through presets you've saved with ~C-x p~ and ~C-x n~.)

Now these will be enabled whenever you send a query from the transient menu. If you want to use these saved options without invoking the transient menu, you can use a keyboard macro:

#+begin_src emacs-lisp ;; Replace with your key to invoke the transient menu: (keymap-global-set " " "C-u C-c ") #+end_src

Or see this [[https://github.com/karthink/gptel/wiki/Commonly-requested-features#save-transient-flags][wiki entry]].

#+html:

**** Using the transient menu leaves behind extra windows #+html:

If using gptel's transient menus causes new/extra window splits to be created, check your value of =transient-display-buffer-action=. [[https://github.com/magit/transient/discussions/358][See this discussion]] for more context.

If you are using Helm, see [[https://github.com/magit/transient/discussions/361][Transient#361]].

In general, do not customize this Transient option unless you know what you're doing!

#+html:

**** Can I change the transient menu key bindings? #+html:

Yes, see =transient-suffix-put=. This changes the key to select a backend/model from "-m" to "M" in gptel's menu: #+begin_src emacs-lisp (transient-suffix-put 'gptel-menu (kbd "-m") :key "M") #+end_src

#+html:

**** (Doom Emacs) Sending a query from the gptel menu fails because of a key conflict with Org mode #+html:

Doom binds ~RET~ in Org mode to =+org/dwim-at-point=, which appears to conflict with gptel's transient menu bindings for some reason.

Two solutions:

Press ~C-m~ instead of the return key.
Change the send key from return to a key of your choice: #+begin_src emacs-lisp (transient-suffix-put 'gptel-menu (kbd "RET") :key " ") #+end_src

#+html:

*** Miscellaneous #+html:

**** I want to use gptel in a way that's not supported by =gptel-send= or the options menu #+html:

gptel's default usage pattern is simple, and will stay this way: Read input in any buffer and insert the response below it. Some custom behavior is possible with the transient menu (=C-u M-x gptel-send=).

For more programmable usage, gptel provides a general =gptel-request= function that accepts a custom prompt and a callback to act on the response. You can use this to build custom workflows not supported by =gptel-send=. See the documentation of =gptel-request=, and the [[https://github.com/karthink/gptel/wiki/Defining-custom-gptel-commands][wiki]] for examples.

#+html:

**** (ChatGPT) I get the error "(HTTP/2 429) You exceeded your current quota" #+html:

#+begin_quote (HTTP/2 429) You exceeded your current quota, please check your plan and billing details. #+end_quote

Using the ChatGPT (or any OpenAI) API requires [[https://platform.openai.com/account/billing/overview][adding credit to your account]].

#+html:

**** Why another LLM client? #+html:

Other Emacs clients for LLMs prescribe the format of the interaction (a comint shell, org-babel blocks, etc). I wanted:

Something that is as free-form as possible: query the model using any text in any buffer, and redirect the response as required. Using a dedicated =gptel= buffer just adds some visual flair to the interaction.
Integration with org-mode, not using a walled-off org-babel block, but as regular text. This way the model can generate code blocks that I can run.

#+html:

** Additional Configuration :PROPERTIES: :ID: f885adac-58a3-4eba-a6b7-91e9e7a17829 :END: #+html:

#+begin_src emacs-lisp :exports none :results list (let ((all)) (mapatoms (lambda (sym) (when (and (string-match-p "^gptel-[^-]" (symbol-name sym)) (get sym 'variable-documentation)) (push sym all)))) all) #+end_src

|-------------------------+--------------------------------------------------------------------| | Connection options | | |-------------------------+--------------------------------------------------------------------| | =gptel-use-curl= | Use Curl? (default), fallback to Emacs' built-in =url=. | | | You can also specify the Curl path here. | | =gptel-proxy= | Proxy server for requests, passed to curl via =--proxy=. | | =gptel-curl-extra-args= | Extra arguments passed to Curl. | | =gptel-api-key= | Variable/function that returns the API key for the active backend. | |-------------------------+--------------------------------------------------------------------|

|-----------------------+---------------------------------------------------------| | LLM request options | /(Note: not supported uniformly across LLMs)/ | |-----------------------+---------------------------------------------------------| | =gptel-backend= | Default LLM Backend. | | =gptel-model= | Default model to use, depends on the backend. | | =gptel-stream= | Enable streaming responses, if the backend supports it. | | =gptel-system-prompt= | Default system prompt used by gptel, can be a function. | | =gptel-directives= | Alist of system prompts, can switch on the fly. | | =gptel-max-tokens= | Maximum token count (in query + response). | | =gptel-temperature= | Randomness in response text, 0 to 2. | | =gptel-cache= | Cache prompts, system message or tools (Anthropic only) | | =gptel-use-context= | How/whether to include additional context | | =gptel-context= | List of context sources (files/buffers) for queries | | =gptel-use-tools= | Disable, allow or force LLM tool-use | | =gptel-tools= | List of tools to include with requests | |-----------------------+---------------------------------------------------------|

|--------------------------------+----------------------------------------------------------------| | Chat UI options | | |--------------------------------+----------------------------------------------------------------| | =gptel-default-mode= | Major mode for dedicated chat buffers. | | =gptel-highlight-methods= | Response highlighting used by =gptel-highlight-mode= | | =gptel-prompt-prefix-alist= | Text inserted before queries. | | =gptel-response-prefix-alist= | Text inserted before responses. | | =gptel-track-response= | Distinguish between user messages and LLM responses? | | =gptel-track-media= | Send text, images or other media from links? | | =gptel-markdown-validate-link= | Function to validate links to include with queries | | =gptel-confirm-tool-calls= | Confirm all tool calls? | | =gptel-include-tool-results= | Include tool results in the LLM response? | | =gptel-use-header-line= | Display status messages in header-line (default) or minibuffer | | =gptel-display-buffer-action= | Placement of the gptel chat buffer. | |--------------------------------+----------------------------------------------------------------|

|-------------------------------+-------------------------------------------------------| | Org mode UI options | | |-------------------------------+-------------------------------------------------------| | =gptel-org-branching-context= | Make each outline path a separate conversation branch | | =gptel-org-ignore-elements= | Ignore parts of the buffer when sending a query | | =gptel-org-validate-link= | Function to validate links to include with queries | |-------------------------------+-------------------------------------------------------|

|------------------------------------+-------------------------------------------------------------| | Hooks for customization | | |------------------------------------+-------------------------------------------------------------| | =gptel-save-state-hook= | Runs before saving the chat state to a file on disk | | =gptel-prompt-transform-functions= | Runs in a temp buffer to transform text before sending | | =gptel-post-request-hook= | Runs immediately after dispatching a =gptel-request=. | | =gptel-pre-response-hook= | Runs before inserting the LLM response into the buffer | | =gptel-post-response-functions= | Runs after inserting the full LLM response into the buffer | | =gptel-post-stream-hook= | Runs after each streaming insertion | | =gptel-pre-tool-call-functions= | Runs before each tool call, can block or modify it | | =gptel-post-tool-call-functions= | Runs after each tool call, can block or modify results | | =gptel-context-wrap-function= | To include additional context formatted your way | | =gptel-rewrite-default-action= | Automatically diff, ediff, merge or replace refactored text | | =gptel-post-rewrite-functions= | Runs after a =gptel-rewrite= request succeeds | |------------------------------------+-------------------------------------------------------------|

#+html:

*** Option presets

If you use several LLMs for different tasks with accompanying system prompts (instructions) and tool configurations, manually adjusting =gptel= settings each time can become tedious. Presets are a bundle of gptel settings -- such as the model, backend, system message, and enabled tools -- that you can switch to at once.

Once defined, presets can be applied from gptel's transient menu:

#+html: #+html:

To define a preset, use the =gptel-make-preset= function, which takes a name and keyword-value pairs of settings.

Presets can be used to set individual options. Here is an example of a preset to set the system message (and do nothing else): #+begin_src emacs-lisp (gptel-make-preset 'explain :system "Explain what this code does to a novice programmer.") #+end_src

More generally, you can specify a bundle of options: #+begin_src emacs-lisp (gptel-make-preset 'gpt4coding ;preset name, a symbol :description "A preset optimized for coding tasks" ;for your reference :backend "Claude" ;gptel backend or backend name :model 'claude-3-7-sonnet-20250219.1 :system "You are an expert coding assistant. Your role is to provide high-quality code solutions, refactorings, and explanations." :tools '("read_buffer" "modify_buffer")) ;gptel tools or tool names #+end_src

Besides a couple of special keys (=:description=, =:parents= to inherit other presets), there is no predefined list of keys. Instead, the key =:foo= corresponds to setting =gptel-foo= (preferred) or =gptel--foo=. So the preset can include the value of any gptel option. For example, the following preset sets =gptel-temperature=, =gptel-use-context= and =gptel-context=, a list of files to include as context:

#+begin_src emacs-lisp (gptel-make-preset 'proofreader :description "Preset for proofreading tasks" :backend "ChatGPT" :model 'gpt-4.1-mini :tools '("read_buffer" "spell_check" "grammar_check") :use-context 'system ;sets gptel-use-context :context '("./.grammar_rules.md" "./jargonfile.md") ;sets gptel-context :temperature 0.2) ;sets gptel-temperature #+end_src

Switching to a preset applies the specified settings without affecting other settings. Depending on the scope option (~=~ in gptel's transient menu), presets can be applied globally, buffer-locally or for the next request only.

**** Applying presets to requests automatically

You can apply a preset to a /single/ query by including =@preset-name= in the prompt, where =preset-name= is the name of the preset. (The =oneshot= scope option in gptel's transient menus is another way to do this, [[id:748cbc00-0c92-4705-8839-619b2c80e566][see the FAQ.]])

For example, if you have a preset named =websearch= defined which includes tools for web access and search: #+begin_src emacs-lisp (gptel-make-preset 'websearch :description "Haiku with basic web search capability." :backend "Claude" :model 'claude-3-5-haiku-20241022 :tools '("search_web" "read_url" "get_youtube_meta")) #+end_src

The following query is sent with this preset applied:

#+begin_quote @websearch Are there any 13" e-ink monitors on the market? Create a table comparing them, sourcing specs and reviews from online sources. Also do the same for "transreflective-LCD" displays -- I'm not sure what exactly they're called but they're comparable to e-ink. #+end_quote

This =@preset-name= cookie only applies to the final user turn of the coversation that is sent. So the presence of the cookie in past messages/turns is not significant.

The =@preset-name= cookie can be anywhere in the prompt. For example: #+begin_quote

What do you make of the above description, @proofreader? #+end_quote

In chat buffers this prefix will be offered as a completion and fontified, making it easy to use and spot.

** Alternatives

Other LLM clients for Emacs include

Libraries:

[[https://github.com/ahyatt/llm][llm]]: llm provides a uniform API across language model providers for building LLM clients in Emacs, and is intended as a library for use by package authors. For similar scripting purposes, gptel provides the command =gptel-request=.

Chat clients:

[[https://github.com/s-kostyaev/ellama][Ellama]]: A full-fledged LLM client built on llm, that supports many LLM providers (Ollama, Open AI, Vertex, GPT4All and more). Its usage differs from gptel in that it provides separate commands for dozens of common tasks, like general chat, summarizing code/text, refactoring code, improving grammar, translation and so on.
[[https://github.com/xenodium/chatgpt-shell][chatgpt-shell]]: comint-shell based interaction with ChatGPT. Also supports DALL-E, executable code blocks in the responses, and more.
[[https://github.com/rksm/org-ai][org-ai]]: Interaction through special =#+begin_ai ... #+end_ai= Org-mode blocks. Also supports DALL-E, querying ChatGPT with the contents of project files, and more.
[[https://github.com/yibie/superchat][Superchat]]: A Claude Code style chat UI for gptel in Emacs, focusing on making structured prompts and file‑grounded conversations effortless.

There are several more: [[https://github.com/iwahbe/chat.el][chat.el]], [[https://github.com/stuhlmueller/gpt.el][gpt.el]], [[https://github.com/AnselmC/le-gpt.el][le-gpt]], [[https://github.com/stevemolitor/robby][robby]].

Coding agents:

[[https://github.com/manzaltu/claude-code-ide.el][claude-code-ide]] and [[https://github.com/stevemolitor/claude-code.el][claude-code.el]]: Emacs interfaces to Claude Code.
[[https://github.com/xenodium/agent-shell][agent-shell]]: Emacs interface to various coding agents, like Claude Code, Gemini, Codex, Opencode, Goose and more.
[[https://github.com/MatthewZMD/aidermacs][Aidermacs]] and [[https://github.com/tninja/aider.el][aider.el]]: Emacs interfaces to [[https://aider.chat/][Aider]].

Completion at point:

[[https://github.com/copilot-emacs/copilot.el][copilot.el]]: Code completion using Copilot.
[[https://github.com/milanglacier/minuet-ai.el][Minuet]]: Code-completion using LLM. Supports fill-in-the-middle (FIM) completion for compatible models such as DeepSeek and Codestral.

*** Packages using gptel

gptel is a general-purpose package for chat and ad-hoc LLM interaction. The following packages use gptel to provide additional or specialized functionality:

Lookup helpers: Calling gptel quickly for one-off interactions

[[https://github.com/karthink/gptel-quick][gptel-quick]]: Quickly look up the region or text at point.

Task-driven workflows: Different interfaces to specify tasks for LLMs.

These differ from full "agentic" use in that the interactions are "one-shot", not chained.

[[https://github.com/dolmens/gptel-aibo/][gptel-aibo]]: A writing assistant system built on top of gptel.
[[https://github.com/daedsidog/evedel][Evedel]]: Instructed LLM Programmer/Assistant.
[[https://github.com/lanceberge/elysium][Elysium]]: Request AI-generated changes as you code.
[[https://github.com/ISouthRain/gptel-watch][gptel-watch]]: Automatically call gptel when typing lines that indicate intent.

Agentic use: Use LLMs as agents, with tool-use

[[https://github.com/kmontag/macher][Macher]]: Project-aware multi-file LLM editing for Emacs.
[[https://github.com/karthink/gptel-agent][gptel-agent]]: Tools, presets and configuration for general agentic LLM use.

Text completion

[[https://github.com/JDNdeveloper/gptel-autocomplete][gptel-autocomplete]]: Inline completions using gptel.

Integration with major-modes

[[https://github.com/jwiegley/ob-gptel][ob-gptel]]: Org-babel backend for running gptel queries.
[[https://github.com/kamushadenes/ai-blog.el][ai-blog.el]]: Streamline generation of blog posts in Hugo.
[[https://github.com/lakkiy/gptel-commit][gptel-commit]]: Generate commit messages using gptel.
[[https://github.com/douo/magit-gptcommit][magit-gptcommit]]: Generate commit messages within magit-status Buffer using gptel.
[[https://github.com/ragnard/gptel-magit/][gptel-magit]]: Generate commit messages for magit using gptel.
[[https://github.com/ArthurHeymans/gptel-forge-prs][gptel-forge-prs]]: Generate pull request message for forge using gptel.

Chat interface addons

[[https://github.com/rob137/Corsair][Corsair]]: Helps gather text to populate LLM prompts for gptel.
[[https://github.com/ultronozm/ai-org-chat.el][ai-org-chat]]: Provides branching conversations in Org buffers using gptel. Note that gptel includes this feature as well (see =gptel-org-branching-context=), but requires a recent version of Org mode 9.7 or later to be installed.

Integration with other packages

[[https://github.com/armindarvish/consult-omni][consult-omni]]: Versatile multi-source search package. It includes gptel as one of its many sources.

gptel configuration management

[[https://github.com/jwiegley/gptel-prompts][gptel-prompts]]: System prompt manager for gptel.

** COMMENT Older Breaking Changes

=gptel-post-response-hook= has been renamed to =gptel-post-response-functions=, and functions in this hook are now called with two arguments: the start and end buffer positions of the response. This should make it easy to act on the response text without having to locate it first.
Possible breakage, see #120: If streaming responses stop working for you after upgrading to v0.5, try reinstalling gptel and deleting its native comp eln cache in =native-comp-eln-load-path=.
The user option =gptel-host= is deprecated. If the defaults don't work for you, use =gptel-make-openai= to customize server settings.
=gptel-api-key-from-auth-source= now searches for the API key using the host address for the active LLM backend, /i.e./ "api.openai.com" when using ChatGPT. You may need to update your =~/.authinfo=.

** Acknowledgments

[[https://github.com/felipeochoa][Felipe Ochoa]] and [[https://github.com/akssri][akssri]] for adding AWS Bedrock support to gptel.
[[https://github.com/jwiegley][John Wiegley]] for the design of gptel's presets and gptel-request's async pipeline, but also for loads of general feedback and advice.
[[https://github.com/pabl0][Henrik Ahlgren]] for a keen eye to detail and polish applied to gptel's UI.
[[https://github.com/psionic-k][psionic-k]] for extensive testing of the tool use feature and the design of gptel's in-buffer tool use records.
[[https://github.com/jdtsmith][JD Smith]] for feedback and code assistance with gptel-menu's redesign
[[https://github.com/meain][Abin Simon]] for extensive feedback on improving gptel's directives and UI.
[[https://github.com/algal][Alexis Gallagher]] and [[https://github.com/d1egoaz][Diego Alvarez]] for fixing a nasty multi-byte bug with =url-retrieve=.
[[https://github.com/tarsius][Jonas Bernoulli]] for the Transient library.
[[https://github.com/daedsidog][daedsidog]] for adding context support to gptel.
[[https://github.com/Aquan1412][Aquan1412]] for adding PrivateGPT support to gptel.
[[https://github.com/r0man][r0man]] for improving gptel's Curl integration.

Local Variables:

toc-org-max-depth: 4

eval: (and (fboundp 'toc-org-mode) (toc-org-mode 1))

End:

doomemacs/core

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/core ~/.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 sync --env to include a snapshot of your shell environment that Doom will load at startup. This allows Emacs to inherit your PATH, among other things. This replaces exec-path-from-shell.
doom upgrade to update Doom to the latest release & all installed packages.
doom doctor to diagnose common issues with your system and config.

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.

Wilfred/elisp-refs

semantic code search for emacs lisp

elisp-refs

elisp-refs is an intelligent code search for Emacs lisp.

It can find references to functions, macros or variables. Unlike a dumb text search, elisp-refs actually parses the code, so it's never confused by comments or variables with the same name as functions.

This is particularly useful for finding all the places a function is used, or finding examples of usage.

Interested readers may enjoy my blog post: Searching A Million Lines Of Lisp.

Installation

Install from MELPA (recommended) or just add elisp-refs to your load-path.

Commands available

elisp-refs-function (find function calls)
elisp-refs-macro (find macro calls)
elisp-refs-variable (find variable references)
elisp-refs-special (find special form calls)
elisp-refs-symbol (find all references to a symbol)

These command search all the files currently loaded in your Emacs instance.

If called with a prefix, you can limit search results to specific directories. For example:

C-u M-x elisp-refs-macro RET pcase RET ~/.emacs.d/elpa/magit-20160927.510 RET

will search for uses of pcase in magit:

Semantic analysis

elisp-refs has street smarts: given (defun foo (bar) (baz)), it understands that bar is a variable and baz is a function.

elisp-refs understands the following forms:

defun defsubst defmacro cl-defun
lambda
let let*
funcall apply
sharp quoted expressions (e.g. #'some-func)

Limitations

elisp-refs understands elisp special forms, and a few common macros. However, it cannot understand arbitrary macros.

Therefore elisp-refs will assume that (other-macro (foo bar)) is a function call to foo. If this is incorrect, you may wish to use the command elisp-refs-symbol to find all references to the foo symbol.

If other-macro is a common macro, please consider submitting a patch to elisp-refs--function-p to make elisp-refs smarter.

elisp-refs also does not support indirect calls.

;; Since we do a simple syntax tree walk, this isn't treated as a
;; call to foo.
(let ((x (symbol-function 'foo)))
  (funcall x))

;; Similarly, indirect function calls are not treated as
;; function calls.
(defun call-func (x)
  (funcall x))
(call-func 'foo)

;; However, if you use sharp quoting, elisp-refs knows it's a function
reference!
(call-func #'foo)

Running tests

You can run the tests with:

$ cask install
$ cask exec ert-runner

Performance

elisp-refs is CPU-intensive elisp and has been carefully optimised. You can run the benchmark script with:

$ cask install
$ ./bench.sh

New features are carefully measured to ensure performance does not get worse.

See elisp-refs-bench.el for more details.

Alternative Projects

xref-find-references: This command is included in Emacs 25.1, but it's based on a text search. It is confused by comments and strings, and cannot distinguish between functions and variables.

xrefs-find-references is also line oriented, so it does not show the whole sexp that matched your search. Since it requires text files, it doesn't search built-in .el.gz files.

TAGS: It is possible to record function references in TAGS files. Whilst universal-ctags (formerly known as exuberant-ctags) does provide the ability to find references, it is not supported in its lisp parser.

etags, the TAGS implementation shipped with Emacs, cannot find references (to my knowledge).

el-search allows you to search for arbitrary forms in elisp files. It's slower, but a much more general tool. Its design greatly influenced elisp-refs.

elisp-slime-nav finds definitions, not references. It's a great complementary tool.

magit/forge

Work with Git forges from the comfort of Magit

** Work with Git forges from the comfort of Magit

Work with Git forges, such as Github and Gitlab, from the comfort of Magit and the rest of Emacs.

[[http://readme.emacsair.me/forge-status.png]]

[[http://readme.emacsair.me/forge-topic.png]]

Please see the [[https://docs.magit.vc/forge][manual]] and the [[https://emacsair.me/2018/12/19/forge-0.1][announcement]] for more information.

#+html:

#+html: #+html: #+html: #+html:

Wilfred/helpful

A better Emacs *help* buffer

Helpful

Helpful is an alternative to the built-in Emacs help that provides much more contextual information.

Usage

Install from MELPA, then call one of the following commands:

helpful-callable
helpful-function
helpful-macro
helpful-command
helpful-key
helpful-variable
helpful-at-point

If you want to replace the default Emacs help keybindings, you can do so:

;; Note that the built-in `describe-function' includes both functions
;; and macros. `helpful-function' is functions only, so we provide
;; `helpful-callable' as a drop-in replacement.
(global-set-key (kbd "C-h f") #'helpful-callable)

(global-set-key (kbd "C-h v") #'helpful-variable)
(global-set-key (kbd "C-h k") #'helpful-key)
(global-set-key (kbd "C-h x") #'helpful-command)

I also recommend the following keybindings to get the most out of helpful:

;; Lookup the current symbol at point. C-c C-d is a common keybinding
;; for this in lisp modes.
(global-set-key (kbd "C-c C-d") #'helpful-at-point)

;; Look up *F*unctions (excludes macros).
;;
;; By default, C-h F is bound to `Info-goto-emacs-command-node'. Helpful
;; already links to the manual, if a function is referenced there.
(global-set-key (kbd "C-h F") #'helpful-function)

Ivy users can use Helpful with counsel commands:

(setq counsel-describe-function-function #'helpful-callable)
(setq counsel-describe-variable-function #'helpful-variable)

Features

Source code

Helpful will try really hard to show the source code. It shows the source code for interactively defined functions (unlike the built-in Help) and falls back to the raw sexp if no source is available.

View Callers

Helpful will show you where a function is being called!

Prettier Docstrings

Docstrings in helpful:

Highlight the summary (the first sentence)
Include cross-references to other functions/variables
Linkify references to Info nodes
Hide superfluous punctuation

If a symbol is also documented in the Info manual, helpful will provide a link to the relevant section too.

Symbol Properties

Helpful will show you the properties that have been applied to the current symbol. This provides visibility of features like edebug or byte-code optimisation.

Helpful will also highlight any symbol aliases.

Describe Commands

Helpful provides a separate helpful-command function, for when you just want to view interactive functions.

View Keymaps

Helpful displays any keybindings that apply to interactive functions.

Integrated Tooling

You can trace, debug or disassemble functions from inside Helpful. This is discoverable and doesn't require memorisation of commands.

Aliases

If a function has multiple aliases in Emacs, Helpful will show all of the aliases defined.

Inspirations

This project has been heavily influenced by:

help+.el, help-fns+.el, help-mode+.el
Dave Williams' demo of Lucid's Energize

License

GPLv3+.

I am providing code in the repository to you under an open source license. Because this is my personal repository, the license you receive to my code is from me and not my employer.

org-roam/org-roam

Rudimentary Roam replica with Org-mode

Org-roam

Org-roam is a plain-text knowledge management system. It brings some of Roam's more powerful features into the Org-mode ecosystem.

Org-roam borrows principles from the Zettelkasten method, providing a solution for non-hierarchical note-taking. It should also work as a plug-and-play solution for anyone already using Org-mode for their personal wiki.

Private and Secure: Edit your personal wiki completely offline, entirely in your control. Encrypt your notes with GPG. Take lasting notes in plain-text.
Networked Thought: Connect notes and thoughts together with ease using backlinks. Discover surprising and previously unseen connections in your notes with the built-in graph visualization.
Extensible and Powerful: Leverage Emacs' fantastic text-editing interface, and the mature Emacs and Org-mode ecosystem of packages.
Free and Open Source: Org-roam is licensed under the GNU General Public License version 3 or later.

Installation

Down below you will find basic installation instructions for how to quickly install org-roam using various environments for various purposes. For more detailed information, please read the manual.

Using `package.el`

Toggle instructions

You can install org-roam from MELPA or MELPA Stable using package.el:

M-x package-install RET org-roam RET

Using `straight.el`

Toggle instructions

Installation from MELPA or MELPA Stable using straight.el:

(straight-use-package 'org-roam)

Or with use-package:

(use-package org-roam
  :straight t
  ...)

If you need to install the package directly from the source repository, instead of from MELPA, the next sample shows how to do so:

(use-package org-roam
  :straight (:host github :repo "org-roam/org-roam"
             :files (:defaults "extensions/*"))
  ...)

If you plan to use your own local fork for the development and contribution, the next sample will get you there:

(use-package org-roam
  :straight (:local-repo "/path/to/org-roam-fork"
             :files (:defaults "extensions/*")
             :build (:not compile))
  ...)

Using Doom Emacs

Toggle instructions

Doom's :lang org module comes with support for org-roam, but it's not enabled by default. To activate it pass +roam flag to org module in your $DOOMDIR/init.el (e.g. (org +roam)), save the file and run doom sync -u in your shell.

To provide better stability, Doom pins the package to a specific commit. If you need to unpin it (not recommended doing that, request Doom to bump the package instead) use the next in your packages.el:

(unpin! org-roam)

If for some reasons you want to use a different recipe for org-roam, you can use the next form in your packages.el to install the package from a recipe repository (e.g. MELPA):

(package! org-roam)

You can pass :pin "commit hash" to pin the package to a specific commit.

With the next sample you can install the package directly from the source repository:

(package! org-roam
  :recipe (:host github :repo "org-roam/org-roam"
           :files (:defaults "extensions/*")))

And if you plan to use your own local fork for the development or contribution, the next sample will get you there:

(package! org-roam
  :recipe (:local-repo "/path/to/org-roam-fork"
           :files (:defaults "extensions/*")
           :build (:not compile)))

Without a package manager

Toggle instructions

To install the package without using a package manager you have the next two options:

Install the package by cloning it with git from the source repository.
Or install the package by downloading the latest release version.

In both of the cases you will need to ensure that you have all the required dependencies. These include:

org (9.6 is the minimum required version!)
emacsql
magit-section

After installing the package, you will need to properly setup load-path to the package:

(add-to-list 'load-path "/path/to/org-roam/")
(add-to-list 'load-path "/path/to-org-roam/extensions/")

After which you should be able to resolve (require 'org-roam) call without any problems.

Org-roam also comes with .texi files to integrate with Emacs' built-in Info system. Read the manual to find more details for how to install them manually.

Configuration

Here's a very basic sample for configuration of org-roam using use-package:

(use-package org-roam
  :ensure t
  :custom
  (org-roam-directory (file-truename "/path/to/org-files/"))
  :bind (("C-c n l" . org-roam-buffer-toggle)
         ("C-c n f" . org-roam-node-find)
         ("C-c n g" . org-roam-graph)
         ("C-c n i" . org-roam-node-insert)
         ("C-c n c" . org-roam-capture)
         ;; Dailies
         ("C-c n j" . org-roam-dailies-capture-today))
  :config
  ;; If you're using a vertical completion framework, you might want a more informative completion interface
  (setq org-roam-node-display-template (concat "${title:*} " (propertize "${tags:10}" 'face 'org-tag)))
  (org-roam-db-autosync-mode)
  ;; If using org-roam-protocol
  (require 'org-roam-protocol))

Note that the file-truename function is only necessary when you use symbolic link to org-roam-directory. Org-roam won't automatically resolve symbolic link to the directory.

Getting Started

David Wilson of System Crafters has produced an introductory video that covers the basic commands:

Getting Help

Before creating a new topic/issue, please be mindful of our time and ensure that it has not already been addressed on GitHub or on Discourse.

If you are new to Emacs and have problem setting up Org-roam, please ask your question on Slack, channel #how-do-i.
For quick questions, please ask them on Slack, channel #troubleshooting.
If something is not working as it should, or if you would like to suggest a new feature, please create a new issue.
If you have questions about your workflow with the slip-box method, please find a relevant topic on Discourse, or create a new one.

Knowledge Bases using Org-roam

Contributing

To report bugs and suggest new feature use the issue tracker. If you have some code which you would like to be merged, then open a pull request. Please also see CONTRIBUTING.md.

License

oantolin/embark

Emacs Mini-Buffer Actions Rooted in Keymaps

#+TITLE: Embark: Emacs Mini-Buffer Actions Rooted in Keymaps #+AUTHOR: Omar Antolín Camarena #+OPTIONS: d:nil #+EXPORT_FILE_NAME: embark.texi #+TEXINFO_DIR_CATEGORY: Emacs misc features #+TEXINFO_DIR_TITLE: Embark: (embark). #+TEXINFO_DIR_DESC: Emacs Mini-Buffer Actions Rooted in Keymaps

#+html: #+html: #+html: #+html:

Overview

Embark makes it easy to choose a command to run based on what is near point, both during a minibuffer completion session (in a way familiar to Helm or Counsel users) and in normal buffers. Bind the command =embark-act= to a key and it acts like prefix-key for a keymap of /actions/ (commands) relevant to the /target/ around point. With point on an URL in a buffer you can open the URL in a browser or eww or download the file it points to. If while switching buffers you spot an old one, you can kill it right there and continue to select another. Embark comes preconfigured with over a hundred actions for common types of targets such as files, buffers, identifiers, s-expressions, sentences; and it is easy to add more actions and more target types. Embark can also collect all the candidates in a minibuffer to an occur-like buffer or export them to a buffer in a major-mode specific to the type of candidates, such as dired for a set of files, ibuffer for a set of buffers, or customize for a set of variables.

** Acting on targets

You can think of =embark-act= as a keyboard-based version of a right-click contextual menu. The =embark-act= command (which you should bind to a convenient key), acts as a prefix for a keymap offering you relevant /actions/ to use on a /target/ determined by the context:

In the minibuffer, the target is the current top completion candidate.
In the =Completions= buffer the target is the completion at point.
In a regular buffer, the target is the region if active, or else the file, symbol, URL, s-expression or defun at point.

Multiple targets can be present at the same location and you can cycle between them by repeating the =embark-act= key binding. The type of actions offered depend on the type of the target. Here is a sample of a few of the actions offered in the default configuration:

For files you get offered actions like deleting, copying, renaming, visiting in another window, running a shell command on the file, etc.
For buffers the actions include switching to or killing the buffer.
For package names the actions include installing, removing or visiting the homepage.
For Emacs Lisp symbols the actions include finding the definition, looking up documentation, evaluating (which for a variable immediately shows the value, but for a function lets you pass it some arguments first). There are some actions specific to variables, such as setting the value directly or though the customize system, and some actions specific to commands, such as binding it to a key.

By default when you use =embark-act= if you don't immediately select an action, after a short delay Embark will pop up a buffer showing a list of actions and their corresponding key bindings. If you are using =embark-act= outside the minibuffer, Embark will also highlight the current target. These behaviors are configurable via the variable =embark-indicators=. Instead of selecting an action via its key binding, you can select it by name with completion by typing =C-h= after =embark-act=.

Everything is easily configurable: determining the current target, classifying it, and deciding which actions are offered for each type in the classification. The above introduction just mentions part of the default configuration.

Configuring which actions are offered for a type is particularly easy and requires no programming: the variable =embark-keymap-alist= associates target types with variables containing keymaps, and those keymaps containing bindings for the actions. (To examine the available categories and their associated keymaps, you can use =C-h v embark-keymap-alist= or customize that variable.) For example, in the default configuration the type =file= is associated with the symbol =embark-file-map=. That symbol names a keymap with single-letter key bindings for common Emacs file commands, for instance =c= is bound to =copy-file=. This means that if you are in the minibuffer after running a command that prompts for a file, such as =find-file= or =rename-file=, you can copy a file by running =embark-act= and then pressing =c=.

These action keymaps are very convenient but not strictly necessary when using =embark-act=: you can use any command that reads from the minibuffer as an action and the target of the action will be inserted at the first minibuffer prompt. After running =embark-act= all of your key bindings and even =execute-extended-command= can be used to run a command. For example, if you want to replace all occurrences of the symbol at point, just use =M-%= as the action, there is no need to bind =query-replace= in one of Embark's keymaps. Also, those action keymaps are normal Emacs keymaps and you should feel free to bind in them whatever commands you find useful as actions and want to be available through convenient bindings.

The actions in =embark-general-map= are available no matter what type of completion you are in the middle of. By default this includes bindings to save the current candidate in the kill ring and to insert the current candidate in the previously selected buffer (the buffer that was current when you executed a command that opened up the minibuffer).

Emacs's minibuffer completion system includes metadata indicating the /category/ of what is being completed. For example, =find-file='s metadata indicates a category of =file= and =switch-to-buffer='s metadata indicates a category of =buffer=. Embark has the related notion of the /type/ of a target for actions, and by default when category metadata is present it is taken to be the type of minibuffer completion candidates when used as targets. Emacs commands often do not set useful category metadata so the [[https://github.com/minad/marginalia][Marginalia]] package, which supplies this missing metadata, is highly recommended for use with Embark.

Embark's default configuration has actions for the following target types: files, buffers, symbols, packages, URLs, bookmarks, and as a somewhat special case, actions for when the region is active. You can read about the [[https://github.com/oantolin/embark/wiki/Default-Actions][default actions and their key bindings]] on the GitHub project wiki.

** The default action on a target

Embark has a notion of default action for a target:

If the target is a minibuffer completion candidate, then the default action is whatever command opened the minibuffer in the first place. For example if you run =kill-buffer=, then the default action will be to kill buffers.
If the target comes from a regular buffer (i.e., not a minibuffer), then the default action is whatever is bound to =RET= in the keymap of actions for that type of target. For example, in Embark's default configuration for a URL found at point the default action is =browse-url=, because =RET= is bound to =browse-url= in the =embark-url-map= keymap.

To run the default action you can press =RET= after running =embark-act=. Note that if there are several different targets at a given location, each has its own default action, so first cycle to the target you want and then press =RET= to run the corresponding default action.

There is also =embark-dwim= which runs the default action for the first target found. It's pretty handy in non-minibuffer buffers: with Embark's default configuration it will:

Open the file at point.
Open the URL at point in a web browser (using the =browse-url= command).
Compose a new email to the email address at point.
In an Emacs Lisp buffer, if point is on an opening parenthesis or right after a closing one, it will evaluate the corresponding expression.
Go to the definition of an Emacs Lisp function, variable or macro at point.
Find the file corresponding to an Emacs Lisp library at point.

** Working with sets of possible targets

Besides acting individually on targets, Embark lets you work collectively on a set of target /candidates/. For example, while you are in the minibuffer the candidates are simply the possible completions of your input. Embark provides three main commands to work on candidate sets:

The =embark-act-all= command runs the same action on each of the current candidates. It is just like using =embark-act= on each candidate in turn. (Because you can easily act on many more candidates than you meant to, by default Embark asks you to confirm uses of =embark-act-all=; you can turn this off by setting the user option =embark-confirm-act-all= to =nil=.)
The =embark-collect= command produces a buffer listing all the current candidates, for you to peruse and run actions on at your leisure. The candidates are displayed as a list showing additional annotations. If any of the candidates contain newlines, then horizontal lines are used to separate candidates.

The Embark Collect buffer is somewhat "dired-like": you can select and deselect candidates through =embark-select= (available as an action in =embark-act=, bound to =SPC=; but you could also give it a global key binding). In an Embark Collect buffer =embark-act= is bound to =a= and =embark-act-all= is bound to =A=; =embark-act-all= will act on all currently marked candidates if there any, and will act on all candidates if none are marked. In particular, this means that =a SPC= will toggle whether the candidate at point is selected, and =A SPC= will select all candidates if none are selected, or deselect all selected candidates if there are some.
The =embark-export= command tries to open a buffer in an appropriate major mode for the set of candidates. If the candidates are files export produces a Dired buffer; if they are buffers, you get an Ibuffer buffer; and if they are packages you get a buffer in package menu mode.

If you use the grepping commands from the [[https://github.com/minad/consult/][Consult]] package, =consult-grep=, =consult-git-grep= or =consult-ripgrep=, then you should install the =embark-consult= package, which adds support for exporting a list of grep results to an honest grep-mode buffer, on which you can even use [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]] if you wish.

When in doubt choosing between exporting and collecting, a good rule of thumb is to always prefer =embark-export= since when an exporter to a special major mode is available for a given type of target, it will be more featureful than an Embark collect buffer, and if no such exporter is configured the =embark-export= command falls back to the generic =embark-collect=.

These commands are always available as "actions" (although they do not act on just the current target but on all candidates) for =embark-act= and are bound to =A=, =S= (for "snapshot"), and =E=, respectively, in =embark-general-map=. This means that you do not have to bind your own key bindings for these (although you can, of course!), just a key binding for =embark-act=.

In Embark Collect or Embark Export buffers that were obtained by running =embark-collect= or =embark-export= from within a minibuffer completion session, =g= is bound to a command that restarts the completion session, that is, the command that opened the minibuffer is run again and the minibuffer contents restored. You can then interact normally with the command, perhaps editing the minibuffer contents, and, if you wish, you can rerun =embark-collect= or =embark-export= to get an updated buffer.

*** Selecting some targets to make an ad hoc candidate set

The commands for working with sets of candidates just described, namely =embark-act-all=, =embark-export= and =embark-collect= by default work with all candidates defined in the current context. For example, in the minibuffer they operate on all currently completion candidates, or in a dired buffer they work on all marked files (or all files if none are marked). Embark also has a notion of /selection/, where you can accumulate an ad hoc list of targets for these commands to work on.

The selection is controlled by using the =embark-select= action, bound to =SPC= in =embark-general-map= so that it is always available (you can also give =embark-select= a global key binding if you wish; when called directly, not as an action for =embark-act=, it will select the first target at point). Calling this action on a target toggles its membership in the current buffer's Embark selection; that is, it adds it to selection if not selected and removes it from the selection if it was selected. Whenever the selection for a buffer is non-empty, the commands =embark-act-all=, =embark-export= and =embark-collect= will act on the selection.

To deselect all selected targets, you can use the =embark-select= action through =embark-act-all=, since this will run =embark-select= on each member of the current selection. Similarly if no targets are selected and you are in a minibuffer completion session, running =embark-select= from =embark-act-all= will select all the current completion candidates.

By default, whenever some targets are selected in the current buffer, a count of selected targets appears in the mode line. This can be turned off or customized through the =embark-selection-indicator= user option.

The selection functionality is supported in every buffer:

In the minibuffer this gives a convenient way to act on several completion candidates that don't follow any simple pattern: just go through the completions selecting the ones you want, then use =embark-act-all=. For example, you could attach several files at once to an email.
For Embark Collect buffers this functionality enables a dired-like workflow, in which you mark various candidates and apply an action to all at once. (It supersedes a previous ad hoc dired-like interface that was implemented only in Embark Collect buffers, with a slightly different interface.)
In a eww buffer you could use this to select various links you wish to follow up on, and then collect them into a buffer. Similarly, while reading Emacs's info manual you could select some symbols you want to read more about and export them to an =apropos-mode= buffer.
You can use selections in regular text or programming buffers to do complex editing operations. For example, if you have three paragraphs scattered over a file and you want to bring them together, you can select each one, insert them all somewhere and finally delete all of them (from their original locations).

*** =embark-live= a live-updating variant of =embark-collect=

Finally, there is also an =embark-live= variant of the =embark-collect= command which automatically updates the collection after each change in the source buffer. Users of a completion UI that automatically updates and displays the candidate list (such as Vertico, Icomplete, Fido-mode, or MCT) will probably not want to use =embark-live= from the minibuffer as they will then have two live updating displays of the completion candidates!

A more likely use of =embark-live= is to be called from a regular buffer to display a sort of live updating "table of contents" for the buffer. This depends on having appropriate candidate collectors configured in =embark-candidate-collectors=. There are not many in Embark's default configuration, but you can try this experiment: open a dired buffer in a directory that has very many files, mark a few, and run =embark-live=. You'll get an Embark Collect buffer containing only the marked files, which updates as you mark or unmark files in dired. To make =embark-live= genuinely useful other candidate collectors are required. The =embark-consult= package (documented near the end of this manual) contains a few: one for imenu items and one for outline headings as used by =outline-minor-mode=. Those collectors really do give =embark-live= a table-of-contents feel.

** Switching to a different command without losing what you've typed

Embark also has the =embark-become= command which is useful for when you run a command, start typing at the minibuffer and realize you meant a different command. The most common case for me is that I run =switch-to-buffer=, start typing a buffer name and realize I haven't opened the file I had in mind yet! I'll use this situation as a running example to illustrate =embark-become=. When this happens I can, of course, press =C-g= and then run =find-file= and open the file, but this requires retyping the portion of the file name you already typed. This process can be streamlined with =embark-become=: while still in the =switch-to-buffer= you can run =embark-become= and effectively make the =switch-to-buffer= command become =find-file= for this run.

You can bind =embark-become= to a key in =minibuffer-local-map=, but it is also available as an action under the letter =B= (uppercase), so you don't need a binding if you already have one for =embark-act=. So, assuming I have =embark-act= bound to, say, =C-.=, once I realize I haven't open the file I can type =C-. B C-x C-f= to have =switch-to-buffer= become =find-file= without losing what I have already typed in the minibuffer.

But for even more convenience, =embark-become= offers shorter key bindings for commands you are likely to want the current command to become. When you use =embark-become= it looks for the current command in all keymaps named in the list =embark-become-keymaps= and then activates all keymaps that contain it. For example, the default value of =embark-become-keymaps= contains a keymap =embark-become-file+buffer-map= with bindings for several commands related to files and buffers, in particular, it binds =switch-to-buffer= to =b= and =find-file= to =f=. So when I accidentally try to switch to a buffer for a file I haven't opened yet, =embark-become= finds that the command I ran, =switch-to-buffer=, is in the keymap =embark-become-file+buffer-map=, so it activates that keymap (and any others that also contain a binding for =switch-to-buffer=). The end result is that I can type =C-. B f= to switch to =find-file=.

Quick start

The easiest way to install Embark is from GNU ELPA, just run =M-x package-install RET embark RET=. (It is also available on MELPA.) It is highly recommended to also install [[https://github.com/minad/marginalia][Marginalia]] (also available on GNU ELPA), so that Embark can offer you preconfigured actions in more contexts. For =use-package= users, the following is a very reasonable starting configuration:

#+begin_src emacs-lisp (use-package marginalia :ensure t :config (marginalia-mode))

(use-package embark :ensure t

:bind
(("C-." . embark-act)         ;; pick some comfortable binding
 ("C-;" . embark-dwim)        ;; good alternative: M-.
 ("C-h B" . embark-bindings)) ;; alternative for `describe-bindings'

:init

;; Optionally replace the key help with a completing-read interface
(setq prefix-help-command #'embark-prefix-help-command)

;; Show the Embark target at point via Eldoc. You may adjust the
;; Eldoc strategy, if you want to see the documentation from
;; multiple providers. Beware that using this can be a little
;; jarring since the message shown in the minibuffer can be more
;; than one line, causing the modeline to move up and down:

;; (add-hook 'eldoc-documentation-functions #'embark-eldoc-first-target)
;; (setq eldoc-documentation-strategy #'eldoc-documentation-compose-eagerly)

;; Add Embark to the mouse context menu. Also enable `context-menu-mode'.
;; (context-menu-mode 1)
;; (add-hook 'context-menu-functions #'embark-context-menu 100)

:config

;; Hide the mode line of the Embark live/completions buffers
(add-to-list 'display-buffer-alist
             '("\\`\\*Embark Collect \\(Live\\|Completions\\)\\*"
               nil
               (window-parameters (mode-line-format . none)))))

;; Consult users will also want the embark-consult package. (use-package embark-consult :ensure t) ; only need to install it, embark loads it after consult if found #+end_src

About the suggested key bindings for =embark-act= and =embark-dwim=:

Those key bindings are unlikely to work in the terminal, but terminal users are probably well aware of this and will know to select different bindings.
The suggested =C-.= binding is used by default in (at least some installations of) GNOME to input emojis, and Emacs doesn't even get a chance to respond to the binding. You can select a different key binding for =embark-act= or use =ibus-setup= to change the shortcut for emoji insertion (Emacs 29 uses =C-x 8 e e=, in case you want to set the same one system-wide).
The suggested alternative of =M-.= for =embark-dwim= is bound by default to =xref-find-definitions=. That is a very useful command but overwriting it with =embark-dwim= is sensible since in Embark's default configuration, =embark-dwim= will also find the definition of the identifier at point. (Note that =xref-find-definitions= with a prefix argument prompts you for an identifier, =embark-dwim= does not cover this case).

Other Embark commands such as =embark-act-all=, =embark-become=, =embark-collect=, and =embark-export= can be run through =embark-act= as actions bound to =A=, =B=, =S= (for "snapshot"), and =E= respectively, and thus don't really need a dedicated key binding, but feel free to bind them directly if you so wish. If you do choose to bind them directly, you'll probably want to bind them in =minibuffer-local-map=, since they are most useful in the minibuffer (in fact, =embark-become= only works in the minibuffer).

The command =embark-dwim= executes the default action at point. Another good keybinding for =embark-dwim= is =M-.= since =embark-dwim= acts like =xref-find-definitions= on the symbol at point. =C-.= can be seen as a right-click context menu at point and =M-.= acts like left-click. The keybindings are mnemonic, both act at the point (=.=).

Embark needs to know what your minibuffer completion system considers to be the list of candidates and which one is the current candidate. Embark works out of the box if you use Emacs's default tab completion, the built-in =icomplete-mode= or =fido-mode=, or the third-party packages [[https://github.com/minad/vertico][Vertico]] or [[https://github.com/abo-abo/swiper][Ivy]].

If you are a [[https://emacs-helm.github.io/helm/][Helm]] or [[https://github.com/abo-abo/swiper][Ivy]] user you are unlikely to want Embark since those packages include comprehensive functionality for acting on minibuffer completion candidates. (Embark does come with Ivy integration despite this.)

Advanced configuration ** Showing information about available targets and actions

By default, if you run =embark-act= and do not immediately select an action, after a short delay Embark will pop up a buffer called =Embark Actions= containing a list of available actions with their key bindings. You can scroll that buffer with the mouse of with the usual commands =scroll-other-window= and =scroll-other-window-down= (bound by default to =C-M-v= and =C-M-S-v=).

That functionality is provided by the =embark-mixed-indicator=, but Embark has other indicators that can provide information about the target and its type, what other targets you can cycle to, and which actions have key bindings in the action map for the current type of target. Any number of indicators can be active at once and the user option =embark-indicators= should be set to a list of the desired indicators.

Embark comes with the following indicators:

=embark-minimal-indicator=: shows a messages in the echo area or minibuffer prompt showing the current target and the types of all targets starting with the current one.
=embark-highlight-indicator=: highlights the target at point; on by default.
=embark-verbose-indicator=: displays a table of actions and their key bindings in a buffer; this is not on by default, in favor of the mixed indicator described next.
=embark-mixed-indicator=: starts out by behaving as the minimal indicator but after a short delay acts as the verbose indicator; this is on by default.
=embark-isearch-highlight-indicator=: this only does something when the current target is the symbol at point, in which case it lazily highlights all occurrences of that symbol in the current buffer, like isearch; also on by default.

Users of the popular [[https://github.com/justbur/emacs-which-key][which-key]] package may prefer to use the =embark-which-key-indicator= from the [[https://github.com/oantolin/embark/wiki/Additional-Configuration#use-which-key-like-a-key-menu-prompt][Embark wiki]]. Just copy its definition from the wiki into your configuration and customize the =embark-indicators= user option to exclude the mixed and verbose indicators and to include =embark-which-key-indicator=.

If you use [[https://github.com/minad/vertico][Vertico]], there is an even easier way to get a =which-key=-like display that also lets you use completion to narrow down the list of alternatives, described at the end of the next section.

** Selecting commands via completions instead of key bindings

As an alternative to reading the list of actions in the verbose or mixed indicators (see the previous section for a description of these), you can press the =embark-help-key=, which is =C-h= by default (but you may prefer =?= to free up =C-h= for use as a prefix) after running =embark-act=. Pressing the help key will prompt you for the name of an action with completion (but feel free to enter a command that is not among the offered candidates!), and will also remind you of the key bindings. You can press =embark-keymap-prompter-key=, which is =@= by default, at the prompt and then one of the key bindings to enter the name of the corresponding action.

You may think that with the =Embark Actions= buffer popping up to remind you of the key bindings you'd never want to use completion to select an action by name, but personally I find that typing a small portion of the action name to narrow down the list of candidates feels significantly faster than visually scanning the entire list of actions.

If you find you prefer selecting actions that way, you can configure embark to always prompt you for actions by setting the variable =embark-prompter= to =embark-completing-read-prompter=.

On the other hand, you may wish to continue using key bindings for the actions you perform most often, and to use completion only to explore what further actions are available or when you've forgotten a key binding. In that case, you may prefer to use the minimal indicator, which does not pop-up an =Embark Actions= buffer at all, and to use the =embark-help-key= whenever you need help. This unobtrusive setup is achieved with the following configuration:

#+begin_src emacs-lisp (setq embark-indicators '(embark-minimal-indicator ; default is embark-mixed-indicator embark-highlight-indicator embark-isearch-highlight-indicator)) #+end_src

[[https://github.com/minad/vertico][Vertico]] users may wish to configure a grid display for the actions and key-bindings, reminiscent of the popular package [[https://github.com/justbur/emacs-which-key][which-key]], but, of course, enhanced by the use of completion to narrow the list of commands. In order to get the grid display, put the following in your Vertico configuration:

#+begin_src emacs-lisp (add-to-list 'vertico-multiform-categories '(embark-keybinding grid)) (vertico-multiform-mode) #+end_src

This will make the available keys be shown in a compact grid like in =which-key=. The =vertico-multiform-mode= also enables keys such as =M-V=, =M-G=, =M-B=, and =M-U= for manually switching between layouts in Vertico buffers.

*** Selecting commands via completion outside of Embark

If you like this completion interface for exploring key bindings for Embark actions, you may want to use it elsewhere in Emacs. You can use Embark's completion-based command prompter to list:

key bindings under a prefix,
local key bindings, or
all key bindings.

To use it for key bindings under a prefix (you can use this to replace the =which-key= package, for example), use this configuration:

#+begin_src emacs-lisp (setq prefix-help-command #'embark-prefix-help-command) #+end_src

Now, when you have started on a prefix sequence such as =C-x= or =C-c=, pressing =C-h= will bring up the Embark version of the built-in =prefix-help-command=, which will list the keys under that prefix and their bindings, and lets you select the one you wanted with completion, or by key binding if you press =embark-keymap-prompter-key=.

If you like this kind of prefix help, but want it to appear automatically after a delay, like =which-key-mode= does by default, you can use =embark-auto-prefix-help-mode= (independently of whether you also use the above setting for =prefix-help-command= or not).

To list local or global key bindings, use the command =embark-bindings=. You can bind that to =C-h b=, which is the default key binding for the built-in =describe-bindings= command, which this command can replace. By default, =embark-bindings= lists local key bindings, typically those bound in the major mode keymap; to get global bindings as well, call it with a =C-u= prefix argument.

** Quitting the minibuffer after an action

By default, if you call =embark-act= from the minibuffer it quits the minibuffer after performing the action. You can change this by setting the user option =embark-quit-after-action= to =nil=. Having =embark-act= /not/ quit the minibuffer can be useful to turn commands into little "thing managers". For example, you can use =find-file= as a little file manager or =describe-package= as a little package manager: you can run those commands, perform a series of actions, and then quit the command.

If you want to control the quitting behavior in a fine-grained manner depending on the action, you can set =embark-quit-after-action= to an alist, associating commands to either =t= for quitting or =nil= for not quitting. When using an alist, you can use the special key =t= to specify the default behavior. For example, to specify that by default actions should not quit the minibuffer but that using =kill-buffer= as an action should quit, you can use the following configuration:

#+begin_src emacs-lisp (setq embark-quit-after-action '((kill-buffer . t) (t . nil))) #+end_src

The variable =embark-quit-after-action= only specifies a default, that is, it only controls whether or not =embark-act= quits the minibuffer when you call it without a prefix argument, and you can select the opposite behavior to what the variable says by calling =embark-act= with =C-u=. Also note that both the variable =embark-quit-after-action= and =C-u= have no effect when you call =embark-act= outside the minibuffer.

If you find yourself using the quitting and non-quitting variants of =embark-act= about equally often, independently of the action, you may prefer to simply have separate commands for them instead of a single command that you call with =C-u= half the time. You could, for example, keep the default exiting behavior of =embark-act= and define a non-quitting version as follows:

#+begin_src emacs-lisp (defun embark-act-noquit () "Run action but don't quit the minibuffer afterwards." (interactive) (let ((embark-quit-after-action nil)) (embark-act))) #+end_src

** Recording acted-on minibuffer candidates in minibuffer history

Confirming minibuffer input with =RET= records the selected candidate in the appropriate history list. The user option =embark-record-minibuffer-history= controls how Embark records acted-on candidates. This option accepts three kinds of values: =t= (always record), =nil= (never record), or =(skip ACTIONS...)= to record for everything except the listed actions. The default is a =skip= form that excludes meta commands such as =embark-export=.

** Running some setup after injecting the target

You can customize what happens after the target is inserted at the minibuffer prompt of an action. There are =embark-target-injection-hooks=, that are run by default after injecting the target into the minibuffer. The variable =embark-target-injection-hooks= is an alist associating commands to their setup hooks. There are two special keys: if no setup hook is specified for a given action, the hook associated to =t= is run; and the hook associated to =:always= is run regardless of the action. (This variable used to have the less explicit name of =embark-setup-action-hooks=, so please update your configuration.)

For example, consider using =shell-command= as an action during file completion. It would be useful to insert a space before the target file name and to leave the point at the beginning, so you can immediately type the shell command to run on that file. That's why in Embark's default configuration there is an entry in =embark-target-injection-hooks= associating =shell-command= to a hook that includes =embark--shell-prep=, a simple helper function that quotes all the spaces in the file name, inserts an extra space at the beginning of the line and leaves point to the left of it.

Now, the preparation that =embark--shell-prep= does would be useless if Embark did what it normally does after it inserts the target of the action at the minibuffer prompt, which is to "press =RET=" for you, accepting the target as is; if Embark did that for =shell-command= you wouldn't get a chance to type in the command to execute! That is why in Embark's default configuration the entry for =shell-command= in =embark-target-injection-hooks= also contains the function =embark--allow-edit=.

Embark used to have a dedicated variable =embark-allow-edit-actions= to which you could add commands for which Embark should forgo pressing =RET= for you after inserting the target. Since its effect can also be achieved via the general =embark-target-injection-hooks= mechanism, that variable has been removed to simplify Embark. Be sure to update your configuration; if you had something like:

#+begin_src emacs-lisp (add-to-list 'embark-allow-edit-actions 'my-command) #+end_src

you should replace it with:

#+begin_src emacs-lisp (push 'embark--allow-edit (alist-get 'my-command embark-target-injection-hooks)) #+end_src

Also note that while you could abuse =embark--allow-edit= so that you have to confirm "dangerous" actions such as =delete-file=, it is better to implement confirmation by adding the =embark--confirm= function to the appropriate entry of a different hook alist, namely, =embark-pre-action-hooks=.

Besides =embark--allow-edit=, Embark comes with another function that is of general utility in action setup hooks: =embark--ignore-target=. Use it for commands that do prompt you in the minibuffer but for which inserting the target would be inappropriate. This is not a common situation but does occasionally arise. For example it is used by default for =shell-command-on-region=: that command is used as an action for region targets, and it prompts you for a shell command; you typically do /not/ want the target, that is the contents of the region, to be entered at that prompt!

** Running hooks before, after or around an action

Embark has three variables, =embark-pre-action-hooks=, =embark-post-action-hooks= and =embark-around-action-hooks=, which are alists associating commands to hooks that should run before or after or as around advice for the command when used as an action. As with =embark-target-injection-hooks=, there are two special keys for the alists: =t= designates the default hook to run when no specific hook is specified for a command; and the hook associated to =:always= runs regardless.

The default values of those variables are fairly extensive, adding creature comforts to make running actions a smooth experience. Embark comes with several functions intended to be added to these hooks, and used in the default values of =embark-pre-action-hooks=, =embark-post-action-hooks= and =embark-around-action-hooks=.

For pre-action hooks:

=embark--confirm= :: Prompt the user for confirmation before executing the action. This is used be default for commands deemed "dangerous", or, more accurately, hard to undo, such as =delete-file= and =kill-buffer=.
=embark--unmark-target= :: Unmark the active region. Use this for commands you want to act on the region contents but without the region being active. The default configuration uses this function as a pre-action hook for =occur= and =query-replace=, for example, so that you can use them as actions with region targets to search the whole buffer for the text contained in the region. Without this pre-action hook using =occur= as an action for a region target would be pointless: it would search for the the region contents /in the region/, (typically, due to the details of regexps) finding only one match!
=embark--beginning-of-target= :: Move to the beginning of the target (for targets that report bounds). This is used by default for backward motion commands such as =backward-sexp=, so that they don't accidentally leave you on the current target.
=embark--end-of-target= :: Move to the end of the target. This is used similarly to the previous function, but also for commands that act on the last s-expression like =eval-last-sexp=. This allow you to act on an s-expression from anywhere inside it and still use =eval-last-sexp= as an action.
=embark--xref-push-markers= :: Push the current location on the xref marker stack. Use this for commands that take you somewhere and for which you'd like to be able to come back to where you were using =xref-pop-marker-stack=. This is used by default for =find-library=.

For post-action hooks:

=embark--restart= :: Restart the command currently prompting in the minibuffer, so that the list of completion candidates is updated. This is useful as a post action hook for commands that delete or rename a completion candidate; for example the default value of =embark-post-action-hooks= uses it for =delete-file=, =kill-buffer=, =rename-file=, =rename-buffer=, etc.

For around-action hooks:

=embark--mark-target= :: Save existing mark and point location, mark the target and run the action. Most targets at point outside the minibuffer report which region of the buffer they correspond to (this is the information used by =embark-highlight-indicator= to know what portion of the buffer to highlight); this function marks that region. It is useful as an around action hook for commands that expect a region to be marked, for example, it is used by default for =indent-region= so that it works on s-expression targets, or for =fill-region= so that it works on paragraph targets.
=embark--cd= :: Run the action with =default-directory= set to the directory associated to the current target. The target should be of type =file=, =buffer=, =bookmark= or =library=, and the associated directory is what you'd expect in each case.
=embark--narrow-to-target= :: Run the action with buffer narrowed to current target. Use this as an around hook to localize the effect of actions that don't already work on just the region. In the default configuration it is used for =repunctuate-sentences=.
=embark--save-excursion= :: Run the action restoring point at the end. The current default configuration doesn't use this but it is available for users.

** Creating your own keymaps

All internal keymaps are defined with the standard helper macro =defvar-keymap=. For example a simple version of the file action keymap could be defined as follows:

#+BEGIN_SRC emacs-lisp (defvar-keymap embark-file-map :doc "Example keymap with a few file actions" :parent embark-general-map "d" #'delete-file "r" #'rename-file "c" #'copy-file) #+END_SRC

These action keymaps are perfectly normal Emacs keymaps. You may want to inherit from the =embark-general-map= if you want to access the default Embark actions. Note that =embark-collect= and =embark-export= are also made available via =embark-general-map=.

** Defining actions for new categories of targets

It is easy to configure Embark to provide actions for new types of targets, either in the minibuffer or outside it. I present below two very detailed examples of how to do this. At several points I'll explain more than one way to proceed, typically with the easiest option first. I include the alternative options since there will be similar situations where the easiest option is not available.

*** New minibuffer target example - tab-bar tabs

As an example let us take a look at the [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Tab-Bars.html][tab bars]]. I'll explain how to configure Embark to offer tab-specific actions when you use the tab-bar-mode commands that mention tabs by name. The configuration explained here is now built-in to Embark (and Marginalia), but it's still a good self-contained example. In order to setup up tab actions you would need to: (1) make sure Embark knows those commands deal with tabs, (2) define a keymap for tab actions and configure Embark so it knows that's the keymap you want.

**** Telling Embark about commands that prompt for tabs by name

For step (1), it would be great if the =tab-bar-mode= commands reported the completion category =tab= when asking you for a tab with completion. (All built-in Emacs commands that prompt for file names, for example, do have metadata indicating that they want a =file=.) They do not, unfortunately, and I will describe a couple of ways to deal with this.

Maybe the easiest thing is to configure [[https://github.com/minad/marginalia][Marginalia]] to enhance those commands. All of the =tab-bar-*-tab-by-name= commands have the words "tab by name" in the minibuffer prompt, so you can use:

#+begin_src emacs-lisp (add-to-list 'marginalia-prompt-categories '("tab by name" . tab)) #+end_src

That's it! But in case you are ever in a situation where you don't already have commands that prompt for the targets you want, I'll describe how writing your own command with appropriate =category= metadata looks:

#+begin_src emacs-lisp (defun my-select-tab-by-name (tab) (interactive (list (let ((tab-list (or (mapcar (lambda (tab) (cdr (assq 'name tab))) (tab-bar-tabs)) (user-error "No tabs found")))) (completing-read "Tabs: " (lambda (string predicate action) (if (eq action 'metadata) '(metadata (category . tab)) (complete-with-action action tab-list string predicate))))))) (tab-bar-select-tab-by-name tab)) #+end_src

As you can see, the built-in support for setting the category meta-datum is not very easy to use or pretty to look at. To help with this I recommend the =consult--read= function from the excellent [[https://github.com/minad/consult/][Consult]] package. With that function we can rewrite the command as follows:

#+begin_src emacs-lisp (defun my-select-tab-by-name (tab) (interactive (list (let ((tab-list (or (mapcar (lambda (tab) (cdr (assq 'name tab))) (tab-bar-tabs)) (user-error "No tabs found")))) (consult--read tab-list :prompt "Tabs: " :category 'tab)))) (tab-bar-select-tab-by-name tab)) #+end_src

Much nicer! No matter how you define the =my-select-tab-by-name= command, the first approach with Marginalia and prompt detection has the following advantages: you get the =tab= category for all the =tab-bar-*-bar-by-name= commands at once, also, you enhance built-in commands, instead of defining new ones.

**** Defining and configuring a keymap for tab actions

Let's say we want to offer select, rename and close actions for tabs (in addition to Embark general actions, such as saving the tab name to the kill-ring, which you get for free). Then this will do:

#+begin_src emacs-lisp (defvar-keymap embark-tab-actions :doc "Keymap for actions for tab-bar tabs (when mentioned by name)." :parent embark-general-map "s" #'tab-bar-select-tab-by-name "r" #'tab-bar-rename-tab-by-name "k" #'tab-bar-close-tab-by-name)

(add-to-list 'embark-keymap-alist '(tab . embark-tab-actions)) #+end_src

What if after using this for a while you feel closing the tab without confirmation is dangerous? You have a couple of options:

You can keep using the =tab-bar-close-tab-by-name= command, but have Embark ask you for confirmation: #+begin_src emacs-lisp (push #'embark--confirm (alist-get 'tab-bar-close-tab-by-name embark-pre-action-hooks)) #+end_src
You can write your own command that prompts for confirmation and use that instead of =tab-bar-close-tab-by-name= in the above keymap: #+begin_src emacs-lisp (defun my-confirm-close-tab-by-name (tab) (interactive "sTab to close: ") (when (y-or-n-p (format "Close tab '%s'? " tab)) (tab-bar-close-tab-by-name tab))) #+end_src

Notice that this is a command you can also use directly from =M-x= independently of Embark. Using it from =M-x= leaves something to be desired, though, since you don't get completion for the tab names. You can fix this if you wish as described in the previous section.

*** New target example in regular buffers - short Wikipedia links

Say you want to teach Embark to treat text of the form =wikipedia:Garry_Kasparov= in any regular buffer as a link to Wikipedia, with actions to open the Wikipedia page in eww or an external browser or to save the URL of the page in the kill-ring. We can take advantage of the actions that Embark has preconfigured for URLs, so all we need to do is teach Embark that =wikipedia:Garry_Kasparov= stands for the URL =https://en.wikipedia.org/wiki/Garry_Kasparov=.

You can be as fancy as you want with the recognized syntax. Here, to keep the example simple, I'll assume the link matches the regexp =wikipedia:[[:alnum:]_]+=. We will write a function that looks for a match surrounding point, and returns a dotted list of the form ='(url URL-OF-THE-PAGE START . END)= where =START= and =END= are the buffer positions bounding the target, and are used by Embark to highlight it if you have =embark-highlight-indicator= included in the list =embark-indicators=. (There are a couple of other options for the return value of a target finder: the bounding positions are optional and a single target finder is allowed to return multiple targets; see the documentation for =embark-target-finders= for details.)

#+begin_src emacs-lisp (defun my-short-wikipedia-link () "Target a link at point of the form wikipedia:Page_Name." (save-excursion (let* ((start (progn (skip-chars-backward "[:alnum:]😊 (point))) (end (progn (skip-chars-forward "[:alnum:]😊 (point))) (str (buffer-substring-no-properties start end))) (save-match-data (when (string-match "wikipedia:$[[:alnum:]_]+$" str) `(url ,(format "https://en.wikipedia.org/wiki/%s" (match-string 1 str)) ,start . ,end))))))

(add-to-list 'embark-target-finders 'my-short-wikipedia-link) #+end_src

How does Embark call the actions?

Embark actions are normal Emacs commands, that is, functions with an interactive specification. In order to execute an action, Embark calls the command with =call-interactively=, so the command reads user input exactly as if run directly by the user. For example the command may open a minibuffer and read a string (=read-from-minibuffer=) or open a completion interface (=completing-read=). If this happens, Embark takes the target string and inserts it automatically into the minibuffer, simulating user input this way. After inserting the string, Embark exits the minibuffer, submitting the input. (The immediate minibuffer exit can be disabled for specific actions in order to allow editing the input; this is done by adding the =embark--allow-edit= function to the appropriate entry of =embark-target-injection-hooks=). Embark inserts the target string at the first minibuffer opened by the action command, and if the command happens to prompt the user for input more than once, the user still interacts with the second and further prompts in the normal fashion. Note that if a command does not prompt the user for input in the minibuffer, Embark still allows you to use it as an action, but of course, never inserts the target anywhere. (There are plenty of examples in the default configuration of commands that do not prompt the user bound to keys in the action maps, most of the region actions, for instance.)

This is how Embark manages to reuse normal commands as actions. The mechanism allows you to use as Embark actions commands that were not written with Embark in mind (and indeed almost all actions that are bound by default in Embark's action keymaps are standard Emacs commands). It also allows you to write new custom actions in such a way that they are useful even without Embark.

Emacs has a variable =y-or-n-p-use-read-key=, which when set to =t= causes =y-or-n-p= to use =read-key= instead of =read-from-minibuffer=. Setting =y-or-n-p-use-read-key= to =t= is recommended for Embark users because it keeps Embark from attempting to insert the target at a =y-or-n-p= prompt, which would almost never be sensible. Also consider this as a warning to structure your own action commands so that if they use =y-or-n-p=, they do so only after the prompting for the target.

Here is a simple example illustrating the various ways of reading input from the user mentioned above. Bind the following commands to the =embark-symbol-map= to be used as actions, then put the point on some symbol and run them with =embark-act=:

#+begin_src emacs-lisp (defun example-action-command1 () (interactive) (message "The input was `%s'." (read-from-minibuffer "Input: ")))

(defun example-action-command2 (arg input1 input2) (interactive "P\nsInput 1: \nsInput 2: ") (message "The first input %swas %s', and the second was %s'." (if arg "truly " "") input1 input2))

(defun example-action-command3 () (interactive) (message "Your selection was `%s'." (completing-read "Select: " '("E" "M" "B" "A" "R" "K"))))

(defun example-action-command4 () (interactive) (message "I don't prompt you for input and thus ignore the target!"))

(keymap-set embark-symbol-map "X 1" #'example-action-command1) (keymap-set embark-symbol-map "X 2" #'example-action-command2) (keymap-set embark-symbol-map "X 3" #'example-action-command3) (keymap-set embark-symbol-map "X 4" #'example-action-command4) #+end_src

Also note that if you are using the key bindings to call actions, you can pass prefix arguments to actions in the normal way. For example, you can use =C-u X2= with the above demonstration actions to make the message printed by =example-action-command2= more emphatic. This ability to pass prefix arguments to actions is useful for some actions in the default configuration, such as =embark-shell-command-on-buffer=.

** Non-interactive functions as actions

Alternatively, Embark does support one other type of action: a non-interactive function of a single argument. The target is passed as argument to the function. For example:

#+begin_src emacs-lisp (defun example-action-function (target) (message "The target was `%s'." target))

(keymap-set embark-symbol-map "X 4" #'example-action-function)

#+end_src

Note that normally binding non-interactive functions in a keymap is useless, since when attempting to run them using the key binding you get an error message similar to "Wrong type argument: commandp, example-action-function". In general it is more flexible to write any new Embark actions as commands, that is, as interactive functions, because that way you can also run them directly, without Embark. But there are a couple of reasons to use non-interactive functions as actions:

You may already have the function lying around, and it is convenient to simply reuse it.
For command actions the targets can only be simple string, with no text properties. For certain advanced uses you may want the action to receive a string /with/ some text properties, or even a non-string target.

Embark, Marginalia and Consult

Embark cooperates well with the [[https://github.com/minad/marginalia][Marginalia]] and [[https://github.com/minad/consult][Consult]] packages. Neither of those packages is a dependency of Embark, but both are highly recommended companions to Embark, for opposite reasons: Marginalia greatly enhances Embark's usefulness, while Embark can help enhance Consult.

In the remainder of this section I'll explain what exactly Marginalia does for Embark, and what Embark can do for Consult.

** Marginalia

Embark comes with actions for symbols (commands, functions, variables with actions such as finding the definition, looking up the documentation, evaluating, etc.) in the =embark-symbol-map= keymap, and for packages (actions like install, delete, browse url, etc.) in the =embark-package-keymap=.

Unfortunately Embark does not automatically offers you these keymaps when relevant, because many built-in Emacs commands don't report accurate category metadata. For example, a command like =describe-package=, which reads a package name from the minibuffer, does not have metadata indicating this fact.

In an earlier Embark version, there were functions to supply this missing metadata, but they have been moved to Marginalia, which augments many Emacs command to report accurate category metadata. Simply activating =marginalia-mode= allows Embark to offer you the package and symbol actions when appropriate again. Candidate annotations in the Embark collect buffer are also provided by the Marginalia package:

If you install Marginalia and activate =marginalia-mode=, Embark Collect buffers will use the Marginalia annotations automatically.
If you don't install Marginalia, you will see only the annotations that come with Emacs (such as key bindings in =M-x=, or the unicode characters in =C-x 8 RET=).

** Consult

The excellent Consult package provides many commands that use minibuffer completion, via the =completing-read= function; plenty of its commands can be considered enhanced versions of built-in Emacs commands, and some are completely new functionality. One common enhancement provided in all commands for which it makes sense is preview functionality, for example =consult-buffer= will show you a quick preview of a buffer before you actually switch to it.

If you use both Consult and Embark you should install the =embark-consult= package which provides integration between the two. It provides exporters for several Consult commands and also tweaks the behavior of many Consult commands when used as actions with =embark-act= in subtle ways that you may not even notice, but make for a smoother experience. You need only install it to get these benefits: Embark will automatically load it after Consult if found.

The =embark-consult= package provides the following exporters:

You can use =embark-export= from =consult-line=, =consult-outline=, or =consult-mark= to obtain an =occur-mode= buffer. As with the built-in =occur= command you use that buffer to jump to a match and after that, you can then use =next-error= and =previous-error= to navigate to other matches. You can also press =e= to activate =occur-edit-mode= and edit the matches in place!
You can export from any of the Consult asynchronous search commands, =consult-grep=, =consult-git-grep=, or =consult-ripgrep= to get a =grep-mode= buffer. Here too you can use =next-error= and =previous-error= to navigate among matches, and, if you install the [[http://github.com/mhayashi1120/Emacs-wgrep/raw/master/wgrep.el ][wgrep]] package, you can use it to edit the matches in place.

In both cases, pressing =g= will rerun the Consult command you had exported from and re-enter the input you had typed (which is similar to reverting but a little more flexible). You can then proceed to re-export if that's what you want, but you can also edit the input changing the search terms or simply cancel if you see you are done with that search.

The =embark-consult= also contains some candidates collectors that allow you to run =embark-live= to get a live-updating table of contents for your buffer:

=embark-consult-outline-candidates= produces the outline headings of the current buffer, using =consult-outline=.
=embark-consult-imenu-candidates= produces the imenu items of the current buffer, using =consult-imenu=.
=embark-consult-imenu-or-outline-candidates= is a simple combination of the two previous functions: it produces imenu items in buffers deriving from =prog-mode= and otherwise outline headings.

The way to configure =embark-live= (or =embark-collect= and =embark-export= for that matter) to use one of these function is to add it at the end of the =embark-candidate-collectors= list. The =embark-consult= package by default adds the last one, which seems to be the most sensible default.

Besides those exporters and candidate collectors, the =embark-consult= package provides many subtle tweaks and small integrations between Embark and Consult. Some examples are:

When used as actions, the asynchronous search commands will search only the files associated to the targets: if the targets /are/ files, it searches those files; for buffers it will search either the associated file if there is one, else all files in the buffer's =default-directory=; for bookmarks it will search the file they point to, same for Emacs Lisp libraries. This is particularly powerful when using =embark-act-all= to act on multiple files at once, for example you can use =consult-find= to search among file /names/ and then =embark-act-all= and =consult-grep= to search within the matching files.
For all other target types, those that do not have a sensible notion of associated file, a Consult search command (asynchronous or not) will search for the text of the target but leave the minibuffer open so you can interact with the Consult command.
=consult-imenu= will search for the target and take you directly to the location if it matches a unique imenu entry, otherwise it will leave the minibuffer open so you can navigate among the matches.

Related Packages

There are several packages that offer functionality similar to Embark's.

Acting on minibuffer completion candidates :: The popular Ivy and Helm packages have support for acting on the completion candidates of commands written using their APIs, and there is an extensive ecosystem of packages meant for Helm and for Ivy (the Ivy ones usually have "counsel" in the name) providing commands and appropriate actions.
Acting on things at point :: The built-in =context-menu-mode= provides a mouse-driven context-sensitive configurable menu. The =do-at-point= package by Philip Kaludercic (available on GNU ELPA), on the other hand is keyboard-driven.
Collecting completion candidates into a buffer :: The Ivy package has the command =ivy-occur= which is similar to =embark-collect=. As with Ivy actions, =ivy-occur= only works for commands written using the Ivy API.

Resources

If you want to learn more about how others have used Embark here are some links to read:

[[https://karthinks.com/software/fifteen-ways-to-use-embark/][Fifteen ways to use Embark]], a blog post by Karthik Chikmagalur.
[[https://protesilaos.com/dotemacs/][Protesilaos Stavrou's dotemacs]], look for the section called "Extended minibuffer actions and more (embark.el and prot-embark.el)"

And some videos to watch:

[[https://protesilaos.com/codelog/2021-01-09-emacs-embark-extras/][Embark and my extras]] by Protesilaos Stavrou.
[[https://youtu.be/qpoQiiinCtY][Embark -- Key features and tweaks]] by Raoul Comninos on the Emacs-Elements YouTube channel.
[[https://youtu.be/WsxXr1ncukY][Livestreamed: Adding an Embark context action to send a stream message]] by Sacha Chua.
[[https://youtu.be/qk2Is_sC8Lk][System Crafters Live! - The Many Uses of Embark]] by David Wilson.
[[https://youtu.be/5ffb2at2d7w][Using Emacs Episode 80 - Vertico, Marginalia, Consult and Embark]] by Mike Zamansky.

Contributions

Contributions to Embark are very welcome. There is a [[https://github.com/oantolin/embark/issues/95][wish list]] for actions, target finders, candidate collectors and exporters. For other ideas you have for Embark, feel free to open an issue on the [[https://github.com/oantolin/embark/issues][issue tracker]]. Any neat configuration tricks you find might be a good fit for the [[https://github.com/oantolin/embark/wiki][wiki]].

Code contributions are very welcome too, but since Embark is now on GNU ELPA, copyright assignment to the FSF is required before you can contribute code.

Acknowledgments

While I, Omar Antolín Camarena, have written most of the Embark code and remain very stubborn about some of the design decisions, Embark has received substantial help from a number of other people which this document has neglected to mention for far too long. In particular, Daniel Mendler has been absolutely invaluable, implementing several important features, and providing a lot of useful advice.

Code contributions:

[[https://github.com/minad][Daniel Mendler]]
[[https://github.com/clemera/][Clemens Radermacher]]
[[https://codeberg.org/jao/][José Antonio Ortega Ruiz]]
[[https://github.com/iyefrat][Itai Y. Efrat]]
[[https://github.com/a13][a13]]
[[https://github.com/jakanakaevangeli][jakanakaevangeli]]
[[https://github.com/mihakam][mihakam]]
[[https://github.com/leungbk][Brian Leung]]
[[https://github.com/karthink][Karthik Chikmagalur]]
[[https://github.com/roshanshariff][Roshan Shariff]]
[[https://github.com/condy0919][condy0919]]
[[https://github.com/DamienCassou][Damien Cassou]]
[[https://github.com/JimDBh][JimDBh]]

Advice and useful discussions:

[[https://github.com/minad][Daniel Mendler]]
[[https://gitlab.com/protesilaos/][Protesilaos Stavrou]]
[[https://github.com/clemera/][Clemens Radermacher]]
[[https://github.com/hmelman/][Howard Melman]]
[[https://github.com/astoff][Augusto Stoffel]]
[[https://github.com/bdarcus][Bruce d'Arcus]]
[[https://github.com/jdtsmith][JD Smith]]
[[https://github.com/karthink][Karthik Chikmagalur]]
[[https://github.com/jakanakaevangeli][jakanakaevangeli]]
[[https://github.com/iyefrat][Itai Y. Efrat]]
[[https://github.com/mohkale][Mohsin Kaleem]]

melpa/melpa

Recipes and build machinery for the biggest Emacs package repo

MELPA

MELPA is a growing collection of package.el-compatible Emacs Lisp packages built automatically on our server from the upstream source code using simple recipes. (Think of it as a server-side version of el-get, or even Homebrew.)

Packages are updated at intervals throughout the day.

To browse available packages, check out the archive index page.

Adding packages is as simple as submitting a new recipe as a pull request; read on for details.

Usage

To use the MELPA repository, you'll need an Emacs with package.el, i.e., Emacs 24.1 or greater. To test TLS support you can visit a HTTPS URL, for example with M-x eww RET https://wikipedia.org RET.

Enable installation of packages from MELPA by adding an entry to package-archives after (require 'package) and before the call to package-initialize in your init.el or .emacs file:

(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
;; Comment/uncomment this line to enable MELPA Stable if desired.
;; See `package-archive-priorities` and `package-pinned-packages`.
;; Most users will not need or want to do this.
;; (add-to-list 'package-archives
;;              '("melpa-stable" . "https://stable.melpa.org/packages/") t)
(package-initialize)

Then just use M-x package-list-packages to browse and install packages from MELPA and elsewhere.

Note that you'll need to run M-x package-refresh-contents or M-x package-list-packages to ensure that Emacs has fetched the MELPA package list before you can install packages with M-x package-install or similar.

MELPA Stable

Packages in MELPA are built directly from the latest package source code in the upstream repositories, but we also build and publish packages corresponding to the latest tagged code in those repositories, where version tags exist. These packages are published in a separate package archive called MELPA Stable. Most users should prefer MELPA over MELPA Stable.

Some notes:

If you leave the original MELPA server in your package-archives then by default you will get the development versions of packages and not the stable ones, because the development versions are higher.
If your Emacs has the variables package-pinned-packages (available in 24.4 and later) and/or package-archive-priorities, you can customize or modify those variables as needed.
You will probably want to remove all packages and then reinstall them. Any packages you already have installed from MELPA will never get "updated" to the stable version because of the way version numbering is handled.

Note that the MELPA maintainers do not use MELPA Stable themselves, and do not particularly recommend its use.

Contributing

See the CONTRIBUTING.org document.

Recipe Format

Packages are specified by files in the recipes directory. You can contribute a new package by adding a new file under recipes using the following form ([...] denotes optional or conditional values),

(<package-name>
 :fetcher [git|github|gitlab|codeberg|sourcehut|hg]
 [:url "<repo url>"]
 [:repo "user-name/repo-name"]
 [:commit "commit"]
 [:branch "branch"]
 [:version-regexp "<regexp>"]
 [:files ("<file1>" ...)]
 [:old-names (<old-name> ...)])

package-name a lisp symbol that has the same name as the package being specified.
:fetcher specifies the type of repository the package is being maintained in.

Melpa supports the Git and Mercurial version control systems and provides generic fetcher types for them: git and hg. When you use one of these fetchers, you must specify the :url property.

Melpa also provides dedicated fetchers for certain Git forges (aka "Git repository hosting platforms"), which should always be preferred over the generic git fetcher. When using a dedicated fetcher, you must specify :repo, not :url. Currently these Git forge fetchers exist: github, gitlab, codeberg and sourcehut.

There are no dedicated fetchers for Mercurial. When a forge supports both Git and Mercurial, then the respective fetcher can only be used for Git repositories. For Mercurial repositories always use the hg fetcher.
:url specifies the URL of the version control repository. It is required for the generic git and hg fetchers and is invalid for forge-specific fetchers.
:repo specifies the repository used by forge-specific fetchers and is of the form user-name/repo-name. It is required for forge-specific fetchers and is invalid for the generic fetchers.

Note that user names in Sourcehut URLs are prefixed with ~, that has to be omitted in the value of this property.
:commit specifies the commit of the Git repository to checkout. The value will be passed to git reset in a repo where upstream is the original repository. Can therefore be either a SHA, if pointing at a specific commit, or a full ref prefixed with "origin/". Only used by the git-based fetchers.
:branch specifies the branch of the Git repository to use. This is like :commit, but it adds the "origin/" prefix automatically. This must be specified when using a branch other than the default branch.
:version-regexp is a regular expression for extracting a version-string from the repository tags. The default matches typical version tags such as 1.0, R16 or v4.3.5, so you should not override it unless necessary. For an unusual tag like "OTP-18.1.5", we might add :version-regexp "[^0-9]*\$.*\$" to strip the "OTP-" prefix. The captured portion of the regexp must be parseable by Emacs' version-to-list function.
:files optional property specifying the Emacs Lisp libraries and info files used to build the package. Please do not override this if the default value (below) is adequate, which it should usually be:
```
'("*.el" "lisp/*.el"
  "dir" "*.info" "*.texi" "*.texinfo"
  "doc/dir" "doc/*.info" "doc/*.texi" "doc/*.texinfo"
  "docs/dir" "docs/*.info" "docs/*.texi" "docs/*.texinfo"
  (:exclude
   ".*.el" "lisp/.*.el"
   "test.el" "tests.el" "*-test.el" "*-tests.el"
   "lisp/test.el" "lisp/tests.el" "lisp/*-test.el" "lisp/*-tests.el"))
```
Note that you should place Emacs Lisp libraries in the root of the repository or in the lisp/ directory. Test files should be placed in the test/ directory and they should not provide a feature. Note that all Emacs Lisp files whose name begin with a period are excluded.

No NAME-pkg.el should be checked into version control. This file is generated from metadata found in the "main library" (NAME.el). This is true not only for MELPA, but also GNU ELPA and NonGNU ELPA.

Please do not track any third-party libraries and test utilities in your repository. If you absolutely must do it, then place these files in a directory dedicated to that purpose, alongside a file named .nosearch. The latter prevents various tools from adding the containing directory to the load-path or from otherwise getting confused.

The elements of the :files list are glob-expanded to make a list of paths that will be copied into the root of the new package. This means a file like lisp/foo.el would become foo.el in the new package. To specify a destination subdirectory, use a list element of the form (TARGET-DIR SOURCE-PATH ...).

To exclude certain paths, use (:exclude SOURCE-PATH ...). There should only be one element that begins with :exclude and it should be the last element, though that is not enforced at this time.

If your package requires some additional files, but is otherwise fine with the defaults, use the special element :defaults as the first element of the :files list. This causes the default value shown above to be prepended to the specified file list. For example :files (:defaults "snippets") would cause the snippets subdir to be copied in addition to the defaults.

Warning: Elements of :files are (no longer) processed in order because we feed these globs to git log or hg log to determine the last commit that touched a relevant file. These commands unfortunately process all exclude globs after all include globs. Therefore it is not possible to override the :exclude element that appears in :defaults in a later element of :files. This means that a package whose name ends with -test cannot use :defaults. Likewise if the name of a library (as opposed to a file implementing tests) ends with -test.el, then :defaults cannot be used.

Warning: Once the appropriate commit has been determined file-expand-wildcards is used to determine the files matched by each glob. Unfortunately (unlike in a shell) a glob that begins with * may also match filenames that begin with ., so you might have to add exclude globs to prevent those from being included. :defaults takes care to exclude .dir-locals.el; if you don't use :defaults, then you might have to exclude that explicitly.
:old-names specifies former names of the package, if any. The value is a list of symbols.

Example: Single File Repository

smex is a repository that contains two files:

README.markdown
smex.el

Since there is only one .el file, this package only needs the :fetcher and :repo specified,

(smex :fetcher github :repo "nonsequitur/smex")

Example: Multiple Packages in one Repository

Assume we have a repository containing three libraries mypackage.el, helm-mypackage.el, and persp-mypackage.el. The latter two libraries are optional and users who don't want to use the packages helm and/or perspective should not be forced to install them just so they can install mypackage. These libraries should therefore be distributed as separate packages.

The three packages have to be declared in three separate files recipes/mypackage, recipes/helm-mypackage, and recipes/persp-mypackage:

(mypackage
 :fetcher github
 :repo "someuser/mypackage"
 :files ("mypackage.el"))

(helm-mypackage
 :fetcher github
 :repo "someuser/mypackage"
 :files ("helm-mypackage.el"))

(persp-mypackage
 :fetcher github
 :repo "someuser/mypackage"
 :files ("persp-mypackage.el"))

Example: Multiple Files in Multiple Directories

There are special cases where creation of the package comes from many different sub-directories in the repository and the destination sub-directories need to be explicitly set.

Consider the flymake-perlcritic recipe,

(flymake-perlcritic
 :fetcher github
 :repo "illusori/emacs-flymake-perlcritic"
 :files ("*.el" ("bin" "bin/flymake_perlcritic")))

which will result in a package structure of,

flymake-perlcritic-YYYYMMDD
|-- bin
|   `-- flymake_perlcritic
|-- flymake-perlcritic-pkg.el
`-- flymake-perlcritic.el

Notice that specifying an entry in :files that is a list takes the first element to be the destination directory.

But a better solution, given that we probably want to copy the entire snippets directory to the root of the package, we could just specify that directory. Consider the pony-mode recipe,

(pony-mode
 :fetcher github
 :repo "davidmiller/pony-mode"
 :files ("src/*.el" "snippets"))

which generates the package,

pony-mode-YYYYMMDD
|-- pony-mode-pkg.el
|-- pony-mode.el
|-- pony-tpl.el
`-- snippets
    |-- html-mode
    |   |-- bl
    |   |-- ex
    |   |-- for
    |   |-- if
    |   |-- loa
    |   |-- sup
    |   |-- testc
    |   `-- {{
    `-- python-mode
        |-- auth-view
        |-- bn
        |-- model
        |-- modelform
        |-- render-to
        |-- testc
        `-- view

Build Scripts

Building MELPA is all based around using the Makefile included in the root repository directory. Described below are the actions that accepted by the Makefile.

all — build all packages under the recipes/ directory and compiles the index.html file for the MELPA website.
recipes/<NAME> — build individual recipe <NAME>. Built packages are put in the packages/ folder with version corresponding to the date of the latest commit that modified at least one of the files specified by the recipe; given according to the %Y%m%d format.
json — build all JSON files.
archive.json — construct the archive.json file that will contain a JSON object of all compiled packages.
recipes.json — construct the recipes.json file containing a JSON object of all packages available for building.
clean — clean everything.
html — build index.html.
clean-working — remove all repositories that have been checked out to the working/ directory.
clean-packages — remove all compiled packages from the packages directory.
clean-json — remove all JSON files.

Note that these scripts require an Emacs with package.el installed, such as Emacs 24. If you have an older version of Emacs, you can get a suitable package.el here.

API

All repository code is contained in the file package-build/package-build.el. That code is maintained in a separate repository: the version in the MELPA repository is imported using git subtree.

Functions

(package-build-all) — build packages for all recipes in the directory specified by package-build-recipes-dir.
(package-build-archive NAME) — interactive Emacs Lisp function to build a single archive. NAME is a symbol for the package to be built. Packages are staged in the directory specified by package-build-working-dir and built packages are placed in the directory specified by package-build-archive-dir.

Packages are versioned based on the most recent commit date to package files based on commits to upstream package repository.

A file named <NAME>-pkg.el, which contains description, version, and requires information about the package is automatically generated. The information is extracted from the summary line and headers of <NAME>.el. For historic reasons, if some of these values cannot be extracted from that file, then Melpa also extracts information from <NAME>-pkg.el if such a file is tracked in the upstream repository (but this fallback will be removed eventually).

Variables

package-build-working-dir — Staging area containing package repositories and package directories being built.
package-build-archive-dir — Location to store archive-contents and any built packages.
package-build-recipes-dir — Directory containing MELPA compatible recipes. See Recipe Format section for more details.

Configuration

Packages end up in the packages/ directory by default. This can be configured using the package-build-archive-dir variable.

Repositories are checked out to the working/ directory by default. This can be configured using the package-build-working-dir variable.

Mirrors

Official mirrors are available (with many thanks to mirrorservice.org) so that if melpa.org is down, packages can still be installed. The following are the HTTP/HTTPS URLs to use in package-archives for MELPA and MELPA Stable respectively:

Only the packages are mirrored, not the web site front-end itself.

We are NOT responsible for the contents of any UNOFFICIAL mirror of our packages.

Use rsync to get started with your own mirror:

rsync -avz --delete rsync://melpa.org/packages/ snapshots/
rsync -avz --delete rsync://melpa.org/packages-stable/ releases/

About

MELPA is Milkypostman's ELPA or Milkypostman's Experimental Lisp Package Archive if you're not into the whole brevity thing.

jwiegley/emacs-async

Simple library for asynchronous processing in Emacs

emacs-async

I've been using Emacs long enough to know that its single-threaded nature is both a strength and a weakness. It keeps things simple -- until you need to copy a hundred files over TRAMP, byte-compile a stack of packages, or send an email through a slow SMTP server. That's when your entire editor locks up, and you're stuck watching the modeline blink.

async.el fixes this by letting you run Emacs Lisp code in a child Emacs process. The child starts with -Q (no init files, no fuss), executes whatever you give it, and passes the result back. Your main Emacs never blocks.

What's in the box

The core library is async.el, but the package ships with several ready-to-use applications built on top of it:

dired-async -- Async file operations (copy, rename, symlink) in Dired
async-bytecomp -- Byte-compiles packages in a clean subprocess, avoiding the stale-bytecode bugs you get when compiling in a running session
async-package -- Downloads and installs packages asynchronously
smtpmail-async -- Sends email in the background

Installation

The package is available on GNU ELPA and MELPA:

(package-install 'async)

Debian/Ubuntu users: apt-get install elpa-async

From source:

make all && make install

Usage

The basics

Run a function in a subprocess and get the result via callback:

(async-start
 (lambda ()
   (sleep-for 3)
   42)
 (lambda (result)
   (message "Got %s" result)))

If you'd rather wait for the result yourself, skip the callback and use async-get:

(let ((future (async-start
               (lambda ()
                 (sleep-for 3)
                 42))))
  ;; do other work...
  (message "Result: %s" (async-get future)))

If you don't care about the return value, pass 'ignore as the callback. Don't just leave it nil -- you'll leak process buffers:

(async-start
 (lambda ()
   (delete-file "/ssh:remote:big-file.tar.gz"))
 'ignore)

Passing variables to the child

The child Emacs starts fresh, so it doesn't have your variables. Use async-inject-variables to send them over:

(async-start
 `(lambda ()
    ,(async-inject-variables "\\`user-mail-address\\'")
    (format "Mail: %s" user-mail-address))
 (lambda (result) (message "%s" result)))

Bidirectional messaging

The parent and child can exchange messages while the child runs:

(let ((proc
       (async-start
        (lambda ()
          (async-send :status "working")
          (sleep-for 2)
          (let ((msg (async-receive)))
            (plist-get msg :data)))
        (lambda (result)
          (if (async-message-p result)
              (message "Status: %s" (plist-get result :status))
            (message "Done: %s" result))))))
  (async-send proc :data "here you go"))

Async let bindings

async-let evaluates bindings asynchronously and runs the body when they're ready:

(async-let ((x (heavy-computation-1))
            (y (heavy-computation-2)))
  (message "x=%s y=%s" x y))

Dired async mode

(dired-async-mode 1)

That's it. Copy, rename, and symlink operations in Dired now run in the background. If you use Helm, this works there too.

Async byte compilation

(async-bytecomp-package-mode 1)
(setq async-bytecomp-allowed-packages '(all))

This compiles packages in a clean Emacs subprocess, which avoids the nasty bugs you get when the old version of a package is still loaded during compilation.

Async email

(setq message-send-mail-function 'async-smtpmail-send-it)

A word of caution: send at least one email synchronously first, so any TLS negotiation or auth prompts happen interactively. After that, async sending works fine.

Authentication

For anything involving remote hosts (TRAMP, SMTP), you'll want auth-sources configured so the child process can authenticate without prompting you:

(setq auth-sources '("~/.authinfo.gpg" "~/.netrc"))

On Emacs 26+, set async-quiet-switch to "-q" when using TRAMP -- there's a bug where -Q prevents auth-source from working properly.

Development

If you have Nix installed:

nix develop          # Enter development shell with all dependencies
nix flake check      # Run all checks (compile, lint, format, tests)

Otherwise:

make all             # Clean, generate autoloads, compile
eask install-deps --dev
eask test buttercup  # Run tests
make lint            # Byte-compile with warnings-as-errors + package-lint
make format-check    # Check code formatting
make format          # Fix code formatting

renzmann/treesit-auto

Automatic installation, usage, and fallback for tree-sitter major modes in Emacs 29

#+TITLE: treesit-auto #+AUTHOR: Robb Enzmann

#+html:

Automatically install and use tree-sitter major modes in Emacs 29+. If the tree-sitter version can't be used, fall back to the original major mode.

Features Each of these behaviors are configurable and documented under the "Configuration" section. By activating =global-treesit-auto-mode=, Emacs will:

Automatically switch to = -ts-mode= when the grammar for = = is installed
Stick with = -mode= if the grammar isn't installed
Automatically install a grammar before opening a compatible file
Modify =auto-mode-alist= for tree-sitter modes

There is also a convenience function =M-x treesit-auto-install-all=, which will install all (or a selected subset) of the maintained and compatible grammars. You can add these grammars to your =auto-mode-alist= automatically by invoking the =treesit-auto-add-to-auto-mode-alist= function in your configuration.

Installation ~treesit-auto~ is available from [[https://melpa.org/][MELPA]]. After following [[https://melpa.org/#/getting-started][their setup]], you can use your preferred package manager. If that's the default =package.el=, simply =M-x package-refresh-contents= and then

#+begin_example M-x package-install RET treesit-auto #+end_example

If you want a local clone of the repository, rather than just a copy of the source, you might instead use =package-vc-install=

#+begin_src example M-x package-vc-install RET https://github.com/renzmann/treesit-auto.git #+end_src

Then, in your Emacs configuration file (=~/.emacs.d/init.el=),

#+begin_src emacs-lisp (use-package treesit-auto :config (global-treesit-auto-mode)) #+end_src

For most users, this will be enough. There are some nifty things you might want to enable, though, which are covered in the "Configuration" section below.

Configuration example This is how I configure =treesit-auto= for my own personal use.

#+begin_src emacs-lisp (use-package treesit-auto :custom (treesit-auto-install 'prompt) :config (treesit-auto-add-to-auto-mode-alist 'all) (global-treesit-auto-mode)) #+end_src

What this package does Emacs 29, while featuring =treesit.el= and a convenient =treesit-install-language-grammar=, [[https://archive.casouri.cc/note/2023/tree-sitter-in-emacs-29/index.html][will not feature an intelligent way to choose]] between a default mode, such as =python-mode=, and its tree-sitter enhanced version, =python-ts-mode=. This package attempts to remedy that by adjusting the =major-mode-remap-alist= and =treesit-language-source-alist= variables in order to get the following behavior:

1. If the grammar is installed, then switch to the appropriate tree-sitter mode:

In this case, assuming we open a Python buffer, and the [[https://github.com/tree-sitter/tree-sitter-python][Python tree-sitter grammar]] is installed, then Emacs will use =python-ts-mode= instead of =python-mode=.

2. The grammar is NOT installed and treesit-auto-install is non-nil:

When the grammar is not installed and ~treesit-auto-install~ is t, then upon activating any major mode that has a corresponding tree-sitter mode, the grammar will be downloaded and compiled using ~treesit-install-language-grammar~. Emacs will then activate the tree-sitter major mode for that buffer.

~prompt~ is like t, except a message will be displayed in the echo area asking for a yes/no response before attempting the installation.

As an example for both cases: if I visit a Python file and didn't already have the grammar installed, I wind up with an installed grammar and a buffer using ~python-ts-mode~.

Otherwise, when ~treesit-auto-install~ is nil, it will try to fall back to another major mode as described in the following two rules.

3. If the grammar is NOT installed, and a fallback is specified

Most languages will have a fallback mode specified, such as =python-ts-mode= falling back to =python-mode=, if the grammar is not installed. If you ever need to double-check what that fallback will be, you can double check what's in the recipe for that language like this:

#+begin_example (treesit-auto-recipe-remap (alist-get 'python treesit-auto-lang-recipe-alist)) ⇒ python-mode #+end_example

See "Configuration/Configuring behavior for a specific language" in case you would like to specify different fallback modes than the default.

4. The grammar is installed, but there is no fallback mode

You can optionally use the =treesit-auto-add-to-auto-mode-alist= function to ensure that your installed tree-sitter languages have their corresponding =...-ts-mode= added to =auto-mode-alist=, so that Emacs opens the buffer in that =...-ts-mode=, rather than the default =Fundamental= mode.

Supposing for instance we don't have =typescript-mode= installed, then even if we /do/ have =typescript-ts-mode= installed along with the typescript grammar compiled in =~/.emacs.d/tree-sitter/=, Emacs still won't use =typescript-ts-mode= unless you also added ='("\.ts\'" . typescript-ts-mode)= to =auto-mode-alist=. By calling =(treesit-auto-add-to-auto-mode-alist)= in your configuration, this modification to =auto-mode-alist= is done automatically for you.

5. All other cases...

This is the most general case, where the grammar is not installed, ~treesit-auto-install~ is nil, and no fallback mode is specified in the language recipe present on =treesit-auto-recipe-list=. In this case, we still gain the benefit of quickly installing grammars through =treesit-install-language-grammar= without having the build the recipe interactively, but =treesit-auto= will make no attempt to switch away from the tree-sitter mode.

Configuration If you have modified =treesit-language-source-alist= through =setq=, then it is recommended to put any configuration of this package AFTER that =setq=.

** Choose which languages =treesit-auto= should consider

You can globally alter the behavior of =treesit-auto= to only consider a specific set of languages by setting the =treesit-auto-langs= list to a set of language symbols. By default, this list includes every possible language that =treesit-auto= supports, so you can use =M-x describe-variable RET treesit-auto-langs= to see what the options are.

One way to use this variable is to just set it manually:

#+begin_src emacs-lisp (setq treesit-auto-langs '(python rust go)) #+end_src

Now, =treesit-auto= features will only ever affect Python, Rust, and Go files. Running =treesit-auto-install-all= will only install these three grammars, and no automatic prompting/installation will occur when visiting a buffer that is not one of these three, either.

Another method is to disable specific languages by just removing them from this list:

#+begin_src emacs-lisp (delete 'awk treesit-auto-langs) #+end_src

Here, =treesit-auto= behaves as it normally would for all languages /except/ AWK.

** Automatically install grammars if they are missing The =treesit-auto-install= variable controls whether a grammar should be installed automatically when activating a major mode compatible with tree-sitter.

=nil=, the default, means =treesit-auto= won't try to install anything, and will rely on the fallback logic outlined above
=t= means =treesit-auto= should always try to clone and install a grammar when missing
~prompt~ will cause a yes/no prompt to appear in the minibuffer before attempting installation

#+begin_src emacs-lisp (setq treesit-auto-install 'prompt) #+end_src

Then, supposing I don't have =libtree-sitter-python.so= (or its mac/Windows equivalent) under =~/.emacs.d/tree-sitter= (or anywhere else in =treesit-extra-load-path=), visiting a Python file or calling =M-x python-ts-mode= will generate this prompt:

#+begin_example Tree-sitter grammar for python is missing. Would you like to install it from https://github.com/tree-sitter/tree-sitter-python? (y or n) #+end_example

Responding with "yes" will use =treesit-install-language-grammar= to go fetch and compile the missing grammar.

The other function that respects this variable is =treesit-auto-install-all=. When =treesit-auto-install= is t, using =M-x treesit-auto-install-all= will skip all prompts. Otherwise, it will ask before attempting the installation.

** Configuring behavior for a specific language The variable =treesit-auto-recipe-list= keeps track of all the language "recipes." These control how =treesit-auto= decides which modes to upgrade/downgrade to/from, where the source code of the language grammar is hosted, and which C/C++ compiler to use. Each recipe can take these arguments:

#+begin_example :lang :ts-mode :remap :url :revision :abi14-revision :requires :source-dir :cc :c++ #+end_example

To create a recipe, use =make-treesit-auto-recipe=:

#+begin_src elisp (setq my-js-tsauto-config (make-treesit-auto-recipe :lang 'javascript :ts-mode 'js-ts-mode :remap '(js2-mode js-mode javascript-mode) :url "https://github.com/tree-sitter/tree-sitter-javascript" :revision "master" :source-dir "src" :ext "\.js\'"))

(add-to-list 'treesit-auto-recipe-list my-js-tsauto-config) #+end_src

Here, we've specified that the tree-sitter compiler will be creating a file named =libtree-sitter-javascript.so= (or =.dylib= or =.dll=), based on the =:lang= field. The corresponding tree-sitter mode in Emacs is called =js-ts-mode=, and all of =js2-mode=, =js-mode=, and =javascript-mode= should attempt switching to the =js-ts-mode=, if possible.

Moreover, since =js-2-mode= is first under the =:remap= section, that is the "primary fallback." Meaning that if the tree-sitter grammar is not available, it will be the first mode tried. If that doesn't work, it will try =js-mode=, and =javascript-mode=, in that order, until one /does/ work. If only one fallback needs to be specified, a single quoted symbol is also acceptable. For instance, =python-ts-mode= just uses =:remap 'python-mode= in this argument position.

If a grammar mandates any other grammars be installed as a dependency, the =:requires= keyword can specify a language symbol or list of symbols that should be installed. One example of this is found in the TypeScript recipe, which specifies =:requires 'tsx=, since activating =typescript-ts-mode= on some Emacs builds will attempt to load the TSX grammar.

The =:url=, =:revision=, =:source-dir=, =:cc=, and =:c++= arguments are all documented under =treesit-language-source-alist=, which is part of base Emacs, not this package.

*** =:abi14-revision= and =version-mismatch= errors If treesit reports reports =(treesit): The installed language grammar for foo cannot be located or has problems (version-mismatch): 15= it means that the grammar is using ABI 15, but Emacs only supports earlier versions (e.g. Emacs 30.1 supports ABI versions 13 and 14). To fix this, set =:abi14-revision= to a git tag that corresponds to an ABI 14 version in the grammar repository.

Finding the right tag can require some trial and error, by checking out different revisions of the grammar and building them. Once you've built a grammar you can use the script =check_treesit_abi.py= to print its ABI version.

Once you find the tag for the ABI 14 revision of a grammar, please submit a pull request to add it to the default value of =treesit-auto-recipe-list=.

Setting =:abi14-revision= is preferable to changing =:revision=, because changing =:revision= would force the ABI 14 version even after Emacs starts supporting ABI 15.

** Keep track of your hooks This package does not modify any of your major mode hooks. That is, if you have functions in =python-mode-hook=, but not in =python-ts-mode-hook=, then your hook from =python-mode= will not be applied, assuming =python-ts-mode= is what gets loaded. For major modes in which this is a concern, the current recommendation is to address this as part of your configuration.

#+begin_src emacs-lisp (setq rust-ts-mode-hook rust-mode-hook) #+end_src

Some modes have a shared base, such as =python-ts-mode= and =python-mode= both deriving from =python-base-mode=. For these languages, you can opt to hook into =python-base-mode-hook= instead of explicitly setting the tree-sitter mode's hook.

** Automatically register extensions for =auto-mode-alist= You can register tree-sitter modes to =auto-mode-alist= by calling =treesit-auto-add-to-auto-mode-alist=. Depending on the optional argument =langs=, this function can behave in three different ways:

=nil=, the default - Only add tree-sitter modes to =auto-mode-alist= if the tree-sitter mode is available to Emacs /and/ the grammar is installed.
='all= - For every tree-sitter mode available to Emacs and in =treesit-auto-langs=, add it to =auto-mode-alist= regardless of whether the grammar is installed. This has the beneficial side effect of installing grammars for you when opening files that have a tree-sitter mode that comes with Emacs, but have no fallback mode. Examples of this are =rust-ts-mode=, =go-ts-mode=, and a few others in Emacs 29+.
A list of language symbols - behaves like ='all=, but only for the listed languages

For instance, you might run this function as:

#+begin_src emacs-lisp (treesit-auto-add-to-auto-mode-alist '(rust go toml)) #+end_src

This registers your tree-sitter modes according to the common file extension for Rust, Go, and TOML, but no other modes. Most users will probably want to use =(treesit-auto-add-to-auto-mode-alist 'all)= for the easiest general behavior; always prompting/installing grammars when we can.

A rough vanilla equivalent I find it a good practice to be skeptical of adding any new dependency to my Emacs configuration. So, what would you have to do to get similar behavior in your Emacs configuration without the =treesit-auto= package?

We'll take two examples: TypeScript and Python.

Emacs 29 ships with =typescript-ts-mode= and =tsx-ts-mode=, but no equivalent =typescript-mode= or =tsx-mode=. =python-ts-mode= and =python-mode=, on the other hand, are both available out of the box. If you wanted these grammars to automatically install on launch, and then use the tree-sitter modes instead of the base modes for every file, you'd need the following code in your init file:

#+begin_src emacs-lisp (setq treesit-language-source-alist '((typescript . ("https://github.com/tree-sitter/tree-sitter-typescript" "master" "typescript/src")) (tsx . ("https://github.com/tree-sitter/tree-sitter-typescript" "master" "tsx/src")) (python . ("https://github.com/tree-sitter/tree-sitter-python"))))

(dolist (source treesit-language-source-alist) (unless (treesit-ready-p (car source)) (treesit-install-language-grammar (car source))))

(add-to-list 'auto-mode-alist '("\.ts\'" . typescript-ts-mode)) (add-to-list 'auto-mode-alist '("\.tsx\'" . tsx-ts-mode)) (add-to-list 'major-mode-remap-alist '(python-mode . python-ts-mode))

#+end_src

There are plenty of reasons why some users would prefer to take this type of hand-tuned approach to their tree-sitter modes. For most Emacs people, though, you can see the natural progression of where a config like the above would go:

You need to maintain a library of language symbols (which /must/ match the language's =grammar.js=), URLs, revisions, and sub-directories for =treesit-language-source-alist=. Additionally, you'd need to know that =typescript-ts-mode= relies on the tree-sitter grammar for =tsx=, which must be installed alongside the grammar for TypeScript. This is probably the main value proposition of this package, since all of this information is stored under the community-contributed =treesit-auto-recipe-list=
You need to be aware of when to use =auto-mode-alist= and =major-mode-remap-alist=, depending on what modes are installed into Emacs
If you want lazy installation of grammars, rather than installing them all up-front in your =init.el=, you'd need to write some hooks or derived modes to check =treesit-ready-p= for the current buffer, and install the language before loading the main tree-sitter mode
After a certain number of langauges, it becomes unweildy to do these =add-to-list= calls for every single one, and it's better to programmatically operate on a list of selected languages

If you were to follow this chain yourself, you'd probably wind up with something in your =init.el= that looks very similar to the code in this package.

All in all, this is a small package. Roughly half of it is just maintaining a library of information for =treesit-language-source-alist=, and the other half works through the logic of handling edge cases related to the remaining bullets above.

Caveats This package is, admittedly, a hack. =treesit.el= provides an excellent foundation to incremental source code parsing for Emacs 29, and over time that foundation /will/ expand into an improved core editing experience. With that in mind, I fully expect this package to eventually be obsolesced by the default options in Emacs 30 and beyond. That does not preclude us from adding a few quality of life improvements to Emacs 29, though, and so it still seems prudent to have this plugin available in the meantime.
Known bugs =treesit-auto= doesn't play super well with Org-babel, since Org has its own methods of hooking into and using languages. In particular, you may need to set =org-src-lang-modes= yourself to get tree-sitter modes working correctly.

Another side behavior you may encounter is when opening an Org document with shell scripts inside and =treesit-auto-install= is non-nil, then =treesit-auto= will prompt to install the Bash grammar, but won't display the prompt until you interact with Emacs in some way, such as using =next-line= (=C-n= by default) or hovering over Emacs with your mouse.

Contributing Bug reports, feature requests, and contributions are most welcome. Even though this is a small project, there is always room for improvement. I also appreciate "nitpicky" contributions, such as formatting, conventions, variable naming, code simplification, and improvements to language in documentation.

Issues are tracked on [[https://github.com/renzmann/treesit-auto/issues][GitHub]], which is also where patches and pull requests should be submitted.

If you would like to submit a new language recipe to be distributed as part of this package, see [[CONTRIBUTING.org][CONTRIBUTING.org]] for a quick guide on how to write and submit the new recipe.

rainstormstudio/nerd-icons.el

#+TITLE: nerd-icons.el - A Library for Nerd Font icons #+AUTHOR: Hongyu Ding #+LANGUAGE: en

[[https://melpa.org/#/nerd-icons][file:https://melpa.org/packages/nerd-icons-badge.svg]]

Nerd-icons.el is a library for easily using [[https://github.com/ryanoasis/nerd-fonts][Nerd Font]] icons inside Emacs, an alternative to [[https://github.com/domtronn/all-the-icons.el][all-the-icons]].

It works on both GUI and terminal! You only need a [[https://www.nerdfonts.com/#home][Nerd Font]] installed on your system.

It is inspired by [[https://github.com/domtronn/all-the-icons.el][all-the-icons]], [[https://github.com/seagle0128/icons-in-terminal.el][icons-in-terminal]], [[https://github.com/ryanoasis/vim-devicons][vim-devicons]], and [[https://github.com/nvim-tree/nvim-web-devicons][nvim-web-devicons]].

in GUI: [[file:screenshots/demo.png]]

in terminal: [[file:screenshots/demo-terminal.png]]

Installing Fonts Please go to [[https://www.nerdfonts.com/][Nerd Fonts website]] and get a Nerd font. After installing the font on your machine, you need to set ~nerd-icons-font-family~ to match its font name so that the font can be properly used under GUI. If you want Nerd Fonts to work under a terminal, please change your terminal's font to a Nerd font.

If the Nerd Font you installed does not display correctly (e.g. appear cut off), it is recommended to use =Symbols Nerd Font Mono= (Symbols Nerd Font). You can use ~M-x nerd-icons-install-fonts~ to install ~Symbols Nerd Font Mono~ for you. Note that for Windows you'll need to manually install the font after you used this function.

To automatically install =Symbols Nerd Font Mono=, you can use this elisp in your ~init.el~. On macOS, Linux and BSDs, this will download and install the font directly for you. On Windows, you can specify the folder to download the font to, but you will still have to manually install it after.

#+BEGIN_SRC emacs-lisp ;; Linux/macOS/BSDs (when (member system-type '(gnu gnu/linux gnu/kfreebsd darwin)) (unless (find-font (font-spec :name "Symbols Nerd Font Mono")) (nerd-icons-install-fonts t)))

;; Windows (when (string-equal system-type 'windows-nt) (unless (find-font (font-spec :name "Symbols Nerd Font Mono")) (nerd-icons-install-fonts "c:/Users/username/Desktop/")))

;; All-in-one ;; This will install in the default fonts folder for Linux/macOS/BSDs ;; (same as “t”), but for Windows this will download to the specified ;; folder (unless (find-font (font-spec :name "Symbols Nerd Font Mono")) (nerd-icons-install-fonts "c:/Users/username/Desktop/")) #+END_SRC

Usage ~nerd-icons~ is on [[https://melpa.org/#/nerd-icons-completion][Melpa]]. You can install it with built-in ~M-x package-install~ #+begin_src emacs-lisp (require 'nerd-icons) #+end_src

or using ~use-package~ #+BEGIN_SRC emacs-lisp (use-package nerd-icons ;; :custom ;; The Nerd Font you want to use in GUI ;; "Symbols Nerd Font Mono" is the default and is recommended ;; but you can use any other Nerd Font if you want ;; (nerd-icons-font-family "Symbols Nerd Font Mono") ) #+END_SRC ** insert icons

use icon based on category
- ~nerd-icons-icon-for-dir~
- ~nerd-icons-icon-for-file~
- ~nerd-icons-icon-for-extension~
- ~nerd-icons-icon-for-mode~
- ~nerd-icons-icon-for-url~
- ~nerd-icons-icon-for-buffer~
example: #+BEGIN_SRC emacs-lisp (insert (nerd-icons-icon-for-file "init.el")) ;; Inserts an icon for Emacs Lisp #+END_SRC
use icon directly
- ~nerd-icons-ipsicon~
- ~nerd-icons-octicon~
- ~nerd-icons-pomicon~
- ~nerd-icons-powerline~
- ~nerd-icons-faicon~
- ~nerd-icons-wicon~
- ~nerd-icons-sucicon~
- ~nerd-icons-devicon~
- ~nerd-icons-codicon~
- ~nerd-icons-flicon~
- ~nerd-icons-mdicon~
example: #+BEGIN_SRC emacs-lisp (insert (nerd-icons-faicon "nf-fa-gitlab")) ;; Inserts a Gitlab icon #+END_SRC
insert icon interactively (~M-x~ functions)
- ~nerd-icons-insert~
- ~nerd-icons-insert-ipsicon~
- ~nerd-icons-insert-octicon~
- ~nerd-icons-insert-pomicon~
- ~nerd-icons-insert-powerline~
- ~nerd-icons-insert-faicon~
- ~nerd-icons-insert-wicon~
- ~nerd-icons-insert-sucicon~
- ~nerd-icons-insert-devicon~
- ~nerd-icons-insert-codicon~
- ~nerd-icons-insert-flicon~
- ~nerd-icons-insert-mdicon~

** customize icons You can customize the icons via ~nerd-icons-extension-icon-alist~, ~nerd-icons-regexp-icon-alist~ and ~nerd-icons-mode-icon-alist~, etc.

For example, #+begin_src emacs-lisp (add-to-list 'nerd-icons-extension-icon-alist '("epub" nerd-icons-faicon "nf-fa-book" :face nerd-icons-green)) #+end_src

Glyph Sets | Glyph Set | prefix | Point Range | insert function | |-------------------------+----------------------+--------------------------------------+----------------------| | Seti-UI + Custom | ~nf-seti-~, ~nf-custom-~ | ~e5fa~ - ~e631~ | ~nerd-icons-sucicon~ | | Devicons | ~nf-dev-~ | ~e700~ - ~e7c5~ | ~nerd-icons-devicon~ | | Font Awesome | ~nf-fa-~ | ~f000~ - ~f2e0~ | ~nerd-icons-faicon~ | | Font Awesome Extension | ~nf-fae-~ | ~e200~ - ~e2a9~ | ~nerd-icons-faicon~ | | Material Design Icons | ~nf-md-~ | ~f500~ - ~fd46~ | ~nerd-icons-mdicon~ | | Weather | ~nf-weather-~ | ~e300~ - ~e3eb~ | ~nerd-icons-wicon~ | | Octicons | ~nf-oct-~ | ~f400~ - ~f4a9~, ~2665~, ~26A1~ | ~nerd-icons-octicon~ | | Powerline Symbols | ~nf-pl-~ | ~e0a0~ - ~e0a2~, ~e0b0~ - ~e0b3~ | ~nerd-icons-powerline~ | | Powerline Extra Symbols | ~nf-ple-~ | ~e0a3~, ~e0b4~ - ~e0c8~, ~e0ca~, ~e0cc~ - ~e0d4~ | ~nerd-icons-powerline~ | | IEC Power Symbols | ~nf-iec-~ | ~23fb~ - ~23fe~, ~2b58~ | ~nerd-icons-ipsicon~ | | Font Logos | ~nf-linux-~ | ~f300~ - ~f32d~ | ~nerd-icons-flicon~ | | Pomicons | ~nf-pom-~ | ~e000~ - ~e00a~ | ~nerd-icons-pomicon~ | | Codicons | ~nf-cod-~ | ~ea60~ - ~ebeb~ | ~nerd-icons-codicon~ |

Please check [[https://github.com/ryanoasis/nerd-fonts/wiki/Glyph-Sets-and-Code-Points][Nerd Fonts Glyph Sets and Code Points]] for more information.

Related Packages

[[https://github.com/rainstormstudio/nerd-icons-dired][nerd-icons-dired]]
[[https://github.com/abougouffa/nerd-icons-multimodal][nerd-icons-multimodal]]
[[https://github.com/rainstormstudio/treemacs-nerd-icons][treemacs-nerd-icons]]
[[https://github.com/seagle0128/nerd-icons-ivy-rich][nerd-icons-ivy-rich]]
[[https://github.com/seagle0128/nerd-icons-ibuffer][nerd-icons-ibuffer]]
[[https://github.com/rainstormstudio/nerd-icons-completion][nerd-icons-completion]]
[[https://github.com/LuigiPiucco/nerd-icons-corfu][nerd-icons-corfu]]
[[https://github.com/alexluigit/dirvish][dirvish]]
[[https://github.com/seagle0128/doom-modeline][doom-modeline]]
[[https://github.com/grolongo/nerd-icons-mode-line][nerd-icons-mode-line]]
[[https://github.com/lucius-martius/tab-line-nerd-icons][tab-line-nerd-icons]]

** use nerd-icons with dirvish sample configuration: #+BEGIN_SRC emacs-lisp (use-package dirvish :init (dirvish-override-dired-mode) :config (setq dirvish-mode-line-format '(:left (sort symlink) :right (omit yank index))) (setq dirvish-mode-line-height 10) (setq dirvish-attributes '(nerd-icons file-time file-size collapse subtree-state vc-state git-msg)) (setq dirvish-subtree-state-style 'nerd) (setq delete-by-moving-to-trash t) (setq dirvish-path-separators (list (format " %s " (nerd-icons-codicon "nf-cod-home")) (format " %s " (nerd-icons-codicon "nf-cod-root_folder")) (format " %s " (nerd-icons-faicon "nf-fa-angle_right")))) (setq dired-listing-switches "-l --almost-all --human-readable --group-directories-first --no-group") (dirvish-peek-mode) ; Preview files in minibuffer (dirvish-side-follow-mode) ; similar to `treemacs-follow-mode' ) #+END_SRC

akermu/emacs-libvterm

Emacs libvterm integration

Introduction

Emacs-libvterm (vterm) is fully-fledged terminal emulator inside GNU Emacs based on libvterm, a C library. As a result of using compiled code (instead of elisp), emacs-libvterm is fully capable, fast, and it can seamlessly handle large outputs.

Warning

This package is in active development and, while being stable enough to be used as a daily-driver, it is currently in alpha stage. This means that occasionally the public interface will change (for example names of options or functions). A list of recent breaking changes is in appendix. Moreover, emacs-libvterm deals directly with some low-level operations, hence, bugs can lead to segmentation faults and crashes. If that happens, please report the problem.

Given that eshell, shell, and (ansi-)term are Emacs built-in, why should I use vterm?

The short answer is: unparalleled performance and compatibility with standard command-line tools.

For the long answer, let us discuss the differences between eshell, shell, term and vterm:

eshell: it is a shell completely implemented in Emacs Lisp. It is well-integrated in Emacs and it runs on Windows. It does not support command line tools that require terminal manipulation capabilities (e.g., ncdu, nmtui, ...).
shell: it interfaces with a standard shell (e.g., bash). It reads an input from Emacs, sends it to the shell, and reports back the output from the shell. As such, like eshell, it does not support interactive commands, especially those that directly handle how the output should be displayed (e.g., htop).
term: it is a terminal emulator written in elisp. term runs a shell (similarly to other terminal emulators like Gnome Terminal) and programs can directly manipulate the output using escape codes. Hence, many interactive applications (like the one aforementioned) work with term. However, term and ansi-term do not implement all the escapes codes needed, so some programs do not work properly. Moreover, term has inferior performance compared to standalone terminals, especially with large bursts of output.
vterm: like term it is a terminal emulator. Unlike term, the core of vterm is an external library written in C, libvterm. For this reason, vterm outperforms term and has a nearly universal compatibility with terminal applications.

Vterm is not for you if you are using Windows, or if you cannot set up Emacs with support for modules. Otherwise, you should try vterm, as it provides a superior terminal experience in Emacs.

Using vterm is like using Gnome Terminal inside Emacs: Vterm is fully-featured and fast, but is not as well integrated in Emacs as eshell (yet), so some of the editing keybinding you are used to using may not work. For example, evil-mode is currently not supported (though, users can enable VI emulation in their shells). This is because keys are sent directly to the shell. We are constantly working to improve this.

Installation

Requirements

Before installing emacs-libvterm, you need to make sure you have installed

GNU Emacs (>= 25.1) with module support. You can check that, by verifying that module-file-suffix is not nil.
cmake (>= 3.11)
libtool-bin (related issues: #66 #85)
OPTIONAL: libvterm (>= 0.2). This library can be found in the official repositories of most distributions (e.g., Arch, Debian, Fedora, Gentoo, openSUSE, Ubuntu). Typical names are libvterm (Arch, Fedora, Gentoo, openSUSE), or libvterm-dev (Debian, Ubuntu). If not available, libvterm will be downloaded during the compilation process. Some distributions (e.g. Ubuntu < 20.04, Debian < 11) have versions of libvterm that are too old. If you find compilation errors related to VTERM_COLOR, you should not use your system libvterm. See FAQ for more details.

From MELPA

vterm is available on MELPA, and it can be installed as a normal package. If the requirements are satisfied (mainly, Emacs was built with support for modules), vterm will compile the module the first time it is run. This is the recommended way to install vterm.

vterm can be installed from MELPA with use-package by adding the following lines to your init.el:

(use-package vterm
    :ensure t)

To take full advantage of the capabilities of vterm, you should configure your shell too. Read about this in the section shell-side configuration.

Manual installation

Clone the repository:

git clone https://github.com/akermu/emacs-libvterm.git

By default, vterm will try to find if libvterm is installed. If it is not found, emacs-libvterm will download the latest version available of libvterm (from here), compile it, and use it. If you always want to use the vendored version as opposed to the one on you system, set USE_SYSTEM_LIBVTERM to no. To do this, change cmake .. with cmake -DUSE_SYSTEM_LIBVTERM=no .. in the following instructions.

Build the module with:

cd emacs-libvterm
mkdir -p build
cd build
cmake ..
make

And add this to your init.el:

(add-to-list 'load-path "path/to/emacs-libvterm")
(require 'vterm)

Or, with use-package:

(use-package vterm
  :load-path  "path/to/emacs-libvterm/")

vterm and Ubuntu

20.04

Using vterm on Ubuntu requires additional steps. The latest LTS version (20.04) ships without CMake installed and Emacs27 is not yet available from Ubuntu's package repository.

The basic steps for getting vterm to work on Ubuntu 20.04 are:

Ensure Emacs27 is installed
Install cmake, libtool, and libtool-bin

There are a few options for installing Emacs27 on Ubuntu 20.04:

Compile Emacs27 from source
Install Emacs27 from Snap
Install Emacs27 from Kevin Kelley's PPA

In any case, if you have an older Emacs version you will need to purge it before proceeding:

Purge Emacs

sudo apt --purge remove emacs
sudo apt autoremove

Installing Emacs27 from Kevin Kelley PPA

sudo add-apt-repository ppa:kelleyk/emacs
sudo apt install emacs27

If you get an error about emacs27_common during the install process:

Errors were encountered while processing:
 /tmp/apt-dpkg-install-RVK8CA/064-emacs27-common_27.1~1.git86d8d76aa3-kk2+20.04_all.deb

run

sudo apt --purge remove emacs-common
sudo apt --fix-broken install

Installing Emacs27 from Snap

I hesitate to include SNAP here, because I ran into a number of GTK Theme parsing errors, and Fontconfig errors when I tested it, and reverted to installing from Kevin Kelley's PPA. YMMV

sudo snap install emacs --classic

Install CMake and Libtool

In Ubuntu 20.04 CMake (v3.16.3-1ubuntu1) and Libtool can be installed with

sudo apt install cmake
sudo apt install libtool
sudo apt install libtool-bin

18.04

Using vterm on Ubuntu 18.04 requires additional steps. 18.04 ships with a version of CMake that is too old for vterm and GNU Emacs is not compiled with support for dynamical module loading.

It is possible to install GNU Emacs with module support from Kevin Kelley's PPA. The binary in Ubuntu Emacs Lisp PPA is currently broken and leads to segmentation faults (see #185). In case Emacs is already on the system, you need to purge it before proceeding with the following commands.

sudo add-apt-repository ppa:kelleyk/emacs
sudo apt update
sudo apt-get install emacs26

A way to install a recent version of CMake (>= 3.11) is with linuxbrew.

brew install cmake

In some cases, /bin/sh needs to be relinked to /bin/bash for the compilation to work (see, #216).

Pull requests to improve support for Ubuntu are welcome (e.g., simplifying the installation).

Some releases of Ubuntu (e.g., 18.04) ship with a old version of libvterm that can lead to compilation errors. If you have this problem, see the FAQ for a solution.

GNU Guix

vterm and its dependencies are available in GNU Guix as emacs-vterm. The package can be installed with guix package -i emacs-vterm.

Shell-side configuration

Some of the most useful features in vterm (e.g., directory-tracking and prompt-tracking or message passing) require shell-side configurations. The main goal of these additional functions is to enable the shell to send information to vterm via properly escaped sequences. A function that helps in this task, vterm_printf, is defined below. This function is widely used throughout this readme.

For bash or zsh, put this in your .zshrc or .bashrc

vterm_printf() {
    if [ -n "$TMUX" ] \
        && { [ "${TERM%%-*}" = "tmux" ] \
            || [ "${TERM%%-*}" = "screen" ]; }; then
        # Tell tmux to pass the escape sequences through
        printf "\ePtmux;\e\e]%s\007\e\\" "$1"
    elif [ "${TERM%%-*}" = "screen" ]; then
        # GNU screen (screen, screen-256color, screen-256color-bce)
        printf "\eP\e]%s\007\e\\" "$1"
    else
        printf "\e]%s\e\\" "$1"
    fi
}

This works also for dash.

For fish put this in your ~/.config/fish/config.fish:

function vterm_printf;
    if begin; [  -n "$TMUX" ]  ; and  string match -q -r "screen|tmux" "$TERM"; end
        # tell tmux to pass the escape sequences through
        printf "\ePtmux;\e\e]%s\007\e\\" "$argv"
    else if string match -q -- "screen*" "$TERM"
        # GNU screen (screen, screen-256color, screen-256color-bce)
        printf "\eP\e]%s\007\e\\" "$argv"
    else
        printf "\e]%s\e\\" "$argv"
    end
end

Debugging and testing

If you have successfully built the module, you can test it by executing the following command in the build directory:

make run

Usage

`vterm`

Open a terminal in the current window.

`vterm-other-window`

Open a terminal in another window.

`vterm-copy-mode`

When you enable vterm-copy-mode, the terminal buffer behaves like a normal read-only text buffer: you can search, copy text, etc. The default keybinding to toggle vterm-copy-mode is C-c C-t. When a region is selected, it is possible to copy the text and leave vterm-copy-mode with the enter key.

If no region is selected when the enter key is pressed it will copy the current line from start to end. If vterm-copy-exclude-prompt is true it will skip the prompt and not include it in the copy.

`vterm-clear-scrollback`

vterm-clear-scrollback does exactly what the name suggests: it clears the current buffer from the data that it is not currently visible. vterm-clear-scrollback is bound to C-c C-l. This function is typically used with the clear function provided by the shell to clear both screen and scrollback. In order to achieve this behavior, you need to add a new shell alias.

For zsh, put this in your .zshrc:

if [[ "$INSIDE_EMACS" = 'vterm' ]]; then
    alias clear='vterm_printf "51;Evterm-clear-scrollback";tput clear'
fi

For bash, put this in your .bashrc:

if [ "$INSIDE_EMACS" = 'vterm' ]; then
    clear() {
        vterm_printf "51;Evterm-clear-scrollback";
        tput clear;
    }
fi

For fish:

if [ "$INSIDE_EMACS" = 'vterm' ]
    function clear
        vterm_printf "51;Evterm-clear-scrollback";
        tput clear;
    end
end

These aliases take advantage of the fact that vterm can execute elisp commands, as explained below.

If it possible to automatically clear the scrollback when the screen is cleared by setting the variable vterm-clear-scrollback-when-clearing: When vterm-clear-scrollback-when-clearing is non nil, C-l clears both the screen and the scrollback. When is nil, C-l only clears the screen. The opposite behavior can be achieved by using the universal prefix (i.e., calling C-u C-l).

Customization

`vterm-shell`

Shell to run in a new vterm. It defaults to $SHELL.

`vterm-environment`

To add more environment variables there is the custom vterm-environment which has a similar format to the internal Emacs variable process-environment. You can check the documentation with C-h v process-environment for more details.

`vterm-term-environment-variable`

Value for the TERM environment variable. It defaults to xterm-256color. If eterm-256color is installed, setting vterm-term-environment-variable to eterm-color improves the rendering of colors in some systems.

`vterm-kill-buffer-on-exit`

If set to t, buffers are killed when the associated process is terminated (for example, by logging out the shell). Keeping buffers around it is useful if you need to copy or manipulate the content.

`vterm-module-cmake-args`

Compilation flags and arguments to be given to CMake when compiling the module. This string is directly passed to CMake, so it uses the same syntax. At the moment, its main use is for compiling vterm using the system libvterm instead of the one downloaded from GitHub. You can find all the arguments and flags available with cmake -LA in the build directory.

`vterm-copy-exclude-prompt`

Controls whether or not to exclude the prompt when copying a line in vterm-copy-mode. Using the universal prefix before calling vterm-copy-mode-done will invert the value for that call, allowing you to temporarily override the setting. When a prompt is not found, the whole line is copied.

`vterm-use-vterm-prompt-detection-method`

The variable vterm-use-vterm-prompt-detection-method determines whether to use the vterm prompt tracking, if false it use the regexp in vterm-copy-prompt-regexp to search for the prompt.

`vterm-enable-manipulate-selection-data-by-osc52`

Vterm support copy text to Emacs kill ring and system clipboard by using OSC 52. See https://invisible-island.net/xterm/ctlseqs/ctlseqs.html for more info about OSC 52. For example: send "blabla" to kill ring: printf "\033]52;c;$(printf "%s" "blabla" | base64)\a"

tmux can share its copy buffer to terminals by supporting OSC 52 (like iterm2 and xterm), you can enable this feature for tmux by:

set -g set-clipboard on         #osc 52 copy paste share with iterm
set -ga terminal-overrides ',xterm*:XT:Ms=\E]52;%p1%s;%p2%s\007'
set -ga terminal-overrides ',screen*:XT:Ms=\E]52;%p1%s;%p2%s\007'

The clipboard querying/clearing functionality offered by OSC 52 is not implemented here, And for security reason, this feature is disabled by default.

This feature needs the new way of handling strings with a struct VTermStringFragment in libvterm. You'd better compile emacs-libvterm with cmake -DUSE_SYSTEM_LIBVTERM=no ... If you don't do that, when the content you want to copy is too long, it would be truncated by a bug in libvterm.

`vterm-buffer-name-string`

When vterm-buffer-name-string is not nil, vterm renames automatically its own buffers with vterm-buffer-name-string. This string can contain the character %s, which is substituted with the title (as defined by the shell, see below). A possible value for vterm-buffer-name-string is vterm %s, according to which all the vterm buffers will be named "vterm TITLE".

This requires some shell-side configuration to print the title. For example to set the name "HOSTNAME:PWD", you can use the following:

For zsh,

autoload -U add-zsh-hook
add-zsh-hook -Uz chpwd (){ print -Pn "\e]2;%m:%2~\a" }

For bash,

PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND; }"'echo -ne "\033]0;${HOSTNAME}:${PWD}\007"'

For fish,

function fish_title
    hostname
    echo ":"
    prompt_pwd
end

See zsh and bash and fish documentations.

`vterm-always-compile-module`

Vterm needs vterm-module to work. This can be compiled externally, or vterm will ask the user whether to build the module when vterm is first called. To avoid this question and always compile the module, set vterm-always-compile-module to t.

`vterm-copy-mode-remove-fake-newlines`

When not-nil fake newlines are removed on entering copy mode. vterm inserts fake-newlines purely for rendering. When using vterm-copy-mode these are in conflict with many emacs functions like isearch-forward. if this variable is not-nil the fake-newlines are removed on entering copy-mode and re-inserted on leaving copy mode. Also truncate-lines is set to t on entering copy-mode and set to nil on leaving.

`vterm-tramp-shells`

The shell that gets run in the vterm for tramp.

This has to be a list of pairs of the format: (TRAMP-METHOD SHELL)

The TRAMP-METHOD is a method string as used by tramp (e.g., "ssh"). Use t as TRAMP-METHOD to specify a default shell for all methods. Specific methods always take precedence over t.

Set SHELL to 'login-shell to use the user's login shell on the remote host. The login-shell detection currently works for POSIX-compliant remote hosts that have the getent command (regular GNU/Linux distros, *BSDs, but not MacOS X unfortunately). You can specify an additional second SHELL command as a fallback that is used when the login-shell detection fails, e.g., '(("ssh" login-shell "/bin/bash") ...) If no second SHELL command is specified with 'login-shell, vterm will fall back to tramp's shell.

Examples:

Use the default login shell for all methods, except for docker. '((t login-shell) ("docker" "/bin/sh"))
Use the default login shell for ssh and scp, fall back to "/bin/bash". Use tramp's default shell for all other methods. '(("ssh" login-shell "/bin/bash") ("scp" login-shell "/bin/bash"))

Keybindings

If you want a key to be sent to the terminal, bind it to vterm--self-insert, or remove it from vterm-mode-map. By default, vterm.el binds most of the C-<char> and M-<char> keys, <f1> through <f12> and some special keys like <backspace> and <return>. Sending a keyboard interrupt is bound to C-c C-c.

In order to send a keypress that is already recognized by Emacs, such as C-g, use the interactive function vterm-send-next-key. This can be bound to a key in the vterm-mode-map like C-q, in which case pressing C-q C-g will send a C-g key to the terminal, and so on for other modified keys:

(define-key vterm-mode-map (kbd "C-q") #'vterm-send-next-key)

This can be useful for controlling an application running in the terminal, such as Emacs or Nano.

Fonts

You can change the font (the face) used in a vterm with the following code:

(add-hook 'vterm-mode-hook
          (lambda ()
            (set (make-local-variable 'buffer-face-mode-face) 'fixed-pitch)
                 (buffer-face-mode t)))

Where instead of 'fixed-pitch you specify the face you want to use. The example reported here can be used to force vterm to use a mono-spaced font (the fixed-pitch face). This is useful when your default font in Emacs is a proportional font.

In addition to that, you can disable some text properties (bold, underline, reverse video) setting the relative option to t (vterm-disable-bold, vterm-disable-underline, or vterm-disable-inverse-video).

You can use another font for vterm buffer

(add-hook 'vterm-mode-hook
          (lambda ()
               (set (make-local-variable 'buffer-face-mode-face) '(:family "IosevkaTerm Nerd Font"))
               (buffer-face-mode t))

Blink cursor

When vterm-ignore-blink-cursor is t, vterm will ignore request from application to turn on or off cursor blink.

If nil, cursor in any window may begin to blink or not blink because blink-cursor-mode is a global minor mode in Emacs, you can use M-x blink-cursor-mode to toggle.

Colors

Customize the following faces to your liking. It is possible to specify different colors for foreground and background via the :foreground and :background attributes.

vterm-color-black
vterm-color-red
vterm-color-green
vterm-color-yellow
vterm-color-blue
vterm-color-magenta
vterm-color-cyan
vterm-color-white
vterm-color-bright-black
vterm-color-bright-red
vterm-color-bright-green
vterm-color-bright-yellow
vterm-color-bright-blue
vterm-color-bright-magenta
vterm-color-bright-cyan
vterm-color-bright-white

Directory tracking and Prompt tracking

vterm supports directory tracking. If this feature is enabled, the default directory in Emacs and the current working directory in vterm are synced. As a result, interactive functions that ask for a path or a file (e.g., dired or find-file) will do so starting from the current location.

And vterm supports prompt tracking. If this feature is enabled, Emacs knows where the prompt ends, you needn't customize term-prompt-regexp any more. Then you can use vterm-next-prompt and vterm-previous-prompt moving to end of next/previous prompt. The default keybinding is C-c C-n and C-c C-p.

And vterm-beginning-of-line would move the point to the first character after the shell prompt on this line. If the point is already there, move to the beginning of the line. The default keybinding is C-a in vterm-copy-mode.

And vterm--at-prompt-p would check whether the cursor is at the point just after the shell prompt.

Directory tracking and Prompt tracking requires some configuration, as the shell has to be instructed to share the relevant information with Emacs. The following pieces of code assume that you have the function vterm_printf as defined in section shell-side configuration.

For zsh, put this at the end of your .zshrc:

vterm_prompt_end() {
    vterm_printf "51;A$(whoami)@$(hostname):$(pwd)"
}
setopt PROMPT_SUBST
PROMPT=$PROMPT'%{$(vterm_prompt_end)%}'

For bash, put this at the end of your .bashrc:

vterm_prompt_end(){
    vterm_printf "51;A$(whoami)@$(hostname):$(pwd)"
}
PS1=$PS1'\[$(vterm_prompt_end)\]'

For fish, put this in your ~/.config/fish/config.fish:

function vterm_prompt_end;
    vterm_printf '51;A'(whoami)'@'(hostname)':'(pwd)
end
functions --copy fish_prompt vterm_old_fish_prompt
function fish_prompt --description 'Write out the prompt; do not replace this. Instead, put this at end of your file.'
    # Remove the trailing newline from the original prompt. This is done
    # using the string builtin from fish, but to make sure any escape codes
    # are correctly interpreted, use %b for printf.
    printf "%b" (string join "\n" (vterm_old_fish_prompt))
    vterm_prompt_end
end

Here we are using the function vterm_printf that we have discussed above, so make sure that this function is defined in your configuration file.

Directory tracking works on remote servers too. In case the hostname of your remote machine does not match the actual hostname needed to connect to that server, change $(hostname) with the correct one. For example, if the correct hostname is foo and the username is bar, you should have something like

HOSTNAME=foo
USER=baz
vterm_printf "51;A$USER@$HOSTNAME:$(pwd)"

Message passing

vterm can read and execute commands. At the moment, a command is passed by providing a specific escape sequence. For example, to evaluate

(message "Hello!")

use

printf "\e]51;Emessage \"Hello\!\"\e\\"
# or
vterm_printf "51;Emessage \"Hello\!\""

The commands that are understood are defined in the setting vterm-eval-cmds.

As split-string-and-unquote is used the parse the passed string, double quotes and backslashes need to be escaped via backslash. A convenient shell function to automate the substitution is

bash or zsh:

vterm_cmd() {
    local vterm_elisp
    vterm_elisp=""
    while [ $# -gt 0 ]; do
        vterm_elisp="$vterm_elisp""$(printf '"%s" ' "$(printf "%s" "$1" | sed -e 's|\\|\\\\|g' -e 's|"|\\"|g')")"
        shift
    done
    vterm_printf "51;E$vterm_elisp"
}

fish:

function vterm_cmd --description 'Run an Emacs command among the ones been defined in vterm-eval-cmds.'
    set -l vterm_elisp ()
    for arg in $argv
        set -a vterm_elisp (printf '"%s" ' (string replace -a -r -- '([\\\\"])' '\\\\\\\\$1' $arg))
    end
    vterm_printf '51;E'(string join '' $vterm_elisp)
end

Now we can write shell functions to call the ones defined in vterm-eval-cmds.

find_file() {
    vterm_cmd find-file "$(realpath "${@:-.}")"
}

say() {
    vterm_cmd message "%s" "$*"
}

Or for fish:

function find_file
    set -q argv[1]; or set argv[1] "."
    vterm_cmd find-file (realpath "$argv")
end

function say
    vterm_cmd message "%s" "$argv"
end

This newly defined find_file function can now be used inside vterm as

find_file name_of_file_in_local_directory

If you call find_file without specifying any file (you just execute find_file in your shell), dired will open with the current directory.

As an example, say you like having files opened below the current window. You could add the command to do it on the lisp side like so:

(push (list "find-file-below"
            (lambda (path)
              (if-let* ((buf (find-file-noselect path))
                        (window (display-buffer-below-selected buf nil)))
                  (select-window window)
                (message "Failed to open file: %s" path))))
      vterm-eval-cmds)

Then add the command in your .bashrc file.

open_file_below() {
    vterm_cmd find-file-below "$(realpath "${@:-.}")"
}

Then you can open any file from inside your shell.

open_file_below ~/Documents

Shell-side configuration files

The configurations described in earlier sections are combined in etc/. These can be appended to or loaded into your user configuration file. Alternatively, they can be installed system-wide, for example in /etc/bash/bashrc.d/, /etc/profile.d/ (for zsh), or /etc/fish/conf.d/ for fish.

When using vterm Emacs sets the environment variable INSIDE_EMACS in the subshell to ‘vterm’. Usually the programs check this variable to determine whether they are running inside Emacs.

Vterm also sets an extra variable EMACS_VTERM_PATH to the place where the vterm library is installed. This is very useful because when vterm is installed from melpa the Shell-side configuration files are in the EMACS_VTERM_PATH inside the /etc sub-directory. After a package update, the directory name changes, so, a code like this in your bashrc could be enough to load always the latest version of the file from the right location without coping any file manually.

if [[ "$INSIDE_EMACS" = 'vterm' ]] \
    && [[ -n ${EMACS_VTERM_PATH} ]] \
    && [[ -f ${EMACS_VTERM_PATH}/etc/emacs-vterm-bash.sh ]]; then
	source ${EMACS_VTERM_PATH}/etc/emacs-vterm-bash.sh
fi

Frequently Asked Questions and Problems

How can I increase the size of the scrollback?

By default, the scrollback can contain up to 1000 lines per each vterm buffer. You can increase this up to 100000 by changing the variable vterm-max-scrollback. If you want to increase it further, you have to edit the file vterm-module.h, change the variable SB_MAX, and set the new value for vterm-max-scrollback. The potential maximum memory consumption of vterm buffers increases with vterm-max-scrollback, so setting SB_MAX to extreme values may lead to system instabilities and crashes.

How can I automatically close vterm buffers when the process is terminated?

There is an option for that: set vterm-kill-buffer-on-exit to t.

The package does not compile, I have errors related to `VTERM_COLOR`.

The version of libvterm installed on your system is too old. You should let emacs-libvterm download libvterm for you. You can either uninstall your libvterm, or instruct Emacs to ignore the system libvterm. If you are compiling from Emacs, you can do this by setting:

(setq vterm-module-cmake-args "-DUSE_SYSTEM_LIBVTERM=no")

and compile again. If you are compiling with CMake, use the flag -DUSE_SYSTEM_LIBVTERM=no.

`<C-backspace>` doesn't kill previous word.

This can be fixed by rebinding the key to what C-w does:

(define-key vterm-mode-map (kbd "<C-backspace>")
    (lambda () (interactive) (vterm-send-key (kbd "C-w"))))

`counsel-yank-pop` doesn't work.

Add this piece of code to your configuration file to make counsel use the correct function to yank in vterm buffers.

(defun vterm-counsel-yank-pop-action (orig-fun &rest args)
  (if (equal major-mode 'vterm-mode)
      (let ((inhibit-read-only t)
            (yank-undo-function (lambda (_start _end) (vterm-undo))))
        (cl-letf (((symbol-function 'insert-for-yank)
               (lambda (str) (vterm-send-string str t))))
            (apply orig-fun args)))
    (apply orig-fun args)))

(advice-add 'counsel-yank-pop-action :around #'vterm-counsel-yank-pop-action)

How can I get the local directory without shell-side configuration?

We recommend that you set up shell-side configuration for reliable directory tracking. If you cannot do it, a possible workaround is the following.

On most GNU/Linux systems, you can read current directory from /proc:

(defun vterm-directory-sync ()
  "Synchronize current working directory."
  (interactive)
  (when vterm--process
    (let* ((pid (process-id vterm--process))
           (dir (file-truename (format "/proc/%d/cwd/" pid))))
      (setq default-directory dir))))

A possible application of this function is in combination with find-file:

(advice-add #'find-file :before #'vterm-directory-sync)

This method does not work on remote machines.

How can I get the directory tracking in a more understandable way?

If you looked at the recommended way to set-up directory tracking, you will have noticed that it requires printing obscure code like \e]2;%m:%2~\a (unless you are using fish).

There is another way to achieve this behavior. Define a shell function, on a local host you can simply use

vterm_set_directory() {
    vterm_cmd update-pwd "$PWD/"
}

On a remote one, use instead

vterm_set_directory() {
    vterm_cmd update-pwd "/-:""$USER""@""$HOSTNAME"":""$PWD/"
}

Then, for zsh, add this function to the chpwd hook:

autoload -U add-zsh-hook
add-zsh-hook -Uz chpwd (){ vterm_set_directory }

For bash, append it to the prompt:

PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND; }vterm_set_directory"

Finally, add update-pwd to the list of commands that Emacs is allowed to execute from vterm:

(add-to-list 'vterm-eval-cmds '("update-pwd" (lambda (path) (setq default-directory path))))

When evil-mode is enabled, the cursor moves back in normal state, and this messes directory tracking

evil-collection provides a solution for this problem. If you do not want to use evil-collection, you can add the following code:

(defun evil-collection-vterm-escape-stay ()
"Go back to normal state but don't move
cursor backwards. Moving cursor backwards is the default vim behavior but it is
not appropriate in some cases like terminals."
(setq-local evil-move-cursor-back nil))

(add-hook 'vterm-mode-hook #'evil-collection-vterm-escape-stay)

Related packages

vterm-toggle: Toggles between a vterm and the current buffer
multi-libvterm: Multiterm for emacs-libvterm

Appendix

Breaking changes

Obsolete variables will be removed in version 0.1.

August 2022

vterm-send-C-[a-z] vterm-send-M-[a-z] vterm-define-key vterm-send-{up/down/left/right/prior/next/meta-dot/meta-comma/ctrl-slash} were obsolete, please use vterm-send or vterm-send-key or vterm--self-insert instead.

October 2020

vterm-disable-bold-font was renamed to vterm-disable-bold to uniform it with the other similar options.

July 2020

vterm-use-vterm-prompt was renamed to vterm-use-vterm-prompt-detection-method.
vterm-kill-buffer-on-exit is set to t by default.

April 2020

vterm-clear-scrollback was renamed to vterm-clear-scrollback-when-clearning.
vterm-set-title-functions was removed. In its place, there is a new custom option vterm-buffer-name-string. See vterm-buffer-name-string for documentation.

MatthewZMD/aidermacs

AI Pair Programming in Emacs with Aider

Aidermacs: AI Pair Programming in Emacs

Aidermacs brings AI-powered development to Emacs by integrating Aider, one of the most powerful open-source AI pair programming tools. If you're missing Cursor but prefer living in Emacs, Aidermacs provides similar AI capabilities while staying true to Emacs workflows.

Key Features

Intelligent model selection with multiple backends
Built-in Ediff integration for AI-generated changes
Enhanced file management from Emacs
Great customizability and flexible ways to add content

Community Speaks

Here's what the community is saying about Aidermacs:

"Are you using aidermacs? For me superior to cursor." - u/berenddeboer

"This is amazing... every time I upgrade my packages I see your new commits. I feel this the authentic aider for emacs" - u/wchmbo

"Between Aidermacs and Gptel it's wild how bleeding edge Emacs is with this stuff. My workplace is exploring MCP registries and even clients that are all the rage (E.g Cursor) lag behind what I can do with mcp.el and gptel for tool use." - u/no_good_names_avail

"This looks amazing... I have been using ellama with local llms, looks like that will work here too. Great stuff!!" - u/lugpocalypse

"Honestly huge fan of this. Thank you for the updates!" - u/ieoa

Quick Start

Requirements

Emacs ≥ 26.1
Aider or its community fork Aider Community Experimentation.
Transient

Download Aidermacs through Melpa or Non-GNU Elpa, or clone manually
Modify this sample config and place it in your Emacs init.el:

(use-package aidermacs
  :bind (("C-c a" . aidermacs-transient-menu))
  :config
  ; Set API_KEY in .bashrc, that will automatically picked up by aider or in elisp
  (setenv "ANTHROPIC_API_KEY" "sk-...")
  ; defun my-get-openrouter-api-key yourself elsewhere for security reasons
  (setenv "OPENROUTER_API_KEY" (my-get-openrouter-api-key))
  :custom
  ; See the Configuration section below
  (aidermacs-default-chat-mode 'architect)
  (aidermacs-default-model "sonnet"))

Open a project and run M-x aidermacs-transient-menu or SPC a a (or your chosen binding).
Add files and start coding with AI!

Spacemacs

For Spacemacs users:

Add aidermacs to your dotspacemacs-additional-packages list in your .spacemacs file:

dotspacemacs-additional-packages '(
  (aidermacs :variables
              aidermacs-default-chat-mode 'architect
              aidermacs-default-model "sonnet")
)

Add the keybinding to your dotspacemacs/user-config function in .spacemacs:

(defun dotspacemacs/user-config ()
  ;; Set leader key for Aidermacs
  (spacemacs/set-leader-keys "aa" 'aidermacs-transient-menu) ; Example binding SPC a a
)

Open a project and run M-x aidermacs-transient-menu or SPC a a (or your chosen binding).
Add files and start coding with AI!

Usage

Getting Started

The main interface to Aidermacs is through its transient menu system (similar to Magit). Access it with:

M-x aidermacs-transient-menu

Or bind it to a key in your config:

(global-set-key (kbd "C-c a") 'aidermacs-transient-menu)

Once the transient menu is open, you can navigate and execute commands using the displayed keys. Here's a summary of the main menu structure:

Core

a: Start/Open Session (auto-detects project root)
.: Start in Current Directory (good for monorepos)
l: Clear Chat History
s: Reset Session
x: Exit Session

Persistent Modes

1: Code Mode
2: Chat/Ask Mode
3: Architect Mode
4: Help Mode

Utilities

^: Show Last Commit (if auto-commits enabled)
u: Undo Last Commit (if auto-commits enabled)
R: Refresh Repo Map
h: Session History
o: Change Main Model
v: Send Voice Command
W: Fetch Web Content
?: Aider Meta-level Help

File Actions

f: Add File (C-u: read-only)
F: Add Current File
d: Add From Directory (same type)
w: Add From Window
m: Add From Dired (marked)
j: Drop File
J: Drop Current File
k: Drop From Dired (marked)
K: Drop All Files
S: Create Session Scratchpad
G: Add File to Session
A: List Added Files

Code Actions

c: Code Change
e: Question Code
r: Architect Change
q: General Question
p: Question This Symbol
g: Accept Proposed Changes
i: Implement TODO
t: Write Test
T: Fix Test
!: Debug Exception

The All File Actions and All Code Actions entries open submenus with more specialized commands. Use the displayed keys to navigate these submenus.

File Management and AI Interaction

When using Aidermacs, you have the flexibility to decide which files the AI should read and edit. Here are some guidelines:

Editable Files: Add files you want the AI to potentially edit. This grants the AI permission to both read and modify these files if necessary.
Read-Only Files: If you want the AI to read a file without editing it, you can add it as read-only. In Aidermacs, all add file commands can be prefixed with C-u to specify read-only access.
Session Scratchpads: Use the session scratchpads (S) to paste notes or documentation that will be fed to the AI as read-only.
External Files: The "Add file to session" (G) command allows you to include files outside the current project (or files in .gitignore), as Aider doesn't automatically include these files in its context.

The AI can sometimes determine relevant files on its own, depending on the model and the context of the codebase. However, for precise control, it's often beneficial to manually specify files, especially when dealing with complex projects.

Aider encourages a collaborative approach, similar to working with a human co-worker. Sometimes the AI will need explicit guidance, while other times it can infer the necessary context on its own.

Prompt Files Minor Mode

Aidermacs provides a minor mode that makes it easy to work with prompt files and other Aider-related files. When enabled, the minor mode provides these convenient keybindings:

C-c C-n or C-<return>: Send line/region line-by-line
C-c C-c: Send block/region as whole
C-c C-z: Switch to Aidermacs buffer

The minor mode is automatically enabled for:

.aider.prompt.org files (create with M-x aidermacs-open-prompt-file)
.aider.chat.md files
.aider.chat.history.md files
.aider.input.history files

Configuration

Pre-Run Hook

You can use the aidermacs-before-run-backend-hook to run custom setup code before starting the Aider backend. This is particularly useful for:

Setting environment variables
Injecting secrets
Performing any other pre-run configuration

Example usage to securely set an OpenAI API key from password-store:

(add-hook 'aidermacs-before-run-backend-hook
          (lambda ()
            (setenv "OPENAI_API_KEY" (password-store-get "code/openai_api_key"))))

An copy of process-environment is used when running the hook and starting Aider, ensuring environment variables set in the hook only affect the Aider backend. This approach keeps sensitive information out of your dotfiles while still making it available to Aidermacs.

Default Model Selection

You can customize the default AI model used by Aidermacs. The model is determined in the following order of priority:

The value of the Emacs variable aidermacs-default-model if you have set it (e.g., via setq).
The value of the AIDER_MODEL environment variable, if set.
A built-in default value (e.g., "sonnet").

To set it in Emacs:

(setq aidermacs-default-model "sonnet")

This enables easy switching between different AI models without modifying the aidermacs-extra-args variable.

Note: This configuration will be overwritten by the existence of an .aider.conf.yml file (see details).

Dynamic Model Selection

Aidermacs offers intelligent model selection for solo (non-Architect) mode, automatically detecting and integrating with multiple AI providers:

Automatically fetches available models from supported providers (OpenAI, Anthropic, DeepSeek, Google Gemini, OpenRouter)
Caches model lists for quick access
Supports both popular pre-configured models and dynamically discovered ones
Handles API keys and authentication automatically from your .bashrc
Provides model compatibility checking

The dynamic model selection is only for the solo (non-Architect) mode.

To change models in solo mode:

Use M-x aidermacs-change-model or press o in the transient menu
Select from either:
- Popular pre-configured models (fast)
- Dynamically fetched models from all supported providers (comprehensive)

The system will automatically filter models to only show ones that are:

Supported by your current Aider version
Available through your configured API keys
Compatible with your current workflow

Architect Mode - Separating Code Reasoning and Editing Models

Aidermacs features an experimental mode using two specialized models for each coding task: an Architect model for reasoning and an Editor model for code generation. This approach has achieved state-of-the-art (SOTA) results on aider's code editing benchmark, as detailed in this blog post.

To start new sessions in Architect mode by default, set aidermacs-default-chat-mode to 'architect.

aidermacs-use-architect-mode is deprecated and will be removed in a future release.

architect mode will default to using aidermacs-default-model. You may also configure the aidermacs-architect-model variable to specify the model to use for the Architect role if you prefer a different main model when using architect mode.

By default, the aidermacs-editor-model is the same as aidermacs-default-model. You only need to set aidermacs-editor-model if you want to use a different model for the Editor role. This variable also respects the AIDER_EDITOR_MODEL environment variable, following the same priority as aidermacs-default-model.

(setq aidermacs-default-chat-mode 'architect)

You can switch to it persistently by M-x aidermacs-switch-to-architect-mode (3 in aidermacs-transient-menu), or temporarily with M-x aidermacs-architect-this-code (r in aidermacs-transient-menu).

You can configure each model independently:

;; Default model used for all modes unless overridden
(setq aidermacs-default-model "sonnet")

;; Optional: Set specific model for architect reasoning
(setq aidermacs-architect-model "deepseek/deepseek-reasoner")

;; Optional: Set specific model for code generation
(setq aidermacs-editor-model "deepseek/deepseek-chat")

The model hierarchy works as follows:

When Architect mode is enabled:
- The Architect model handles high-level reasoning and solution design
- The Editor model executes the actual code changes
When Architect mode is disabled, only aidermacs-default-model is used
You can configure specific models or let them automatically use the default model

Models will reflect changes to aidermacs-default-model unless they've been explicitly set to a different value.

Note: These configurations will be overwritten by the existence of an .aider.conf.yml file (see details).

Customize Weak Model

The Weak model is used for commit messages (if you have aidermacs-auto-commits set to t) and chat history summarization (default depends on –model). You can customize it using the aidermacs-weak-model variable, which also respects the AIDER_WEAK_MODEL environment variable.

;; default to nil
(setq aidermacs-weak-model "deepseek/deepseek-chat")

You can change the Weak model during a session by using C-u o (aidermacs-change-model with a prefix argument). In most cases, you won't need to change this as Aider will automatically select an appropriate Weak model based on your main model.

Note: These configurations will be overwritten by the existence of an .aider.conf.yml file (see details).

Architect Mode Confirmation

By default, Aidermacs requires explicit confirmation before applying changes proposed in Architect mode. This gives you a chance to review the AI's plan before any code is modified.

If you prefer to automatically accept all Architect mode changes without confirmation (similar to Aider's default behavior), you can enable this with:

(setq aidermacs-auto-accept-architect t)

Note: These configurations will be overwritten by the existence of an .aider.conf.yml file (see details).

Terminal Backend Selection

Choose your preferred terminal backend by setting aidermacs-backend:

vterm offers better terminal compatibility, while comint provides a simple, built-in option that remains fully compatible with Aidermacs.

;; Use vterm backend (default is comint)
(setq aidermacs-backend 'vterm)

Available backends:

comint (default): Uses Emacs' built-in terminal emulation
vterm: Leverages vterm for better terminal compatibility

Emacs theme support

The vterm backend will use the faces defined by your active Emacs theme to set the colors for aider. It tries to guess some reasonable color values based on your themes. In some cases this will not work perfectly; if text is unreadable for you, you can turn this off as follows:

;; don't match emacs theme colors
(setopt aidermacs-vterm-use-theme-colors nil)

Multiline Input Configuration

You can customize keybindings for multiline input, this key allows you to enter multiple lines without sending the command to Aider. Press RET normally to send the command.

;; Comint backend:
(setq aidermacs-comint-multiline-newline-key "S-<return>")
;; Vterm backend:
(setq aidermacs-vterm-multiline-newline-key "S-<return>")

Remote File Support with Tramp

Aidermacs fully supports working with remote files through Emacs' Tramp mode. This allows you to use Aidermacs on files hosted on remote servers via SSH, Docker, and other protocols supported by Tramp.

When working with remote files:

File paths are automatically localized for the remote system
All Aidermacs features work seamlessly across local and remote files
Edits are applied directly to the remote files
Diffs and change reviews work as expected

Example usage:

;; Open a remote file via SSH
(find-file "/ssh:user@remotehost:/path/to/file.py")

;; Start Aidermacs session - it will automatically detect the remote context
M-x aidermacs-transient-menu

Prompt Selection and History

Aidermacs makes it easy to reuse prompts through:

Prompt History - Your previously used prompts are saved and can be quickly selected
Common Prompts - A curated list of frequently used prompts for common tasks defined in aidermacs-common-prompts:

When entering a prompt, you can:

Select from your history or common prompts using completion
Still type custom prompts when needed

The prompt history and common prompts are available across all sessions.

File Watching

Enable watching for AI coding instructions in your repository files with aidermacs-watch-files:

;; Enable file watching
(setq aidermacs-watch-files t)

When enabled, Aidermacs will will watch all files in your repo and look for any AI coding instructions you add using your favorite IDE or text editor.

Specifically, aider looks for one-liner comments (# ..., // ... or -- ..., regardless of the comment style that language supports) that either start or end with AI, AI! or AI? like these:

# Make a snake game. AI!
# What is the purpose of this method AI?

// Write a protein folding prediction engine. AI!

Aidermacs will take note of all the comments that start or end with AI. Comments that include AI! with an exclamation point or AI? with a question mark are special. They trigger aider to take action to collect all the AI comments and use them as your instructions.

AI! triggers aider to make changes to your code.
AI? triggers aider to answer your question.

Note: This feature currently only works in the vterm mode.

Note: These configurations will be overwritten by the existence of an .aider.conf.yml file (see details).

Read-Only Files

You can configure certain files to always be added as read-only when starting any Aidermacs session by setting the aidermacs-global-read-only-files and aidermacs-project-read-only-files.

;; Always add these files as read-only to all Aidermacs sessions
;; For files that exists outside the project directory
(setq aidermacs-global-read-only-files '("~/.aider/AI_RULES.md"))
;; For files that exists within the project directory
(setq aidermacs-project-read-only-files '("CONVENTIONS.md" "README.md"))

When an Aidermacs session starts, these files will be automatically added as read-only if they exist in the project. This is useful for documentation files or other references that you want the AI to be aware of but not modify.

Diff and Change Review

Control whether to show diffs for AI-generated changes with aidermacs-show-diff-after-change:

;; Enable/disable showing diffs after changes (default: t)
(setq aidermacs-show-diff-after-change t)

When enabled, Aidermacs will:

Capture the state of files before AI edits
Show diffs using Emacs' built-in ediff interface
Allow you to review and accept/reject changes

Re-Enable Auto-Commits

Aider automatically commits AI-generated changes by default. We consider this behavior very intrusive, so we've disabled it. You can re-enable auto-commits by setting aidermacs-auto-commits to t:

;; Enable auto-commits
(setq aidermacs-auto-commits t)

With auto-commits disabled, you must manually commit changes using your preferred Git workflow.

Note: This configuration will be overwritten by the existence of an .aider.conf.yml file (see details).

Control Buffer Killing on Exit

By default, when you exit an Aidermacs session using aidermacs-exit (or x in the transient menu), the Aidermacs buffer remains open. If you prefer the buffer to be automatically killed upon exiting the session, you can customize this behavior:

;; Kill the Aider buffer when exiting the session
(setq aidermacs-exit-kills-buffer t)

Customize Aider Options with `aidermacs-extra-args`

If these configurations aren't sufficient, the aidermacs-extra-args variable enables passing any Aider-supported command-line options.

See the Aider configuration documentation for a full list of available options.

;; Set the verbosity:
(add-to-list 'aidermacs-extra-args "--verbose")

These arguments will be appended to the Aider command when it is run. Note that the --model argument is automatically handled by aidermacs-default-model and should not be included in aidermacs-extra-args.

Overwrite Configuration with Configuration File

Aidermacs supports project-specific configurations via .aider.conf.yml files. To enable this:

Create a .aider.conf.yml in your home dir, project's root, or the current directory, defining your desired settings. See the Aider documentation for available options.

Tell Aidermacs to use the config file in one of two ways:

;; Set the `aidermacs-config-file` variable in your Emacs config:
(setq aidermacs-config-file "/path/to/your/project/.aider.conf.yml")
;; *Or*, include the `--config` or `-c` flag in `aidermacs-extra-args`:
(setq aidermacs-extra-args '("--config" "/path/to/your/project/.aider.conf.yml"))

Note: You can also rely on Aider's default behavior of automatically searching for .aider.conf.yml in the home directory, project root, or current directory, in that order. In this case, you do not need to set aidermacs-config-file or include --config in aidermacs-extra-args.

Important: Configuration Precedence

When an Aidermacs session starts, it determines which settings to use based on the following hierarchy:

Aider Configuration File (.aider.conf.yml): If a config file is found (either in a default location or specified via aidermacs-config-file or aidermacs-extra-args), it takes highest priority. Aidermacs will ignore its own Emacs variables (like aidermacs-default-model) and let the aider tool manage settings directly from the file. The precedence is then determined by aider itself (where command-line arguments override environment variables, which override the config file).
Emacs Configuration (if no config file is used): If no .aider.conf.yml is present, Aidermacs will build the command-line arguments for aider. The values it uses are determined by this order of priority: a. Emacs Variables (Highest): Values you set in your init.el (e.g., (setq aidermacs-default-model "...")). b. Environment Variables: If an Emacs variable is not set, its value is taken from the corresponding environment variable (e.g., AIDER_MODEL). c. Built-in Defaults (Lowest): If neither of the above are set, a hardcoded default is used.

To avoid conflicts: When using a .aider.conf.yml file, you should define all your settings within that file. Do not set variables like aidermacs-default-model in Emacs or pass arguments like --model in aidermacs-extra-args, as they will be ignored and can cause confusion.

Claude Sonnet 3.7, 4, 4.5 Thinking Tokens

Aider can work with Sonnet 3.7's new thinking tokens and newer models in this series. You can now enable and configure thinking tokens more easily using the following methods:

In-Chat Command: Use the /think-tokens command followed by the desired token budget. For example: /think-tokens 8k or /think-tokens 10000. Supported formats include 8096, 8k, 10.5k, and 0.5M.
Command-Line Argument: Set the --thinking-tokens argument when starting Aidermacs. For example, you can add this to your aidermacs-extra-args:
```
(setq aidermacs-extra-args '("--thinking-tokens" "16k"))
```

These methods provide a more streamlined way to control thinking tokens without requiring manual configuration of .aider.model.settings.yml files.

Note: If you are using an .aider.conf.yml file, you can also set the thinking_tokens option there.

Working with Prompt Files

The .aider.prompt.org file is particularly useful for:

Storing frequently used prompts
Documenting common workflows
Quick access to complex instructions

You can customize which files automatically enable the minor mode by configuring aidermacs-auto-mode-files:

(setq aidermacs-auto-mode-files
      '(".aider.prompt.org"
        ".aider.chat.md"
        ".aider.chat.history.md"
        ".aider.input.history"
        "my-custom-aider-file.org"))  ; Add your own files

FAQ

Aider?

Please check Aider's FAQ for Aider related questions.

Can I use my own AI models?

Yes! Aidermacs supports any OpenAI-compatible API endpoint. Check Aider documentation on Ollama and LiteLLM.

Is my code sent to the AI provider?

Yes, the code you add to the session is sent to the AI provider. Be mindful of sensitive code.

Why aider not support Python 3.13

Aider only support Python 3.12 currently, you can use uv install aider:

uv tool install --force --python python3.12 aider-chat@latest

If you encounter a proxy-related issue , such as the error indicating that the 'socksio' package is not installed, please use:

uv tool install --force --python python3.12 aider-chat@latest --with 'httpx[socks]'

And adjust aidermacs program with below config.

(setq aidermacs-program (expand-file-name "~/.local/bin/aider"))

Local models prefer English, even if the prompt language is different

Some local models in aider may default to English, even if you use a different language in your prompt. To ensure the chat language matches your preference (e.g., Russian), add the following to your Emacs configuration:

(add-to-list 'aidermacs-extra-args "--chat-language ru")

This will instruct aider to use Russian for chat interactions.

Aidermacs or Aider ignores command-line arguments and prompts for provider selection when using Ollama

If the ~/.aider directory exists (even if empty), Aidermacs or Aider may silently ignore command-line arguments and unexpectedly prompt for provider selection (e.g., forcing OpenRouter), even if your configuration is correct for Ollama or other providers.

Workaround: Remove the existing aider directory and restart Emacs:

rm -rf ~/.aider*

After this, Aidermacs should start as expected with your configured provider (e.g., Ollama).

Aidermacs vs Aider CLI vs aider.el?

Aidermacs is designed to provide a more Emacs-native experience while integrating with Aider CLI. It began as a fork of aider.el, but has since diverged significantly to prioritize Emacs workflow integration, built by Emacser, for Emacser.

While aider.el tries to mirror Aider's CLI behavior, Aidermacs is built around Emacs-specific features and paradigms. This design philosophy allows you to harness Aider's powerful capabilities through a natural, Emacs-native coding experience.

With Aidermacs, you get:

Built-in Ediff Integration for AI-Generated Changes
- Seamless Code Review: Automatically shows diffs for all AI-modified files using Emacs' powerful ediff interface
- Familiar Interface: Uses Emacs' native ediff workflow for reviewing changes
- Interactive Workflow: Accept or reject changes with standard ediff commands
- Syntax Highlighting: Maintains proper syntax highlighting during comparisons
- Safe Change Management: Preserves original file states for easy comparison and rollback
Intelligent Model Selection
- Automatic discovery of available models from multiple providers
- Real-time model compatibility checking
- Seamless integration with your configured API keys
- Caching for quick access to frequently used models
- Support for both popular pre-configured models and dynamically discovered ones
Flexible Terminal Backend Support
- Aidermacs supports multiple terminal backends (comint and vterm) for better compatibility and performance
- Easy configuration to choose your preferred terminal emulation
- Extensible architecture for adding new backends
Smarter Syntax Highlighting
- AI-generated code appears with proper syntax highlighting in major languages.
- Ensures clarity and readability without additional configuration.
Better Support for Multiline Input
- Aider is designed as a CLI program, where multiline input is restricted by terminal limitations.
- Terminal-based tools require special syntax or manual formatting to handle multiline input, which can be cumbersome and unintuitive.
- Aidermacs eliminates these restrictions by handling multiline prompts natively within Emacs, allowing you to compose complex AI requests just like any other text input.
- Whether you're pasting blocks of code or refining AI-generated responses, multiline interactions in Aidermacs feel natural and seamless.
Enhanced File Management from Emacs
- List files currently in chat with M-x aidermacs-list-added-files
- Drop specific files from chat with M-x aidermacs-drop-file
- View output history with M-x aidermacs-show-output-history
- Interactively select files to add with M-x aidermacs-add-files-interactively
- Add content from any file to a specific session with M-x aidermacs-add-file-to-session
- Create a temporary file for adding code snippets or notes to the Aider session with M-x aidermacs-create-session-scratchpad
- Full support for remote files via Tramp (SSH, Docker, etc.)
- and more
Greater Configurability
- Aidermacs offers more customization options to tailor the experience to your preferences.
Streamlined Transient Menu Selection
- The transient menus have been completely redesigned to encompass functionality and ergonomics, prioritizing user experience.
Flexible Ways to Add Content
- Aidermacs provides multiple ways to add content to the Aider session, including adding files, creating temporary scratchpad files, and more.
Community-Driven Development
- Aidermacs is actively developed and maintained by the community, incorporating user feedback and contributions.
- We prioritize features and improvements that directly benefit Emacs users, ensuring a tool that evolves with your needs.

... and more to come 🚀

Video Demo

Community-Driven Development

Aidermacs thrives on community involvement. We believe collaborative development with user and contributor input creates the best software. We encourage you to:

Contribute Code: Submit pull requests with bug fixes, new features, or improvements to existing functionality.
Report Issues: Let us know about any bugs, unexpected behavior, or feature requests through GitHub Issues.
Share Ideas: Participate in discussions and propose new ideas for making Aidermacs even better.
Improve Documentation: Help us make the documentation clearer, more comprehensive, and easier to use.

Your contributions are essential for making Aidermacs the best AI pair programming tool in Emacs!

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 interact with any ACP-driven agent like:

[[https://code.claude.com/docs/en/overview][Claude Agent]] (Anthropic)
[[https://github.com/agentclientprotocol/codex-acp][Codex]] (OpenAI)
[[https://github.com/google-gemini/gemini-cli][Gemini CLI]] (Google)
[[https://goose-docs.ai/docs/getting-started/installation][Goose]]
[[https://docs.x.ai/docs/overview][Grok Build]] (xAI)
[[https://cursor.com/docs/cli][Cursor]]
[[https://www.kimi.com/code][Kimi Code CLI]]
[[https://www.codebuddy.ai][CodeBuddy]]
[[https://kiro.dev][Kiro CLI]]
[[https://github.com/QwenLM/qwen-code][Qwen Code]]
[[https://docs.augmentcode.com/cli/overview][Auggie]]
[[https://github.com/mistralai/mistral-vibe][Mistral Vibe]]
[[https://factory.ai][Factory Droid]]
[[https://github.com/svkozak/pi-acp][Pi]]
[[https://github.com/can1357/oh-my-pi][Oh My Pi]]
[[https://opencode.ai][Opencode]]

[[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]]

[[https://www.youtube.com/watch?v=7fdHeUoRRgg][Bending Emacs Episode 14: Prototyping iOS apps with agent-shell, artist-mode, and Claude Skills - YouTube]]

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

News

Do take a look at all these blog posts as they showcase most =agent-shell= features.

[[https://xenodium.com/agent-shell-0-63-updates][agent-shell 0.63 updates]].
[[https://xenodium.com/agent-shell-0-55-updates][agent-shell 0.55 updates]].
[[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.
[[https://github.com/alberti42/agent-shell-math-renderer][agent-shell-math-renderer]]: Render LaTeX math equations as SVGs in =agent-shell=.
[[https://github.com/junyi-hou/agent-shell-tramp][agent-shell-tramp]]: Tramp integration for =agent-shell=.
[[https://github.com/nohzafk/agent-shell-hud][agent-shell-hud]]: Real-time =agent-shell= status overlay via a floating dashboard.
[[https://github.com/timfel/agent-shell-desktop.el][agent-shell-desktop]]: Desktop save mode integration for =agent-shell=. Saves and resumes shells by folder, config, and session id.
[[https://github.com/ultronozm/agent-shell-links.el][agent-shell-links.el]]: Bookmarks and Org links for =agent-shell= sessions.
[[https://github.com/wandersoncferreira/agent-shell-dashboard][agent-shell-dashboard]]: A landing page for =agent-shell=.
[[https://github.com/SreenivasVRao/agent-shell-hq][agent-shell-hq]]: A heads-up display and peek interface for managing multiple =agent-shell= sessions, organized by project.

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]].
Fedora Project Wiki: [[https://fedoraproject.org/wiki/SIGs/AI-ML#agent-shell][AI/ML Special Interest Group]].

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/agentclientprotocol/codex-acp][@agentclientprotocol/codex-acp]] (=npm install -g @agentclientprotocol/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://goose-docs.ai/docs/getting-started/installation][goose]] and ensure the =goose= executable is in PATH.

*** Grok Build (xAI)

For [[https://docs.x.ai/docs/overview][Grok Build]], install the Grok CLI so =grok= is on =PATH= (the installer typically puts it at =~/.grok/bin=). Authenticate once via the CLI login flow (credentials live in =~/.grok/auth.json=).

Grok Build speaks ACP over stdio:

#+begin_src bash grok agent stdio #+end_src

Optional flags (set via =agent-shell-xai-acp-command=):

#+begin_src bash grok agent -m grok-build stdio grok agent --always-approve stdio #+end_src

See also the [[https://zed.dev/acp/agent/grok-build][Zed ACP registry listing]] for Grok Build.

*** Cursor

For Cursor agent, install the official [[https://cursor.com/docs/cli][Cursor CLI]] and ensure the =agent= executable is in PATH. =agent-shell= uses its official ACP server (=agent acp=).

A recent Cursor CLI is required (the =acp= subcommand was added in 2026). Older CLIs won't expose =agent acp=.

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

*** CodeBuddy

For CodeBuddy agent, install the CodeBuddy CLI and ensure ACP mode is available. For example:

#+begin_src bash codebuddy --acp #+end_src

See https://www.codebuddy.ai/docs/zh/ide/Getting-Started/Installation 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. *** Oh My Pi (=omp=)

For the =omp= agent, install with:

#+begin_src bash bun install -g @oh-my-pi/pi-coding-agent #+end_src

See https://github.com/can1357/oh-my-pi for details.

*** Opencode + local ollama models

For opencode coding agent, install with:

#+begin_src bash curl -fsSL https://opencode.ai/install | bash #+end_src

See https://opencode.ai/ for details.

For local ollama models, sudo permission is needed to initialize ~ollama.service~. The following will install ollama and a local Qwen2.5:7b model.

#+begin_src bash curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:7b #+end_src

If you are behind a network proxy, ~ollama pull~ will timeout. You then need to add proxy settings inside ~/etc/systemd/system/ollama.service~

See https://ollama.com/ 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]]).

*** Optional: image utilities

Pasting images from the clipboard (=agent-shell-send-clipboard-image= or =yank= or =C-y=) and capturing screenshots (=agent-shell-send-screenshot=) rely on external tools. Install the ones for your platform:

| Platform | Clipboard paste | Screenshot capture | |-----------------+------------------------------------------+------------------------------| | macOS | =brew install pngpaste= | =screencapture= (preinstalled) | | Linux (Wayland) | =wl-paste= (e.g. =apt install wl-clipboard=) | =import= (from ImageMagick) | | Linux (X11) | =apt install xclip= | =import= (from ImageMagick) | | Windows | =powershell= | (not bundled) |

Handlers are detected at runtime via =executable-find=. See =agent-shell-clipboard-image-handlers= and =agent-shell-screenshot-command= to customize.

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

By default, authentication is handled by Goose's built-in configuration. This needs no =agent-shell= configuration.

Optionally, pass an OpenAI API key from =agent-shell= instead:

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

For an OpenAI-compatible provider (for example OpenRouter), pass the API key and set the base URL and model via =agent-shell-qwen-environment=:

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

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

(setq agent-shell-qwen-environment (agent-shell-make-environment-variables "OPENAI_BASE_URL" "https://openrouter.ai/api/v1" "OPENAI_MODEL" "x-ai/grok-4.3")) #+end_src

*** Cursor

By default authentication is handled externally: run =agent login= once outside Emacs and agent-shell uses that existing login (it sends no ACP authenticate request). This needs no configuration.

Optionally, have agent-shell drive login-based authentication (=cursor_login=):

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

For API key authentication (passed via the =CURSOR_API_KEY= environment variable):

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

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

For auth token authentication (passed via the =CURSOR_AUTH_TOKEN= environment variable):

#+begin_src emacs-lisp (setq agent-shell-cursor-authentication (agent-shell-cursor-make-authentication :auth-token "your-cursor-auth-token")) #+end_src

For no authentication (already authenticated externally):

#+begin_src emacs-lisp (setq agent-shell-cursor-authentication (agent-shell-cursor-make-authentication :none 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

*** Opencode + local ollama Qwen2.5

If ~opencode~ is not found by ~agent-shell~, you can add it to the search path

#+begin_src emacs-lisp (use-package agent-shell :ensure t :config (add-to-list 'exec-path "~/.opencode/bin/")) #+end_src

To register the local Qwen2.5:7b model in opencode, two files needs to be edited:

~/.config/opencode/opencode.json~ #+BEGIN_SRC js { "$schema": "https://opencode.ai/config.json", "permission": { "edit": "ask", "bash": "ask", "webfetch": "allow" }, "provider": { "ollama": { "name": "qwen2.5:7b", "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "qwen2.5:7b": { "name": "Qwen2.5 7b" } } } } } #+END_SRC

and a dummy auth file ~/.local/share/opencode/auth.json~

#+begin_src js { "ollama": { "type": "api", "key": "ollama" } } #+end_src

Huge thanks for /gdindi/ for finding and and describing this in https://github.com/xenodium/agent-shell/issues/526

*** Customizing Available Agents

By default, =agent-shell= includes configurations for all supported agents (Claude Agent, Gemini CLI, Codex, Goose, Grok Build, Cursor, CodeBuddy, 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.

*** Viewport interaction

Viewport is an alternative interface for composing prompts and viewing one request/response interaction at a time. It uses a separate buffer named after its associated shell with =" [viewport]"= appended. This buffer switches between =agent-shell-viewport-edit-mode= while composing and =agent-shell-viewport-view-mode= while reading.

Use one of these entry points to create and initialize the viewport buffer:

From an agent shell, type =C-c C-o= (=agent-shell-other-buffer=). At the live prompt this opens the viewport for composing; from an earlier interaction it opens the viewport at that interaction. Use =C-c C-o= again to return to the shell (=o= also works from viewport view mode).
Run =M-x agent-shell-prompt-compose= to compose in a dedicated buffer. With the default configuration, =C-c C-c= sends or queues the prompt and dismisses the compose window.
Set =agent-shell-prefer-viewport-interaction= to make the normal =agent-shell= command and related commands prefer the viewport:

#+begin_src emacs-lisp (setopt agent-shell-prefer-viewport-interaction t) #+end_src

In edit mode, =C-c C-c= sends or queues the prompt and switches to view mode when viewport interaction is preferred. Use =C-u C-c C-c= to send or queue while keeping the compose buffer open, =C-c C-p= to peek at the latest interaction without losing the draft, =C-c C-k= to cancel, and =C-c C-h= for help.

In view mode, use =r= to compose a reply, =R= to quote the response in a reply, =b= / =f= to move between interactions, =p= / =n= to move between items, =?= for help, and =q= to bury the viewport.

#+begin_quote [!NOTE]

Do not invoke =agent-shell-viewport-edit-mode= or =agent-shell-viewport-view-mode= directly in an agent shell buffer. They are major modes installed by the entry points above on the separate viewport buffer, not commands for converting the shell buffer. #+end_quote

*** 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-codebuddy-start-agent= - Start a CodeBuddy 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-xai-start-grok= - Start a Grok Build (xAI) 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

Or by identifier (e.g. Grok Build):

#+begin_src emacs-lisp (setq agent-shell-preferred-agent-config 'grok-build) #+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. If you configure =agent-shell-dot-subdir-function= to store data outside the project =.agent-shell/= directory, agent-shell will not update the project's =.gitignore=.

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

*** Keeping the system awake during long turns

Long agent turns can outlast the system idle-sleep timeout, suspending the machine (and the agent) before the turn completes. On Emacs 31.1 or later, =agent-shell-inhibit-system-sleep= (enabled by default) keeps the system awake for the duration of each turn and releases the block once the turn finishes, so the system is only kept awake while there is work in progress (the display is still allowed to blank). This relies on the built-in [[https://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/system-sleep.el][=system-sleep=]] library and has no effect on earlier Emacs versions. It does not prevent "hard" sleep such as closing a laptop lid.

To turn it off:

#+begin_src emacs-lisp (setopt agent-shell-inhibit-system-sleep nil) #+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

*** Session controls

When the active agent advertises the corresponding session option, you can switch it from the shell buffer:

=C-c C-v= - Set model.
=C-c C-m= - Set session mode.
=C-c C-t= - Set thought level (reasoning effort).
=C- = - Cycle session mode.

The current selections are shown in the header right after the agent name; click any segment to open a popup menu. The thought level segment only appears for models that expose it (e.g. Claude Sonnet/Opus with effort levels; Codex's reasoning_effort).

From the viewport (=agent-shell-viewport-view-mode= / =agent-shell-viewport-edit-mode=), the same controls are bound to:

View mode: =v= (model), =s= (mode), =t= (thought level).
Edit mode: =C-c C-v=, =C-c C-m=, =C-c C-t=.

*** 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-activity-group-expand-by-default | When activity group sections should be expanded. | | 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-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-session-restore-verbosity | How much prior context to show when restoring a session. | | 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. | | agent-shell-xai-acp-command | Command and parameters for the Grok Build (xAI) ACP client. | | agent-shell-xai-default-model-id | Default Grok Build model ID. | | agent-shell-xai-default-session-mode-id | Default Grok Build session mode ID. | | agent-shell-xai-environment | Environment variables for the Grok Build ACP client. |

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-prompt-queue | Queue or immediately send a prompt depending on shell busy state. | | | agent-shell-prompt-queue-remove | Remove all pending prompts or a specific prompt by REMOVE-INDEX. | | | agent-shell-prompt-queue-resume | Resume processing pending prompts in the queue. | | r | agent-shell-quote-region | Quote the active region into the shell's latest prompt. | | | agent-shell-qwen-start | Start an interactive Qwen Code CLI agent shell. | | C-x x r | agent-shell-rename-buffer | Rename current shell buffer. | | | agent-shell-reset-logs | Reset all log buffers. | | | 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 | Toggle fragment fold at or near point. | | | agent-shell-ui-toggle-all-fragments | Toggle global fold state: all-expanded ↔ all-collapsed. | | | 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-quote-reply | Reply with the entire response block-quoted. | | | 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]].

protesilaos/modus-themes

Highly accessible themes for GNU Emacs, conforming with the highest standard for colour contrast between background and foreground values (WCAG AAA).

Modus themes for GNU Emacs

IMAGES HERE: https://protesilaos.com/emacs/modus-themes-pictures.

Highly accessible themes, conforming with the highest standard for colour contrast between background and foreground values (WCAG AAA). They also are optimised for users with red-green colour deficiency.

The themes are very customisable and provide support for a very wide range of packages. Their manual is detailed so that new users can get started, while it also provides custom code for all sorts of more advanced customisations.

Since August 2020, the original Modus themes (modus-operandi, modus-vivendi) are built into Emacs version 28 or higher. Emacs 28 ships with modus-themes version 1.6.0. Emacs 29 includes version 3.0.0. Emacs 30 provides a newer, refactored version that thoroughly refashions how the themes are implemented and customized. Such major versions are not backward-compatible due to the limited resources at my disposal to support multiple versions of Emacs and of the themes across the years.

Starting with version 5.0.0 of the modus-themes, other packages can be built on top to provide their own "Modus" derivative themes. The manual has a section about building on top of Modus. My ef-themes and standard-themes are done in this way (versions 2.0.0 and 3.0.0, respectively).

Package name (GNU ELPA): modus-themes
Official manual: https://protesilaos.com/emacs/modus-themes
Change log: https://protesilaos.com/emacs/modus-themes-changelog
Colour palette: https://protesilaos.com/emacs/modus-themes-colors
Sample pictures: https://protesilaos.com/emacs/modus-themes-pictures
Git repositories:
- GitHub: https://github.com/protesilaos/modus-themes
- GitLab: https://gitlab.com/protesilaos/modus-themes
Backronym: My Old Display Unexpectedly Sharpened ... themes.

(use-package modus-themes
  :ensure t
  :demand t
  :init
  ;; Starting with version 5.0.0 of the `modus-themes', other packages
  ;; can be built on top to provide their own "Modus" derivatives.
  ;; For example, this is what I do with my `ef-themes' and
  ;; `standard-themes' (starting with versions 2.0.0 and 3.0.0,
  ;; respectively).
  ;;
  ;; The `modus-themes-include-derivatives-mode' makes all Modus
  ;; commands that act on a theme consider all such derivatives, if
  ;; their respective packages are available and have been loaded.
  ;;
  ;; Note that those packages can even completely take over from the
  ;; Modus themes such that, for example, `modus-themes-rotate' only
  ;; goes through the Ef themes (to this end, the Ef themes provide
  ;; the `ef-themes-take-over-modus-themes-mode' and the Standard
  ;; themes have the `standard-themes-take-over-modus-themes-mode'
  ;; equivalent).
  ;;
  ;; If you only care about the Modus themes, then (i) you do not need
  ;; to enable the `modus-themes-include-derivatives-mode' and (ii) do
  ;; not install and activate those other theme packages.
  (modus-themes-include-derivatives-mode 1)
  :bind
  (("<f5>" . modus-themes-rotate)
   ("C-<f5>" . modus-themes-select)
   ("M-<f5>" . modus-themes-load-random))
  :config
  ;; Your customizations here.  All customizations must evaluated
  ;; BEFORE loading the theme.
  (setq modus-themes-to-toggle '(modus-operandi modus-vivendi)
        modus-themes-to-rotate modus-themes-items
        modus-themes-mixed-fonts t
        modus-themes-variable-pitch-ui t
        modus-themes-italic-constructs t
        modus-themes-bold-constructs t
        modus-themes-completions '((t . (bold)))
        modus-themes-prompts '(bold)
        modus-themes-headings
        '((agenda-structure . (variable-pitch light 2.2))
          (agenda-date . (variable-pitch regular 1.3))
          (t . (regular 1.15))))

  (setq modus-themes-common-palette-overrides nil)

  ;; Finally, load your theme of choice (or a random one with
  ;; `modus-themes-load-random', `modus-themes-load-random-dark',
  ;; `modus-themes-load-random-light').
  (modus-themes-load-theme 'modus-operandi))

Emacs themes based on Modus

This is not an exhaustive list. You are welcome to add your package here. Newer projects are at the bottom and are added as I am made aware of them.

ef-themes by Protesilaos https://github.com/protesilaos/ef-themes
standard-themes by Protesilaos https://github.com/protesilaos/standard-themes
modus-ewal-theme by Oliwier Czerwiński https://github.com/deadendpl/modus-ewal-theme
modus-flexoki by Derek Passen https://github.com/dpassen/modus-flexoki
faff-theme (since version 4) by James Ferguson https://github.com/WJCFerguson/emacs-faff-theme
modus-catpuccin by Magnus Therning https://gitlab.com/magus/modus-catppuccin
pixel-themes by Lucas https://github.com/lucasobx/pixel-themes
modus-nordic (modus-nordic-night and modus-nordic-midnight) by Ashton Wiersdorf https://codeberg.org/ashton314/modus-nordic-night
folio-theme by kn66 (nobu43) https://github.com/kn66/folio-theme.el
modus-alabaster by Derek Passen https://github.com/dpassen/modus-alabaster

Other Emacs packages based on Modus

modus-themes-exporter by Protesilaos https://github.com/protesilaos/modus-themes-exporter

Projects inspired by the Modus themes

This is not an exhaustive list. You are welcome to add your project here.

hugo-modus by Yejun Su is a theme for the Hugo static site generator: https://github.com/goofansu/hugo-modus. It uses colours from the Modus themes.
modus-themes.nvim by Miika Nissi and others is a port for NeoVim: https://github.com/miikanissi/modus-themes.nvim.
zed-modus-themes by Vitaly Slobodin is a port for the Zed editor: https://github.com/vitallium/zed-modus-themes.
word-smith by Sadsnake1 is a distraction-free writing for Obsidian that includes ports of the Modus themes: https://github.com/Sadsnake1/word-smith

mhayashi1120/Emacs-wgrep

Writable grep buffer and apply the changes to files

wgrep.el

Summary:

wgrep allows you to edit a grep buffer and apply those changes to the file buffer like sed interactively. No need to learn sed script, just learn Emacs.

Install:

Put this file into load-path'ed directory, and byte compile it if desired. And put the following expression into your ~/.emacs.

(require 'wgrep)

Usage:

You can edit the text in the grep buffer after typing C-c C-p . After that the changed text is highlighted. The following keybindings are defined:

C-c C-e: Apply the changes to file buffers.
C-c C-u: All changes are unmarked and ignored.
C-c C-d: Mark as delete to current line (including newline).
C-c C-r: Remove the changes in the region (these changes are not applied to the files. Of course, the remaining changes can still be applied to the files.)
C-c C-p: Toggle read-only area.
C-c C-k: Discard all changes and exit.
C-x C-q: Exit wgrep mode.
To save all buffers that wgrep has changed, run

M-x wgrep-save-all-buffers

To save buffer automatically when wgrep-finish-edit.

(setq wgrep-auto-save-buffer t)

You can change the default key binding to switch to wgrep.

(setq wgrep-enable-key "r")

To apply all changes regardless of whether or not buffer is read-only.

(setq wgrep-change-readonly-file t)

Trivial features:

wdired.el like interface.
Support GNU grep --context (-A -B and -C) option.
Can handle too many files.
Can handle newline insertion in grep buffer.
Delete whole line include newline.

Similar software:

GNU sed helm-ag has a similar feature.

History:

This program was forked from Matsushita Akihisa's grep-edit.el v2.11. As this website is now inaccessible, emacswiki.org's copy may be consulted.

Imported version can be downloaded from this orphan commit: https://github.com/mhayashi1120/Emacs-wgrep/tree/import-original-author/

Following added implementations and differences.

Support GNU grep context option -A -B and -C
Some bugfix. (wrong coloring text etc..)
wdired.el like interface.
Remove all advice.
Bind to local variables. (grep-a-lot.el works well)
After save buffer, colored face will be removed.
Change face easy to see.
Reinforce checking error.
Support removing whole line include new-line.

radian-software/straight.el

🍀 Next-generation, purely functional package manager for the Emacs hacker.

straight.el: next-generation, purely functional package manager for the Emacs hacker.

Please check out the FAQ and news 😃

Features

Install Emacs packages listed on MELPA, GNU ELPA, or Emacsmirror, or provide your own recipes.
Packages are cloned as Git (or other) repositories, not as opaque tarballs.
Make changes to a package simply by editing its source code, no additional steps required. Contribute upstream just by pushing your changes.
Powerful interactive workflows (with popups à la Magit) for performing bulk maintenance on the Git repositories for your packages.
Save and load version lockfiles that ensure 100% reproducibility for your Emacs configuration. Package state is defined entirely by your init-file and (optional) lockfile, with no extra persistent data floating around.
Specify package descriptions using a powerful format based on MELPA recipes (with a familiar but improved syntax).
use-package integration.
Modular: you can install your packages manually and straight.el will load them for you. Or you can also have straight.el install your packages, while you provide the recipes explicitly. Or straight.el can also fetch recipes, if you want. Bulk repository management and package updates are also optional.
Extensible APIs to add new recipe sources and version-control backends.
The cleanest source code you've ever seen. 45% of straight.el is comments and docstrings.

Note: straight.el is a replacement for package.el, not use-package. use-package can be used with either package.el or straight.el.

Guiding principles

Init-file and version lockfiles as the sole source of truth. No persistent state kept elsewhere.
100% reproducible package management, accounting for changes in packages, recipe repositories, configuration, and the package manager itself.
No support whatsoever for package.el.
Edit packages by editing their code, no extra steps required. Allow for manual version control operations.
Compatibility with MELPA, GNU ELPA, and Emacsmirror.
Trivial to quickly try out a package without permanently installing it.
Good for reproducing an issue with emacs -Q.

Getting started

Note: straight.el supports a minimum version of Emacs 25.1, and works on macOS, Windows, and most flavors of Linux. You must install Git in order to use straight.el.

First, place the following bootstrap code in your init-file:

(defvar bootstrap-version)
(let ((bootstrap-file
       (expand-file-name
        "straight/repos/straight.el/bootstrap.el"
        (or (bound-and-true-p straight-base-dir)
            user-emacs-directory)))
      (bootstrap-version 7))
  (unless (file-exists-p bootstrap-file)
    (with-current-buffer
        (url-retrieve-synchronously
         "https://raw.githubusercontent.com/radian-software/straight.el/develop/install.el"
         'silent 'inhibit-cookies)
      (goto-char (point-max))
      (eval-print-last-sexp)))
  (load bootstrap-file nil 'nomessage))

(If raw.githubusercontent.com is blocked by your ISP, try replacing the URL with https://radian-software.github.io/straight.el/install.el. Or you can clone straight.el manually to ~/.emacs.d/straight/repos/straight.el.)

Here are some variables you may be interested in (some of them must be set before the bootstrap code runs, if they might affect how straight.el itself is loaded - see the :set option on any defcustom in straight.el source code for specific information about when the option needs to be set):

straight-repository-branch -- to get the latest version of straight.el from the develop branch, rather than the default main which is updated less frequently but which is ostensibly more stable.
straight-check-for-modifications -- to configure an alternate way for straight.el to check for modifications made to package source code, rather than the default (which is 100% reliable, but has a minor cost to startup time).
straight-use-package-by-default -- if you use use-package, then this makes each use-package form also invoke straight.el to install the package, unless otherwise specified.
straight-vc-git-default-protocol -- by default, straight.el clones over HTTPS. If you need packages from private Git repositories in your configuration, then you might want to use SSH instead.
straight-base-dir -- by default, straight's main directory, containing its build files and package repos, is located in user-emacs-directory. You can change the location of straight's base directory via this variable.
straight-build-dir -- by default, the directory in which packages are built is located at straight-base-dir/build. Changing this variable will change the name of that directory and the name of the build cache file (unless straight-build-cache-fixed-name is non-nil).
straight-use-version-specific-build-dir -- if non-nil, use an Emacs-version-specific straight-build-dir directory to support running multiple versions of Emacs against the same user-emacs-directory. There is a minor performance penalty on startup because straight.el will not be byte-compiled.

You should remove any code that relates to package.el; for example, references to package-initialize, package-archives, and (if you're using use-package) :ensure or use-package-always-ensure.

Users of Emacs versions >= 27 will want to add:

(setq package-enable-at-startup nil)

to their early init-file to prevent package.el loading packages prior to their init-file loading. Alternatively you can also remove ~/.emacs.d/elpa, which will have the same effect. If you do neither, straight.el will signal a warning.

While it is technically possible to use both package.el and straight.el at the same time, there is no real reason to, and it might result in oddities like packages getting loaded more than once.

Debugging

Sometimes, in a corporate environment, url-retrieve-synchronously may not work and straight.el will be unable to download the installation script mentioned in the bootstrap snippet. In this case, you may simply clone this repository into ~/.emacs.d/straight/repos/straight.el and check out your desired revision/branch. The installation script is just a more convenient way of doing that automatically when necessary (and looking up the correct revision of straight.el in your lockfile, if any).
On macOS, you may receive an error:
```
Could not create connection to raw.githubusercontent.com:443
```
This is likely because you are using an ancient version of Emacs which has a broken TLS configuration. Upgrade with brew upgrade emacs.

Install packages

Out of the box, you can install any package listed on MELPA, GNU ELPA, or Emacsmirror, which is to say any package in existence. (Although MELPA is used as a package listing, packages are installed by cloning their Git repositories rather than by downloading tarballs like package.el does.) To install a package temporarily (until you restart Emacs), run M-x straight-use-package and select the package you want. To install a package permanently, place a call to straight-use-package in your init-file, like:

(straight-use-package 'el-patch)

Note that installing a package will activate all of its autoloads, but it will not actually require the features provided by the package. This means that you might need to use require or autoload for some antiquated packages that do not properly declare their autoloads.

To learn more, see the documentation on the package lifecycle.

But what about my fork of (obscure .el package)?

Instead of passing just a package name to straight-use-package, you can pass a list ("recipe"). You can see the default recipe for any given package by running M-x straight-get-recipe. For example, the recipe for el-patch is:

(el-patch :type git :host github :repo "radian-software/el-patch")

So, if you have forked el-patch and you want to use your fork instead of the upstream, do:

(straight-use-package
 '(el-patch :type git :host github :repo "your-name/el-patch"))

In fact, straight.el has explicit support for using a forked package, since this is so common:

(straight-use-package
 '(el-patch :type git :host github :repo "radian-software/el-patch"
            :fork (:host github
                   :repo "your-name/el-patch")))

In the above, :type git may be omitted if you leave straight-default-vc at its default value of git. Parts of the :fork keyword may be omitted as well. One common case is when your fork is on the same host and has the same name as the upstream repository. In this case, assuming straight-host-usernames is set, specifying a fork is as simple as:

(straight-use-package
 '(el-patch :type git :host github :repo "radian-software/el-patch"
            :fork t))

Note that straight.el doesn't do any Git operations during startup unless it needs to clone a package from scratch. This is for performance. You can explicitly request for straight.el to fix up the Git configuration after you change a package recipe, e.g. to add a fork. See Automatic repository management below.

To learn more, see the documentation on the recipe format and the Git backend.

Integration with `use-package`

use-package is a macro that provides convenient syntactic sugar for many common tasks related to installing and configuring Emacs packages. Of course, it does not actually install the packages, but instead defers to a package manager, like straight.el (which comes with use-package integration by default).

To use use-package, first install it with straight.el:

(straight-use-package 'use-package)

Now use-package will use straight.el to automatically install missing packages if you provide :straight t:

(use-package el-patch
  :straight t)

You can still provide a custom recipe for the package:

(use-package el-patch
  :straight (el-patch :type git :host github :repo "radian-software/el-patch"
                      :fork (:host github
                             :repo "your-name/el-patch")))

The :straight keyword accepts backquoted forms. This makes it possible to dynamically compute part of the recipe:

(use-package el-patch
  :straight `(el-patch :type git
                       :repo ,(alist-get 'el-patch my-package-urls)))

Specifying :straight t is unnecessary if you set straight-use-package-by-default to a non-nil value. (Note that the variable use-package-always-ensure is associated with package.el, and you should not use it with straight.el.)

To learn more, see the documentation on straight.el's use-package integration.

Edit packages locally

One of the biggest strengths of straight.el is that editing packages locally is trivial. You literally just edit the files (find-function and friends all work as you would expect). Packages will be automatically rebuilt if necessary when Emacs next starts up.

You can even commit your changes and push or pull to various remotes using Git. You have complete control over your packages' Git repositories.

To learn more, see the documentation on the package lifecycle.

Automatic repository management

While being able to make arbitrary changes to your packages is very powerful, it can also get tiring to keep track of the all those changes. For this reason, straight.el provides a suite of powerful interactive workflows to perform bulk operations on your packages.

To restore each package to its canonical state (a clean working directory with the main branch checked out, and the remotes set correctly), run M-x straight-normalize-package or M-x straight-normalize-all.
To fetch from each package's configured remote, run M-x straight-fetch-package-and-deps or M-x straight-fetch-all; to also fetch from the upstream for forked packages, supply a prefix argument.
To merge changes from each package's configured remote, run M-x straight-merge-package-and-deps or M-x straight-merge-all; to also merge from the upstream for forked packages, supply a prefix argument.
To push all local changes to each package's configured remote, run M-x straight-push-package or M-x straight-push-all.

All of these commands are highly interactive and ask you before making any changes. At any point, you can stop and perform manual operations with Magit or other tools in a recursive edit.

To learn more, see the documentation on bulk repository management.

Configuration reproducibility

To save the currently checked out revisions of all of your packages, run M-x straight-freeze-versions. The resulting file (~/.emacs.d/straight/versions/default.el), together with your init-file, perfectly define your package configuration. Keep your version lockfile checked into version control; when you install your Emacs configuration on another machine, the versions of packages specified in your lockfile will automatically be checked out after the packages are installed. You can manually revert all packages to the revisions specified in the lockfile by running M-x straight-thaw-versions.

To learn more, see the documentation on version lockfiles.

Conceptual overview

This section describes, at a high level, how the different mechanisms in straight.el play together. This illustrates how straight.el manages to accomplish all of its guiding principles.

TL;DR

straight.el operates by cloning Git repositories and then symlinking files into Emacs' load path. The collection of symlinked files constitutes the package, which is defined by its recipe. The recipe also describes which local repository to link the files from, and how to clone that repository, if it is absent.

When you call straight-use-package, the recipe you provide is registered with straight.el for future reference. Then the package's repository is cloned if it is absent, the package is rebuilt if its files have changed since the last build (as determined by find(1)), and its autoloads are evaluated.

You can also provide only a package name, in which case the recipe will be looked up in one of several configurable recipe repositories, which are just packages themselves (albeit with the build step disabled).

straight.el determines which packages are installed solely by how and when straight-use-package is invoked in your init-file.

What is a package?

A package is a collection of Emacs Lisp (and possibly other) files. The most common case is just a single .el file, but some packages have many .el files, and some even have a directory structure.

Note that a package is defined only as a collection of files. It doesn't necessarily correspond to a Git repository, or an entry on MELPA, or anything like that. Frequently there is a relationship between all of these concepts, but that relationship does not always have to be direct or one-to-one.

A package also has a name, which must be unique. This is the name that is used for the folder holding the package's files. It is frequently the same as the name of a Git repository, or an entry on MELPA, but again this does not have to be the case.

Where do packages come from?

If you really wanted all of your packages to be unambiguously defined, you could just copy and paste all of their files into version control. But that would defeat the purpose of using a package manager like straight.el. In straight.el, packages are defined by two sources of information:

a local repository
a build recipe

The local repository is just a directory containing some files. Of course, it also has a name, which may or may not be the same as the package's name. Frequently, the local repository is also a Git repository, but this is not necessary.

The build recipe is not a literal data structure. It is a concept that represents a certain subset of the package's recipe. Specifically, the :files, :local-repo, and :build keywords.

To transform this information into an actual package that Emacs can load, straight.el builds the package. This means that some symbolic links are created in the package's directory that point back into the local repository's directory. Exactly how these symlinks are created is determined by the :files directive, and which local repository the symlinks point to is determined by the :local-repo directive.

After the symlinks are created, the resulting files are byte-compiled, and their autoloads are generated and written into a file in the package's directory.

If :build nil is specified, however, this entire process is skipped. This mechanism is used for recipe repositories.

What does this look like on disk?

The local repositories are kept in ~/.emacs.d/straight/repos, and the built packages are kept in ~/.emacs.d/straight/build. If you have initialized straight.el and loaded package el-patch, then your ~/.emacs.d/straight directory will look roughly like this (some irrelevant details have been omitted for pedagogical purposes):

straight
├── build
│   ├── el-patch
│   │   ├── el-patch-autoloads.el
│   │   ├── el-patch.el -> ~/.emacs.d/straight/repos/el-patch/el-patch.el
│   │   └── el-patch.elc
│   └── straight
│       ├── straight-autoloads.el
│       ├── straight.el -> ~/.emacs.d/straight/repos/straight.el/straight.el
│       └── straight.elc
└── repos
    ├── el-patch
    │   ├── CHANGELOG.md
    │   ├── LICENSE.md
    │   ├── README.md
    │   └── el-patch.el
    └── straight.el
        ├── LICENSE.md
        ├── Makefile
        ├── README.md
        ├── bootstrap.el
        ├── install.el
        └── straight.el

As you can see, the package names are el-patch and straight. While el-patch is built from a local repository of the same name, straight is built from a local repository by the name straight.el. Also note that only .el files are symlinked, since only they are relevant to Emacs.

Where do repositories come from?

Local repositories provide a way to define packages without specifying the contents of all of their files explicitly. But that's not helpful without a higher-level way to define local repositories without specifying the contents of all of their files. In straight.el, local repositories are defined by two sources of information:

a fetch recipe
the version lockfiles

The fetch recipe is, like the build recipe, a concept representing a certain subset of the package's overall recipe. The situation is more interesting here because straight.el supports multiple version-control backends. The version-control backend specified by the fetch recipe is determined by the :type directive (which defaults to straight-default-vc). Each version-control backend then accepts some set of additional directives. For example, the git backend accepts:

:repo
:host
:branch
:nonrecursive
:fork
:protocol

If a local repository is not present, then its fetch recipe describes how to obtain it. This is done using the straight-vc-clone function, which delegates to one of the backend implementations of the clone operation, according to :type. (The option :type built-in is a special case that results in all version-control operations for the package being ignored. You can also use :type nil to accomplish the same, but with the difference that the package is still loaded from its specified :local-repo.)

However, even with a particular repository source specified, there is still the question of which version of the repository to use. This is where the version lockfiles come in. When a local repository is cloned, the version lockfiles are searched to see if there is a particular commit specified for that local repository's name. If so, that commit is checked out. (For the git backend, commits are 40-character strings representing SHA-1 hashes, but the representation of a commit identifier could be different across different backends.)

The straight-freeze-versions and straight-thaw-versions methods also use backend-delegating methods; in this case, they are straight-vc-get-commit and straight-vc-check-out-commit.

The fetch recipe and version lockfiles, together with the configuration options for straight.el, precisely define the state of a local repository. Of course, you may make any changes you want to the local repository. But this information defines a "canonical" state that you may revert to at any time.

When this information is combined with the build recipe, straight.el is able to construct canonical, universal versions of your Emacs packages that will be the same everywhere and forever.

Note that you do not have to provide fetch recipes or version lockfiles. You may manage your local repositories manually, if you wish, although this has obvious disadvantages in terms of repeatability and maintainability.

What does it mean to load a package?

A prerequisite to loading a package is making sure the package has been built. After that is done, loading the package means adding its directory to the load path and evaluating its autoloads file.

Adding the directory to the load path means that you can use require to load the package's files. Note that straight.el does not do this for you, since loading packages immediately is usually not necessary and it immensely slows down Emacs startup.

Evaluating the autoloads file means that calling the functions that are defined in the autoloads file will automatically require the files that define those functions. All modern packages define their functions in autoloads and are designed to be loaded on-demand when those functions are called. Antiquated packages may need you to explicitly define autoloads, or to just require the package right away.

Where do recipes come from?

straight-use-package does not require an actual recipe. You can just give it a package name, and it will look up the recipe. This is done using recipe repositories. Recipe repositories are set up as a swappable backend system, much like the version-control backend system.

A recipe repository consists of four parts:

a fetch recipe for the local repository (this will typically include :build nil, since recipe repositories usually do not need to be built)
a function that, provided the local repository is already available, returns a list of all packages that have recipes in the recipe repository
a function that, given a package name, returns the recipe for that package, or nil if the recipe repository does not provide a recipe for the package
an entry in straight-recipe-repositories indicating that the recipe provided actually corresponds to a recipe repository (otherwise it would just be a regular package)

Note that recipe repositories are implemented as regular packages! This means that all the usual package management operations work on them as well. It also means that you use straight-use-package to register them (although typically you will provide arguments to straight-use-package so that the recipe repository is only registered, and not cloned until it is needed; see the section on straight-use-package).

If you give straight-use-package just a package name, then each recipe repository in straight-recipe-repositories is checked for a recipe for that package. Once one is found, it is used. Otherwise, an error is signaled (unless the package is built-in to Emacs, according to package.el).

Note that straight.el uses its own recipe format which is similar, but not identical, to the one used by MELPA (see the section on the recipe format for information on the differences). The recipe repository backends abstract over the formatting differences in different recipe sources to translate recipes into the uniform format used by straight.el. When you run M-x straight-get-recipe, the translated recipe is what is returned.

What happens when I call `straight-use-package`?

There are three actions that straight-use-package can take:

Register a package's recipe with straight.el.
Clone a package's local repository, if it is missing.
Build a package, if it has been changed since the last time it was built, and load it.

These actions must be performed in order. Depending on the arguments you pass to straight-use-package, one, two, or all three may be performed.

The normal case is to do all three. The fetch recipe is only required if the local repository is actually missing, but the build recipe is always required.

Deferred installation can be accomplished by telling straight-use-package to stop if the local repository is not already available. The deferred installation can be triggered by invoking straight-use-package again, but telling it to go ahead and clone the repository (this is the default behavior). Because straight-use-package already registered the package's recipe the first time, you don't have to provide it again.

In some extraordinary circumstances (such as when straight.el is bootstrapping its own installation), it may be desirable to clone a package's local repository if it is missing, but to stop before building and loading the package. This can also be done by straight-use-package.

What does it mean to register a package?

Package registration is the first action taken by straight-use-package, before building and cloning. First, if only a package name was provided to straight-use-package, a recipe is obtained from the configured recipe repositories. Next, the resulting recipe is recorded in various caches.

This is important, since it allows for several things to happen:

if you later want to perform another operation on the package using straight.el, you do not need to provide the recipe again
if you use a custom recipe for Package A, and Package B requires Package A as a dependency, your custom recipe is remembered and re-used when Package A is used as a dependency, to avoid conflicts.
when multiple packages are built from the same local repository, and you have specified a custom fetch recipe for one of those packages, straight.el can intelligently merge that fetch recipe into the automatically retrieved recipes of dependencies, in order to avoid conflicts.
straight.el knows which packages you have installed, if you want to perform interactive operations on them.
if you accidentally provide two different recipes for the same package, straight.el can issue a helpful warning, since this may lead to surprising behavior.

How does `straight.el` know when to rebuild packages?

When you request for straight.el to load a package (using straight-use-package), it first checks if the package needs to be rebuilt. This means that some of the files in its local repository have been modified since the last time the package was built. straight.el uses an optimized find(1) command to check for package modifications, and it uses some caching mechanisms to perform bulk find(1) operations on multiple packages, to speed up these checks (although it never performs optimizations that may result in erroneous behavior).

This check occurs during Emacs init, when your init-file makes calls to straight-use-package. You may notice a significant delay on the first straight-use-package call, because this is when straight.el performs a bulk find(1) call and caches the results for later usage (this speeds up init considerably). The total delay is likely to be on the order of 100ms for a double-digit number of packages.

The rebuild detection system is what allows for you to make changes to packages whenever you would like, without performing any additional operations.

(Packages are also rebuilt when their recipes change, of course.)

How does `straight.el` know what packages are installed?

straight.el does not require you to declare a central list of packages anywhere, like Cask does. Instead, it determines what packages are to be loaded implicitly, by your invocations of straight-use-package during Emacs initialization. Furthermore, straight.el allows you to install packages after initialization using M-x straight-use-package (or even by evaluating straight-use-package forms). However, straight.el still provides advanced features such as bulk package management and version locking. This creates some interesting challenges which other package managers do not have to deal with.

straight.el solves these problems using a concept called transactions. The operation of the transaction system is mostly transparent to the user, at least in recent versions of straight.el. Basically, it provides a way for straight.el to keep track of what happens within a single user operation (e.g. evaluate a buffer of straight-use-package calls, or load the init-file).

straight.el uses the transaction system to keep track of what packages you request in your init-file. If you invoke straight-use-package interactively, then this invalidates that information, since you have now requested a package that is not in your init-file. For this reason, if you have invoked straight-use-package interactively, running M-x straight-freeze-versions will prompt you to first reload your init-file.

Note: reloading your init-file must have the effect of running all of the same straight.el-related functions again. For example, if you bootstrap straight.el in a sub-file that you only require instead of load, then the reloading functionality will not work correctly and you may receive the message Caches are still outdated; something is seriously wrong. See #437 for discussion.

Comparison to other package managers

(Disclaimer: while I try to be as objective and comprehensive as possible here, I'm obviously biased. Please submit corrections if I have unfairly disparaged your favorite package manager!)

There are many package managers for Emacs, ranging from simple scripts to download files from EmacsWiki to full-featured package management solutions like straight.el. Here are the most feature-rich alternatives to straight.el:

package.el: de facto standard, bundled with Emacs.
Quelpa: allows you to use external sources like GitHub with package.el. Essentially a local MELPA.
Cask: another package.el wrapper. Specify your dependencies in a Cask file; can be used for project management or an Emacs configuration.
el-get: ridiculously OP in terms of how many different sources you can pull packages from (package.el, every known VCS, distro package managers, go get(!!)).
Borg: assimilates packages as Git submodules into .emacs.d, relying on Emacsmirror.
"Screw package managers! I'll just handle it all myself!"

TL;DR

Here is a summary of the main differences in philosophy between the package managers:

Use package.el if you want package management to be as easy as possible, and do not much care for installing packages from specific sources, keeping track of their versions, or doing local development on them.
Use Quelpa if you like package.el but really wish you could specify the sources of your packages.
Use Cask if you like package.el but wish it came with some project management tools, as well.
Use el-get if you want to easily install packages from as many different sources as possible.
Use Borg if you like a more lightweight approach to package management that leverages existing solutions, if contributing changes to packages upstream is important to you, and if using Git submodules isn't a deal-breaker.
Use the manual approach if you need to contribute changes to a package that is versioned in something other than Git.
Use straight.el if you like reproducibility in your Emacs configuration, you regularly contribute changes to packages upstream, or you are writing an Emacs configuration to be used by others.

And here is a brief list of the main reasons you might not want to use straight.el:

straight.el is largely unusable if you do not have Git installed, although it is still possible to use the package-building features if you manage your repositories manually (you also cannot use the magic bootstrap snippet, in that case). If you don't want to install Git, you'll have to use package.el or take the manual approach.
straight.el is not built in to Emacs. If you want something that will work right out of the box, you're stuck with package.el or the manual approach.
straight.el takes a minute or two to update all your packages, since it does not rely on a centralized server. If you want quick update checking, you'll have to use package.el.
straight.el does not provide any user interface for package management. For that, you'll have to use package.el, el-get, Cask, or Borg (which expects you to use epkg for browsing packages).
straight.el does not currently support using only stable versions of packages (i.e. tagged revisions), although this is a planned feature. If this is important to you, you probably want to go with package.el (with GNU ELPA and MELPA Stable), Cask, or Quelpa.
If you don't like having to modify your init-file to do package management, then straight.el is absolutely not for you. You want package.el, Quelpa, el-get, or Borg.
If you really want to contribute changes to packages that are not versioned in Git, then straight.el will not help you. You'll have to manage the package's repository manually. Unfortunately, there is no existing package manager that supports both non-Git version-control systems and contributing changes upstream. You'll have to go with the manual approach.
straight.el does not provide project management tools. It is a package manager. If you want project management tools, check out Cask.
straight.el is quite new and moving fast. Things might break. The other package managers can generally be ranked as follows, from most active to least active: el-get, Quelpa, Borg, Cask, package.el (glacial).

Comparison to `package.el`

package.el downloads pre-built packages from central servers using a special (undocumented?) HTTP protocol, while straight.el clones Git (or other) repositories and builds packages locally.

Advantages of `straight.el`

straight.el allows you to install a package from any branch of any Git repository. package.el only allows you to install a package from a package.el-compliant central server.
straight.el allows you to check out any Git revision of any package. package.el only allows you to install the latest version, and there is no way to downgrade.
straight.el supports Emacsmirror, while package.el does not.
straight.el uses your init-file as the sole source of truth for package operations. package.el loads every package you ever installed at startup, even if some of those packages are no longer referenced by your init-file.
straight.el supports 100% reproducibility for your Emacs packages with version lockfiles. package.el cannot provide reproducibility for the set of packages installed, the central servers they were installed from, or the versions in use.
straight.el allows you to make arbitrary changes to your packages locally. While it is possible to make local changes to package.el packages, these changes cannot be version-controlled and they will be silently overwritten whenever package.el performs an update.
straight.el allows you to perform arbitrary version-control operations on your package's Git repositories, including contributing changes upstream. straight.el has explicit support for specifying both an upstream and a fork for a package. Contributing changes upstream with package.el is impossible.
straight.el is designed with emacs -Q bug reports in mind. package.el is unsuitable for minimal bug reproductions, since it automatically loads all of your packages on any package operation, even in emacs -Q.
straight.el operates quietly when all is going well. package.el displays all messages, errors, and warnings that come from byte-compilation and autoload generation.
straight.el considers modifying the user's init-file extremely uncouth. package.el aggressively inserts (via Customize) auto-generated code setting package-selected-packages into the init-file whenever a package is installed. Furthermore, package.el has a history of impolite treatment of user configuration, which I think says some things about the design: until Emacs 27.1 (when my patch to fix this issue was adopted after around 300 emails' worth of squabbling on emacs-devel), it also inserted a call to the package-initialize function into the init-file if it was not already present, with the officially recommended workaround "comment it out if you don't want it, but don't get rid of it".
straight.el has a profile system that allows users of someone else's Emacs configuration to manage an additional subset of packages, or to override upstream package configuration, without forking the upstream. package.el has no such concept.
straight.el is developed openly on GitHub, using a modern issue tracker and continuous integration from GitHub Actions. It welcomes contributions of any type. straight.el is licensed under the permissive MIT license and does not require a copyright assignment. straight.el is developed actively and has explicit support for installing development versions of itself, as well as for contributing upstream changes. package.el is maintained as a part of Emacs core, meaning that the contribution process is poorly documented and discouraging. Releases of package.el coincide with releases of Emacs, which are infrequent and inflexible. There is no issue tracker specifically for package.el, only the Emacs bug tracker and the emacs-devel mailing list. Contributing to package.el requires a poorly-documented, cumbersome copyright assignment process and is done by submitting patches to an antiquated mailing list, unsupported by modern code review tooling or continuous integration.

Advantages of `package.el`

package.el does not require that you have Git installed, since the central server deals with where the packages originally came from. straight.el cannot be used at all without Git.
package.el is built in to Emacs and does not require additional configuration to get started with. straight.el requires the use of a 10-line bootstrap snippet in your init-file.
package.el can perform bulk package updates more quickly since it relies on central servers.
package.el has a user interface for package management that also displays package metadata. straight.el has no user interface for package management; any UI is provided by the user's completing-read framework.
package.el does not require you to touch your init-file to install packages, while straight.el absolutely refuses to permanently install a package without an explicit reference to it in your init-file (although this may be considered an advantage, depending on your perspective).
Using MELPA Stable, package.el can install only stable versions of packages. By default, package.el also installs only stable versions of packages from GNU ELPA. These modes of operation are unsupported by straight.el at this time, although this is a planned feature.

Additional notes

package.el and straight.el usually take approximately the same time to install packages, despite the fact that straight.el is cloning entire Git repositories. This is because network latency and byte-compilation are the dominant factors.
Some package.el servers build packages from non-Git upstreams. package.el can install these packages, while straight.el cannot. However, since package.el has no version-control support, this is more or less equivalent to installing those packages from the Emacsmirror, which straight.el can do by default.

Comparison to Quelpa

Quelpa allows for fetching packages from arbitrary sources and building them into a format that can be installed by package.el. straight.el has a philosophy which is fundamentally incompatible with package.el, and non-compatibility with package.el is one of its design goals.

Advantages of `straight.el`

straight.el has out-of-the-box compatibility with MELPA, GNU ELPA, and Emacsmirror, while Quelpa only has support for MELPA. To use GNU ELPA, you must drop down to package.el. Emacsmirror is not supported by default, although it is easy to specify an Emacsmirror repository in a recipe. While Quelpa allows you to specify custom recipe folders, it does not have support for cloning these folders automatically from version control, nor for generating the recipes in any way other than copying them literally from files. straight.el allows you full flexibility in this regard.
straight.el has integrated support for selecting particular Git revisions of packages. This process is more manual in Quelpa, as it requires placing the commit hash into the recipe, which disables updates.
straight.el uses your init-file as the sole source of truth for package operations. Since Quelpa is based on package.el, it also loads every package you ever installed at startup, even if those packages are no longer referenced by your init-file. Furthermore, there is an additional caching layer, so that deleting a package from the package.el interface and removing it from your init-file still does not actually delete it.
straight.el supports 100% reproducibility for your Emacs packages with version lockfiles. Quelpa can theoretically provide some measure of reproducibility, but this requires significant manual effort since all packages are not associated with specific revisions by default, nor is the revision of MELPA saved anywhere.
straight.el allows you to make arbitrary changes to your packages locally. While it is possible to make local changes to Quelpa packages, there are two places to do so: the built package, which is the default destination of find-function, and the original repository. Changes to the former are not version-controlled and will be silently overwritten by package.el operations, while changes to the latter will be silently overwritten by Quelpa operations.
straight.el has explicit support for configuring both an upstream repository and a fork for the same package. Quelpa does not have such a concept.
straight.el allows you complete control over how your repositories are managed, and the default behavior is to draw all packages versioned in a single repository from a single copy of that repository. Quelpa is hardcoded to require a separate repository for each package, so that installing Magit requires three copies of the Magit repository.
straight.el builds packages using symlinks, meaning that find-function works as expected. Quelpa builds packages by copying, a feature inherited from MELPA. This means that find-function brings you to the built package, instead of the actual repository, which is not version-controlled and will be overwritten whenever package.el performs an update.
straight.el allows you to perform arbitrary version-control operations on your package's Git repositories. Quelpa allows this, but all local changes will be silently overridden whenever Quelpa performs an update.
straight.el is designed with emacs -Q bug reports in mind. Since Quelpa is based on package.el, it is also unsuitable for minimal bug reproductions, since it automatically loads all of your packages on any package operation, even in emacs -Q.
straight.el operates quietly when all is going well. Since Quelpa is based on package.el, it displays all messages, errors, and warnings that come from byte-compilation and autoload generation. It also displays additional messages while cloning Git repositories, downloading files, and building packages from their repositories into package.el format.
straight.el does not modify your init-file. Since Quelpa is based on package.el, it inherits the behavior of aggressively inserting a call to package-initialize into your init-file on any package management operation.
straight.el has a profile system that allows users of someone else's Emacs configuration to manage an additional subset of packages, or to override upstream package configuration, without forking the upstream. Quelpa has no such concept.

Advantages of Quelpa

Quelpa supports all the version-control systems supported by MELPA, which is to say almost every commonly and uncommonly used VCS. straight.el only supports Git, although it is designed to support other version-control backends.
Quelpa allows for installing only stable versions of packages, from any source. This mode of operation is unsupported by straight.el, although it is a planned feature.
Since Quelpa is based on package.el, it inherits a user interface for package management that also displays package metadata. straight.el has no such interface.

Additional notes

straight.el and Quelpa both allow you to manage your package's local repositories manually, if you wish.
In principle, straight.el and Quelpa have identical package installation times, since they are performing the same operations. In practice, Quelpa is slightly slower since it builds packages by copying rather than symlinking, and it clones multiple copies of the same Git repository when multiple packages are built from it.
straight.el encourages you to keep a tight handle on your package versions by default. Quelpa encourages you to stick to the latest versions of your packages, and to upgrade them automatically.

Comparison to Cask

I have not used Cask extensively, so please feel especially free to offer corrections for this section.

Cask installs packages using the package.el protocol, based on a Cask file written in the Cask DSL. straight.el eschews package.el entirely, and clones packages from source based on how you invoke straight-use-package in your init-file.
Cask focuses more on being a build manager, like Maven or Leiningen, while straight.el focuses exclusively on being a package manager.

Advantages of `straight.el`

straight.el has out-of-the-box compatibility with Emacsmirror, while Cask only supports package.el-compliant repositories. However, it is easy to specify an Emacsmirror repository in a recipe. Cask does not support custom package sources. straight.el supports MELPA, GNU ELPA, and Emacsmirror, and allows you to add any other sources you would like.
straight.el has integrated support for selecting particular Git revisions of packages. This process is more manual in Cask, as it requires placing the commit hash into the recipe, which disables updates.
straight.el uses your init-file as the sole source of truth for package operations. Since Cask is based on package.el, it loads every package you ever installed at startup, even if some of those packages are no longer referenced by your Cask file.
straight.el determines your package management configuration implicitly by detecting how you call straight-use-package in your init-file and making the appropriate changes immediately. Cask requires manual intervention (for example, issuing a cask install command when you have updated your Cask file). However, both straight.el and Cask can be considered declarative package managers.
straight.el supports 100% reproducibility for your Emacs packages with version lockfiles. Cask can theoretically provide some measure of reproducibility, but this requires significant manual effort since all packages are not associated with specific revisions by default, nor is the revision of Cask saved anywhere.
straight.el allows you to make arbitrary changes to your packages locally. While it is possible to make local changes to Cask packages, these will not be version-controlled and they will be silently overwritten or shadowed when Cask performs an update.
straight.el allows you to perform arbitrary version-control operations on your package's Git repositories, including contributing changes upstream. straight.el has explicit support for specifying both an upstream and a fork for a package. Contributing changes upstream with Cask is impossible.
straight.el is designed with emacs -Q bug reports in mind. Cask appears to be unsuitable for minimal bug reproductions, since there does not appear to be a straightforward way to load a single package, without loading all other packages configured in your Cask file.
straight.el operates quietly when all is going well. Since Cask is based on package.el, it displays all messages, errors, and warnings that come from byte-compilation and autoload generation.
straight.el has a profile system that allows users of someone else's Emacs configuration to manage an additional subset of packages, or to override upstream package configuration, without forking the upstream. Cask has no such concept.

Advantages of Cask

Cask provides a useful toolbox of operations for project management, which are completely absent from straight.el.
Since Cask is based on package.el, it does not require that you have Git installed. (It does require Python, however.) straight.el is mostly unusable without Git.
Since Cask is based on package.el, it can perform bulk package updates more quickly than straight.el.
Since Cask is based on package.el, it inherits a user interface for package management that also displays package metadata.
Since Cask is based on package.el, you can install packages without editing a file manually, although this rather defeats the entire purpose of using Cask instead of package.el. straight.el absolutely refuses to permanently install a package without an explicit reference to it in your init-file (although this may be considered an advantage, depending on your perspective).
Using MELPA Stable, Cask can install only stable versions of packages. By default, Cask also installs only stable versions of packages from GNU ELPA. These modes of operation are unsupported by straight.el at this time, although this is a planned feature.
Cask supports more version-control systems than straight.el (which only supports Git).

Comparison to el-get

I have not used el-get extensively, so please feel especially free to offer corrections for this section.

Both el-get and straight.el implement their own package management abstractions instead of delegating to package.el. However:
- el-get goes the route of adding as many package sources as possible (e.g. package.el, many different version-control systems, various specific websites, and even system package managers) so that packages can be used very easily.
- straight.el only supports Git and in doing so is able to provide more advanced package management features.

Advantages of `straight.el`

straight.el uses your init-file as the sole source of truth for package operations. el-get has additional metadata stored outside the init-file, although specifying all packages in your init-file is a supported mode of operation.
straight.el supports 100% reproducibility for your Emacs packages with version lockfiles. el-get can theoretically provide some measure of reproducibility, but this requires significant manual effort since all packages are not associated with specific revisions by default, nor is the revision of el-get saved anywhere.
straight.el allows you to make arbitrary changes to your packages locally, and conflicts during updates are presented to the user and resolved interactively. While it is possible to make local changes to el-get packages, the el-get manual warns that such changes may break the update mechanism.
straight.el has explicit support for configuring both an upstream repository and a fork for the same package. el-get does not have such a concept.
straight.el allows you to perform arbitrary version-control operartions on your package's Git repositories. el-get allows this, but local changes will be overwritten when el-get performs an update.
straight.el provides a suite of powerful interactive workflows for performing bulk operations on your package's Git repositories. el-get only allows you to install, uninstall, and update packages.
straight.el operates quietly when all is going well. el-get reports its progress verbosely.
straight.el has a profile system that allows users of someone else's Emacs configuration to manage an additional subset of packages, or to override upstream package configuration, without forking the upstream. el-get has no such concept.

Advantages of el-get

el-get supports virtually all known version-control systems, as well as system package managers, EmacsWiki, arbitrary HTTP, and even go get. straight.el supports only Git, although it does allow you to manage your local repositories manually if you would like.
el-get has been around since 2010 and is on its fifth major version, whereas straight.el was created in January 2017 and is only now approaching a 1.0 release. Clearly, el-get is more stable, although despite its recency straight.el is already almost 50% of the size of el-get, by the line count. Both package managers are actively maintained.
el-get has a recipe format which is several orders of magnitude more powerful than that of straight.el, since it supports many more package sources that can be configured and since it allows for a more complex build process.
el-get provides a number of features for running per-package initialization and setup code, including pulling that code from arbitrary sources. straight.el does not support this and expects you to use a dedicated tool like use-package (with which integration is built in) for that purpose.
el-get has a user interface for package management that also displays package metadata, similarly to package.el. straight.el has no user interface for package management; any UI is provided by the user's completing-read framework.

Comparison to Borg

Borg and straight.el are perhaps the two most similar package managers on this list. The difference is that Borg is very minimal and expects you to complement it with other tools such as Magit, epkg, use-package, and auto-compile. On the other hand, straight.el aspires to be a one-stop package management solution, although it does not try to replace dedicated version-control packages (Magit) or dedicated package configuration packages (use-package).
Borg uses Git submodules, while straight.el uses independently managed Git repositories.

Advantages of `straight.el`

straight.el supports MELPA, GNU ELPA, Emacsmirror, and custom recipe sources. Borg only supports Emacsmirror and custom recipe sources. However, as the Emacsmirror is a near-complete superset of both GNU ELPA and MELPA, this does not necessarily mean you have access to more packages: it just means you benefit from the recipe maintenance efforts of the MELPA team and the Emacsmirror team, rather than only the latter.
Borg, even when combined with related tools, do not allow for the kind of massive interactive repository management provided by straight.el.
straight.el provides an API designed for other version-control backends to be added in future. Borg is inextricably tied to Git.
The interface for Git submodules has a number of sharp edges.
straight.el provides dependency management. This is a manual process in Borg.
straight.el provides mechanisms for updating your packages. This is a manual process in Borg.
straight.el is configured solely by how you use in your init-file. Configuring Borg requires customizing ~/.emacs.d/.gitmodules, which means (for example) that you cannot generate recipes dynamically. (However, the handling of configuration is planned to be improved in a future release.)
straight.el has a profile system that allows users of someone else's Emacs configuration to manage an additional subset of packages, or to override upstream package configuration, without forking the upstream. Borg has no such concept.

Advantages of Borg

Borg does a heck of a lot less magic, so if you want a solution with simple implementation details, straight.el may not be for you. (But see the developer manual and docstrings, first.)

Comparison to Nix

Nix and straight.el both use the tagline "purely functional", but Nix probably uses it in a more correct sense than straight.el. Nix, by default, uses a fully static and 100% reproducible format for everything, based on the regularly-updated package definitions in the nixpkgs repository. straight.el on the other hand clones packages directly from source; while it provides lockfiles to theoretically ensure reproducibility, nothing on a technical level prevents you from directly modifying the source code.

Advantages of `straight.el`

When you want to hack on a package or contribute upstream, you can navigate directly to the source code and edit it immediately. The Git repository is ready for branching and pull requests right away. With Nix, package derivations are read-only, and setting up a package for local development requires you to clone it yourself and reconfigure your Nix environment to pull from the local copy, similarly to package.el.
Configuration for straight.el happens all within Emacs Lisp as opposed to an external configuration language, so there is not a new language (unless you are already using Nix).

Advantages of Nix

Nix community contributions in nixpkgs contain lots of repackaging and fixes for various packages to make them work better.
Being integrated with the rest of the Nix package manager means that installing an Emacs package can also install any required system dependencies, something that straight.el has no support for (by design) as it is limited to within-Emacs package management.
Package configuration is much more guaranteed to be fully reproducible on any system.
Due to the use of a centralized and versioned package repository, security is likely higher, since published changes to individual Git repositories of package authors have slightly more opportunity to go through community auditing (although the system is still automated, as opposed to requiring review by individual package maintainers like in Linux distribution packaging).

Comparison to the manual approach

The manual approach is to download packages yourself and put them on your load-path. straight.el is more or less what you get when you take the manual approach, think very hard about the best way to do everything, and then automate all of it.

Advantages of `straight.el`

straight.el figures out where to clone your packages from for you.
straight.el byte-compiles your packages for you and generates their autoloads automatically.
straight.el frees you from needing to manually recompile and regenerate autoloads.
straight.el keeps track of dependencies for you.
straight.el provides tools to manage all your packages in bulk, which would otherwise be a long, tedious process.
straight.el allows you to get reproducibility for your configuration without needing to keep all of your packages under version control.
straight.el links packages into a separate build directories. Running packages directly from their repositories has a number of problems, including:
- making it impossible to run only one package, if others are provided in the same repository.
- making your working directory dirty when the package author forgot to add their build artifacts like *.elc and autoload files to the .gitignore.
- instantly losing compatibility with MELPA recipes.
straight.el offers you a single entry point to install only a single package in isolation, for a minimal bug reproduction. With the manual approach this would be more complicated, especially if the package has dependencies.
straight.el frees you from needing to think about package management, since I already did all the thinking to figure how best to design everything.

Advantages of the manual approach

No dependencies.
You learn a lot, if you don't give up first.
You might end up writing a package manager (case in point).
This is the only way to deal with packages that have non-Git upstreams which you need to contribute changes to. (However, you can always use the manual approach for one package and straight.el for the rest. Or you can just eschew straight.el's version-control support for that package, and use it only for building the package.)

User manual

This section tells you everything you need to know about the user-facing features of straight.el. For implementation details, see the developer manual. It may also be helpful to get some perspective on the overarching concepts of straight.el from the conceptual overview.

Bootstrapping `straight.el`

In order to use straight.el, you will need to somehow get it loaded into Emacs. (This is easy for package.el, since package.el is built in to Emacs. straight.el must work a little harder.)

straight.el comes with a file to do just this, bootstrap.el. All you need to do is load that file. You can do this with M-x load-file or by a call to load in your init-file. However, there is an obvious shortcoming: bootstrap.el will only be available once straight.el is already installed.

You could just invoke git clone from your init-file, if straight.el is not installed, but then you would have to manually take care of selecting the correct branch, parsing your version lockfile to check out the right revision, and so on. Instead, you can just use this snippet, which uses a copious amount of magic to take care of all these details for you:

(defvar bootstrap-version)
(let ((bootstrap-file
       (expand-file-name
        "straight/repos/straight.el/bootstrap.el"
        (or (bound-and-true-p straight-base-dir)
            user-emacs-directory)))
      (bootstrap-version 7))
  (unless (file-exists-p bootstrap-file)
    (with-current-buffer
        (url-retrieve-synchronously
         "https://raw.githubusercontent.com/radian-software/straight.el/develop/install.el"
         'silent 'inhibit-cookies)
      (goto-char (point-max))
      (eval-print-last-sexp)))
  (load bootstrap-file nil 'nomessage))

Despite the reference to develop, this snippet actually installs from the main branch by default, just like every other package. Furthermore, the correct revision of straight.el is checked out, if you have one specified in your lockfile. Even better, you can override the recipe for straight.el, just like for any other package.

Installing packages programmatically

The primary entry point to straight.el is the straight-use-package function. It can be invoked interactively (for installing a package temporarily) or programmatically (for installing a package permanently). This section covers the programmatic usage; see later for interactive usage.

Here is the basic usage of straight-use-package:

(straight-use-package 'el-patch)

This will ensure that the package el-patch is installed and loaded. (Note that straight-use-package takes a symbol, not a string, for the name of the package.) Precisely, this is what happens:

If the local Git repository for el-patch is not available, it is cloned, and the appropriate revision is checked out (if one is specified in your version lockfiles).
If the local Git repository has been modified since the last time the package was built, it is rebuilt. This means:
- The .el files are symlinked into a separate directory to isolate them from other, irrelevant files.
- The main package file is checked for dependencies, which are installed recursively if necessary using straight-use-package.
- The .el files are byte-compiled.
- Autoloads are extracted from the .el files and saved into a separate file.
The package's directory is added to Emacs' load-path.
The package's autoloads are evaluated.

Package authors should note that straight.el checks for dependencies that are specified in the package.el format. To spare you reading that documentation, this is either a Package-Requires header in PACKAGENAME.el, or an argument to a define-package invocation in PACKAGENAME-pkg.el. Despite the many shortcomings of package.el, it has done a good job of creating a standardized format for dependency declarations.

There is one exception to the above statement: not all entries specified in the Package-Requires header necessarily correspond to packages. For example, specifying a minimum Emacs version for a package is done by depending on the emacs pseudo-package. Such packages are simply ignored by straight.el, using the variable straight-built-in-pseudo-packages.

Note that loading a package does not entail invoking require on any of its features. If you wish to actually load the files of the package, you need to do this separately. This is because most packages do not need to be loaded immediately, and are better served by the autoload system.

Installing with a custom recipe

straight-use-package can also take a list instead of a symbol. In that case, the first member of the list is a symbol giving the package name, and the remainder of the list is a property list providing information about how to install and build the package. Here is an example:

(straight-use-package
 '(el-patch :type git :host github :repo "radian-software/el-patch"
            :fork (:host github
                   :repo "your-name/el-patch")))

If you give straight-use-package just a package name, then a recipe will be looked up by default (see the section on recipe lookup). You can see the default recipe for a package by invoking M-x straight-get-recipe.

If straight-allow-recipe-inheritance is non-nil, then you only need to specify the components of the recipe that you want to override. All other components will still be looked up in the default recipe. In the example above, we are only interested in changing the :fork component. Therefore if straight-allow-recipe-inheritance is set, the recipe could be simplified as follows:

(straight-use-package
 '(el-patch :fork (:repo "your-name/el-patch")))

or even simpler:

(straight-use-package
 '(el-patch :fork "your-name/el-patch"))

The :files keyword and all version control keywords support inheritance.

To learn more, see the section on the recipe format.

Additional arguments to `straight-use-package`

The full user-facing signature of straight-use-package is:

(straight-use-package PACKAGE-OR-RECIPE &optional NO-CLONE NO-BUILD)

As discussed previously, by default straight-use-package will do three things:

Register the recipe provided with straight.el.
Clone the package's local repository, if it is absent.
Rebuild the package if necessary, and load it.

By providing the optional arguments, you may cause processing to halt before all three of these tasks are completed. Specifically, providing NO-CLONE causes processing to halt after registration but before cloning, and providing NO-BUILD causes processing to halt after cloning (if necessary) but before building and loading.

straight.el supports lazy-loading by means of a special value for NO-CLONE, the symbol lazy. If this symbol is passed, then processing will halt at the clone step, unless the package is already cloned. This means that the package is built and loaded if it is already installed, but otherwise installation is deferred until later. When you want to trigger the lazy installation, simply call straight-use-package again, but without NO-CLONE. (There is no need to pass the recipe again; see recipe lookup.)

You can also pass functions for NO-CLONE or NO-BUILD, which will be called with the package name as a string; their return values will then be used instead.

Note that if it makes no sense to build a package, then you should put :build nil in its recipe, rather than specifying NO-BUILD every time you register it with straight.el. (This is especially relevant when writing recipes for recipe repositories.)

Variants of `straight-use-package`

For convenience, straight.el provides some functions that wrap straight-use-package with particular arguments, to cover all of the common cases. Each of these functions takes only a package name or recipe, and no additional arguments.

straight-register-package: always stop after the registration step. This may be useful for specifying the recipe for an optional dependency (see recipe lookup, but see also recipe overrides).
straight-use-package-no-build: always stop before the build step. This is used by straight-freeze-versions to make sure packages are cloned, since building them is unnecessary for writing the lockfiles.
straight-use-package-lazy: stop at the clone step if the package's local repository is not already cloned. This is used for lazy-loading.

Customizing when packages are built

By default, when straight.el is bootstrapped during Emacs init, it uses a bulk find(1) command to identify files that were changed since the last time a package depending on them was built. These packages are then rebuilt when they are requested via straight-use-package. Normally, straight.el will try to detect what sort of find(1) program is installed, and issue the appropriate command. If it makes a mistake, then you can manually customize straight-find-flavor. Alternately, you can install GNU find and customize the variable straight-find-executable to point to it.

For about 100 packages on an SSD, calling find(1) to detect modifications takes about 500ms. You can save this time by customizing straight-check-for-modifications. This is a list of symbols which determines how straight.el detects package modifications. The default value is (find-at-startup find-when-checking), which means that find(1) is used to detect modifications at startup, and also when you invoke M-x straight-check-package or M-x straight-check-all. If you prefer to avoid this performance hit, or do not have find(1) installed, then you can remove these symbols from the list. In that case, you will probably want to add either check-on-save or watch-files to the list.

check-on-save causes straight.el to use before-save-hook to detect package modifications as you make them (modifications made by the straight.el repository management commands are also detected). This reduces init time, but modifications made outside of Emacs (or modifications that bypass before-save-hook) are not detected. Pull requests extending the number of cases in which straight.el is able to detect live modifications are welcome. Also, for the sake of efficiency, this form of modification checking is restricted to subdirectories of ~/.emacs.d/straight/repos, so you must put your local repositories into that directory for it to work. (Pull requests to change this would be welcome.)

watch-files causes straight.el to automatically invoke a filesystem watcher to detect modifications as they are made, inside or outside of Emacs. For this setting to work, you must have python3 and watchexec installed on your PATH. By default, the watcher persists after Emacs is closed. You can stop it manually by running M-x straight-watcher-stop, and start it again by running M-x straight-watcher-start. The watcher script is designed so that when one instance is started, all the others gracefully shut down, so you don't have to worry about accidentally ending up with more than one. There is nothing exciting in the process buffer for the watcher, but if you are interested in it then its name is given by straight-watcher-process-buffer. (By default, the name has a leading space so that the buffer does not appear in the buffer list.)

There is probably no good reason to use both check-on-save and watch-files at the same time. Your configuration can dynamically switch between which one is used depending on (executable-find "watchexec") or similar.

If you prefer to eschew automatic package rebuilding entirely, you can just set straight-check-for-modifications to nil. In that case, packages will only be rebuilt when metadata (e.g. the recipe or the Emacs version) changes, or when you manually invoke M-x straight-rebuild-package or M-x straight-rebuild-all.

Regardless of your preferred setting for straight-check-for-modifications, you should set it before the straight.el bootstrap snippet is run, since hooks relating to this variable are set during bootstrap.

On Microsoft Windows, find(1) is generally not available, so the default value of straight-check-for-modifications is instead (check-on-save).

Custom or manual modification detection

You can also use the low-level functions for modification detection directly.

The function straight-register-repo-modification takes a string (e.g. "straight.el") corresponding to the name of a local repository, and marks all packages from that local repository to be rebuilt at next Emacs startup. This function silently ignores local repositories which contain slashes, a limitation which might be removed in future.

The function straight-register-file-modification takes no arguments and checks if the file visited by the current buffer (if any) is contained by any local repository. If so, it delegates to straight-register-repo-modification. The check-on-save value for straight-check-for-modifications just adds straight-register-file-modification to before-save-hook.

Summary of options for package modification detection

`find-at-startup`

Save build timestamps and run find(1) at startup to detect changes

Most reliable, never misses changes
Requires find(1)
Slows down startup

`check-on-save`

Use before-save-hook to detect changes

No external dependencies
No startup delay
No additional CPU or memory impact
Doesn't catch changes made except via save-file inside Emacs

`watch-files`

Run filesystem watcher to detect changes

Requires Python 3 and Watchexec
No startup delay
Takes a few seconds to build virtualenv the first time
Memory and CPU impact of running filesystem watcher
Only misses changes if you make them after booting the system but before starting Emacs

Customizing how packages are built

By specifying :build nil in a package's recipe, you may prevent the package from being built at all. This is usually useful for recipe repositories which do not bundle executable Lisp code. (Make sure to use straight-use-recipes for registering recipe repositories.)

Autoload generation

By specifying :build (:not autoloads) in a package's recipe, you may prevent any autoloads provided by the package from being generated and loaded into Emacs. This is mostly useful if the package provides a large number of autoloads, you know you need only a few of them, and you wish to optimize your startup time (although this is almost certainly premature optimization unless you really know what you're doing). You can also customize the variable straight-disable-autoloads to effect this change on all recipes which do not explicitly disable autoloads via the :build keyword.

Byte compilation

By specifying :build (:not compile) in a package's recipe, you may inhibit byte-compilation. See this issue for discussion of why this might be useful. You can also customize the variable straight-disable-compile to effect this change on all recipes which do not explicitly disable byte-compilation via the :build keyword.

Native compilation

Experimental support for native compilation of Emacs Lisp code can be enabled in the latest main branch of the official Emacs repository (see gccemacs). When running on this version of Emacs, straight.el will perform native compilation of packages.

By specifying a :build (:not native-compile) in a package's recipe, you may inhibit native compilation. You can also customize the variable straight-disable-native-compile to effect this change on all recipes which do not explicitly disable native-compilation via the :build keyword.

Native compilation requires byte-compilation, so :build (:not compile) and straight-disable-compile will also disable native compilation.

Symbolic links

Usually, straight.el uses symbolic links ("symlinks") to make package files available from the build directory. This happens when straight-use-symlinks is non-nil, the default. On Microsoft Windows, however, support for symlinks is not always available, so the default value of straight-use-symlinks is nil on that platform. That causes copying to be used instead, and an advice is placed on find-file to cause the copied files to act as symlinks if you try to edit them.

If you want to activate symlink-support on MS Windows 7, 8, or 10, you should ensure the following requirements:

straight-use-symlinks has to be set to non-nil manually.
Your user-account needs to be assigned the right to create symbolic links. To do so, run "secpol.msc" and in "Local Policies → User Rights Assignment" assign the right to "Create symbolic links" to your user-account.
If you have User Account Control (UAC) enabled and your user-account belongs to the the Administrators group you'll need to run Emacs in elevated mode to be able to create symlinks (see here and here and, for an official reference, section Access Token Changes in this document.
Windows Creators Update supports symlink-creation without any special permission setup.

Customizing how packages are made available

By setting the variable straight-cache-autoloads to a non-nil value, you can cause straight.el to cache the autoloads of all used packages in a single file on disk, and load them from there instead of from the individual package files if they are still up to date. This reduces the number of disk IO operations during startup from O(number of packages) to O(1), so it should improve performance. No other configuration should be necessary to make this work; however, you may wish to call straight-prune-build occasionally, since otherwise this cache file may grow quite large over time.

Hooks run by `straight-use-package`

Currently, straight-use-package supports four hooks:

straight-vc-git-post-clone-hook: The functions in this hook are run just after cloning a git repository. This allows users to automate custom configuration of Elisp Git repositories after they have been cloned. For example, the user.email git-config variable could be set on clone, to make upstream contributions more convenient for developers who use different email addresses for different repositories.

Each hook function is passed the following keyword arguments:
- :repo-dir - the local directory to which the repository was cloned
- :remote - the name of the remote from which the repository was cloned
- :url - the URL from which the repository was cloned
- :branch - the branch as specified by the recipe, if any, otherwise nil
- :depth - the clone depth as specified by the recipe or straight-vc-git-default-clone-depth
- :commit - the specific commit which was requested via the lockfile, if any, otherwise nil
Since keyword arguments are used, each function should be defined via cl-defun, and &key used at the front of the argument list.
straight-use-package-prepare-functions: The functions in this hook are run just before a package would be built, even if the package does not actually need to be rebuilt. They are passed the name of the package being (maybe) built as a string, and should take and ignore any additional arguments.
straight-use-package-pre-build-functions: The functions in this hook are run just before building a package (and only if the package needs to be built). They are passed the name of the package being built as a string, and should take and ignore any additional arguments.
straight-use-package-post-build-functions: The functions in this hook are run just after building a package (and only if the package needs to be built). They are passed the name of the package being built as a string, and should take and ignore any additional arguments.

The recipe format

The general format for a straight.el recipe is:

(package-name :keyword value :keyword value ...)

Note that if you wish to pass a recipe to straight-use-package, you will need to quote it. If you need to compute part of the recipe dynamically, use backquoting:

(straight-use-package
  `(el-patch :type git :repo ,(alist-get 'el-patch my-package-urls)))

The supported keywords are similar, but not identical to those used in MELPA recipes. There is a complete list below which you can compare with the MELPA documentation, but the main differences from the user's point of view are:

We use :host instead of :fetcher.
We only support Git recipes by default, although the system is extensible to other VCs to be added in the future or in user configurations. Thus the supported :host values are:
- nil (any Git repository)
- github, gitlab, sourcehut, codeberg, or bitbucket.
We support :branch, but not :commit or :version-regexp. To lock a package to a specific commit, use a lockfile. See also #246 for discussion of extensions to the recipe to support package pinning, which is a planned feature.
We support several additional keywords that affect how a package is built; see below.
There are consistency and feature improvements to edge cases of the :files keyword as documented in straight-expand-files-directive.
:includes indicates a package is a superset of another package.

Here is a comprehensive list of all keywords which have special meaning in a recipe (unknown keywords are ignored but preserved):

:local-repo

This is the name of the local repository that is used for the package. If a local repository by that name does not exist when you invoke straight-use-package, one will be cloned according to the package's version-control settings. Note that the repository does not have to be version-controlled; it can also just be a directory containing Emacs Lisp files (set :type nil in this case).

Multiple packages can use the same local repository. If so, then a change to the local repository will cause both packages to be rebuilt. Typically, if multiple packages are drawn from the same repository, both should specify a :files directive.

If you do not provide :local-repo, then it defaults to a value derived from the version-control settings, or as a last resort the package name.
:files

This is a list specifying which files in a package's local repository need to be symlinked into its build directory, and how to arrange the symlinks. For most packages, the default value (straight-default-files-directive) will suffice, and you do not need to specify anything.

If you do need to override the :files directive (this happens most commonly when you are taking a single package from a repository that holds multiple packages), it is almost always sufficient to just specify a list of globs or filenames. All matching files will be linked into the top level of the package's build directory.

In spite of this, the :files directive supports an almost comically powerful DSL (with nested excludes and everything!) that allows you full flexibility on how the links are made; see the docstring of straight-expand-files-directive for the full details.
:flavor

If this is non-nil, then it changes the interpretation of the :files directive for compatibility with an existing upstream recipe source. See the docstring of straight-expand-files-directive for details.
:build This specifies the steps taken on the files symlinked within a package's straight/build/PACKAGE directory. It may be any of the following values:
- nil, in which case nothing is done. This also prevents :pre/:post-build commands from running.

(example :build nil)

t, runs the steps listed in straight--build-default-steps. Note this ignores all straight-disable-SYMBOL keywords.

(example :build t)

A list of steps. Each step is a symbol which represents a function named: straight--build-SYMBOL. The function is passed the recipe as its sole argument. Steps are executed in the order they are listed. e.g.

(example :build (autoloads compile native-compile info))

A list which has :not as its car and step symbols as its cdr. This eliminates the listed steps from the default steps. e.g. The following recipe will not be compiled or have its texinfo generated:

(example :build (:not compile info))

Steps may be disabled globally for recipes which do not explicitly declare their :build via the defcustom variables named straight--build-SYMBOL. e.g. The last example but for all recipes without a :build:

(setq straight-disable-compile t
      straight-disable-info t)

In the absence of a :build keyword, straight--build-default-steps are run.

:pre-build

This specifies system commands and/or elisp to be evaluated before symlinking, and running a recipe's :build steps.

Each command is either an elisp form to be evaluated or a list of strings to be executed in a shell context of the form:

("executable" "arg"...)

Commands are executed in the package's repository directory.

The :pre-build keyword's value may be:

A single command
A list of commands
nil, in which case no commands are executed.

For example:

(straight-use-package
 '( example :type git :host github :repo "user/example.el"
    :pre-build ("make" "all")))

(straight-use-package
 `( example :type git :host github :repo "user/example.el"
    :pre-build ,(pcase system-type
                  (`windows-nt '(message "This might take a while"))
                  (_ '(("./configure") ("make") ("make" "install"))))))

:post-build

This specifies system commands and/or elisp to be evaluated after the :build steps are run.

Otherwise, it is identical to the :pre-build keyword in terms of the values it accepts and how it is executed.

For example:

(straight-use-package
 '( example :type git :host github :repo "user/example.el"
    :pre-build  (("./pre-build.sh") (message "hi"))
    :post-build (("./post-build.sh") (message "bye"))))

:type

This specifies the version-control backend to use for cloning and managing the package's local repository. It defaults to the value of straight-default-vc, which defaults to git.

The only traditional version-control backend currently supported is git, although more backends may be added.

As a special case, however, you may specify the value built-in, which results in all version-control operations on the package being ignored. This allows you to tell straight.el that a package has already been provided (for example, because a version of it is shipped by Emacs) and does not have a local repository which needs to be cloned, updated, and so on. Here is how you can tell straight.el that you would like to use the Emacs-provided copy of Org, rather than cloning it from the upstream repository if another package declares it as a dependency:

(straight-use-package '(org :type built-in))

You can also use :type nil, which has the same effect as :type 'built-in, except that the package is still loaded from its configured :local-repo.

:source

Overrides straight-recipe-repositories on a per-recipe basis. Its value may be:

a symbol representing a recipe repository
a list of such symbols The order of the symbols determines their precedence. For example:

(straight-use-package '(package :source melpa))

Will search only the melpa recipe repository for package's recipe. While:

(straight-use-package '(package :source (melpa gnu-elpa-mirror)))

will search for package's recipe first in melpa. If it is not found there it will check gnu-elpa-mirror next.

backend-specific keywords

Depending on the value of :type, additional keywords (relevant to how the package's repository is cloned and managed) will be meaningful. See the next section.

The built-in and nil pseudo-backends do not take any other keywords.
:includes

Informs straight.el that a package is a superset of another package. For example org-contrib includes ol-vm. The following will prevent straight.el from attempting to install ol-vm after org-contrib has been installed:

(straight-use-package '(org-contrib :includes ol-vm))

Its value may also be a list of symbols indicating multiple packages:

(straight-use-package '(example :includes (foo bar)))

:inherit

Overrides straight-allow-recipe-inheritance on a per-recipe basis. If its value is non-nil, inheritance is enabled for the recipe. Otherwise it is not.

Version-control backends

Defining a version-control backend consists of declaring a number of functions named as straight-vc-BACKEND-METHOD, where BACKEND is the name of the version-control backend being defined and METHOD is a backend API method. The relevant methods are:

clone: given a recipe and a commit object, clone the repository and attempt to check out the given commit.
commit-present-p: given a recipe and a commit object, return whether the commit can be checked out offline, i.e., without fetching from the remote.
normalize: given a recipe, "normalize" the repository (this generally means reverting it to a standard state, such as a clean working directory, but does not entail checking out any particular commit).
fetch-from-remote: given a recipe, fetch the latest version from its configured remote, if one is specified.
fetch-from-upstream: given a recipe, fetch the latest version from its configured upstream, if the package is forked.
merge-from-remote: given a recipe, merge the latest version fetched from the configured remote, if any, to the local copy.
merge-from-upstream: given a recipe, merge the latest version fetched from the configured upstream, if the package is forked, to the local copy.
push-to-remote: given a recipe, push the current version of the repository to its configured remote, if one is specified.
check-out-commit: given a recipe and a commit object, attempt to check out that commit in the repository for that recipe.
get-commit: given a local repository name, return the commit object that is currently checked out, or nil if the local repository should not be included in a lockfile.
local-repo-name: given a recipe, return a good name for the local repository, or nil.
keywords: return a list of keywords which are meaningful for this version-control backend.

Most of these methods are highly interactive: they don't actually do anything without prompting you to confirm it, and very often they will offer you a number of different options to proceed (including starting a recursive edit and allowing you to do whatever you would like).

Also, all of the methods in this section take straight.el-style recipes; see the section on defining VC backends in the developer manual for more details.

Git backend

These are the keywords meaningful for the git backend:

:repo: the clone URL for the Git repository.
:host: either nil or one of the symbols github, gitlab, bitbucket, codeberg, or sourcehut.
- If nil, then :repo should be a string which is the full URL of the target repository. For example:
```
( :package "package" :host nil :type git
  :repo "http://myhost.tld/repo")
```
- If non-nil, then :repo should be a string "username/repo", and the URL is constructed automatically. For example:
```
( :package "package" :host github :type git
  :repo "username/repo")
```
:branch: the name of the branch used for primary development, as a string. If your version lockfiles do not specify a commit to check out when the repository is cloned, then this branch is checked out, if possible. This branch is also viewed as the "primary" branch for the purpose of normalization and interaction with the remote.
:remote: the name to use for the Git remote. If the package is forked, this name is used for the upstream remote.
:nonrecursive: if non-nil, then submodules are not cloned. This is particularly important for the Emacsmirror recipe repository, which contains every known Emacs package in existence as submodules.
:fork: the settings for a fork, if desired. This causes the fetch-from-remote method to operate on the fork; you can use the fetch-from-upstream method to operate on the upstream instead.

Note: the following section assumes straight-host-usernames has a value of:

'((github    . "githubUser")
  (gitlab    . "gitlabUser")
  (codeberg  . "codebergUser")
  (sourcehut . "sourcehutUser")
  (bitbucket . "bitbucketUser")))

Its value may be:

t: Look up the username in straight-host-usernames. Inherit the repository name from the upstream repository. For example:

( :package "package" :host github :type git :repo "upstream/repo"
  :fork t)

computes the fork's :repo value as githubUser/repo.

a string (optionally ending with "/"): Use the string as the username. Inherit repository name from the upstream repository. For example:

( :package "package" :host github :type git :repo "upstream/repo"
  :fork "user")

computes the fork's :repo value as user/repo.

a string starting with "/": Look up the username in straight-host-usernames. Use the string as the repository name. For example:

( :package "package" :host github :type git :repo "upstream/repo"
  :fork "/renamed")

computes the fork's :repo value as githubUser/renamed.

a string with both the recipe and repository specified: Use string as the :repo value for the fork. For example:

( :package "package" :host github :type git :repo "upstream/repo"
  :fork "user/renamed")

computes the fork's :repo value as user/renamed.

a plist: The allowed keywords are :repo, :host, :branch, and :remote. The same rules as above apply for the :repo string. Likewise, if the :host is overridden and the :repo does not provide the username, it is looked up in straight-host-usernames. For example:

( :package "package" :host github :type git :repo "upstream/repo"
  :fork (:host gitlab))

computes the fork's :repo value as gitlabUser/repo.

( :package "package" :host github :type git :repo "upstream/repo"
  :fork (:host gitlab :repo "/renamed"))

computes the fork's :repo value as gitlabUser/renamed.

( :package "package" :host github :type git :repo "upstream/repo"
  :fork (:host gitlab :repo "user"))

computes the fork's :repo value as user/repo.

:depth: either the symbol full or an integer. If full, then the repository is cloned with its whole history. If an integer N, then the repository is cloned with the option --depth N. This works even when a commit is specified (e.g. by version lockfiles). The default value is full.
:protocol: If non-nil, force this protocol to be used when interacting with the remote repository. Takes the same values as straight-vc-git-default-protocol.

This section tells you how the git backend, specifically, implements the version-control backend API:

clone: clones the repository, including submodules if :nonrecursive is not provided. Checks out the commit specified in your revision lockfile, or the :branch (from the :fork configuration, if given), or origin/HEAD. If a :fork is specified, also fetches from the upstream.
commit-present-p: checks if the commit SHA is among the revisions that are present locally.
normalize: verifies that remote URLs are set correctly, that no merge is in progress, that the worktree is clean, and that the primary :branch (from the :fork configuration, if given) is checked out.
fetch-from-remote: checks that remote URLs are set correctly, then fetches from the primary remote (the fork, if the package is forked).
fetch-from-upstream: checks that remote URLs are set correctly, then fetches from the upstream remote. If the package is not a fork, does nothing.
merge-from-remote: performs normalization, then merges from the primary remote (the fork, if the package is forked) into the primary local :branch.
merge-from-upstream: performs normalization, then merges from the upstream remote into the primary local :branch. If the package is not a fork, does not attempt to merge.
push-to-remote: performs normalization, pulls from the primary remote if necessary, and then pushes if necessary. This operation acts on the fork, if the package is forked.
check-out-commit: verifies that no merge is in progress and that the worktree is clean, then resets the worktree to the specified commit.
get-commit: returns HEAD as a 40-character string.
local-repo-name: if :host is non-nil, then :repo will be of the form "username/repository", and "repository" is used. Otherwise, if the URL is of the form .../<something>.git, then <something> is used. Otherwise, nil is returned.
keywords: see the list of keywords above.

You can customize the following user options:

straight-vc-git-default-remote-name: the name to use for the primary remote, or the upstream remote if the package is forked. Defaults to "origin". The :remote keyword may be used to override the value of this variable on a per-repository basis.
straight-vc-git-default-fork-name: the name to use for the fork remote, if the package is forked. Defaults to "fork". The :remote keyword may be used to override the value of this variable on a per-repository basis.
straight-vc-git-default-protocol: the default protocol to use for automatically generated URLs when :host is non-nil. It can be either https or ssh, and defaults to https because this requires less work to set up.
straight-vc-git-force-protocol: if this is non-nil, then HTTPS and SSH URLs are not treated as equivalent, so that bulk version-control operations will offer to re-set your remote URLs from HTTPS to SSH or vice versa, depending on the value of straight-vc-git-default-protocol. This is nil by default.
straight-vc-git-auto-fast-forward: if this is non-nil, pulling will quietly do fast-forward, to suppress asking for instructions on each package with updates, unless they're not trivial. Set to nil if you'd prefer to inspect all changes.
straight-vc-git-default-clone-depth: the default value for the :depth keyword. It can be either the symbol full or an integer, and defaults to full. Setting this variable to a small integer will reduce the size of repositories. This variable affects all packages, even those whose versions are locked.

Please be careful with setting straight-vc-git-default-clone-depth, which may break some packages' installing processes such as elfeed that depend on org.

Recipe lookup

If you only provide a symbol (package name) to straight-use-package, then the recipe is looked up automatically. By default, MELPA, GNU ELPA, and Emacsmirror are searched for recipes, in that order. This means that one or more of them may need to be cloned. Recipe repositories are actually just the same as ordinary packages, except that their recipes specify :build nil, so they are not symlinked or added to the load-path.

Note that dependencies always use the default recipes, since the only information straight.el gets about a package's dependencies are their names.

This leads to a few interesting questions regarding requesting a package multiple times. For example, you might need to load two features using use-package that are provided from the same package, or one of the packages you have installed is also requested as a dependency by another package. straight.el uses a number of heuristics to try to make these interactions as intuitive and painless as possible:

The first time a package is registered with straight.el, its recipe (either the recipe that you provided, or the one that was looked up from a recipe repository) is recorded. In future registration, if you just provide the package name to straight-use-package, the existing recipe is reused.

Note, however: if you want to use a custom recipe for a given package, you must load it before all of its dependencies. Otherwise, the package will first be registered as a dependency, using the default recipe.
If a package has already been registered with straight.el, and you attempt to load it again with an explicit recipe which is different from the one previously registered, the new recipe is used but a warning is signalled.
If you attempt to register a package which shares a :local-repo (either by default, or due to explicit specification) with a previously registered package, and the two packages specify different values for their version-control keywords (see version-control backends), then the new recipe is used but a warning is signalled. If the repository was already cloned, this means the second recipe will have no effect.

But if the second recipe was fetched automatically from a recipe repository, all of its version-control keywords will be silently overwritten with the ones from the first recipe, to avoid conflicts (although if there are conflicts in other parts of the recipe, a warning will still be displayed).

Updating recipe repositories

As mentioned in the conceptual overview, recipe repositories are just regular packages, with some extra code to look up recipes in the relevant local repository.

This means that updating a recipe repository may be done the same way as updating a regular package, i.e. with M-x straight-pull-package. A convenience command with interactive completion for recipe repositories, straight-pull-recipe-repositories, is provided as well. You should use one of these if you find that a package isn't listed by M-x straight-use-package—perhaps it was added recently.

Note that there is currently some potentially surprising behavior if you update all packages at once using M-x straight-pull-all or M-x straight-merge-all, and this bulk update includes recipe repository updates: see #323.

Customizing recipe repositories

The recipe repository system is designed to be extended. Firstly, you can control which recipe repositories are searched, and in what order of precedence, by customizing straight-recipe-repositories. The default value is defined by the straight-use-recipes declarations present in the file bootstrap.el in the straight.el version you are using, as customized by the user options you configure in your init-file before loading the bootstrap snippet. As of the time of this writing, with no custom user options set, that works out to be:

(org-elpa melpa gnu-elpa-mirror nongnu-elpa el-get emacsmirror-mirror)

GNU ELPA

You can customize the following user options:

straight-recipes-gnu-elpa-url: The Git URL to use for the gnu-elpa recipe repository.
straight-recipes-gnu-elpa-use-mirror: GNU ELPA uses a stupidly complex build system for no good reason, and it's unlikely to change any time soon. What this means for you is that you have to run the Elisp-powered Makefile of the GNU ELPA repository (which has a fatal bug last I checked, so you'd have to patch it locally) and have a full checkout of the Emacs source repository (more than 1GB) if you want all the packages to work correctly. To work around this problem, I maintain a full mirror of GNU ELPA on GitHub. (The tooling used to maintain this mirror is located here.) By default, straight.el retrieves packages from this mirror instead of the source repository; this behavior is controlled by the value of straight-recipes-gnu-elpa-use-mirror. You must do any customization of this variable before the straight.el bootstrap. Note that setting the value of this user option to nil causes the default value of straight-recipe-repositories to shift to:

(org-elpa melpa gnu-elpa el-get emacsmirror)

Emacsmirror

You can customize the following user option:

straight-recipes-emacsmirror-use-mirror: Yes, there is also a mirror for Emacsmirror. This is because the epkgs repository contains a fair amount of metadata, which means it can take a little on the long side to clone with slow network connections (see #356 and #700). My solution to this problem is to generate a new repository which contains the information that straight.el needs but which is much smaller. By default, straight.el uses the official epkgs repository to find packages on Emacsmirror, but you can tell it to use my mirror by configuring the value of this variable to non-nil. You must do any customization of this variable before the straight.el bootstrap. Note that setting the value of this user option to non-nil causes the default value of straight-recipe-repositories to shift to:

(org-elpa melpa gnu-elpa-mirror el-get emacsmirror-mirror)

Defining new recipe repositories

To define a new recipe repository called NAME, you should do the following things:

Define a function straight-recipes-NAME-retrieve, which takes a package name as a symbol and returns a recipe for that package if it is available, else nil. This is used for recipe lookup. This function may assume that the local repository for the recipe repository has already been cloned, and that default-directory has been set to that local repository. This is used for recipe lookup during the course of straight-use-package.

If the returned recipe is a backquoted list, it will be evaluated during straight--convert-recipe. This is useful for specifying dynamic elements within the recipe such as system-specific build commands. For example, if straight-recipes-NAME-retrieve returns:

'`( package :type git :repo "host/repo"
    :pre-build ,(pcase system-type
                  (`berkeley-unix '("gmake"))
                  (_ '("make")))
    :files (:defaults))

The recipe is converted to:

(package :type git :repo "host/repo"
 :pre-build ("make")
 :files (:defaults))

on a gnu/linux system, and:

(package :type git :repo "host/repo"
         :pre-build ("gmake")
         :files (:defaults))

on a berkely-unix system.

The recipe could be read from a file in the recipe repository as well. In this case, the quote is not included in the recipe, as straight-recipes-NAME-retrieve would make use of read, which will return the literal Lisp object. For example, considering the following retrieval function:

(defun straight-recipes-example-retrieve (name)
  (with-temp-buffer
    (insert-file-literally "./recipes/example.recipe")
    (read (buffer-string))))

The recipe from above could be stored in the file, example.recipe, as:

`( package :type git :repo "host/repo"
   :pre-build ,(pcase system-type
                 (`berkeley-unix '("gmake"))
                 (_ '("make")))
   :files (:defaults))

Define a function straight-recipes-NAME-list, which takes no arguments and returns a list of strings representing packages for which recipes are available. It is permissible to return some strings for which recipes are actually not available, for performance reasons. However, this is discouraged. (The MELPA backend uses this functionality, since all files in the recipes directory are potentially recipes, but only the Git-based ones can actually be used.)
(Optional) Define a function straight-recipes-NAME-version which returns a non-nil value indicating the current version of the logic in your straight-recipes-NAME-retrieve function. Each time you change the logic, this version value must be changed. If this function is defined, then straight.el automatically and transparently caches calls to straight-recipes-NAME-retrieve persistently, using your version value (and its detection of modifications to the recipe repository) to decide when to invalidate the cache.
Call straight-use-recipes with the recipe for your recipe repository. Make sure to include :build nil in the recipe, unless you also want to use the recipe repository as an executable Emacs Lisp package. Alternatively, you can take the manual approach:
- Call straight-use-package-lazy with the recipe for your recipe repository.
- Add the symbol for your recipe repository's name (the car of the recipe you provided, that is) to straight-recipe-repositories, at the appropriate place.

Overriding recipes

You can always use straight-register-package to specify a specific recipe for a package without cloning or building it, so that just in case that package is requested later (possibly as a dependency, or in somebody else's code) your recipe will be used instead of the default one. However, this does not help in the case that a specific recipe is passed to straight-use-package.

Also, it is obviously impossible to call straight-register-package before straight.el has been loaded, so you can't use it to specify a custom recipe for straight.el itself.

To remedy these difficulties, straight.el provides a mechanism for specifically overriding the recipe for a particular package. You can use it by customizing straight-recipe-overrides, or by calling straight-override-recipe.

straight-recipe-overrides is an association list from profile names to override alists. If you don't care about the profile system, you can just use a single override specification, with the profile name nil. Each override alist is just a list of recipes. Because the car of a recipe is just the package name as a symbol, this list of recipes is also an alist whose keys are recipe names and whose values are the plists for those recipes.

Even if an explicit recipe is supplied to straight-use-package, the one given in straight-recipe-overrides will be used instead, if such a recipe is specified there.

For convenience, you may add to straight-recipe-overrides by passing a recipe to straight-override-recipe. This will register it in the override alist for the current profile. Note that if you do this, you will probably want to explicitly set straight-recipe-overrides to nil before bootstrapping straight.el. This will make it so that if you remove a call to straight-override-recipe from your init-file and then reload it, the entry will actually be removed from straight-recipe-overrides.

Overriding the recipe for `straight.el`

As was briefly mentioned earlier, you can actually override the recipe of straight.el itself using straight-recipe-overrides! How does this work? Well, it's basically black magic. If you want the details, go read the developer manual. All you need to know is that you can set straight-recipe-overrides, and it will magically work. The only caveat is that if you change the :local-repo for straight.el, then you will also need to adjust the value of bootstrap-file in the bootstrap snippet accordingly, since otherwise your init-file will not know where to find straight.el. (You must use straight-recipe-overrides instead of straight-override-recipe, since the latter function definition hasn't been loaded yet before straight.el is installed and bootstrapped.)

Here is the default recipe used for straight.el, if you don't override it:

(straight :type git :host github
          :repo ,(format "%s/straight.el" straight-repository-user)
          :files ("straight*.el")
          :branch ,straight-repository-branch)

Note that even though the bootstrap snippet references the develop branch of straight.el, the default recipe installs from main.

If all you want to do is change which branch you are installing straight.el from, simply customize the variable straight-repository-branch, which is provided for this purpose. (Although using straight-recipe-overrides will work just as well, at least until the recipe happens to be changed upstream and your init-file isn't updated.)

Similarly, if all you want to do is switch to your own fork of straight.el on GitHub, simply customize the variable straight-repository-user to your GitHub username.

There is one minor caveat to the above discussion. If your fork makes changes to the way in which recipes are interpreted, then those changes will not be effective during the interpretation of your own recipe for straight.el. If you wish for them to be, then you will have to follow the same procedure that is followed in straight.el itself for making changes to recipe interpretation. These details are outlined in the developer manual; see also install.el for an explanation of this aspect of the bootstrap mechanism.

Interactive usage

The primary usage of straight.el is expected to be in your init-file. For example, this is where you will need to put the bootstrap code as well as any packages that you always want to be installed. However, there are three important interactive uses of straight.el: temporary installation of packages, various helpful utility functions, and version control operations.

To install a package temporarily, run M-x straight-use-package. All registered recipe repositories will be cloned, and you will be presented with a combined list of all recipes available from them. Simply select a package and it will be cloned, built, and loaded automatically. This does not affect future Emacs sessions.

If you provide a prefix argument to M-x straight-use-package, then you are presented with a list of registered recipe repositories. After you select one, you are shown a list of recipes specifically from that recipe repository. This is helpful if you do not want to clone all registered recipe repositories, or you have a particular recipe repository in mind.

You can also call M-x straight-get-recipe, which has the same interface as M-x straight-use-package, except that instead of the package being cloned, built, and loaded, its recipe is copied to the kill ring. If you are writing a custom recipe, this may be helpful, because you may be able to reuse parts of the existing recipe, particularly the :files directive.

Normally, packages are rebuilt automatically if needed, when Emacs restarts. If you for some reason want them to be rebuilt at another time, you can call M-x straight-check-all to rebuild all packages that have been modified since their last build. Alternatively, use M-x straight-rebuild-all to unconditionally rebuild all packages. Note that this will probably take a while. There are also M-x straight-check-package and M-x straight-rebuild-package, which allow you to select a particular package to check or rebuild.

Finally, you may use M-x straight-prune-build in order to tell straight.el to forget about any packages which were not registered since the last time you loaded your init-file. This may improve performance, although only slightly, and will clean up stale entries in the build directory. You can call this function in your init-file if you really wish your filesystem to be as clean as possible, although it's not particularly recommended as the performance implications are uninvestigated. If you do call it in your init-file, be sure to only call it on a fully successful init; otherwise, an error during init will result in some packages' build information being discarded, and they will need to be rebuilt next time.

If you have enabled autoloads caching, it is advisable to call straight-prune-build occasionally, since otherwise the build cache may grow quite large over time.

Version control operations

straight.el provides a number of highly interactive workflows for managing your package's local repositories, using the configured version-control backends. They are as follows:

M-x straight-normalize-package: normalize a package
M-x straight-normalize-all: normalize all packages
M-x straight-fetch-package: fetch from a package's configured remote; with prefix argument, then for forks also fetch from the upstream
M-x straight-fetch-package-and-deps: fetch from the configured remotes of a package and all of its dependencies (including the dependencies of its dependencies); with prefix argument, then for forks also fetch from the upstream
M-x straight-fetch-all: fetch from all packages' configured remotes; with prefix argument, then for forks also fetch from the upstreams
M-x straight-merge-package: merge the latest version fetched from a package's configured remote into the local copy; with prefix argument, then for forks also merge from the upstream
M-x straight-merge-package-and-deps: merge the latest versions fetched from the configured remotes of a package and all of its dependencies (including the dependencies of its dependencies); with prefix argument, then for forks also merge from the upstreams
M-x straight-merge-all: merge the latest versions fetched from each package's configured remote into its local copy; with prefix argument, then for forks also merge from the upstreams
M-x straight-pull-package: combination of M-x straight-fetch-package and M-x straight-merge-package
M-x straight-pull-package-and-deps: combination of M-x straight-fetch-package-and-deps and M-x straight-merge-package-and-deps
M-x straight-pull-all: combination of M-x straight-fetch-all and M-x straight-merge-all
M-x straight-push-package: push a package to its remote, if necessary
M-x straight-push-all: push all packages to their remotes, if necessary

See the sections on version-control backends and the Git backend in particular for more information about the meanings of these operations.

Lockfile management

straight.el determines your package management configuration from two, and only two, sources: the contents of your init-file, and your version lockfiles (which are optional). Your init-file specifies the configuration of straight.el (for example, the values of straight-recipe-overrides and straight-default-vc), the packages you want to use, and their recipes. Your version lockfiles specify the exact revisions of each package, recipe repository, and even straight.el itself. Together, they lock down your Emacs configuration to a state of no uncertainty: perfect reproducibility.

To write the current revisions of all your packages into version lockfiles, run M-x straight-freeze-versions. This will first check that straight.el has an up-to-date account of what packages are installed by your init-file, then ensure that all your local changes are pushed (remember, we are aiming for perfect reproducibility!). If you wish to bypass these checks, provide a prefix argument.

Version lockfiles are written into ~/.emacs.d/straight/versions. By default, there will be one, called default.el. It is recommended that you keep your version lockfiles under version control with the rest of your Emacs configuration. If you symlink your init-file into ~/.emacs.d from somewhere else, you should also make sure to symlink your version lockfiles into ~/.emacs.d/straight/versions. On a new machine, do this before launching Emacs: that way, straight.el can make sure to check out the specified revisions of each package when cloning them for the first time.

To install the versions of the packages specified in your version lockfiles, run M-x straight-thaw-versions. Thawing will interactively check for local changes before checking out the relevant revisions, so don't worry about things getting overwritten.

The profile system

straight.el has support for writing multiple version lockfiles, instead of just one. Why? Consider a large Emacs configuration such as Radian, Spacemacs, or Prelude, which is used by many different people. There are two parts to the configuration that is actually loaded: the "default" part, and the local customizations that each user has added. Generally, these configurations have a mechanism for making local customizations without forking the entire project.

So Radian will have some set of packages that it requires, and my local customizations of Radian have some other set of packages that they require. In order for me to maintain Radian, I need to be able to separate Radian's packages (which go into a versions lockfile in the Radian repository) from my own local packages (which go into a versions lockfile in my own private local dotfiles repository). straight.el provides this ability through the profile system.

The idea is that whenever a package is registered, either directly or as a dependency, it is associated with a given profile. Any given package can be associated with multiple profiles.

When you call straight-use-package, which profile the registered packages are associated with is determined by the value of straight-current-profile, which defaults to nil. In Radian, for example, straight-current-profile is bound to radian while the Radian libraries are being loaded, and it is bound to radian-local while the user's local customizations are being loaded. This results in Radian packages being associated with the radian profile, and the user's local packages being associated with the radian-local profile.

When you call M-x straight-freeze-versions, one or more version lockfiles are written, according to the value of straight-profiles. This variable is an association list whose keys are symbols naming profiles and whose values are filenames for the corresponding version lockfiles to be written into ~/.emacs.d/straight/versions. You should make sure that each potential value of straight-current-profile has a corresponding entry in straight-profiles, since otherwise some packages might not be written into your lockfiles.

When customizing straight-recipe-overrides, note that if multiple profiles are set to override the same recipe, then the last one listed in straight-profiles will take precedence. Similarly, when using M-x straight-thaw-versions, if different lockfiles specify revisions for the same local repository, the last one in straight-profiles will take precedence.

Packages and the init-file

Package managers like package.el store mutable state outside your init-file, including the set of packages that are installed. straight.el does not do this, so it has a rather different way of determining what packages are installed. To straight.el, a package is part of your Emacs configuration if it is passed to straight-use-package when your init-file is loaded.

Note that this means packages installed interactively (using M-x straight-use-package) are not considered part of your Emacs configuration, since the invocation of straight-use-package does not happen in your init-file.

This raises an interesting question: if you add a package to your init-file, how can you convince straight.el that it really is part of your init-file, and not just part of a temporary straight-use-package form that you evaluated ad-hoc? The answer is simple: reload your entire init-file. That way, straight.el will see whether or not that package is registered during your init-file.

One might ask how straight.el determines that you have finished loading your init-file. The answer is simple: post-command-hook is used to execute code only after the current interactive operation has finished. The implementation of this concept is part of the transaction system of straight.el, and it is also used to amortize certain performance costs when many calls to straight-use-package are made sequentially. However, since the transaction system (at least in recent versions of straight.el) operates transparently, its details are relegated to the developer manual.

Byte-compiling the init-file

There is considerable complexity with byte-compiling your init-file, with any configuration (not just with straight.el). In fact, the official Emacs manual recommends against doing so. However, you can still do it, and this is supported by straight.el. This section explains what you have to know in order to do it correctly.

The biggest issue with byte-compilation is that the environment in which you are byte-compiling the code, may affect how the code is byte-compiled. This may not be obvious because in other languages such as C, there is no such thing as there being an "existing environment" derived from the runtime state of a program, when you compile something.

Consider a case where you depend on macros in your init-file, for example use-package. use-package has various extension libraries which provide additional keywords, including straight.el itself which provides the :straight keyword. If those libraries are not loaded in the context in which the use-package macro is expanded, then the keywords will not process correctly, because the keyword logic is implemented at macroexpansion time, not runtime (and macros are expanded during byte-compilation, unless the macros are not defined yet).

So, in order to correctly byte-compile an init-file which contains use-package declarations, you must ensure that any keyword-providing libraries are loaded not only in your runtime context, but also the byte-compilation context. In the case that the libraries are provided by straight.el, then you would also need to load straight.el at byte-compilation time. You can arrange for this sort of thing via eval-when-compile or eval-and-compile, however there are additional complications, for example invoking straight.el during byte-compilation may lead to straight.el trying to clone or build packages during byte-compilation, possibly leading to unexpected results since byte-compilation generally does not have stateful effects on files outside the one being compiled. Furthermore straight.el expects that all relevant packages are registered during a single initialization session, so creating a second context in which a different set of packages are registered for byte-compilation, may create unexpected results with respect to modification detection and the build cache.

Personally, my "foolproof" way of byte-compiling the init-file is to always byte-compile it from within an Emacs instance which has already loaded the init-file, which guarantees that the environment matches what would be expected. I then wrote a wrapper script that allows me to perform the byte-compilation from the command line, by invoking a child Emacs process to load the init-file and then (if that was successful), running a byte-compilation from within that process. This wrapper script is in fact triggered asynchronously after a successful Emacs initialization, if the init-file has changed since the last compilation. See Radian for an example of this implementation.

Using `straight.el` to reproduce bugs

... in other packages

One of the major reasons I wanted to write straight.el was that existing package managers were not good for reproducing bugs. For instance, some of them would load all installed packages when the package manager was initialized! Obviously that is not acceptable for a "minimal test case".

On the contrary, bootstrapping straight.el does not load anything except for straight.el itself (the default recipe repositories are registered, but not cloned until needed). You should normally be loading straight.el by means of the bootstrap snippet, but when you are in emacs -Q, here is how you can initialize straight.el:

M-x load-file RET ~/.emacs.d/straight/repos/straight.el/bootstrap.el RET

You can also do this from the command line, perhaps by creating an alias for it:

$ emacs -Q -l ~/.emacs.d/straight/repos/straight.el/bootstrap.el

Let's say you are making a bug report for Projectile. To load just Projectile and all of its dependencies, run:

M-x straight-use-package RET projectile RET

Note that this will use the currently checked-out revisions of Projectile and all of its dependencies, so you should take note of those in order to make your bug report.

... in `straight.el` itself

straight.el provides a macro, straight-bug-report, to test straight.el in a clean environment. If possible, please use this when creating bug reports.

straight-bug-report accepts the following keyword value pairs:

:pre-bootstrap (Form)... Forms evaluated before bootstrapping straight.el e.g.

(setq straight-repository-branch "develop")

Note this example is already in the default bootstrapping code.

:post-bootstrap (Form)... Forms evaluated in the testing environment after bootstrapping. e.g.

(straight-use-package '(example :type git :host github))

:interactive Boolean If nil, the subprocess will immediately exit after the test. Output will be printed to straight-bug-report--process-buffer Otherwise, the subprocess will be interactive.
:preserve Boolean If t, the test directory is left in the directory stored in the variable `temporary-file-directory'. Otherwise, it is immediately removed after the test is run.
:executable String Indicate the Emacs executable to launch. Defaults to "emacs".
:raw Boolean If t, the raw process output is sent to straight-bug-report--process-buffer. Otherwise, it is formatted as markdown for submitting as an issue."

For example:

(straight-bug-report
  :pre-bootstrap
  (message "before bootstrap")
  (message "multiple forms allowed")
  :post-bootstrap
  (message "after bootstrap")
  (message "multiple forms allowed")
  (straight-use-package '(my-broken-package))
  (message "bye"))

The above will run your test in a clean environment and produce a buffer with information you can paste directly into the issue body.

Using `straight.el` to develop packages

The workflow for developing a package using straight.el is quite straightforward:

Add the package to your configuration as usual, via a call to straight-use-package.
Use M-x find-function or a similar command to jump to the code you wish to edit.
Edit the code.
Either evaluate the edited code using M-x eval-buffer, M-x eval-defun, or a similar command, or just restart Emacs to pick up your changes.
When you are satisfied with your changes, use Magit or just Git directly in order to commit and possibly push them. I suggest using Forge to create pull requests directly from Emacs, with Magit integration.

Development on built-in packages

Unfortunately, you cannot edit packages that are built-in to Emacs in the same way as you can for external packages. However, there are a few options for how you can go about working on contributions to packages in Emacs core.

One option is to see if the package is distributed separately from Emacs, in addition to being distributed in Emacs core. Believe it or not this is the case for several packages, which is a frequent cause of confusion. Typically in this case there is a most recent version of the package available from a separate repository, versus an older version vendored into Emacs core.
- In this case, you can load the package from the separate repository using straight.el (making sure to register it with straight.el before anything causes the built-in version of the package to be require-ed or load-ed, else you will get the wrong version already loaded). Then proceed with normal development workflow.
- If the package is already pre-loaded during Emacs init before your init-file even runs (check with featurep), you are sort of out of luck here, as there is no way to run an external version of the package instead. You might be able to unload-feature and then load the external version, or maybe just forcibly loading the external version on top of the built-in version will work in some situations, however no guarantees.
Another option is to switch to the development version of Emacs, i.e. clone the Git repository and build it from source. Then you can modify the built-in package files directly and commit your changes to a branch.
- If you don't want to build from source, but you still want to modify the package files in Emacs core directly, one option that avoids the need to interfere with your system package manager is to duplicate the files you want to modify, and put them elsewhere, earlier on the load-path (or forcibly load them if they are pre-loaded packages, as mentioned above). You can then even version-control the copies, if you wish.
Alternatively, if you don't need to contribute changes upstream, consider using hooks, advice, or el-patch to make internal changes to packages directly within your configuration without the need for source code modification. Emacs is extremely mutable, so you can even overwrite internal functions directly in your configuration without any additional framework or access to upstream.

Development on GNU ELPA packages

Development on GNU ELPA packages is somewhat complicated by the strange nature of GNU ELPA development, where some packages are copied out of Emacs core and into the repository, while others are copied from external repositories, while still others are maintained directly in the GNU ELPA repository itself, and all the packages are in the same repository but on different branches.

Since straight.el does not have support for using Git worktrees at present (which is the only really reasonable way to deal with a one-package-per-worktree model), there are not too many good options, which is why GNU ELPA Mirror was created. However using GEM obviously does not allow external contributions back, since the source code is repackaged into a different (more convenient) format than is used for upstream development.

Some work could be done here to find a good solution.

Integration with other packages

Integration with `use-package`

By default, straight.el installs a new keyword :straight for use-package which may be used to install packages via straight.el. The algorithm is extremely simple. This:

(use-package el-patch
  :straight t)

macroexpands (essentially) to:

(straight-use-package 'el-patch)

And this:

(use-package el-patch
  :straight (:host github :repo "radian-software/el-patch"
             :branch "develop"))

becomes:

(straight-use-package
 '(el-patch :host github :repo "radian-software/el-patch"
            :branch "develop"))

If the feature you are requiring with use-package is different from the package name, you can provide a full recipe:

(use-package tex-site
  :straight (auctex :host github
                    :repo "emacsmirror/auctex"
                    :files (:defaults (:exclude "*.el.in"))))

And you may also provide just the package name:

(use-package tex-site
  :straight auctex)

If you don't provide :straight, then by default nothing happens. You may customize straight-use-package-by-default to make it so that :straight t is assumed unless you explicitly override it with :straight nil.

Previously, straight.el used a different syntax for its use-package integration. For backwards compatibility, you can use this syntax instead by customizing straight-use-package-version.

You can disable use-package integration entirely by customizing straight-enable-use-package-integration.

For more details on the available keywords inside a recipe, see the recipe format.

Loading packages conditionally

use-package has various features intended to support code being executed conditionally for a package. For example, the :when keyword lets you provide a form that will essentially disable the use-package form if it evaluates to nil.

However, when using the :straight keyword, either explicitly or via straight-use-package-by-default, then :when has no effect on it. straight.el is invoked unconditionally. The reason for this behavior is that if you invoke straight-use-package on a different set of packages during different init sessions, then your version lockfile would end up containing different sets of packages depending on which session you generated it in.

Currently, the officially recommended pattern for conditionally loading a package is the following:

(straight-register-package 'foobar)
(when some-condition
  (use-package foobar
    :straight t))

This ensures that the package is registered to straight.el, so it will be cloned if absent, and will be added to the lockfile, but it will not be compiled or loaded unless the subsequent use-package form is evaluated. You can also invoke straight-register-package only in the case that some-condition is nil; either way will produce the same result with roughly the same performance due to idempotency and caching.

If you do this for a lot of packages, it may be advisable to wrap it in a macro, as my own Emacs configuration Radian does in the macro radian-use-package. It would be a good idea if straight.el did this by default in its use-package integration but this has not been implemented yet.

If you want to not even clone a package when it is disabled, you can also technically achieve it by simply making the entire use-package form conditional, without using straight-register-package. However, this is not recommended because it will cause the generated lockfile to be deterministic, so straight.el will not be changed to make :when act that way by default.

It would be desirable if you could clone a package conditionally without breaking the lockfile functionality; this is a hopefully planned future feature, but it needs design work.

"Integration" with `package.el`

By default, package.el will automatically insert a call to package-initialize into your init-file as soon as Emacs starts, which is ridiculous. It will also do this when you perform any package management operation. A separate system inserts some custom forms into your init-file when you install a package. straight.el disables all of these "features" by setting package-enable-at-startup to nil and enabling some advice. You can override this behavior by customizing straight-enable-package-integration, however.

To help avoid you shooting yourself in the foot by using both :ensure and :straight at the same time in a use-package form (which would cause the same package to be installed twice using two different package managers), straight.el will helpfully disable :ensure whenever you include :straight in a use-package form. See #425.

Integration with Flycheck

Flycheck sometimes creates temporary files in order to perform syntax checking. This is a problem for straight.el because creation of temporary files will cause straight.el to think that you have modified a package when you actually have not. (You might ask why straight.el cannot recognize temporary files and ignore them. The answer is that for eager modification checking, all we see is that the directory mtime for the repository has been updated, and there's no way to disambiguate between temporary file shenanigans versus if you, say, deleted a file.)

To work around the problem, a user option straight-fix-flycheck is provided, disabled by default (for now). You can enable it before loading straight.el, and it will work around the Flycheck problem in the following way. When you first visit a buffer, any Flycheck checker that involves creation of temporary files will be inhibited automatically, although other checkers will still run. (In practice this means no byte-compilation errors for Emacs Lisp, but you still get Checkdoc errors.) However, after you make a change to the buffer (by typing, etc.) then all checkers will be re-enabled. This means that straight.el won't think the package was modified unless you actually modify the buffer of a file inside it, which I think is a reasonable compromise.

See #508 for discussion.

Integration with Hydra

See the Hydra wiki.

Miscellaneous

By default, straight.el explains what it is doing in the echo area, like this:

Looking for cider recipe → Cloning melpa...

If your terminal does not support Unicode characters nicely, you can customize straight-arrow to display something else for the arrow.

By default, straight.el reports process output the *straight-process* buffer. You can customize the name of this buffer via the straight-process-buffer user option. If you want to hide this buffer by default, consider adding a leading space to the name.
You can prevent straight.el from making any modifications to the filesystem (though it may still read) by customizing the user option straight-safe-mode to non-nil. This may be useful for running tasks automatically in batch mode, to avoid multiple concurrent Emacs processes all making changes to the filesystem. For an example of how this feature may be used to safely implement asynchronous byte-compilation of the init-file on successful startup, see Radian.

Troubleshooting

There are a couple of commonly encountered issues with straight.el. I would like to change things so these problems do not happen, or are repaired automatically. But, I can write documentation faster than I can fix code, so here are tips in the meantime.

When investigating an issue, consider turning on logging. You can set straight-log to non-nil at the start of your init-file, and then check *straight-log* to see detailed information about exactly what straight.el is doing to process package management operations. You can also see *straight-process* for exact process output for any subcommands executed.

Why are my packages always/never rebuilding?

So, the first thing you have to check is the value of straight-check-for-modifications. You can set it to nil, obviously then straight.el will never rebuild anything, but that is probably not what you want. Based on the enabled checkers, we can dive into what is malfunctioning with the ones you have enabled. The basic principle is straight.el uses various methods to detect when the source repo of a package is changed, and if it has changed since the last time the package was built, then it is rebuilt on next Emacs init (or re-init).

You should start by looking at the docstring of that variable and seeing if the enabled modes match the behavior you are expecting to see. This is because there are different limitations to the modes, for example if you only use check-on-save, then modifications will only register when you edit a file within Emacs, and not from an external program. The rest of this section will assume you have the user option set to what you want, and it is some technical bug that is preventing the rebuild system from working properly.

You can probably ignore check-on-save and find-when-checking, neither of those have ever caused anyone problems that I have known of. The ones that are complicated (and thus prone to failure) are find-at-startup and watch-files.

The way find-at-startup works is by using the find utility (GNU or BSD is supported) to scan for files in ~/.emacs.d/straight/repos that are more recent than the corresponding packages were built. If a package directory contains files that have filesystem mtimes more recent than the timestamp of the last time straight.el rebuilt the package, another rebuild is triggered.

So, a couple of ways this could fail:

filesystem doesn't support mtimes properly, or some tooling is updating mtimes constantly instead of letting them be
maybe building a package causes its own files to get updated, so straight.el thinks it needs to be rebuilt again
- normally this does not happen, because files are linked from the source repo into the build directory, and then build steps are run in the build directory
- however, custom code in the package could potentially reach back into the source repo on purpose somehow, which can cause problems. This is rare but I've seen it happen, especially with big complicated packages like Org/AUCTeX
weird version of find installed? you can go to *straight-process* and see the exact command that's being run, as well as the output - this may give a clue as to what modifications are being detected, as the filenames will be printed, or if there is some kind of warning being printed by find
- try copying and pasting the find command to your terminal and experimenting with it to find out why it is returning results when it shouldn't be
straight.el is not completing the init process properly and writing the build cache file, so next time it does not remember that it built anything
- check ~/.emacs.d/straight/build-cache.el, you can see the recorded last build time of each package, is that getting updated?

Now let's talk watch-files, the most obvious failure condition for this is you don't have watchexec installed since that is a dependency. Get it from your distro package manager. Python 3 is also required, as well as the venv-whatever package that is needed on Ubuntu to run python3 -m venv successfully.

The filesystem watcher runs in the background and uses nohup to fork out and survive Emacs termination. The invocation of nohup itself logs to *straight-watcher*, and includes log lines that tell you it has forked successfully, as well as pointing to the watchexec log file, which is ~/.emacs.d/straight/watcher/nohup.out. You might see warnings or fatal errors here. We should really be reporting those proactively but we don't currently.

The most common cause that the filesystem watcher doesn't work, for me at least, is the virtualenv gets bricked. This seems to happen every time I upgrade Python versions, no matter what operating system I'm on. Thanks Python. However this case should be caught proactively by straight.el and reported in the echo area during startup. You can run C-u M-x straight-watcher-start to delete and recreate it.

It's also possible you have a wrong (or just different than expected) version of watchexec, maybe the command-line options we are passing. Check for warnings in the nohup.out log, maybe try out the watchexec invocation in your terminal and see if it works. You can also compare your watchexec --version and see the upstream changelog. Our watchexec invocation should be running the Python callback file for every file modification and that should be mapping it back to a straight.el repository.

There may also be warnings from watchexec notifying you that there are issues with your system configuration; some cases are known to work best with some custom sysctl configuration, and will tell you so in that log file.

If that's working then the next step is that when a modification is detected, the callback script creates a file in ~/.emacs.d/straight/modified. Each file in here corresponds to the name of a directory in ~/.emacs.d/straight/repo, and the directory listing is read on Emacs startup to determine repos to rebuild. This is how the information is collected over time by the watcher but then collated into a place where it can be read in all at once quickly.

One thing that's not super well tested is what happens with either find-at-startup or watch-files when you have custom repo locations. Custom base directory should work, but if you have specific repos with hardcoded absolute paths (instead of having them all in the repos base-dir), my scripting might not take that into account properly. That's an area for improvement.

I changed something but `straight.el` is still using the old value!

For performance reasons, straight.el uses many many caches. The implementation goal is that all caches are transparent to the user, i.e. if anything is changed that would make the cached data no longer valid, then the cache is automatically invalidated without the need for user action. Sometimes however this may not work correctly. This doc section is about helping you find out what's going wrong and how to make straight.el do what you want without needing to delete everything and start again.

I don't know any perfect way to provide a universal guide, so let's start with a list of all the different types of data that is cached by straight.el and why it does so / when the cache is invalidated:

Types of data that are cached in memory, within a single Emacs session. All this data will be cleared by restarting Emacs. Some of it will also be cleared by re-loading your init-file.
- The set of packages registered by your init-file, and what recipes were used for them.
  - This is used to identify which set of packages should be written to the lockfile, if you use M-x straight-freeze-versions.
  - This cache is cleared during straight.el bootstrap, which will be invoked if you re-load your init-file, and is populated as your init-file invokes straight-use-package.
  - straight.el pays attention to whether additional packages have been registered after your init-file finished loading (e.g., via M-x straight-use-package for temporary testing). If so, this cache will no longer match your init-file package-set, and straight-freeze-versions will prompt you to re-load your init-file to ensure a correct lockfile is written.
  - When straight-use-package is invoked without providing a recipe, or interactively, or internally because a package has dependencies, normally the recipe is looked up from recipe repositories. However, if that package was already registered in the current Emacs session (tracked in this cache), then the already-registered recipe is automatically reused.
  - To force the recipe to change for an already-registered package, either provide the new recipe explicitly to straight-use-package, or re-load your init-file. Recipe repository lookup will only be triggered once per package per init-file load. (See also the recipe lookup cache, below.)
  - The internal data structures used to maintain this cache are straight--recipe-cache, straight--repo-cache, straight--profile-cache, and straight--profile-cache-valid.
Types of data that are cached on disk, between multiple Emacs sessions, but are not needed for correctness. This data is stored in ~/.emacs.d/straight/build-cache.el unless otherwise specified, and that file can be safely deleted as a nuclear option (note this will trigger rebuilds of all packages).
- The built versions of every package.
  - These are stored in ~/.emacs.d/straight/build, which can also be removed to trigger a rebuild of all packages. However, the contents of this directory are not trusted without timestamps in the build cache to authenticate them, so removing the build cache file is also sufficient.
  - When anything that would cause the package to be built differently is changed, the package should be rebuilt automatically the next time it is registered.
    - However, if only-once is included in straight-check-for-modifications, you need to actually re-load your init-file before another modification check will be run for a package that was already registered in the current session.
  - The built version of a package is considered outdated if: a file in its source repository is modified (see the modification detection system); the recipe for the package changes (but see also the recipe lookup cache); or certain global configuration options affecting package builds are changed (which will invalidate the entire build cache).
    - A package rebuild is only triggered if one of the changed recipe keywords is actually relevant to package build behavior (e.g., :files but not :repo).
- The timestamp for the last time a package was built, and the last used recipe for it.
  - This is used to implement the rules outlined in the previous section.
- The list of dependencies for each package.
  - This is a performance optimization; the list of dependencies is read out of the package from disk when building it, and then cached until the next package build, since any operation that could change the set of dependencies should also trigger a rebuild.
- The entire contents of the autoloads generated for each package.
  - This is also a performance optimization; the autoloads similarly only change during a package build, so they are copied out of the package into the build cache during each package build.
- The recipes looked up from recipe repositories.
  - Making changes to a recipe repository should result in the new recipes being used during the next package registration. However, it is relatively slow to always check the recipe used for each package during every init. The previously used recipes are stored in the build cache, but they may not still be valid if the recipe repository has changed.
  - To track this information correctly, recipes looked up from recipe repositories are cached persistently, but the cache for a recipe repository is invalided automatically when the modification detection system detects a modification to the recipe repository, or the Emacs Lisp code for generating recipes from that recipe repository is changed (e.g. due to updating straight.el).
  - Note that packages are only checked for modifications at registration time (and only once per init-file load if only-once is included in straight-check-for-modifications). As a result, normally it would be required to re-load the entire init-file so that the modification to the recipe repository could be detected and then subsequently used for the dependent recipe. However, as a concession to usability, reading from the recipe lookup cache is automatically disabled when straight.el is not being invoked from the init-file, making it so you do not need to think about this cache when exploring interactively with changes to recipes.
Types of data that are stored on disk, persistently, and are needed for correctness. Deleting this data may change behavior as it is considered user content/configuration.
- The physical Git state for every package repository.
  - During init, straight.el never makes any changes to package source repositories, nor checks that they are in a valid state. This means manual edits will be neither detected nor reverted. If you delete a source repository, it will automatically be cloned again (at the revision specified in your lockfile, or at the latest revision if there is no lockfile), but if you check out a different revision in an already-cloned source repository, that revision will remain checked out. However, the change will still be detected and will result in the package being rebuilt.
    - To ensure that your checked-out packages match your lockfile, or to update your lockfile to reflect changes you have made to your checked-out packages, use the VC system commands or the lockfile management commands. These commands operate orthogonally to the straight.el subsystems that execute during init, and they do not use any caching, because they are not on the critical path that affects init time.

Developer manual

This section tells you about all the interesting implementation details and design decisions that power straight.el behind the scenes. It assumes you have already read the user manual and the conceptual overview.

More to be written here in future. See #51.

Low-level functions

The function straight-chase-emulated-symlink is provided in order for external packages to correctly handle the emulated symlinks created by straight.el when straight-use-symlinks is nil. See, for example, #520.

Trivia

This section has random, (possibly) interesting tidbits about straight.el that don't fit in the other sections.

Comments and docstrings

How did I get that statistic about the percentage of straight.el that is comments and docstrings? Simple: by abusing the syntax highlighting.

(let ((lines (make-hash-table :test #'equal)))
  (goto-char (point-min))
  (while (< (point) (point-max))
    (when (memq (face-at-point)
                '(font-lock-comment-face
                  font-lock-doc-face))
      (puthash (line-number-at-pos) t lines))
    (forward-char))
  (* (/ (float (length (hash-table-keys lines)))
        (line-number-at-pos))
     100))

Note that you will have to scroll through the entire buffer first, since font-lock-mode computes syntax highlighting lazily.

Contributing

Please do! Development takes place on the develop branch. You can switch to that branch with

(setq straight-repository-branch "develop")

and base your pull requests from it. If you have an outstanding pull request whose features you would like to use in your configuration, there is full support for defining straight.el as coming from any branch in any fork:

(setq straight-repository-user "my-github-username")
(setq straight-repository-branch "feat/my-cool-feature")

For additional information, please see the contributor guide for my projects. Note that straight.el has not yet had an initial release, so you don't have to worry about a changelog.

CI administration

Maintaining the GitHub Container Registry images used by CI looks like this for a given Emacs version. We have the base image:

docker pull silex/emacs:30
docker tag silex/emacs:30 ghcr.io/radian-software/emacs-base:30
docker push ghcr.io/radian-software/emacs-base:30

And the full image:

DOCKER_BASE=ghcr.io/radian-software/emacs-base  \
  make docker VERSION=30 CMD="make lint test"
docker tag straight.el:30 ghcr.io/radian-software/straight-ci:30
docker push ghcr.io/radian-software/straight-ci:30

For this you of course need GHCR authentication, for example by generating a personal access token (classic) with the packages:write scope, and then docker login https://ghcr.io -u yourlogin --password-stdin <<< yourtoken.

FAQ

My init time got slower

Your first step should be to customize the value of straight-check-for-modifications. The best setting is (watch-files find-when-checking); this is not enabled by default because it is impolite to spawn persistent background processes without asking, and because you must install Python 3 and watchexec for it to work. If you can't stand the extra dependencies and background process, consider the setting (check-on-save find-when-checking) instead, which is just as fast but won't catch package modifications unless they are made within Emacs via the save-buffer command.

Even with lazy modification detection, as described above, straight.el is not quite as fast as package.el (by a few percentage points). There are some planned changes which will make straight.el just as fast as package.el, if not faster. See #9.

"Could not find package in recipe repositories"

Assuming that the package you're trying to install actually exists, you need to update your recipe repositories (most likely MELPA, possibly Emacsmirror). See the next FAQ entry. This is like running package-refresh-contents under package.el.

Another possibility is that you are providing straight.el with a feature name rather than a package name. Features are what you load with require or load, or find in files. For example, org-agenda and org-capture are features. Packages, on the other hand, can provide one or more features. They are what are listed on MELPA et al. or by M-x straight-get-recipe. For example, org and org-contrib are packages.

When you write (use-package foo ...), the foo is a feature, not a package. You can give a different package name bar by saying (use-package foo :straight bar). And when you write (straight-use-package 'bar), the bar is a package, not a feature.

How do I update MELPA et al.?

Using M-x straight-pull-package, like for any other package. Read more.

My `use-package` form isn't working properly

There are a number of common problems you might be encountering. Check out the following list to see if there is an easy fix.

Make sure you're not using :ensure or use-package-always-ensure. Those are for package.el and using them with straight.el will produce weird results (namely both package.el and straight.el will be invoked for the same package).
Make sure you know both the name of the feature and the name of the package. These are usually the same but not always (packages may provide more than one feature, ...). You give use-package the name of a feature, not a package (despite the name of the macro). With straight-use-package-by-default or with :straight t, the default is to try installing a package by the same name as the feature.
- If you don't actually need to install a package, then pass :straight nil to override straight-use-package-by-default.
- If the package name is different from the feature name, then pass :straight <package-name>.
If the package or your configurations aren't being loaded, you probably have something wrong with your usage of :init and :config. By default, the behavior of use-package is unusably inconsistent. You must set either use-package-always-defer (override with :demand t) or use-package-always-demand (override with :defer t) to set a default for whether evaluating a use-package form will load the package and your configurations.
- If you've set a package to be deferred, you then need to make sure there's a way for it to get loaded when needed, for example by means of an autoload (either provided by the package, or set up automatically by use-package via :bind, or set up manually through use-package via :commands) or by an explicit require in one of your custom commands.

How do I uninstall a package?

My first question is: do you really need to uninstall the package? Under package.el, every package on disk gets loaded into Emacs, whether you asked for it or not. However, under straight.el, only the packages you explicitly mention in your init-file get loaded into Emacs. So the only problem with leaving a package on disk is that it takes up a little bit of disk space. (But the advantage is if you decide you want to use that package again later then you won't have to redownload it.)

If you really want to uninstall a package, simply delete its local repository from ~/.emacs.d/straight/repos or run the straight-remove-unused-repos command.

The wrong version of my package was loaded

To explain this problem, let us consider a concrete example. In this issue, a user found that the code

(straight-use-package 'company-lsp)
(straight-use-package 'eglot)

sometimes resulted in runtime errors because an old version of Flymake was being used.

The root problem here is that you want the most recent version of Flymake to be installed by straight.el, but Emacs also ships an older version, and that older version is getting loaded instead.

The older version will be loaded if (require 'flymake) (or similar) is invoked before straight.el has made Flymake available (by means of (straight-use-package 'flymake) or similar). But why would straight.el not make Flymake available?

The only way that straight.el knows to make Flymake available is if either you manually invoke straight-use-package in your init-file, or if one of the packages that you request in your init-file declares Flymake as a dependency. Now, any package that uses Flymake ought to declare it as a dependency. Thus, there should be no way for a package to load the Emacs-provided version of Flymake. However, sometimes package authors overlook this problem (it does not always cause an error, and sometimes package authors do not test exhaustively enough).

In this case, the problem was that company-lsp declared a dependency on lsp-mode, and lsp-mode used Flymake without declaring a dependency on flymake. There are two ways to work around the problem:

(Preferable) Fix lsp-mode to declare a dependency on flymake.
(Workaround) Manually invoke (straight-use-package 'flymake) before (straight-use-package 'company-lsp).

If you test this yourself, you might find it difficult to reproduce the problem. That is because there is only an issue when Flymake is actually loaded, and this doesn't necessarily happen when invoking (straight-use-package 'company-lsp) unless straight.el needs to rebuild the relevant packages (which includes byte-compilation, which sometimes means actually loading dependencies). Keep this in mind when testing.

This problem commonly occurs with Org, since (1) Org is popular, (2) Emacs ships an obsolete version of Org, (3) many users want to use the up-to-date version, and (4) Org breaks backwards compatibility frequently. To solve it, simply make sure that you invoke (straight-use-package 'org) before running any code that could load Org, including installing any package that lists it as a dependency.

See this issue for discussion about ways of mitigating the bad UX of this situation.

I get "could not read username/password" errors

This is because straight.el is not currently able to detect when SSH or Git asks for your username and/or password/passphrase and then pipe that prompt through to the minibuffer (#334).

To work around the problem, set up git-credential-cache if you use HTTPS, and ssh-agent if you use SSH. That way, you won't be prompted for your username/password. When setting up ssh-agent, be careful to make sure that the relevant environment variables get set in Emacs. This might be tricky since starting Emacs from the desktop (rather than from the command line) sometimes results in it not inheriting any environment variables from your shell.

How do I pin package versions or use only tagged releases?

This is a planned feature. In the meantime, contributors have proposed various workarounds. See #246 and #31.

straight-x.el now contains an experimental solution. In order to use it you will need to add similar snippets to your Emacs configuration.

First you need to add a new profile to straight-profiles which also needs to be the last profile in the list. This should be done before you bootstrap straight.el.

;; Tell straight.el about the profiles we are going to be using.
(setq straight-profiles
      '((nil . "default.el")
        ;; Packages which are pinned to a specific commit.
        (pinned . "pinned.el")))

After straight's install procedure you will need to add straight-x.el and load the required commands.

(autoload #'straight-x-pull-all "straight-x")
(autoload #'straight-x-freeze-versions "straight-x")

A variable called straight-x-pinned-packages has been defined in straight-x.el and will contain your list of pinned packages.

From now on, you can pin a package to a specific commit like in the following example which will pin org-mode to the 9.2.3 release version:

(let ((straight-current-profile 'pinned))
  (straight-use-package 'org)
  (straight-use-package 'org-contrib)
  ;; Pin org-mode version.
  (add-to-list 'straight-x-pinned-packages
               '("org" . "924308a150ab82014b69c46c04d1ab71e874a2e6")))

If you invoke straight-x-freeze-versions it will first write the default lockfile and then pinned lockfile which takes precedence over the default one if packages are thawed. straight-x-pull-all will first invoke straight-pull-all and then restore all pinned packages.

You might want to assign the following aliases for more convenience:

(defalias 'straight-pull-all #'straight-x-pull-all)
(defalias 'straight-freeze-versions #'straight-x-freeze-versions)

Please keep in mind that this is only a temporary solution and experimental!

How can I use the built-in version of a package?

To tell straight.el that you want to use the version of Org shipped with Emacs, rather than cloning the upstream repository:

(straight-use-package '(org :type built-in))

Note that :type is a keyword for straight.el, not for use-package. If you are using use-package, then use:

(use-package org :straight (:type built-in))

News

Note that recent changes are available on the develop branch, and are only periodically merged into the default main branch once there has been the opportunity for users to test their stability.

Jul 1, 2025

The default branch of straight.el is now called main instead of master, to follow prevailing conventions. For backwards compatibility, master still points at the same commit, and will continue to be updated for some time.

Jul 1, 2025

The source code of straight.el now indicates, for each user option (defcustom), when that user option needs to be set to take effect. This is shown in a :set property of each variable definition.

Jun 26, 2025

We now have a troubleshooting section for caches, in case you changed a user option or package configuration and wondered why straight.el seemed to be unable to notice the update.

Jun 25, 2025

Performance is improved for non-SSD users of the default straight-check-for-modifications value that includes find-at-startup, since it would incur a nontrivial delay when re-evaluating a use-package form that invoked straight.el, as a bulk find command would be executed in a likely unnecessary way. The default value for straight-check-for-modifications now includes only-once which restricts modification checking to once per init session.

Jun 23, 2025

Customize straight-vc-use-snapshot-installation to try out snapshot installation. Packages will be initially cloned by extracting a downloaded tarball, with a tracking file written to note which commit was installed, and can later be converted into full repository clones if you want to make changes. This massively improves bootstrap performance, especially on a slow network connection, and reduces disk space utilization. Some VC operations may not be implemented yet for packages managed as snapshots; please report any bugs.

Jun 23, 2025

Org is installed by default from a GitHub mirror maintained by Jonas. Customize straight-recipes-org-url to configure.

Jun 17, 2025

GNU ELPA is usable from source again; that is, you can elect to disable straight-recipes-gnu-elpa-use-mirror and operation will generally be as intended, due to the returned recipes being updated to perform single-branch clones of sub-packages rather than trying to interact with the GNU ELPA build system.

Jun 16, 2025

GNU ELPA and NonGNU ELPA repositories are, by default, now pulled from GitHub mirrors maintained by Jonas, rather than from source. This improves performance significantly. The change is to the default value of straight-initial-recipe-repositories, and is controlled by separate user options which you can customize as well, straight-recipes-gnu-elpa-url and straight-recipes-nongnu-elpa-url.

Jun 13, 2025

The behavior of M-x straight-use-package is somewhat changed: it is possible to select already-registered packages, and the existing recipes for those packages will be respected rather than being reverted to the default pulled from a recipe repository. To accomplish this the user interface is modified to present a virtual cache recipe repository at the front of straight-recipe-repositories within M-x straight-use-package, which contains package recipes that have already been registered in the current session.

Jun 13, 2025

When Git requires a passphrase to be entered to clone a repository, you are now prompted for this interactively in the minibuffer, like how it works in Magit. For now, this feature is opt-in via the user option straight-display-subprocess-prompts.

Jun 10, 2025

It's now possible to customize the default recipe repositories. You can change their recipes arbitrarily, reorder them, or remove them entirely. See the new user option straight-initial-recipe-repositories, whose default value corresponds to the previous behavior.

Jun 9, 2025

It's now possible to register your own custom hosts with full feature parity to the built-in :host github, :host sourcehut, etc. See the docstring of the straight-hosts for information. This changes the format of entries in straight-hosts, but the previous more-limited format is still supported for backwards compatibility.

Apr 5, 2025

We have a troubleshooting guide available for finding out why your packages are always/never rebuilding during Emacs init. Check the new README section.

radian-software/apheleia

🌷 Run code formatter on buffer contents without moving point, using RCS patches and dynamic programming.

Apheleia

Good code is automatically formatted by tools like Black or Prettier so that you and your team spend less time on formatting and more time on building features. It's best if your editor can run code formatters each time you save a file, so that you don't have to look at badly formatted code or get surprised when things change just before you commit. However, running a code formatter on save suffers from the following two problems:

It takes some time (e.g. around 200ms for Black on an empty file), which makes the editor feel less responsive.
It invariably moves your cursor (point) somewhere unexpected if the changes made by the code formatter are too close to point's position.

Apheleia is an Emacs package which solves both of these problems comprehensively for all languages, allowing you to say goodbye to language-specific packages such as Blacken and prettier-js.

The approach is as follows:

Run code formatters on after-save-hook, rather than before-save-hook, and do so asynchronously. Once the formatter has finished running, check if the buffer has been modified since it started; only apply the changes if not.
After running the code formatter, generate an RCS patch showing the changes and then apply it to the buffer. This prevents changes elsewhere in the buffer from moving point. If a patch region happens to include point, then use a dynamic programming algorithm for string alignment to determine where point should be moved so that it remains in the same place relative to its surroundings. Finally, if the vertical position of point relative to the window has changed, adjust the scroll position to maintain maximum visual continuity. (This includes iterating through all windows displaying the buffer, if there are more than one.) The dynamic programming algorithm runs in quadratic time, which is why it is only applied if necessary and to a single patch region.

Installation

Apheleia is available on MELPA. It is easiest to install it using straight.el:

(straight-use-package 'apheleia)

However, you may install using any other package manager if you prefer.

Dependencies

Emacs 27 or later is supported. Apheleia does not include any formatters. You must install any formatter separately that you wish to use. As long as it is on $PATH then Apheleia will pick it up automatically; missing formatters will silently be skipped, but errors from invoking installed formatters will be reported on buffer save.

It is recommended to have Bash installed, as this is used as a dependency for Apheleia to invoke certain formatters (e.g. Node.js-based formatters).

Windows support is not guaranteed due to lack of support for common open standards on this platform. Pull requests adjusting Apheleia for improved cross-platform portability will be accepted, but no guarantees are made about stability on Windows.

User guide

To your init-file, add the following form:

(apheleia-global-mode +1)

The autoloading has been configured so that this will not cause Apheleia to be loaded until you save a file.

By default, Apheleia is configured to format with Black, Prettier, and Gofmt on save in all relevant major modes. To configure this, you can adjust the values of the following variables:

apheleia-formatters: Alist mapping names of formatters (symbols like black and prettier) to commands used to run those formatters (such as ("black" "-") and (npx "prettier" input)). See the docstring for more information.
- You can manipulate this alist using standard Emacs functions. For example, to add some command-line options to Black, you could use:
```
(setf (alist-get 'black apheleia-formatters)
      '("black" "--option" "..." "-"))
```
- There are a list of symbols that are interpreted by apheleia specially when formatting a command (example: npx). Any non-string entries in a formatter that doesn't equal one of these symbols is evaluated and replaced in place. This can be used to pass certain flags to the formatter process depending on the state of the current buffer. For example:
```
(push '(shfmt . ("beautysh"
                 "-filename" filepath
                 (when-let ((indent (bound-and-true-p sh-basic-offset)))
                   (list "--indent-size" (number-to-string indent)))
                 (when indent-tabs-mode "--tab")
                 "-"))
      apheleia-formatters)
```
  This adds an entry to apheleia-formatters for the beautysh formatter. The evaluated entries makes it so that the --tab flag is only passed to beautysh when the value of indent-tabs-mode is true. Similarly the indent-size flag is passed the exact value of the sh-basic-offset variable only when it is bound. Observe that one of these evaluations returns a list of flags whereas the other returns a single string. These are substituted into the command as you'd expect.
- You can also use Apheleia to format buffers that have no underlying files. In this case the value of file and filepath will be the name of the current buffer with any special characters for the file-system (such as * on windows) being stripped out.
  
  This is also how the extension for any temporary files apheleia might create will be determined. If you're using a formatter that determines the file-type from the extension you should name such buffers such that their suffixed with the extension. For example a buffer called *foo-bar.c* that has no associated file will have an implicit file-name of foo-bar.c and any temporary files will be suffixed with a .c extension.
- You can implement formatters as arbitrary Elisp functions which operate directly on a buffer, without needing to invoke an external command. This can be useful to integrate with e.g. language servers. See the docstring for more information on the expected interface for Elisp formatters.
apheleia-mode-alist: Alist mapping major modes and filename regexps to names of formatters to use in those modes and files. See the docstring for more information.
- You can use this variable to configure multiple formatters for the same buffer by setting the cdr of an entry to a list of formatters to run instead of a single formatter. For example you may want to run isort and black one after the other.
```
(setf (alist-get 'isort apheleia-formatters)
      '("isort" "--stdout" "-"))
(setf (alist-get 'python-mode apheleia-mode-alist)
      '(isort black))
```
  This will make apheleia run isort on the current buffer and then black on the result of isort and then use the final output to format the current buffer.
  
  Warning: At the moment there's no smart or configurable error handling in place. This means if one of the configured formatters fail (for example if isort isn't installed) then apheleia just doesn't format the buffer at all, even if black is installed.
  
  Warning: If a formatter uses file (rather than filepath or input or none of these keywords), it can't be chained after another formatter, because file implies that the formatter must read from the original file, not an intermediate temporary file. For this reason it's suggested to avoid the use of file in general.
apheleia-formatter: Optional buffer-local variable specifying the formatter to use in this buffer. Overrides apheleia-mode-alist. You can set this in a local variables list, or in .dir-locals.el (e.g. ((python-mode . ((apheleia-formatter . (isort black)))))), or in a custom hook of your own that sets the local variable conditionally.
apheleia-inhibit: Optional buffer-local variable, if set to non-nil then Apheleia does not turn on automatically even if apheleia-global-mode is on.

You can run M-x apheleia-mode to toggle automatic formatting on save in a single buffer, or M-x apheleia-global-mode to toggle the default setting for all buffers. Also, even if apheleia-mode is not enabled, you can run M-x apheleia-format-buffer to manually invoke the configured formatter for the current buffer. Running with a prefix argument will cause the command to prompt you for which formatter to run.

Apheleia does not currently support TRAMP, and is therefore automatically disabled for remote files.

If an error occurs while formatting, a message is displayed in the echo area. You can jump to the error by invoking M-x apheleia-goto-error, or manually switch to the log buffer mentioned in the message.

You can configure error reporting using the following user options:

apheleia-hide-log-buffers: By default, errors from formatters are put in buffers named like *apheleia-cmdname-log*. If you customize this user option to non-nil then a space is prepended to the names of these buffers, hiding them by default in switch-to-buffer (you must type a space to see them).
apheleia-log-only-errors: By default, only failed formatter runs are logged. If you customize this user option to nil then all runs are logged, along with whether or not they succeeded. This could be helpful in debugging.

The following user options are also available:

apheleia-post-format-hook: Normal hook run after Apheleia formats a buffer. Run if the formatting is successful, even when no changes are made to the buffer.
apheleia-max-alignment-size: The maximum number of characters that a diff region can have to be processed using Apheleia's dynamic programming algorithm for point alignment. This cannot be too big or Emacs will hang noticeably on large reformatting operations, since the DP algorithm is quadratic-time.
apheleia-mode-lighter: apheleia-mode lighter displayed in the mode-line. If you don't want to display it, use nil. Otherwise, its value must be a string.

Apheleia exposes some hooks for advanced customization:

apheleia-formatter-exited-hook: Abnormal hook which is run after a formatter has completely finished running for a buffer. Not run if the formatting was interrupted and no action was taken. Receives two arguments: the symbol for the formatter that was run (e.g. black, or it could be a list if multiple formatters were run in a chain), and a boolean for whether there was an error.
apheleia-inhibit-functions: List of functions to run before turning on Apheleia automatically from apheleia-global-mode. If one of these returns non-nil then apheleia-mode is not enabled in the buffer.
apheleia-skip-functions: List of functions to run before each Apheleia formatter invocation. If one of these returns non-nil then the formatter is not run, even if apheleia-mode is enabled.

Formatter configuration

There is no configuration interface in Apheleia for formatter behavior. The way to configure a formatter is by editing a standard config file that it reads (e.g. .prettierrc.json), or setting an environment variable that it reads, or by changing the entry in apheleia-formatters to customize the command-line arguments.

There is one exception to this, which is that Apheleia's default command-line arguments for the built-in formatters will automatically check Emacs' indentation options for the corresponding major mode, and pass that information to the formatter. This way, the indentation (tabs vs spaces, and how many) applied by the formatter will match what electric indentation in Emacs is doing, preventing a shuffle back and forth as you type.

This behavior can be disabled by setting apheleia-formatters-respect-indent-level to nil.

Troubleshooting

Try running your formatter outside of Emacs to verify it works there. Check what command-line options it is configured with in apheleia-formatters.

To debug internal bugs, race conditions, or performance issues, try setting apheleia-log-debug-info to non-nil and check the contents of *apheleia-debug-log*. It will have detailed trace information about most operations performed by Apheleia.

Known issues

process aphelieia-whatever no longer connected to pipe; closed it: This happens on older Emacs versions when formatting a buffer with size greater than 65,536 characters. There is no known workaround besides disabling apheleia-mode for the affected buffer, or upgrading to a more recent version of Emacs. See #20.

Contributing

Please see the contributor guide for my projects for general information, and the following sections for Apheleia-specific details.

There's also a wiki that could do with additions/clarity. Any improvement suggestions should be submitted as an issue.

Adding a formatter

I have done my best to make it straightforward to add a formatter. You just follow these steps:

Install your formatter on your machine so you can test.
Create an entry in apheleia-formatters with how to run it. (See the docstring of this variable for explanation about the available keywords.)
Add entries for the relevant major modes in apheleia-mode-alist.
See if it works for you!
Add a file at test/formatters/installers/yourformatter.bash which explains how to install the formatter on Ubuntu. This will be used by CI.
Test with make fmt-build FORMATTERS=yourformatter to do the installation, then make fmt-docker to start a shell with the formatter available. Verify it runs in this environment.
Add an example input (pre-formatting) and output (post-formatting) file at test/formatters/samplecode/yourformatter/in.whatever and test/formatters/samplecode/yourformatter/out.whatever.
Verify that the tests are passing, using make fmt-test FORMATTERS=yourformatter from inside the fmt-docker shell.
Submit a pull request, CI should now be passing!

Acknowledgements

I got the idea for using RCS patches to avoid moving point too much from prettier-js, although that package does not implement the dynamic programming algorithm which Apheleia uses to guarantee stability of point even within a formatted region.

Note that despite this inspiration, Apheleia is a clean-room implementation which is free of the copyright terms of prettier-js.

zkry/yaml.el

YAML parser in Elisp

yaml.el

yaml.el is a YAML parser written in Emacs List without any external dependencies. It provides an interface similar to the Emacs JSON parsing utility. The functions provided are as follows:

(yaml-parse-string string &rest args)

The following keyword args are accepted:

:object-type specifies the Lisp data structure to store parsed objects data in. It takes the following symbols:
- hash-table (default)
- alist
- plist
:object-key-type specifies how map keys should be handled. It takes the following symbols:
- string
- symbol (default) Use symbols as keys. If :object-type is plist, this becomes the same as keyword.
- keyword Always use keywords as keys.
:sequence-type specifies the Lisp data structure to store the parsed sequences in. It takes the following symbols:
- array (default)
- list
:null-object specifies the lisp object to use for nulls. Defaults to the symbol :null.
:false-object specifies the lisp object to use for false. Defaults to the symbol :false.

(yaml-encode object)

The function yaml-encode will encode a Lisp object to a YAML string.

Installation

Until this is published to MELPA you will need to use the code from this repo directly. You can put yaml.el in you load path directly or use a tool like use-package or straight.el.

Examples

(require 'yaml)

(yaml-parse-string "
recipe:
  ingredients:
  - milk
  - eggs
  - oil
  - flour
  duration: 10
  steps: null" :object-type 'alist
               :sequence-type 'array
               :null-object :empty)

;; => (("recipe" ("ingredients" . ["milk" "eggs" "oil" "flour"]) ("duration" . 10) ("steps" . :empty)))

(yaml-parse-string "
translations:
  one: бір
  two: екі
  three: үш")

;; => #s(hash-table ... data ("translations" #s(hash-table ...)))


(yaml-encode '("omitted" ((count . 3) (value . 10) (items ("ruby" "diamond"))) "omitted"))

;; => "
- omitted
- count: 3
  value: 10
  items:
    ruby: [diamond]
- omitted"

Caveats

Since this is implemented in Emacs Lisp performance is probably not the best. An alternative implementation using libyaml exists and can be found here.

If you have a very deeply nested YAML file and your max-lisp-eval-depth variable is set too low, these is a chance that you might hit the maximum Lisp eval depth limit. In the future I may work on changing the parsing algorithm to avoid this problem but in the meantime you can bump up the max-lisp-eval-depth variable in your config.

Development

You can run the tests by executing

$ ~/path/to/git-repo/yaml.el
$ emacs -batch -l ert -l yaml.el -l yaml-tests.el -f ert-run-tests-batch-and-exit

GitHub Emacs Lisp Weekly Trending Repositories

syl20bnr/spacemacs

Introduction

Features

Documentation

Getting Help

Prerequisites

Linux

macOS

Windows

Install

Default Install

Alternative Install Location

First Launch and Configuration

Spacemacs logo

Notes

Update

Upgrading from the deprecated master branch

Quotes

Contributions

Communities

Spacemacs Everywhere

License

Supporting Spacemacs

karthink/gptel

Media support

#+html:

https://github.com/user-attachments/assets/1fd947e1-226b-4be2-bc68-7b22b2e3215f

#+html:

Multi-LLM support demo:

https://github-production-user-asset-6210df.s3.amazonaws.com/8607532/278854024-ae1336c4-5b87-41f2-83e9-e415349d6a43.mp4

TODO Remove this when writing the manual.

Local Variables:

toc-org-max-depth: 4

eval: (and (fboundp 'toc-org-mode) (toc-org-mode 1))

End:

doomemacs/core

Doom Emacs

Table of Contents

Introduction

Features

Prerequisites

Install

Roadmap

Getting help

Contribute

Wilfred/elisp-refs

elisp-refs

Installation

Commands available

Semantic analysis

Limitations

Running tests

Performance

Alternative Projects

magit/forge

Wilfred/helpful

Helpful

Usage

Features

Source code

View Callers

Prettier Docstrings

Symbol Properties

Describe Commands

View Keymaps

Integrated Tooling

Aliases

Inspirations

License

org-roam/org-roam

Org-roam

Installation

Using package.el

Using straight.el

Using Doom Emacs

Without a package manager

Configuration

Getting Started

Getting Help

Upgrading from the deprecated `master` branch

Using `package.el`

Using `straight.el`

`vterm`

`vterm-other-window`

`vterm-copy-mode`

`vterm-clear-scrollback`

`vterm-shell`

`vterm-environment`

`vterm-term-environment-variable`

`vterm-kill-buffer-on-exit`

`vterm-module-cmake-args`

`vterm-copy-exclude-prompt`

`vterm-use-vterm-prompt-detection-method`

`vterm-enable-manipulate-selection-data-by-osc52`