GitHub Emacs Lisp Monthly Trending

doomemacs/doomemacs

An Emacs framework for the stubborn martian hacker

Doom Emacs

Install • Documentation • FAQ • Screenshots • Contribute

Introduction

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

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

Its design is guided by these mantras:

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

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

Features

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

Prerequisites

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

Warning

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

Important

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

Install

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

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

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

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

Roadmap

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

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

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

Getting help

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

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

Contribute

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

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

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.

NixOS/nix-mode

An Emacs major mode for editing Nix expressions.

nix-mode

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

Submodes

A quick list of what is provided.

nix-mode.el

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

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

or with use-package:

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

nix.el

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

nix-unpack - unpack source of a Nix attribute.

To use this just type:

M-x nix-unpack

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

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

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

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

Other useful functions for Lisp scripts are provided:

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

nix-flake.el

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

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

M-x nix-flake

You can also initialize a flake from a template:

M-x nix-flake-init

nix-repl.el

nix-repl.el has two purposes.

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

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

M-x nix-repl

nix-store.el

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

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

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

nix-prettify-mode.el

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

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

Origins

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

Other Emacs packages

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

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

manzaltu/claude-code-ide.el

Claude Code IDE integration for Emacs

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

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

Overview

Claude Code IDE for Emacs provides native integration with Claude Code CLI through the Model Context Protocol (MCP). Unlike simple terminal wrappers, this package creates a bidirectional bridge between Claude and Emacs, enabling Claude to understand and leverage Emacs' powerful features—from LSP and project management to custom Elisp functions. This transforms Claude into a true Emacs-aware AI assistant that works within your existing workflow and can interact with your entire Emacs ecosystem.

** Features

Automatic project detection and session management
Terminal integration with full color support using =vterm= or =eat=
MCP protocol implementation for IDE integration
Tool support for file operations, editor state, and workspace info
Extensible MCP tools server for accessing Emacs commands (xrefs, tree-sitter, project info, e.g.)
Diagnostic integration with Flycheck and Flymake
Advanced diff view with ediff integration (modify suggestions before applying)
Tab-bar support for proper context switching
Selection and buffer tracking for better context awareness

** Emacs Tool Integration

This package enables Claude Code to leverage the full power of Emacs through MCP tools integration. Claude can directly access and utilize Emacs capabilities including:

Language Server Protocol (LSP) integration through xref commands for intelligent code navigation (eglot, lsp-mode and others)
Tree-sitter for syntax tree analysis and understanding code structure at the AST level
Imenu for structured symbol listing and navigation within files
Project integration for project-aware operations
Any Emacs command or function can be exposed as an MCP tool, allowing Claude to:
- Perform project-wide searches and refactoring
- Access specialized modes and their features
- Execute custom Elisp functions tailored to your workflow

This deep integration means Claude Code understands your project context and can leverage Emacs' extensive ecosystem to provide more intelligent and context-aware assistance.

** Screenshots

*** Active File Awareness #+CAPTION: Claude Code automatically knows which file you're currently viewing in Emacs #+html: #+html:

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

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

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

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

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

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

Automatically mention and reference selected text in Claude conversations

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

Resume previous Claude Code conversations with the --resume flag

Installation

** Prerequisites

Emacs 28.1 or higher
Claude Code CLI installed and available in PATH
=vterm= or =eat= package (for terminal support)

** Installing Claude Code CLI

Follow the installation instructions at [[https://docs.anthropic.com/en/docs/claude-code][Claude Code Documentation]].

** Installing the Emacs Package

Currently, this package is in early development.

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

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

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

#+begin_src emacs-lisp (use-package claude-code-ide :straight (:type git :host github :repo "manzaltu/claude-code-ide.el") :bind ("C-c C-'" . claude-code-ide-menu) ; Set your favorite keybinding :config (claude-code-ide-emacs-tools-setup)) ; Optionally enable Emacs MCP tools #+end_src

*** Doom Emacs

In =packages.el=:

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

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

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

Usage

** Basic Commands

The easiest way to interact with Claude Code IDE is through the transient menu interface, which provides visual access to all available commands. Simply run =M-x claude-code-ide-menu= to open the interactive menu.

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

** Multi-Project Support

Claude Code IDE automatically detects your project using Emacs' built-in =project.el=. Each project gets its own Claude Code instance with a unique buffer name like =claude-code[project-name]=.

You can run multiple Claude Code instances simultaneously for different projects. Use =claude-code-ide-list-sessions= to see all active sessions and switch between them.

** Window Management

Running =claude-code-ide= when a session is already active will toggle the window visibility
The window can be closed with standard Emacs window commands (=C-x 0=) without stopping Claude
Use =claude-code-ide-toggle-recent= to toggle the most recent Claude window from anywhere, regardless of your current project context. This is useful when you're outside a project directory but want to quickly hide/show Claude

** Diff Viewing with Ediff

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

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

*** How to use ediff:

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

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

** Configuration

*** Configuration Variables

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

*** Side Window Configuration

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

#+begin_src emacs-lisp ;; Open Claude on the left side (setq claude-code-ide-window-side 'left)

;; Open Claude at the bottom with custom height (setq claude-code-ide-window-side 'bottom claude-code-ide-window-height 30)

;; Open Claude on the right with custom width (setq claude-code-ide-window-side 'right claude-code-ide-window-width 100)

;; Don't automatically focus the Claude window (setq claude-code-ide-focus-on-open nil)

;; Keep focus on ediff control window when opening diffs (setq claude-code-ide-focus-claude-after-ediff nil)

;; Hide Claude window during ediff for more screen space (setq claude-code-ide-show-claude-window-in-ediff nil)

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

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

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

*** Terminal Backend Configuration

Claude Code IDE supports both =vterm= and =eat= as terminal backends. By default, it uses =vterm=, but you can switch to =eat= if preferred:

#+begin_src emacs-lisp ;; Use eat instead of vterm (setq claude-code-ide-terminal-backend 'eat)

;; Or switch back to vterm (default) (setq claude-code-ide-terminal-backend 'vterm) #+end_src

The =eat= backend is a pure Elisp terminal emulator that may work better in some environments where =vterm= compilation is problematic. Both backends provide full terminal functionality including color support and special key handling.

**** Flicker-Free Renderer (Experimental)

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

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

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

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

**** vterm Rendering Optimization

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

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

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

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

**** Terminal Initialization Delay

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

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

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

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

**** Terminal Keybindings

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

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

These keybindings are automatically set up for both =vterm= and =eat= backends and only apply within Claude Code terminal buffers.

**** Terminal Reflow Glitch Prevention (Temporary)

Claude Code IDE includes a temporary workaround for a known Claude Code bug ([[https://github.com/anthropics/claude-code/issues/1422][#1422]]) where terminal reflows during window resizes can cause uncontrollable scrolling. This workaround is enabled by default but can be disabled if needed:

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

The workaround will be removed once the upstream bug is fixed.

*** Diagnostics Configuration

Claude Code IDE supports both Flycheck and Flymake for code diagnostics. By default, it will automatically detect which one is active:

#+begin_src emacs-lisp ;; Let Claude Code automatically detect the active diagnostics backend (setq claude-code-ide-diagnostics-backend 'auto) ; default

;; Or force a specific backend (setq claude-code-ide-diagnostics-backend 'flycheck) (setq claude-code-ide-diagnostics-backend 'flymake) #+end_src

*** Elisp Code Execution

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

To disable it:

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

*** Custom Buffer Naming

You can customize how Claude Code buffers are named:

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

*** Custom CLI Flags

You can pass additional flags to the Claude Code CLI:

#+begin_src emacs-lisp ;; Use a specific model (setq claude-code-ide-cli-extra-flags "--model opus")

;; Pass multiple flags (setq claude-code-ide-cli-extra-flags "--model opus --no-cache")

;; Flags are added to all Claude Code sessions #+end_src

Note: These flags are appended to the Claude command after any built-in flags like =-d= (debug) or =-r= (resume).

*** Custom System Prompt

You can append a custom system prompt to Claude's default prompt, allowing you to customize Claude's behavior for specific projects or contexts:

#+begin_src emacs-lisp ;; Set a custom system prompt (setq claude-code-ide-system-prompt "You are an expert in Elisp and Emacs development.")

;; Or configure it per-project using dir-locals.el ;; In .dir-locals.el: ((nil . ((claude-code-ide-system-prompt . "Focus on functional programming patterns and avoid mutations."))))

;; Set via the transient menu: M-x claude-code-ide-menu → Configuration → Set system prompt #+end_src

When set, this adds the =--append-system-prompt= flag to the Claude command. Set to =nil= to disable (default).

*** Debugging

**** Claude CLI Debug Mode

To enable debug mode for Claude Code CLI (passes the =-d= flag):

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

**** Emacs Debug Logging

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

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

Then view debug logs with:

=M-x claude-code-ide-show-debug= - Show the debug buffer
=M-x claude-code-ide-clear-debug= - Clear the debug buffer

The debug buffer shows:

WebSocket connection events
All JSON-RPC messages (requests/responses)
Error messages and diagnostics
General debug information with session context

** Multiple Claude Code Instances on One Project

Using git worktrees is the recommended way for running multiple Claude Code instances on different branches of the same project. This allows you to develop features or fix bugs in parallel:

#+begin_src bash

Create a new worktree for a feature branch

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

#+begin_src elisp ;; Start Claude Code in the main project find-file /path/to/myproject M-x claude-code-ide

;; Start another Claude Code instance in the worktree find-file /path/to/myproject-worktree M-x claude-code-ide #+end_src

Each worktree is treated as a separate project by =project.el=, allowing you to have independent Claude Code sessions with their own buffers (e.g., =claude-code[myproject]= and =claude-code[myproject-worktree]=).

** Emacs MCP Tools

Claude Code IDE includes built-in MCP tools that expose Emacs functionality to Claude, enabling powerful code navigation and analysis capabilities:

*** Built-in Tools

=xref-find-references= - Find all references to a symbol throughout the project
=xref-find-apropos= - Find symbols matching a pattern across the entire project
=treesit-info= - Get tree-sitter syntax tree information for deep code structure analysis
=imenu-list-symbols= - List all symbols (functions, classes, variables) in a file using imenu
=project-info= - Get information about the current project (directory, files, etc.)

*** Enabling MCP Tools

To enable these tools, add to your configuration:

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

Once enabled, Claude can use these tools to navigate your codebase. For example:

"Find the definition of function foo"
"Show me all places where this variable is used"
"What type of AST node is under the cursor?"
"Analyze the parse tree of this entire file"
"List all functions and variables in this file"
"How many files are in this project?"

** Creating Custom MCP Tools

You can expose your own Emacs functions to Claude through the MCP tools system. This allows Claude to interact with specialized Emacs features, custom commands, or domain-specific functionality.

*** Tool Definition Format

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

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

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

*** Context-Aware Tool Example

#+begin_src emacs-lisp ;; Define a context-aware function that operates in the session's project (defun my-project-grep (pattern) "Search for PATTERN in the current session's project." (claude-code-ide-mcp-server-with-session-context nil ;; This executes with the session's project directory as default-directory (let* ((project-dir default-directory) (results (shell-command-to-string (format "rg -n '%s' %s" pattern project-dir)))) results)))

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

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

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

License

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

Trademark Notice

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

Related Projects

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

rust-lang/rust-mode

Emacs configuration for Rust

rust-mode

Table of Contents

rust-mode

Introduction

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

This mode provides:

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

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

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

Known issues

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

Installation

Melpa

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

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

Now you can install rust-mode with:

M-x package-install rust-mode

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

(require 'rust-mode)

NonGNU ELPA

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

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

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

Manual installation

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

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

Feature guide

Indentation

Commands like TAB should indent correctly.

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

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

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

Code formatting

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

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

(setq rust-format-on-save t)

Prettifying

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

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

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

Running / testing / compiling code

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

By default these are bound to:

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

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

Clippy

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

Easy insertion of dbg!

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

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

More commands

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

tree-sitter

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

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

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

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

LSP

eglot

A lightweight lsp client.

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

lsp-mode

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

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

Auto-completion

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

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

Other recommended packages

flycheck

flycheck allows highlighting compile errors and Clippy lints inline.

cargo.el

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

cargo-mode

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

rustic

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

Optional features

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

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

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

Customization

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

For package maintainers

Tests

Run elisp tests:

make test

Contributing

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

progfolio/elpaca

An elisp package manager

Elpaca: An Elisp Package Manager

"Chews data, spits packages."

Elpaca is an elisp package manager. It allows users to find, install, update, and remove third-party packages for Emacs. It is a replacement for the built-in Emacs package manager, package.el.

Elpaca:

Installs packages asynchronously, in parallel for fast, non-blocking installations.
Includes a flexible UI for finding and operating on packages.
Downloads packages from their sources for convenient elisp development.
Supports thousands of elisp packages out of the box (MELPA, NonGNU/GNU ELPA, Org/org-contrib).
Makes it easy for users to create their own ELPAs.

See the manual and wiki for in-depth information on Elpaca usage, customization, and development. Users who wish to experiment with Elpaca may find the example init.el and early-init.el files useful.

Video Tour

Installation

Requirements

Elpaca requires:

Emacs >= 27.1
git (minimum version TBD)

Installer

To install Elpaca, add the following elisp to your init.el. It must come before any calls to other Elpaca functions/macros. This will clone Elpaca into your user-emacs-directory under the elpaca subdirectory. It then builds and activates Elpaca.

(defvar elpaca-installer-version 0.12)
(defvar elpaca-directory (expand-file-name "elpaca/" user-emacs-directory))
(defvar elpaca-builds-directory (expand-file-name "builds/" elpaca-directory))
(defvar elpaca-sources-directory (expand-file-name "sources/" elpaca-directory))
(defvar elpaca-order '(elpaca :repo "https://github.com/progfolio/elpaca.git"
                              :ref nil :depth 1 :inherit ignore
                              :files (:defaults "elpaca-test.el" (:exclude "extensions"))
                              :build (:not elpaca-activate)))
(let* ((repo  (expand-file-name "elpaca/" elpaca-sources-directory))
       (build (expand-file-name "elpaca/" elpaca-builds-directory))
       (order (cdr elpaca-order))
       (default-directory repo))
  (add-to-list 'load-path (if (file-exists-p build) build repo))
  (unless (file-exists-p repo)
    (make-directory repo t)
    (when (<= emacs-major-version 28) (require 'subr-x))
    (condition-case-unless-debug err
        (if-let* ((buffer (pop-to-buffer-same-window "*elpaca-bootstrap*"))
                  ((zerop (apply #'call-process `("git" nil ,buffer t "clone"
                                                  ,@(when-let* ((depth (plist-get order :depth)))
                                                      (list (format "--depth=%d" depth) "--no-single-branch"))
                                                  ,(plist-get order :repo) ,repo))))
                  ((zerop (call-process "git" nil buffer t "checkout"
                                        (or (plist-get order :ref) "--"))))
                  (emacs (concat invocation-directory invocation-name))
                  ((zerop (call-process emacs nil buffer nil "-Q" "-L" "." "--batch"
                                        "--eval" "(byte-recompile-directory \".\" 0 'force)")))
                  ((require 'elpaca))
                  ((elpaca-generate-autoloads "elpaca" repo)))
            (progn (message "%s" (buffer-string)) (kill-buffer buffer))
          (error "%s" (with-current-buffer buffer (buffer-string))))
      ((error) (warn "%s" err) (delete-directory repo 'recursive))))
  (unless (require 'elpaca-autoloads nil t)
    (require 'elpaca)
    (elpaca-generate-autoloads "elpaca" repo)
    (let ((load-source-file-function nil)) (load "./elpaca-autoloads"))))
(add-hook 'after-init-hook #'elpaca-process-queues)
(elpaca `(,@elpaca-order))

Windows users must be able to create symlinks¹, or enable elpaca-no-symlink-mode

;; Uncomment for systems which cannot create symlinks:
;; (elpaca-no-symlink-mode)

You'll also want to disable package.el in your early-init file²:

(setq package-enable-at-startup nil)

And remove anything related to package.el in your init file. e.g. calls to (package-activate-all).

Quick Start

Operation	UI (keys apply in elpaca-ui-mode)	completing-read interface commands
Finding Packages	`g` `m` (or `M-x` `elpaca-manager`)	`elpaca-info`
Trying Packages (for current session)	`i` `x`	`elpaca-try`
Fetching Package Updates	`f` `x`	`elpaca-fetch` or `elpaca-fetch-all`
Merging Updates	`m` `x`	`elpaca-merge` or `elpaca-merge-all`
Updating Packages^*	`p` `x`	`elpaca-update` or `elpaca-update-all`
Rebuilding Packages	`r` `x`	`elpaca-rebuild`
Deleting Packages	`d` `x`	`elpaca-delete`
View Package Logs	`g` `l`	`elpaca-log`
Visit Package Source Directory	`v`	`elpaca-visit`
Visit Package Build Directory	`C-u` `v`	`C-u M-x` `elpaca-visit`
Browse Package Website	`b`	`elpaca-browse`

* Update is an alias for "pull". It's encouraged to fetch, review, and then merge package updates rather than pulling.

Packages installed via the above commands are not loaded on subsequent Emacs sessions (after restarting). To install and load packages persistently (across Emacs restarts), use the elpaca macro in your init file after the installer. (installer)

For example:

;; Install a package via the elpaca macro
;; See the "recipes" section of the manual for more details.

;; (elpaca example-package)

;; Install use-package support
(elpaca elpaca-use-package
  ;; Enable use-package :ensure support for Elpaca.
  (elpaca-use-package-mode))

;;When installing a package used in the init file itself,
;;e.g. a package which adds a use-package key word,
;;use the :wait recipe keyword to block until that package is installed/configured.
;;For example:
;;(use-package general :ensure (:wait t) :demand t)

;; Expands to: (elpaca evil (use-package evil :demand t))
(use-package evil :ensure t :demand t)

;;Turns off elpaca-use-package-mode current declaration
;;Note this will cause evaluate the declaration immediately. It is not deferred.
;;Useful for configuring built-in emacs features.
(use-package emacs :ensure nil :config (setq ring-bell-function #'ignore))

IMPORTANT:

Elpaca installs and activates packages asynchronously. Elpaca processes its package queues after Emacs reads the init file.³ Consider the following example:

(elpaca package-a (message "First")) ; Queue First
(message "Second") ; Second messaged
(elpaca package-b (message "Third")) ; Queue Third
(elpaca-process-queues) ; Process queue: First messaged, Third messaged.

"Second" will be message before "First" and "Third". If a form should be evaluated after a package is installed/activated, put it in that package declaration's BODY. Declaration BODY forms are evaluated synchronously in declared order. e.g.

(elpaca package-a (message "First") (message "Second"))  ; Queue First, Second
(elpaca package-b (message "Third"))  ; Queue Third
(elpaca-process-queues) ; Process queue: First, Second, then Third messaged.

Add configuration which relies on after-init-hook, emacs-startup-hook, etc to elpaca-after-init-hook so it runs after Elpaca has activated all queued packages. This includes loading of saved customizations. e.g.

(setq custom-file (expand-file-name "customs.el" user-emacs-directory))
(add-hook 'elpaca-after-init-hook (lambda () (load custom-file 'noerror)))

Footnotes

¹ windows symlink guide

² early-init file

³ This is so Elpaca can build a proper dependency tree. It ensures packages the user explicitly requests are not preempted by dependencies of other packages.

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]]
- [[#chatgpt][ChatGPT]]
- [[#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]]
  - [[#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.4 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/doomemacs/tree/master/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 | |----------------------+----------------------------| | ChatGPT | [[ https://platform.openai.com/account/api-keys][API key]] | | 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:

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

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

**** 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 '(llama-3.3-70b-versatile llama-3.1-8b-instant llama3-70b-8192 llama3-8b-8192 mixtral-8x7b-32768 gemma-7b-it)) #+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 easily 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 '(llama-3.1-70b-versatile llama-3.1-8b-instant llama3-8b-8192 mixtral-8x7b-32768 gemma-7b-it))) #+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 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: Unless ~AWS_BEARER_TOKEN_BEDROCK~ token is used, the Bedrock backend needs curl >= 8.9 in order for the sigv4 signing to work properly, https://github.com/curl/curl/issues/11794

An error will be signalled if ~gptel-use-curl~ is ~NIL~.

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/, 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. | |----------------------------+-----------------------------------------------------------------------------------------|

|------------------+-------------------------------------------------------------------------------------------| | GitHub Copilot | | |------------------+-------------------------------------------------------------------------------------------| | =gptel-gh-login= | Authenticate with GitHub Copilot. (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, directives 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 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-directives= | Alist of system directives, 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:

emacs-mirror/emacs

Mirror of GNU Emacs

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

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

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

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

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

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

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

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

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

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

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

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

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

There are several subdirectories:

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

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

NOTE ON COPYRIGHT YEARS

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

This file is part of GNU Emacs.

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

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

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

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 .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!

xenodium/agent-shell

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

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

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

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

[[file:agent-shell.png]]

This project needs your funding

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

Thank you!

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

agent-shell

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

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

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

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

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

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

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

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

News

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

Related projects

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

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

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

Articles

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

Icons

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

Setup

** External dependencies

*** Claude Agent SDK

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

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

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

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

*** Codex

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

*** Gemini CLI

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

*** Goose

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

*** Cursor

For Cursor agent, install with:

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

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

*** Kimi Code CLI

For Kimi Code CLI, install with:

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

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

*** Kiro CLI

For Kiro CLI, install with:

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

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

*** Qwen Code

For Qwen Code, install with:

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

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

*** Auggie

For Auggie CLI, install with:

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

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

For Mistral Vibe, install with:

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

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

*** Factory Droid

For Factory Droid, install Droid:

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

See https://factory.ai for details.

*** Pi

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

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

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

** Installation

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

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

You can install via:

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

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

*** Doom Emacs

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

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

Run =doom sync= and restart.

Include =require= before configuration:

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

** Configuration

Configure authentication for the agent providers you want to use.

*** Environment variables

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

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

**** Inheriting environment variables

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

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

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

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

**** Loading environment variables from files

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

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

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

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

*** Anthropic Claude

For login-based authentication (default):

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

For API key authentication:

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

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

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

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

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

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

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

*** Google Gemini

For login-based authentication (default):

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

For API key authentication:

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

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

For Vertex AI authentication:

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

*** OpenAI Codex

For login-based authentication (default):

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

For API key authentication:

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

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

*** Goose

For OpenAI API key authentication:

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

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

*** Qwen Code

For OAuth login-based authentication:

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

*** Auggie

For login-based authentication (default):

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

For no authentication (when using alternative authentication methods):

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

*** Mistral Vibe

For API key authentication:

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

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

*** Customizing Available Agents

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

** Usage

*** Quick Start

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

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

*** Specific Agent Commands

Start a specific agent shell session directly:

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

*** Setting a default agent for all new shells

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

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

*** Configuring MCP servers

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

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

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

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

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

*** Static command list

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

*** Function-based configuration

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

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

*** Per-session containers

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

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

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

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

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

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

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

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

*** Data storage location

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

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

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

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

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

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

*** Screenshots from clipboard

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

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

*** Inhibiting minor modes during file writes

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

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

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

** Key bindings

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

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

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

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

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

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

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

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

#+end_src

Customizations

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

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

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

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

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

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

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

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

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

[[file:slash-commands.png]]

** Can you add support for another agent?

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

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

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

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

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

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

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

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

[[file:traffic.png]]

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

** Where should I file bug or feature request?

*** Agent issues or feature requests

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

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

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

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

*** Not sure where to file an issue?

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

Contributing

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

Contributors

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

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

qjcg/awesome-typst

Awesome Typst Links

English | 简体中文

Awesome Typst

Curated collection of useful links for Typst users.

Contributions are welcome!

Official Project Links

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

Typst Community Links

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

Integrations & Tools

Browser Extensions

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

Chatbots

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

CI/CD

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

CLI Tools

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

Editors

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

Editor Integrations

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

Online Tools

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

Office

pptypst - Bring the power of Typst to PowerPoint

Programming

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

Typst As A Service

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

Templates & Libraries

Official

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

General

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

Assignments

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

CV

Examples

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

Templates

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

Calendar / Timetable

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

Footnotes & Endnotes

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

Formatting

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

Graphics

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

Letters

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

Linguistics

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

Music

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

Plotting

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

Posters

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

Science, Technology, Engineering & Math (STEM)

Chemistry

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

Engineering

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

Mathematics

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

Physics

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

Conferences

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

Journals

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

Grants/Proposals

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

Scripting

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

Slides

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

tumashu/posframe

Pop a posframe (just a child-frame) at point, posframe is a **GNU ELPA** package!

Created 2021-06-01 Tue 10:41

#+TITLE: Pop a posframe (just a frame) at point #+AUTHOR: Feng Shu

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

What is posframe? Posframe can pop up a frame at point, this posframe is a child-frame connected to its root window's buffer.

The main advantages are:

It is fast enough for daily usage 😃
It works well with CJK languages.

NOTE:

For MacOS users, posframe needs Emacs version >= 26.0.91
GNOME users with GTK3 builds need Emacs 27 or later. See variable `posframe-gtk-resize-child-frames' which auto-detects this configuration.

More details:
1. [[https://git.savannah.gnu.org/cgit/emacs.git/commit/?h=emacs-27&id=c49d379f17bcb0ce82604def2eaa04bda00bd5ec][Fix some problems with moving and resizing child frames]]
2. [[https://lists.gnu.org/archive/html/emacs-devel/2020-01/msg00343.html][Emacs's set-frame-size can not work well with gnome-shell?]]

[[file:./snapshots/posframe-1.png]]

Installation

#+begin_example (require 'posframe) #+end_example

Usage

** Create a posframe

*** Simple way #+begin_example (when (posframe-workable-p) (posframe-show " my-posframe-buffer" :string "This is a test" :position (point))) #+end_example

*** Advanced way #+begin_example (defvar my-posframe-buffer " my-posframe-buffer")

(with-current-buffer (get-buffer-create my-posframe-buffer) (erase-buffer) (insert "Hello world"))

(when (posframe-workable-p) (posframe-show my-posframe-buffer :position (point))) #+end_example

*** Arguments

#+begin_example C-h f posframe-show #+end_example

** Hide a posframe #+begin_example (posframe-hide " my-posframe-buffer") #+end_example

** Hide all posframes #+begin_example M-x posframe-hide-all #+end_example

** Delete a posframe

Delete posframe and its buffer #+begin_example (posframe-delete " my-posframe-buffer") #+end_example
Only delete the frame #+begin_example (posframe-delete-frame " my-posframe-buffer") #+end_example ** Delete all posframes #+begin_example M-x posframe-delete-all #+end_example

Note: this command will delete all posframe buffers. You probably shouldn't use it if you are sharing a buffer between posframe and other packages.

** posframe-arghandler

posframe-arghandler feature has been removed from posframe-1.1, user can use advice feature instead.

** Mouse banish Default setting will work well in most case, but for EXWM user, suggest use the below config.

#+begin_src emacs-lisp (setq posframe-mouse-banish-function #'posframe-mouse-banish-simple) #+end_src

dominikh/go-mode.el

Emacs mode for the Go programming language

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

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

Features

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

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

Installation

MELPA

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

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

Manual

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

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

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

Other extensions

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

Gopls integration

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

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

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

Syntax/error checking

There are two ways of using flymake with Go:

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

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

Auto completion

For auto completion, take a look at gocode.

eldoc

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

Snippets

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

Integration with errcheck

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

Stability

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

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

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