GitHub Emacs Lisp Daily Trending

dakra/ghostel

Terminal emulator powered by libghostty

Ghostel

Ghostel is a terminal emulator for Emacs powered by libghostty-vt, the VT engine behind the Ghostty terminal.

It aims to be featureful, fast, robust and correct.

Ghostel's features include synchronized output, true color, the Kitty keyboard and graphics protocols, hyperlinks, desktop notifications, progress reports and a lot more.

Shell integration (directory tracking, prompt navigation) all works out of the box for bash, zsh, fish and nushell.

Check the documentation for a full list of features or how it compares to vterm or eat.



`btop`: true color and full TUI rendering	`yazi`: inline image preview via the Kitty graphics

Quick Start

Requirements: Emacs 28.1+ with dynamic module support, on macOS, Linux, FreeBSD, or native Windows. The native module is a prebuilt binary that auto-downloads on first use. No toolchain or build step required.

Windows release binaries are built for common native Windows Emacs builds on x86_64 and aarch64. Releases include optional ConPTY support files from Microsoft's redistributable console runtime, which can improve latency and correctness compared with older inbox Windows ConPTY versions.

Install from MELPA:

(use-package ghostel
  :ensure t)

Then M-x ghostel to open a terminal. That's it.

See installation for different installation instructions.

A fuller example

This example shows more features and how you can add custom keybindings or custom functions that interact with the Ghostel buffer.

(use-package ghostel
  :bind (("C-x m" . ghostel)
         :map ghostel-semi-char-mode-map
         ("C-s"  . consult-line)
         ("C-k"  . my/ghostel-send-C-k-and-kill)
         ;; I'm used to go up/down the shell history with M-n/p from eshell
         ;; Simulate this behavior in ghostel by sending C-p and C-n
         ("M-p" . (lambda () (interactive) (ghostel-send-key "p" "ctrl")))
         ("M-n" . (lambda () (interactive) (ghostel-send-key "n" "ctrl")))
         :map project-prefix-map
         ("m" . ghostel-project)
         ("M" . ghostel-project-list-buffers))
  :config
  (defun my/ghostel-send-C-k-and-kill ()
    "Send `C-k' to ghostel.
Like normal Emacs `C-k'.  Kill to end of line and put content in kill-ring."
    (interactive)
    (kill-ring-save (point) (line-end-position))
    (ghostel-send-key "k" "ctrl"))

  (add-to-list 'project-switch-commands '(ghostel-project "Ghostel") t)
  (add-to-list 'project-switch-commands '(ghostel-project-list-buffers "Ghostel buffers") t)
  (add-to-list 'ghostel-eval-cmds '("magit-status-setup-buffer" magit-status-setup-buffer)))

Now you can C-x m to open a Ghostel buffer, or you can switch to a project (C-x p p) and then press m to open a Ghostel buffer in this project. In a project you can press C-x p M to get a list of Ghostel buffers running in the current project that you can switch to.

Extensions

These ship with the Ghostel package, no separate install necessary. Just enable what you want:

Make eshell-visual-commands run in a Ghostel buffer.

(use-package ghostel-eshell
  :hook (eshell-load . ghostel-eshell-visual-command-mode))

Run all compile commands in a Ghostel buffer.

(use-package ghostel-compile
  :hook (after-init . ghostel-compile-global-mode))

Replace comint's built-in ansi-color-process-output with Ghostel's VT parser.

(use-package ghostel-comint
  :hook (after-init . ghostel-comint-global-mode))

If you use an Emacs Lisp input method (e.g. Korean Hangul), add Ghostel support:

(use-package ghostel-ime
  :hook (ghostel-mode . ghostel-ime-mode))

Evil

If you're an evil user you can install the evil-ghostel extension:

(use-package evil-ghostel
  :after (ghostel evil)
  :hook (ghostel-mode . evil-ghostel-mode))

Shell integration

Directory tracking and prompt navigation are on by default for local bash, zsh, fish or nushell sessions. See shell integration for tramp support and more.

To call Emacs functions from your shell you have to add them to the ghostel-eval-cmds whitelist and then add something like this to your bashrc:

if [[ "$INSIDE_EMACS" = 'ghostel' ]]; then
    # Open a file in Emacs from the terminal
    e()   { ghostel_cmd find-file-other-window "$@"; }

    # Open dired in another window
    dow() { ghostel_cmd dired-other-window "$@"; }

    # Open magit for the current directory
    gst() { ghostel_cmd magit-status-setup-buffer "$(pwd)"; }
fi

Input modes

Ghostel offers five eat.el-style input modes.

The default is semi-char mode (C-c C-j), which forwards almost all keys to the terminal besides a few exceptions (e.g. M-x, C-c).

In char mode (C-c M-d), all keys go to the terminal. M-RET to exit.

line mode (C-c C-l) is similar to M-x shell in that Ghostel is like a normal Emacs buffer and no key gets sent to the terminal. Only after you finish typing a line and press enter, the whole line is sent at once.

emacs (C-c C-e) and copy mode (C-c C-t) give you normal Emacs navigation over the read-only terminal buffer so you can look around and copy text. The difference between the two is that copy mode freezes the terminal, so if you have continuous output nothing "scrolls away" while you try to select something. emacs mode is live so new output keeps coming in while you scroll/select.

Those read-only modes have by default ghostel-readonly-fast-exit set to true, which automatically exits those modes on most keys that you expect to be sent to the terminal. This makes for seamless transitions, e.g. you have some output running and see something you want to copy, you press C-c C-t and enter copy-mode navigate like in a normal Emacs buffer and select your text. When you copy something or type any character you're automatically back in your normal ghostel terminal session. Similarly, some actions automatically activate copy mode, like selecting with the mouse, navigating to hyperlinks (C-c C-p), activating the mark. In copy mode, mouse selection remains normal Emacs selection even if the terminal app enabled mouse tracking.

Documentation

doomemacs/core

An Emacs framework for the stubborn martian hacker

Doom Emacs

Install • Documentation • FAQ • Screenshots • Contribute

Introduction

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

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

Its design is guided by these mantras:

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

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

Features

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

Prerequisites

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

Warning

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

Important

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

Install

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

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

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

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

Roadmap

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

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

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

Getting help

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

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

Contribute

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

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

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

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.

karthink/gptel

A simple, extensible LLM client for Emacs

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

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

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

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

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

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

In-place usage

#+html:

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

Tool use

#+html:

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

#+html:

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

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

Media support

#+html:

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

#+html:

Multi-LLM support demo:

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

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

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

** Contents :toc:

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

** Installation

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

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

#+html:

*** Straight #+html:

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

#+html:

*** Manual #+html:

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

#+html:

*** Doom Emacs #+html:

In =packages.el=

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

In =config.el=

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

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

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

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

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

#+html:

*** Spacemacs #+html:

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

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

** Setup

gptel supports a number of LLM providers:

#+html:

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

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

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

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

*** Other LLM backends

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

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

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

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

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

#+html:

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

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

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

#+html:

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

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

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

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

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

If no environment variable is provided:

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

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

#+html:

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

Includes access to OpenAI Codex models. Register a backend with

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

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

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

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

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

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

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

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

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

#+html:

**** Azure #+html:

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

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

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

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

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

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

#+html:

**** GPT4All #+html:

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

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

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

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

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

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

#+html:

**** Ollama #+html:

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

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

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

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

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

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

#+html:

**** Open WebUI #+html:

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

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

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

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

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

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

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

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

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

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

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

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

#+html:

**** Gemini #+html:

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

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

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

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

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

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

#+html:

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

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

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

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

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

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

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

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

#+html:

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

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

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

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

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

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

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

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

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

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

#+html:

**** together.ai #+html:

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

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

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

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

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

#+html:

**** Anyscale #+html:

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

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

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

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

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

#+html:

**** Perplexity #+html:

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

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

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

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

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

#+html:

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

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

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

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

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

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

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

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

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

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

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

#+html:

**** Groq #+html:

#+begin_src emacs-lisp ;; Groq offers an OpenAI compatible API (gptel-make-openai "Groq" ;Any name you want :host "api.groq.com" :endpoint "/openai/v1/chat/completions" :stream t :key "your-api-key" ;can be a function that returns the key :models '(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 also log in manually with =M-x gptel-gh-login=.)

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

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

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

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

#+html:

**** AWS Bedrock #+html:

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

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

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

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

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

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

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

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

#+html:

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

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

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

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

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

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

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

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

#+html:

** Usage

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

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

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

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

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

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

*** In any buffer:

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

#+html:

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

#+html:

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

*** In a dedicated chat buffer:

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

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

#+html:

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

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

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

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

#+html:

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

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

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

#+html:

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

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

#+html:

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

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

Support for custom Org link types is planned.

#+html:

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

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

#+html:

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

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

TODO Remove this when writing the manual.

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

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

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

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

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

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

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

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

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

*** Handle "reasoning" content

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

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

*** Tool use

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

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

#+html:

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

To use tools in gptel, you need

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

#+html:

**** Defining gptel tools #+html:

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

To read the contents of an Emacs buffer:

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

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

To create a text file:

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

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

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

#+html:

**** Selecting tools #+html:

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

#+html:

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

Alternatively, you can add/remove tools via

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

#+html:

**** LLM tool collections #+html:

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

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

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

#+html:

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

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

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

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

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

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

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

#+html:

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

#+html:

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

Here's an example of using these tools:

#+html:

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

#+html:

*** Rewrite, refactor or fill in a region

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

#+html:

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

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

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

#+html:

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

Acting on the LLM response:

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

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

#+html:

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

#+html:

*** Extra Org mode conveniences

gptel offers a few extra conveniences in Org mode.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#+html:

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

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

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

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

#+html:

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

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

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

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

#+html:

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

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

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

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

#+html:

*** Transient menu behavior #+html:

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

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

#+html:

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

#+html:

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

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

#+html:

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

#+html:

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

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

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

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

#+html:

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

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

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

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

#+html:

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

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

#+html:

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

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

Two solutions:

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

#+html:

*** Miscellaneous #+html:

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

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

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

#+html:

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

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

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

#+html:

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

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

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

#+html:

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

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

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

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

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

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

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

#+html:

*** Option presets

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

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

#+html: #+html:

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

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

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

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

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

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

**** Applying presets to requests automatically

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

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

The following query is sent with this preset applied:

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

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

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

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

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

** Alternatives

Other LLM clients for Emacs include

Libraries:

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

Chat clients:

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

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

Coding agents:

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

Completion at point:

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

*** Packages using gptel

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

Lookup helpers: Calling gptel quickly for one-off interactions

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

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

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

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

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

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

Text completion

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

Integration with major-modes

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

Chat interface addons

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

Integration with other packages

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

gptel configuration management

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

** COMMENT Older Breaking Changes

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

** Acknowledgments

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

Local Variables:

toc-org-max-depth: 4

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

End:

rainstormstudio/nerd-icons.el

#+TITLE: nerd-icons.el - A Library for Nerd Font icons #+AUTHOR: Hongyu Ding #+LANGUAGE: en

[[https://melpa.org/#/nerd-icons][file:https://melpa.org/packages/nerd-icons-badge.svg]]

Nerd-icons.el is a library for easily using [[https://github.com/ryanoasis/nerd-fonts][Nerd Font]] icons inside Emacs, an alternative to [[https://github.com/domtronn/all-the-icons.el][all-the-icons]].

It works on both GUI and terminal! You only need a [[https://www.nerdfonts.com/#home][Nerd Font]] installed on your system.

It is inspired by [[https://github.com/domtronn/all-the-icons.el][all-the-icons]], [[https://github.com/seagle0128/icons-in-terminal.el][icons-in-terminal]], [[https://github.com/ryanoasis/vim-devicons][vim-devicons]], and [[https://github.com/nvim-tree/nvim-web-devicons][nvim-web-devicons]].

in GUI: [[file:screenshots/demo.png]]

in terminal: [[file:screenshots/demo-terminal.png]]

Installing Fonts Please go to [[https://www.nerdfonts.com/][Nerd Fonts website]] and get a Nerd font. After installing the font on your machine, you need to set ~nerd-icons-font-family~ to match its font name so that the font can be properly used under GUI. If you want Nerd Fonts to work under a terminal, please change your terminal's font to a Nerd font.

If the Nerd Font you installed does not display correctly (e.g. appear cut off), it is recommended to use =Symbols Nerd Font Mono= (Symbols Nerd Font). You can use ~M-x nerd-icons-install-fonts~ to install ~Symbols Nerd Font Mono~ for you. Note that for Windows you'll need to manually install the font after you used this function.

To automatically install =Symbols Nerd Font Mono=, you can use this elisp in your ~init.el~. On macOS, Linux and BSDs, this will download and install the font directly for you. On Windows, you can specify the folder to download the font to, but you will still have to manually install it after.

#+BEGIN_SRC emacs-lisp ;; Linux/macOS/BSDs (when (member system-type '(gnu gnu/linux gnu/kfreebsd darwin)) (unless (find-font (font-spec :name "Symbols Nerd Font Mono")) (nerd-icons-install-fonts t)))

;; Windows (when (string-equal system-type 'windows-nt) (unless (find-font (font-spec :name "Symbols Nerd Font Mono")) (nerd-icons-install-fonts "c:/Users/username/Desktop/")))

;; All-in-one ;; This will install in the default fonts folder for Linux/macOS/BSDs ;; (same as “t”), but for Windows this will download to the specified ;; folder (unless (find-font (font-spec :name "Symbols Nerd Font Mono")) (nerd-icons-install-fonts "c:/Users/username/Desktop/")) #+END_SRC

Usage ~nerd-icons~ is on [[https://melpa.org/#/nerd-icons-completion][Melpa]]. You can install it with built-in ~M-x package-install~ #+begin_src emacs-lisp (require 'nerd-icons) #+end_src

or using ~use-package~ #+BEGIN_SRC emacs-lisp (use-package nerd-icons ;; :custom ;; The Nerd Font you want to use in GUI ;; "Symbols Nerd Font Mono" is the default and is recommended ;; but you can use any other Nerd Font if you want ;; (nerd-icons-font-family "Symbols Nerd Font Mono") ) #+END_SRC ** insert icons

use icon based on category
- ~nerd-icons-icon-for-dir~
- ~nerd-icons-icon-for-file~
- ~nerd-icons-icon-for-extension~
- ~nerd-icons-icon-for-mode~
- ~nerd-icons-icon-for-url~
- ~nerd-icons-icon-for-buffer~
example: #+BEGIN_SRC emacs-lisp (insert (nerd-icons-icon-for-file "init.el")) ;; Inserts an icon for Emacs Lisp #+END_SRC
use icon directly
- ~nerd-icons-ipsicon~
- ~nerd-icons-octicon~
- ~nerd-icons-pomicon~
- ~nerd-icons-powerline~
- ~nerd-icons-faicon~
- ~nerd-icons-wicon~
- ~nerd-icons-sucicon~
- ~nerd-icons-devicon~
- ~nerd-icons-codicon~
- ~nerd-icons-flicon~
- ~nerd-icons-mdicon~
example: #+BEGIN_SRC emacs-lisp (insert (nerd-icons-faicon "nf-fa-gitlab")) ;; Inserts a Gitlab icon #+END_SRC
insert icon interactively (~M-x~ functions)
- ~nerd-icons-insert~
- ~nerd-icons-insert-ipsicon~
- ~nerd-icons-insert-octicon~
- ~nerd-icons-insert-pomicon~
- ~nerd-icons-insert-powerline~
- ~nerd-icons-insert-faicon~
- ~nerd-icons-insert-wicon~
- ~nerd-icons-insert-sucicon~
- ~nerd-icons-insert-devicon~
- ~nerd-icons-insert-codicon~
- ~nerd-icons-insert-flicon~
- ~nerd-icons-insert-mdicon~

** customize icons You can customize the icons via ~nerd-icons-extension-icon-alist~, ~nerd-icons-regexp-icon-alist~ and ~nerd-icons-mode-icon-alist~, etc.

For example, #+begin_src emacs-lisp (add-to-list 'nerd-icons-extension-icon-alist '("epub" nerd-icons-faicon "nf-fa-book" :face nerd-icons-green)) #+end_src

Glyph Sets | Glyph Set | prefix | Point Range | insert function | |-------------------------+----------------------+--------------------------------------+----------------------| | Seti-UI + Custom | ~nf-seti-~, ~nf-custom-~ | ~e5fa~ - ~e631~ | ~nerd-icons-sucicon~ | | Devicons | ~nf-dev-~ | ~e700~ - ~e7c5~ | ~nerd-icons-devicon~ | | Font Awesome | ~nf-fa-~ | ~f000~ - ~f2e0~ | ~nerd-icons-faicon~ | | Font Awesome Extension | ~nf-fae-~ | ~e200~ - ~e2a9~ | ~nerd-icons-faicon~ | | Material Design Icons | ~nf-md-~ | ~f500~ - ~fd46~ | ~nerd-icons-mdicon~ | | Weather | ~nf-weather-~ | ~e300~ - ~e3eb~ | ~nerd-icons-wicon~ | | Octicons | ~nf-oct-~ | ~f400~ - ~f4a9~, ~2665~, ~26A1~ | ~nerd-icons-octicon~ | | Powerline Symbols | ~nf-pl-~ | ~e0a0~ - ~e0a2~, ~e0b0~ - ~e0b3~ | ~nerd-icons-powerline~ | | Powerline Extra Symbols | ~nf-ple-~ | ~e0a3~, ~e0b4~ - ~e0c8~, ~e0ca~, ~e0cc~ - ~e0d4~ | ~nerd-icons-powerline~ | | IEC Power Symbols | ~nf-iec-~ | ~23fb~ - ~23fe~, ~2b58~ | ~nerd-icons-ipsicon~ | | Font Logos | ~nf-linux-~ | ~f300~ - ~f32d~ | ~nerd-icons-flicon~ | | Pomicons | ~nf-pom-~ | ~e000~ - ~e00a~ | ~nerd-icons-pomicon~ | | Codicons | ~nf-cod-~ | ~ea60~ - ~ebeb~ | ~nerd-icons-codicon~ |

Please check [[https://github.com/ryanoasis/nerd-fonts/wiki/Glyph-Sets-and-Code-Points][Nerd Fonts Glyph Sets and Code Points]] for more information.

Related Packages

[[https://github.com/rainstormstudio/nerd-icons-dired][nerd-icons-dired]]
[[https://github.com/abougouffa/nerd-icons-multimodal][nerd-icons-multimodal]]
[[https://github.com/rainstormstudio/treemacs-nerd-icons][treemacs-nerd-icons]]
[[https://github.com/seagle0128/nerd-icons-ivy-rich][nerd-icons-ivy-rich]]
[[https://github.com/seagle0128/nerd-icons-ibuffer][nerd-icons-ibuffer]]
[[https://github.com/rainstormstudio/nerd-icons-completion][nerd-icons-completion]]
[[https://github.com/LuigiPiucco/nerd-icons-corfu][nerd-icons-corfu]]
[[https://github.com/alexluigit/dirvish][dirvish]]
[[https://github.com/seagle0128/doom-modeline][doom-modeline]]
[[https://github.com/grolongo/nerd-icons-mode-line][nerd-icons-mode-line]]
[[https://github.com/lucius-martius/tab-line-nerd-icons][tab-line-nerd-icons]]

** use nerd-icons with dirvish sample configuration: #+BEGIN_SRC emacs-lisp (use-package dirvish :init (dirvish-override-dired-mode) :config (setq dirvish-mode-line-format '(:left (sort symlink) :right (omit yank index))) (setq dirvish-mode-line-height 10) (setq dirvish-attributes '(nerd-icons file-time file-size collapse subtree-state vc-state git-msg)) (setq dirvish-subtree-state-style 'nerd) (setq delete-by-moving-to-trash t) (setq dirvish-path-separators (list (format " %s " (nerd-icons-codicon "nf-cod-home")) (format " %s " (nerd-icons-codicon "nf-cod-root_folder")) (format " %s " (nerd-icons-faicon "nf-fa-angle_right")))) (setq dired-listing-switches "-l --almost-all --human-readable --group-directories-first --no-group") (dirvish-peek-mode) ; Preview files in minibuffer (dirvish-side-follow-mode) ; similar to `treemacs-follow-mode' ) #+END_SRC

google-coral/coralnpu

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

Coral NPU

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

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

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

Coral NPU Architecture Datasheet

Coral NPU Features

Coral NPU offers the following top-level feature set:

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

System Requirements

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

Verification & Testing

For details on our testing methodologies and how to run or write tests, see the corresponding test READMEs:

Quick Start

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

# Build a binary
bazel build //examples:coralnpu_v2_hello_world_add_floats

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

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

radian-software/apheleia

🌷 Run code formatter on buffer contents without moving point, using RCS patches and dynamic programming.

Apheleia

Good code is automatically formatted by tools like Black or Prettier so that you and your team spend less time on formatting and more time on building features. It's best if your editor can run code formatters each time you save a file, so that you don't have to look at badly formatted code or get surprised when things change just before you commit. However, running a code formatter on save suffers from the following two problems:

It takes some time (e.g. around 200ms for Black on an empty file), which makes the editor feel less responsive.
It invariably moves your cursor (point) somewhere unexpected if the changes made by the code formatter are too close to point's position.

Apheleia is an Emacs package which solves both of these problems comprehensively for all languages, allowing you to say goodbye to language-specific packages such as Blacken and prettier-js.

The approach is as follows:

Run code formatters on after-save-hook, rather than before-save-hook, and do so asynchronously. Once the formatter has finished running, check if the buffer has been modified since it started; only apply the changes if not.
After running the code formatter, generate an RCS patch showing the changes and then apply it to the buffer. This prevents changes elsewhere in the buffer from moving point. If a patch region happens to include point, then use a dynamic programming algorithm for string alignment to determine where point should be moved so that it remains in the same place relative to its surroundings. Finally, if the vertical position of point relative to the window has changed, adjust the scroll position to maintain maximum visual continuity. (This includes iterating through all windows displaying the buffer, if there are more than one.) The dynamic programming algorithm runs in quadratic time, which is why it is only applied if necessary and to a single patch region.

Installation

Apheleia is available on MELPA. It is easiest to install it using straight.el:

(straight-use-package 'apheleia)

However, you may install using any other package manager if you prefer.

Dependencies

Emacs 27 or later is supported. Apheleia does not include any formatters. You must install any formatter separately that you wish to use. As long as it is on $PATH then Apheleia will pick it up automatically; missing formatters will silently be skipped, but errors from invoking installed formatters will be reported on buffer save.

It is recommended to have Bash installed, as this is used as a dependency for Apheleia to invoke certain formatters (e.g. Node.js-based formatters).

Windows support is not guaranteed due to lack of support for common open standards on this platform. Pull requests adjusting Apheleia for improved cross-platform portability will be accepted, but no guarantees are made about stability on Windows.

User guide

To your init-file, add the following form:

(apheleia-global-mode +1)

The autoloading has been configured so that this will not cause Apheleia to be loaded until you save a file.

By default, Apheleia is configured to format with Black, Prettier, and Gofmt on save in all relevant major modes. To configure this, you can adjust the values of the following variables:

apheleia-formatters: Alist mapping names of formatters (symbols like black and prettier) to commands used to run those formatters (such as ("black" "-") and (npx "prettier" input)). See the docstring for more information.
- You can manipulate this alist using standard Emacs functions. For example, to add some command-line options to Black, you could use:
```
(setf (alist-get 'black apheleia-formatters)
      '("black" "--option" "..." "-"))
```
- There are a list of symbols that are interpreted by apheleia specially when formatting a command (example: npx). Any non-string entries in a formatter that doesn't equal one of these symbols is evaluated and replaced in place. This can be used to pass certain flags to the formatter process depending on the state of the current buffer. For example:
```
(push '(shfmt . ("beautysh"
                 "-filename" filepath
                 (when-let ((indent (bound-and-true-p sh-basic-offset)))
                   (list "--indent-size" (number-to-string indent)))
                 (when indent-tabs-mode "--tab")
                 "-"))
      apheleia-formatters)
```
  This adds an entry to apheleia-formatters for the beautysh formatter. The evaluated entries makes it so that the --tab flag is only passed to beautysh when the value of indent-tabs-mode is true. Similarly the indent-size flag is passed the exact value of the sh-basic-offset variable only when it is bound. Observe that one of these evaluations returns a list of flags whereas the other returns a single string. These are substituted into the command as you'd expect.
- You can also use Apheleia to format buffers that have no underlying files. In this case the value of file and filepath will be the name of the current buffer with any special characters for the file-system (such as * on windows) being stripped out.
  
  This is also how the extension for any temporary files apheleia might create will be determined. If you're using a formatter that determines the file-type from the extension you should name such buffers such that their suffixed with the extension. For example a buffer called *foo-bar.c* that has no associated file will have an implicit file-name of foo-bar.c and any temporary files will be suffixed with a .c extension.
- You can implement formatters as arbitrary Elisp functions which operate directly on a buffer, without needing to invoke an external command. This can be useful to integrate with e.g. language servers. See the docstring for more information on the expected interface for Elisp formatters.
apheleia-mode-alist: Alist mapping major modes and filename regexps to names of formatters to use in those modes and files. See the docstring for more information.
- You can use this variable to configure multiple formatters for the same buffer by setting the cdr of an entry to a list of formatters to run instead of a single formatter. For example you may want to run isort and black one after the other.
```
(setf (alist-get 'isort apheleia-formatters)
      '("isort" "--stdout" "-"))
(setf (alist-get 'python-mode apheleia-mode-alist)
      '(isort black))
```
  This will make apheleia run isort on the current buffer and then black on the result of isort and then use the final output to format the current buffer.
  
  Warning: At the moment there's no smart or configurable error handling in place. This means if one of the configured formatters fail (for example if isort isn't installed) then apheleia just doesn't format the buffer at all, even if black is installed.
  
  Warning: If a formatter uses file (rather than filepath or input or none of these keywords), it can't be chained after another formatter, because file implies that the formatter must read from the original file, not an intermediate temporary file. For this reason it's suggested to avoid the use of file in general.
apheleia-formatter: Optional buffer-local variable specifying the formatter to use in this buffer. Overrides apheleia-mode-alist. You can set this in a local variables list, or in .dir-locals.el (e.g. ((python-mode . ((apheleia-formatter . (isort black)))))), or in a custom hook of your own that sets the local variable conditionally.
apheleia-inhibit: Optional buffer-local variable, if set to non-nil then Apheleia does not turn on automatically even if apheleia-global-mode is on.

You can run M-x apheleia-mode to toggle automatic formatting on save in a single buffer, or M-x apheleia-global-mode to toggle the default setting for all buffers. Also, even if apheleia-mode is not enabled, you can run M-x apheleia-format-buffer to manually invoke the configured formatter for the current buffer. Running with a prefix argument will cause the command to prompt you for which formatter to run.

Apheleia does not currently support TRAMP, and is therefore automatically disabled for remote files.

If an error occurs while formatting, a message is displayed in the echo area. You can jump to the error by invoking M-x apheleia-goto-error, or manually switch to the log buffer mentioned in the message.

You can configure error reporting using the following user options:

apheleia-hide-log-buffers: By default, errors from formatters are put in buffers named like *apheleia-cmdname-log*. If you customize this user option to non-nil then a space is prepended to the names of these buffers, hiding them by default in switch-to-buffer (you must type a space to see them).
apheleia-log-only-errors: By default, only failed formatter runs are logged. If you customize this user option to nil then all runs are logged, along with whether or not they succeeded. This could be helpful in debugging.

The following user options are also available:

apheleia-post-format-hook: Normal hook run after Apheleia formats a buffer. Run if the formatting is successful, even when no changes are made to the buffer.
apheleia-max-alignment-size: The maximum number of characters that a diff region can have to be processed using Apheleia's dynamic programming algorithm for point alignment. This cannot be too big or Emacs will hang noticeably on large reformatting operations, since the DP algorithm is quadratic-time.
apheleia-mode-lighter: apheleia-mode lighter displayed in the mode-line. If you don't want to display it, use nil. Otherwise, its value must be a string.

Apheleia exposes some hooks for advanced customization:

apheleia-formatter-exited-hook: Abnormal hook which is run after a formatter has completely finished running for a buffer. Not run if the formatting was interrupted and no action was taken. Receives two arguments: the symbol for the formatter that was run (e.g. black, or it could be a list if multiple formatters were run in a chain), and a boolean for whether there was an error.
apheleia-inhibit-functions: List of functions to run before turning on Apheleia automatically from apheleia-global-mode. If one of these returns non-nil then apheleia-mode is not enabled in the buffer.
apheleia-skip-functions: List of functions to run before each Apheleia formatter invocation. If one of these returns non-nil then the formatter is not run, even if apheleia-mode is enabled.

Formatter configuration

There is no configuration interface in Apheleia for formatter behavior. The way to configure a formatter is by editing a standard config file that it reads (e.g. .prettierrc.json), or setting an environment variable that it reads, or by changing the entry in apheleia-formatters to customize the command-line arguments.

There is one exception to this, which is that Apheleia's default command-line arguments for the built-in formatters will automatically check Emacs' indentation options for the corresponding major mode, and pass that information to the formatter. This way, the indentation (tabs vs spaces, and how many) applied by the formatter will match what electric indentation in Emacs is doing, preventing a shuffle back and forth as you type.

This behavior can be disabled by setting apheleia-formatters-respect-indent-level to nil.

Troubleshooting

Try running your formatter outside of Emacs to verify it works there. Check what command-line options it is configured with in apheleia-formatters.

To debug internal bugs, race conditions, or performance issues, try setting apheleia-log-debug-info to non-nil and check the contents of *apheleia-debug-log*. It will have detailed trace information about most operations performed by Apheleia.

Known issues

process aphelieia-whatever no longer connected to pipe; closed it: This happens on older Emacs versions when formatting a buffer with size greater than 65,536 characters. There is no known workaround besides disabling apheleia-mode for the affected buffer, or upgrading to a more recent version of Emacs. See #20.

Contributing

Please see the contributor guide for my projects for general information, and the following sections for Apheleia-specific details.

There's also a wiki that could do with additions/clarity. Any improvement suggestions should be submitted as an issue.

Adding a formatter

I have done my best to make it straightforward to add a formatter. You just follow these steps:

Install your formatter on your machine so you can test.
Create an entry in apheleia-formatters with how to run it. (See the docstring of this variable for explanation about the available keywords.)
Add entries for the relevant major modes in apheleia-mode-alist.
See if it works for you!
Add a file at test/formatters/installers/yourformatter.bash which explains how to install the formatter on Ubuntu. This will be used by CI.
Test with make fmt-build FORMATTERS=yourformatter to do the installation, then make fmt-docker to start a shell with the formatter available. Verify it runs in this environment.
Add an example input (pre-formatting) and output (post-formatting) file at test/formatters/samplecode/yourformatter/in.whatever and test/formatters/samplecode/yourformatter/out.whatever.
Verify that the tests are passing, using make fmt-test FORMATTERS=yourformatter from inside the fmt-docker shell.
Submit a pull request, CI should now be passing!

Acknowledgements

I got the idea for using RCS patches to avoid moving point too much from prettier-js, although that package does not implement the dynamic programming algorithm which Apheleia uses to guarantee stability of point even within a formatted region.

Note that despite this inspiration, Apheleia is a clean-room implementation which is free of the copyright terms of prettier-js.

purcell/exec-path-from-shell

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

exec-path-from-shell

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

Motivation

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

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

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

Compatibility

Supported shells:

zsh
bash
tcsh
fish
nu

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

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

There is a compatible package if you are using powershell or pwsh so you can share Emacs config with platforms that use that shell.

Installation

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

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

Usage

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

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

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

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

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

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

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

This function may also be called interactively.

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

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

Setting up your shell startup files correctly

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

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

but instead do this:

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

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

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

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

Making `exec-path-from-shell` faster

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

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

Further help

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

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

💼 LinkedIn profile

✍ sanityinc.com

company-mode/company-mode

Modular in-buffer completion framework for Emacs

See the homepage for installation and usage instructions.

File a bug report in Issues.

Ask a question or suggest a feature in Discussions.

See Contributing on other ways to help out.

Fanael/rainbow-delimiters

Emacs rainbow delimiters mode

rainbow-delimiters

rainbow-delimiters is a "rainbow parentheses"-like mode which highlights delimiters such as parentheses, brackets or braces according to their depth. Each successive level is highlighted in a different color. This makes it easy to spot matching delimiters, orient yourself in the code, and tell which statements are at a given depth.

Great care has been taken to make this mode fast. You shouldn't see any change in scrolling or editing speed when it's on even when working in delimiter-rich languages like Clojure or Emacs Lisp. It can be used with any language.

You can customize the colors rainbow-delimiters uses. The default colors are intentionally subtle; they are unobtrusive enough to make the mode worth looking at even if you usually don't like rainbow parentheses modes. A number of major color themes such as Zenburn and Solarized have added their own faces for the mode.

This is the official github repository for rainbow-delimiters.

The latest release of rainbow-delimiters is always found at https://github.com/Fanael/rainbow-delimiters/tree/master

Installation

The recommended way is to use MELPA or MELPA Stable. If either is in your package-archives, do

M-x package-install RET rainbow-delimiters RET

Otherwise, open rainbow-delimiters.el in Emacs and use

M-x package-install-from-buffer

Any other methods of installation are unsupported.

Usage

To toggle the mode in the current buffer:

M-x rainbow-delimiters-mode

To start the mode automatically in foo-mode, add the following to your init file:

(add-hook 'foo-mode-hook #'rainbow-delimiters-mode)

To start the mode automatically in most programming modes (Emacs 24 and above):

(add-hook 'prog-mode-hook #'rainbow-delimiters-mode)

Global mode

There's no global-rainbow-delimiters-mode anymore. It used to exist, but it was impossible to keep it from breaking some major modes. It's strongly recommended to use major mode hooks instead, as shown above. There's nothing stopping you from defining global-rainbow-delimiters-mode yourself, but if it breaks something, you're on your own.

Customization

To customize various options, including the color theme:

M-x customize-group rainbow-delimiters

You can specify custom colors by customizing following faces:

Faces take the form rainbow-delimiters-depth-N-face, with N being the depth. Depth begins at 1, the outermost color. Faces exist for depths 1-9.
The unmatched delimiter face: rainbow-delimiters-unmatched-face.
The mismatched delimiter face: rainbow-delimiters-mismatched-face.

magnars/dash.el

A modern list library for Emacs

dash.el

A modern list API for Emacs. No 'cl required.

See the end of the file for license conditions.

Change log

See the NEWS.md file.

Installation

Dash is available on GNU ELPA, GNU-devel ELPA, and MELPA, and can be installed with the standard command package-install:

M-x package-install RET dash RET

See (info "(emacs) Package Installation").

Alternatively, you can just dump dash.el in your load-path somewhere. See (info "(emacs) Lisp Libraries").

Using in a package

Add something like this to the library’s headers:

;; Package-Requires: ((dash "2.20.0"))

See (info "(elisp) Library Headers").

Fontification of special variables

Font lock of special Dash variables (it, acc, etc.) in Emacs Lisp buffers can optionally be enabled with the autoloaded minor mode dash-fontify-mode. In older Emacs versions which do not dynamically detect macros, the minor mode also fontifies Dash macro calls.

To automatically enable the minor mode in all Emacs Lisp buffers, just call its autoloaded global counterpart global-dash-fontify-mode, either interactively or from your user-init-file:

(global-dash-fontify-mode)

Info symbol lookup

While editing Elisp files, you can use C-h S (info-lookup-symbol) to look up Elisp symbols in the relevant Info manuals (see (emacs) Info Lookup). To enable the same for Dash symbols, use the command dash-register-info-lookup. It can be called directly when needed, or automatically from your user-init-file. For example:

(with-eval-after-load 'info-look
  (dash-register-info-lookup))

Functions

All functions and constructs in the library use a dash (-) prefix.

The library also provides anaphoric macro versions of functions where that makes sense. The names of these macros are prefixed with two dashes (--) instead of one.

While -map applies a function to each element of a list, its anaphoric counterpart --map evaluates a form with the local variable it temporarily bound to the current list element instead. For example:

(-map (lambda (n) (* n n)) '(1 2 3 4)) ; Normal version.
(--map (* it it) '(1 2 3 4))           ; Anaphoric version.

The normal version can of course also be written as follows:

(defun my-square (n)
  "Return N multiplied by itself."
  (* n n))

(-map #'my-square '(1 2 3 4))

This demonstrates the utility of both versions.

Maps

Functions in this category take a transforming function, which is then applied sequentially to each or selected elements of the input list. The results are collected in order and returned as a new list.

-map (fn list)
-map-when (pred rep list)
-map-first (pred rep list)
-map-last (pred rep list)
-map-indexed (fn list)
-annotate (fn list)
-splice (pred fun list)
-splice-list (pred new-list list)
-mapcat (fn list)
-copy (list)

Sublist selection

Functions returning a sublist of the original list.

-filter (pred list)
-remove (pred list)
-remove-first (pred list)
-remove-last (pred list)
-remove-item (item list)
-non-nil (list)
-slice (list from &optional to step)
-take (n list)
-take-last (n list)
-drop (n list)
-drop-last (n list)
-take-while (pred list)
-drop-while (pred list)
-select-by-indices (indices list)
-select-columns (columns table)
-select-column (column table)

List to list

Functions returning a modified copy of the input list.

-keep (fn list)
-concat (&rest sequences)
-flatten (l)
-flatten-n (num list)
-replace (old new list)
-replace-first (old new list)
-replace-last (old new list)
-insert-at (n x list)
-replace-at (n x list)
-update-at (n func list)
-remove-at (n list)
-remove-at-indices (indices list)

Reductions

Functions reducing lists to a single value (which may also be a list).

-reduce-from (fn init list)
-reduce-r-from (fn init list)
-reduce (fn list)
-reduce-r (fn list)
-reductions-from (fn init list)
-reductions-r-from (fn init list)
-reductions (fn list)
-reductions-r (fn list)
-count (pred list)
-sum (list)
-running-sum (list)
-product (list)
-running-product (list)
-inits (list)
-tails (list)
-common-prefix (&rest lists)
-common-suffix (&rest lists)
-min (list)
-min-by (comparator list)
-max (list)
-max-by (comparator list)
-frequencies (list)

Unfolding

Operations dual to reductions, building lists from a seed value rather than consuming a list to produce a single value.

-iterate (fun init n)
-unfold (fun seed)
-repeat (n x)
-cycle (list)

Predicates

Reductions of one or more lists to a boolean value.

-some (pred list)
-every (pred list)
-any? (pred list)
-all? (pred list)
-none? (pred list)
-only-some? (pred list)
-contains? (list element)
-is-prefix? (prefix list)
-is-suffix? (suffix list)
-is-infix? (infix list)
-cons-pair? (obj)

Partitioning

Functions partitioning the input list into a list of lists.

-split-at (n list)
-split-with (pred list)
-split-on (item list)
-split-when (fn list)
-separate (pred list)
-partition (n list)
-partition-all (n list)
-partition-in-steps (n step list)
-partition-all-in-steps (n step list)
-partition-by (fn list)
-partition-by-header (fn list)
-partition-after-pred (pred list)
-partition-before-pred (pred list)
-partition-before-item (item list)
-partition-after-item (item list)
-group-by (fn list)

Indexing

Functions retrieving or sorting based on list indices and related predicates.

-elem-index (elem list)
-elem-indices (elem list)
-find-index (pred list)
-find-last-index (pred list)
-find-indices (pred list)
-grade-up (comparator list)
-grade-down (comparator list)

Set operations

Operations pretending lists are sets.

-union (list1 list2)
-difference (list1 list2)
-intersection (list1 list2)
-powerset (list)
-permutations (list)
-distinct (list)
-same-items? (list1 list2)

Other list operations

Other list functions not fit to be classified elsewhere.

-rotate (n list)
-cons* (&rest args)
-snoc (list elem &rest elements)
-interpose (sep list)
-interleave (&rest lists)
-iota (count &optional start step)
-zip-with (fn list1 list2)
-zip-pair (list1 list2)
-zip-lists (&rest lists)
-zip-lists-fill (fill-value &rest lists)
-zip (&rest lists)
-zip-fill (fill-value &rest lists)
-unzip-lists (lists)
-unzip (lists)
-pad (fill-value &rest lists)
-table (fn &rest lists)
-table-flat (fn &rest lists)
-first (pred list)
-last (pred list)
-first-item (list)
-second-item (list)
-third-item (list)
-fourth-item (list)
-fifth-item (list)
-last-item (list)
-butlast (list)
-sort (comparator list)
-list (arg)
-fix (fn list)

Tree operations

Functions pretending lists are trees.

-tree-seq (branch children tree)
-tree-map (fn tree)
-tree-map-nodes (pred fun tree)
-tree-reduce (fn tree)
-tree-reduce-from (fn init-value tree)
-tree-mapreduce (fn folder tree)
-tree-mapreduce-from (fn folder init-value tree)
-clone (list)

Threading macros

Macros that conditionally combine sequential forms for brevity or readability.

-> (x &optional form &rest more)
->> (x &optional form &rest more)
--> (x &rest forms)
-as-> (value variable &rest forms)
-some-> (x &optional form &rest more)
-some->> (x &optional form &rest more)
-some--> (expr &rest forms)
-doto (init &rest forms)

Binding

Macros that combine let and let* with destructuring and flow control.

-when-let ((var val) &rest body)
-when-let* (vars-vals &rest body)
-if-let ((var val) then &rest else)
-if-let* (vars-vals then &rest else)
-let (varlist &rest body)
-let* (varlist &rest body)
-lambda (match-form &rest body)
-setq ([match-form val] ...)

Side effects

Functions iterating over lists for side effect only.

-each (list fn)
-each-while (list pred fn)
-each-indexed (list fn)
-each-r (list fn)
-each-r-while (list pred fn)
-dotimes (num fn)

Destructive operations

Macros that modify variables holding lists.

!cons (car cdr)
!cdr (list)

Function combinators

Functions that manipulate and compose other functions.

-partial (fun &rest args)
-rpartial (fn &rest args)
-juxt (&rest fns)
-compose (&rest fns)
-applify (fn)
-on (op trans)
-flip (fn)
-rotate-args (n fn)
-const (c)
-cut (&rest params)
-not (pred)
-orfn (&rest preds)
-andfn (&rest preds)
-iteratefn (fn n)
-fixfn (fn &optional equal-test halt-test)
-prodfn (&rest fns)

Maps

-map `(fn list)`

Apply fn to each item in list and return the list of results.

This function's anaphoric counterpart is --map.

(-map (lambda (num) (* num num)) '(1 2 3 4)) ;; => (1 4 9 16)
(-map #'1+ '(1 2 3 4)) ;; => (2 3 4 5)
(--map (* it it) '(1 2 3 4)) ;; => (1 4 9 16)

-map-when `(pred rep list)`

Use pred to conditionally apply rep to each item in list. Return a copy of list where the items for which pred returns nil are unchanged, and the rest are mapped through the rep function.

Alias: -replace-where

-map-first `(pred rep list)`

Use pred to determine the first item in list to call rep on. Return a copy of list where the first item for which pred returns non-nil is replaced with the result of calling rep on that item.

-map-last `(pred rep list)`

Use pred to determine the last item in list to call rep on. Return a copy of list where the last item for which pred returns non-nil is replaced with the result of calling rep on that item.

-map-indexed `(fn list)`

Apply fn to each index and item in list and return the list of results. This is like -map, but fn takes two arguments: the index of the current element within list, and the element itself.

This function's anaphoric counterpart is --map-indexed.

For a side-effecting variant, see also -each-indexed.

(-map-indexed (lambda (index item) (- item index)) '(1 2 3 4)) ;; => (1 1 1 1)
(--map-indexed (- it it-index) '(1 2 3 4)) ;; => (1 1 1 1)
(-map-indexed #'* '(1 2 3 4)) ;; => (0 2 6 12)

-annotate `(fn list)`

Pair each item in list with the result of passing it to fn.

Return an alist of (result . item), where each item is the corresponding element of list, and result is the value obtained by calling fn on item.

This function's anaphoric counterpart is --annotate.

(-annotate #'1+ '(1 2 3)) ;; => ((2 . 1) (3 . 2) (4 . 3))
(-annotate #'length '((f o o) (bar baz))) ;; => ((3 f o o) (2 bar baz))
(--annotate (> it 1) '(0 1 2 3)) ;; => ((nil . 0) (nil . 1) (t . 2) (t . 3))

-splice `(pred fun list)`

Splice lists generated by fun in place of items satisfying pred in list.

Call pred on each element of list. Whenever the result of pred is nil, leave that it as-is. Otherwise, call fun on the same it that satisfied pred. The result should be a (possibly empty) list of items to splice in place of it in list.

This can be useful as an alternative to the ,@ construct in a ``' structure, in case you need to splice several lists at marked positions (for example with keywords).

This function's anaphoric counterpart is --splice.

-splice-list `(pred new-list list)`

Splice new-list in place of elements matching pred in list.

-mapcat `(fn list)`

Return the concatenation of the result of mapping fn over list. Thus function fn should return a list.

(-mapcat 'list '(1 2 3)) ;; => (1 2 3)
(-mapcat (lambda (item) (list 0 item)) '(1 2 3)) ;; => (0 1 0 2 0 3)
(--mapcat (list 0 it) '(1 2 3)) ;; => (0 1 0 2 0 3)

-copy `(list)`

Create a shallow copy of list. The elements of list are not copied; they are shared with the original.

(-copy '(1 2 3)) ;; => (1 2 3)
(let ((a '(1 2 3))) (eq a (-copy a))) ;; => nil

Sublist selection

Functions returning a sublist of the original list.

-filter `(pred list)`

Return a new list of the items in list for which pred returns non-nil.

Alias: -select.

This function's anaphoric counterpart is --filter.

For similar operations, see also -keep and -remove.

(-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => (2 4)
(-filter #'natnump '(-2 -1 0 1 2)) ;; => (0 1 2)
(--filter (= 0 (% it 2)) '(1 2 3 4)) ;; => (2 4)

-remove `(pred list)`

Return a new list of the items in list for which pred returns nil.

Alias: -reject.

This function's anaphoric counterpart is --remove.

For similar operations, see also -keep and -filter.

(-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => (1 3)
(-remove #'natnump '(-2 -1 0 1 2)) ;; => (-2 -1)
(--remove (= 0 (% it 2)) '(1 2 3 4)) ;; => (1 3)

-remove-first `(pred list)`

Remove the first item from list for which pred returns non-nil. This is a non-destructive operation, but only the front of list leading up to the removed item is a copy; the rest is list's original tail. If no item is removed, then the result is a complete copy.

Alias: -reject-first.

This function's anaphoric counterpart is --remove-first.

See also -map-first, -remove-item, and -remove-last.

(-remove-first #'natnump '(-2 -1 0 1 2)) ;; => (-2 -1 1 2)
(-remove-first #'stringp '(1 2 "first" "second")) ;; => (1 2 "second")
(--remove-first (> it 3) '(1 2 3 4 5 6)) ;; => (1 2 3 5 6)

-remove-last `(pred list)`

Remove the last item from list for which pred returns non-nil. The result is a copy of list regardless of whether an element is removed.

Alias: -reject-last.

This function's anaphoric counterpart is --remove-last.

See also -map-last, -remove-item, and -remove-first.

(-remove-last #'natnump '(1 3 5 4 7 8 10 -11)) ;; => (1 3 5 4 7 8 -11)
(-remove-last #'stringp '(1 2 "last" "second")) ;; => (1 2 "last")
(--remove-last (> it 3) '(1 2 3 4 5 6 7 8 9 10)) ;; => (1 2 3 4 5 6 7 8 9)

-remove-item `(item list)`

Return a copy of list with all occurrences of item removed. The comparison is done with equal.

(-remove-item 3 '(1 2 3 2 3 4 5 3)) ;; => (1 2 2 4 5)
(-remove-item 'foo '(foo bar baz foo)) ;; => (bar baz)
(-remove-item "bob" '("alice" "bob" "eve" "bob")) ;; => ("alice" "eve")

-non-nil `(list)`

Return a copy of list with all nil items removed.

(-non-nil '(nil 1 nil 2 nil nil 3 4 nil 5 nil)) ;; => (1 2 3 4 5)
(-non-nil '((nil))) ;; => ((nil))
(-non-nil ()) ;; => ()

-slice `(list from &optional to step)`

Return copy of list, starting from index from to index to.

from or to may be negative. These values are then interpreted modulo the length of the list.

If step is a number, only each stepth item in the resulting section is returned. Defaults to 1.

(-slice '(1 2 3 4 5) 1) ;; => (2 3 4 5)
(-slice '(1 2 3 4 5) 0 3) ;; => (1 2 3)
(-slice '(1 2 3 4 5 6 7 8 9) 1 -1 2) ;; => (2 4 6 8)

-take `(n list)`

Return a copy of the first n items in list. Return a copy of list if it contains n items or fewer. Return nil if n is zero or less.

-take-last `(n list)`

Return a copy of the last n items of list in order. Return a copy of list if it contains n items or fewer. Return nil if n is zero or less.

-drop `(n list)`

Return the tail (not a copy) of list without the first n items. Return nil if list contains n items or fewer. Return list if n is zero or less.

For another variant, see also -drop-last.

(-drop 3 '(1 2 3 4 5)) ;; => (4 5)
(-drop 17 '(1 2 3 4 5)) ;; => ()
(-drop 0 '(1 2 3 4 5)) ;; => (1 2 3 4 5)

-drop-last `(n list)`

Return a copy of list without its last n items. Return a copy of list if n is zero or less. Return nil if list contains n items or fewer.

-take-while `(pred list)`

Take successive items from list for which pred returns non-nil. pred is a function of one argument. Return a new list of the successive elements from the start of list for which pred returns non-nil.

This function's anaphoric counterpart is --take-while.

For another variant, see also -drop-while.

(-take-while #'even? '(1 2 3 4)) ;; => ()
(-take-while #'even? '(2 4 5 6)) ;; => (2 4)
(--take-while (< it 4) '(1 2 3 4 3 2 1)) ;; => (1 2 3)

-drop-while `(pred list)`

Drop successive items from list for which pred returns non-nil. pred is a function of one argument. Return the tail (not a copy) of list starting from its first element for which pred returns nil.

This function's anaphoric counterpart is --drop-while.

For another variant, see also -take-while.

(-drop-while #'even? '(1 2 3 4)) ;; => (1 2 3 4)
(-drop-while #'even? '(2 4 5 6)) ;; => (5 6)
(--drop-while (< it 4) '(1 2 3 4 3 2 1)) ;; => (4 3 2 1)

-select-by-indices `(indices list)`

Return a list whose elements are elements from list selected as (nth i list) for all i from indices.

(-select-by-indices '(4 10 2 3 6) '("v" "e" "l" "o" "c" "i" "r" "a" "p" "t" "o" "r")) ;; => ("c" "o" "l" "o" "r")
(-select-by-indices '(2 1 0) '("a" "b" "c")) ;; => ("c" "b" "a")
(-select-by-indices '(0 1 2 0 1 3 3 1) '("f" "a" "r" "l")) ;; => ("f" "a" "r" "f" "a" "l" "l" "a")

-select-columns `(columns table)`

Select columns from table.

table is a list of lists where each element represents one row. It is assumed each row has the same length.

Each row is transformed such that only the specified columns are selected.

(-select-columns '(0 2) '((1 2 3) (a b c) (:a :b :c))) ;; => ((1 3) (a c) (:a :c))
(-select-columns '(1) '((1 2 3) (a b c) (:a :b :c))) ;; => ((2) (b) (:b))
(-select-columns nil '((1 2 3) (a b c) (:a :b :c))) ;; => (nil nil nil)

-select-column `(column table)`

Select column from table.

table is a list of lists where each element represents one row. It is assumed each row has the same length.

The single selected column is returned as a list.

(-select-column 1 '((1 2 3) (a b c) (:a :b :c))) ;; => (2 b :b)

List to list

Functions returning a modified copy of the input list.

-keep `(fn list)`

Return a new list of the non-nil results of applying fn to each item in list. Like -filter, but returns the non-nil results of fn instead of the corresponding elements of list.

Its anaphoric counterpart is --keep.

(-keep #'cdr '((1 2 3) (4 5) (6))) ;; => ((2 3) (5))
(-keep (lambda (n) (and (> n 3) (* 10 n))) '(1 2 3 4 5 6)) ;; => (40 50 60)
(--keep (and (> it 3) (* 10 it)) '(1 2 3 4 5 6)) ;; => (40 50 60)

-concat `(&rest sequences)`

Concatenate all sequences and make the result a list. The result is a list whose elements are the elements of all the arguments. Each argument may be a list, vector or string.

All arguments except the last argument are copied. The last argument is just used as the tail of the new list. If the last argument is not a list, this results in a dotted list.

As an exception, if all the arguments except the last are nil, and the last argument is not a list, the return value is that last argument unaltered, not a list.

(-concat '(1)) ;; => (1)
(-concat '(1) '(2)) ;; => (1 2)
(-concat '(1) '(2 3) '(4)) ;; => (1 2 3 4)

-flatten `(l)`

Take a nested list l and return its contents as a single, flat list.

Note that because nil represents a list of zero elements (an empty list), any mention of nil in l will disappear after flattening. If you need to preserve nils, consider -flatten-n or map them to some unique symbol and then map them back.

Conses of two atoms are considered "terminals", that is, they aren't flattened further.

-flatten-n `(num list)`

Flatten num levels of a nested list.

-replace `(old new list)`

Replace all old items in list with new.

Elements are compared using equal.

-replace-first `(old new list)`

Replace the first occurrence of old with new in list.

Elements are compared using equal.

-replace-last `(old new list)`

Replace the last occurrence of old with new in list.

Elements are compared using equal.

-insert-at `(n x list)`

Return a list with x inserted into list at position n.

-replace-at `(n x list)`

Return a list with element at nth position in list replaced with x.

-update-at `(n func list)`

Use func to update the nth element of list. Return a copy of list where the nth element is replaced with the result of calling func on it.

-remove-at `(n list)`

Return list with its element at index n removed. That is, remove any element selected as (nth n list) from list and return the result.

This is a non-destructive operation: parts of list (but not necessarily all of it) are copied as needed to avoid destructively modifying it.

See also: -remove-at-indices, -remove.

(-remove-at 0 '(a b c)) ;; => (b c)
(-remove-at 1 '(a b c)) ;; => (a c)
(-remove-at 2 '(a b c)) ;; => (a b)

-remove-at-indices `(indices list)`

Return list with its elements at indices removed. That is, for each index i in indices, remove any element selected as (nth i list) from list.

This is a non-destructive operation: parts of list (but not necessarily all of it) are copied as needed to avoid destructively modifying it.

Reductions

Functions reducing lists to a single value (which may also be a list).

-reduce-from `(fn init list)`

Reduce the function fn across list, starting with init. Return the result of applying fn to init and the first element of list, then applying fn to that result and the second element, etc. If list is empty, return init without calling fn.

This function's anaphoric counterpart is --reduce-from.

For other folds, see also -reduce and -reduce-r.

(-reduce-from #'- 10 '(1 2 3)) ;; => 4
(-reduce-from #'list 10 '(1 2 3)) ;; => (((10 1) 2) 3)
(--reduce-from (concat acc " " it) "START" '("a" "b" "c")) ;; => "START a b c"

-reduce-r-from `(fn init list)`

Reduce the function fn across list in reverse, starting with init. Return the result of applying fn to the last element of list and init, then applying fn to the second-to-last element and the previous result of fn, etc. That is, the first argument of fn is the current element, and its second argument the accumulated value. If list is empty, return init without calling fn.

This function is like -reduce-from but the operation associates from the right rather than left. In other words, it starts from the end of list and flips the arguments to fn. Conceptually, it is like replacing the conses in list with applications of fn, and its last link with init, and evaluating the resulting expression.

This function's anaphoric counterpart is --reduce-r-from.

For other folds, see also -reduce-r and -reduce.

(-reduce-r-from #'- 10 '(1 2 3)) ;; => -8
(-reduce-r-from #'list 10 '(1 2 3)) ;; => (1 (2 (3 10)))
(--reduce-r-from (concat it " " acc) "END" '("a" "b" "c")) ;; => "a b c END"

-reduce `(fn list)`

Reduce the function fn across list. Return the result of applying fn to the first two elements of list, then applying fn to that result and the third element, etc. If list contains a single element, return it without calling fn. If list is empty, return the result of calling fn with no arguments.

This function's anaphoric counterpart is --reduce.

For other folds, see also -reduce-from and -reduce-r.

(-reduce #'- '(1 2 3 4)) ;; => -8
(-reduce #'list '(1 2 3 4)) ;; => (((1 2) 3) 4)
(--reduce (format "%s-%d" acc it) '(1 2 3)) ;; => "1-2-3"

-reduce-r `(fn list)`

Reduce the function fn across list in reverse. Return the result of applying fn to the last two elements of list, then applying fn to the third-to-last element and the previous result of fn, etc. That is, the first argument of fn is the current element, and its second argument the accumulated value. If list contains a single element, return it without calling fn. If list is empty, return the result of calling fn with no arguments.

This function is like -reduce but the operation associates from the right rather than left. In other words, it starts from the end of list and flips the arguments to fn. Conceptually, it is like replacing the conses in list with applications of fn, ignoring its last link, and evaluating the resulting expression.

This function's anaphoric counterpart is --reduce-r.

For other folds, see also -reduce-r-from and -reduce.

(-reduce-r #'- '(1 2 3 4)) ;; => -2
(-reduce-r #'list '(1 2 3 4)) ;; => (1 (2 (3 4)))
(--reduce-r (format "%s-%d" acc it) '(1 2 3)) ;; => "3-2-1"

-reductions-from `(fn init list)`

Return a list of fn's intermediate reductions across list. That is, a list of the intermediate values of the accumulator when -reduce-from (which see) is called with the same arguments.

This function's anaphoric counterpart is --reductions-from.

For other folds, see also -reductions and -reductions-r.

(-reductions-from #'max 0 '(2 1 4 3)) ;; => (0 2 2 4 4)
(-reductions-from #'* 1 '(1 2 3 4)) ;; => (1 1 2 6 24)
(--reductions-from (format "(FN %s %d)" acc it) "INIT" '(1 2 3)) ;; => ("INIT" "(FN INIT 1)" "(FN (FN INIT 1) 2)" "(FN (FN (FN INIT 1) 2) 3)")

-reductions-r-from `(fn init list)`

Return a list of fn's intermediate reductions across reversed list. That is, a list of the intermediate values of the accumulator when -reduce-r-from (which see) is called with the same arguments.

This function's anaphoric counterpart is --reductions-r-from.

For other folds, see also -reductions and -reductions-r.

(-reductions-r-from #'max 0 '(2 1 4 3)) ;; => (4 4 4 3 0)
(-reductions-r-from #'* 1 '(1 2 3 4)) ;; => (24 24 12 4 1)
(--reductions-r-from (format "(FN %d %s)" it acc) "INIT" '(1 2 3)) ;; => ("(FN 1 (FN 2 (FN 3 INIT)))" "(FN 2 (FN 3 INIT))" "(FN 3 INIT)" "INIT")

-reductions `(fn list)`

Return a list of fn's intermediate reductions across list. That is, a list of the intermediate values of the accumulator when -reduce (which see) is called with the same arguments.

This function's anaphoric counterpart is --reductions.

For other folds, see also -reductions and -reductions-r.

(-reductions #'+ '(1 2 3 4)) ;; => (1 3 6 10)
(-reductions #'* '(1 2 3 4)) ;; => (1 2 6 24)
(--reductions (format "(FN %s %d)" acc it) '(1 2 3)) ;; => (1 "(FN 1 2)" "(FN (FN 1 2) 3)")

-reductions-r `(fn list)`

Return a list of fn's intermediate reductions across reversed list. That is, a list of the intermediate values of the accumulator when -reduce-r (which see) is called with the same arguments.

This function's anaphoric counterpart is --reductions-r.

For other folds, see also -reductions-r-from and -reductions.

(-reductions-r #'+ '(1 2 3 4)) ;; => (10 9 7 4)
(-reductions-r #'* '(1 2 3 4)) ;; => (24 24 12 4)
(--reductions-r (format "(FN %d %s)" it acc) '(1 2 3)) ;; => ("(FN 1 (FN 2 3))" "(FN 2 3)" 3)

-count `(pred list)`

Counts the number of items in list where (pred item) is non-nil.

(-count 'even? '(1 2 3 4 5)) ;; => 2
(--count (< it 4) '(1 2 3 4)) ;; => 3

-sum `(list)`

Return the sum of list.

(-sum ()) ;; => 0
(-sum '(1)) ;; => 1
(-sum '(1 2 3 4)) ;; => 10

-running-sum `(list)`

Return a list with running sums of items in list. list must be non-empty.

(-running-sum '(1 2 3 4)) ;; => (1 3 6 10)
(-running-sum '(1)) ;; => (1)
(-running-sum ()) ;; Wrong type argument: consp, nil

-product `(list)`

Return the product of list.

(-product ()) ;; => 1
(-product '(1)) ;; => 1
(-product '(1 2 3 4)) ;; => 24

-running-product `(list)`

Return a list with running products of items in list. list must be non-empty.

(-running-product '(1 2 3 4)) ;; => (1 2 6 24)
(-running-product '(1)) ;; => (1)
(-running-product ()) ;; Wrong type argument: consp, nil

-inits `(list)`

Return all prefixes of list.

(-inits '(1 2 3 4)) ;; => (nil (1) (1 2) (1 2 3) (1 2 3 4))
(-inits nil) ;; => (nil)
(-inits '(1)) ;; => (nil (1))

-tails `(list)`

Return all suffixes of list.

(-tails '(1 2 3 4)) ;; => ((1 2 3 4) (2 3 4) (3 4) (4) nil)
(-tails nil) ;; => (nil)
(-tails '(1)) ;; => ((1) nil)

-common-prefix `(&rest lists)`

Return the longest common prefix of lists.

(-common-prefix '(1)) ;; => (1)
(-common-prefix '(1 2) '(3 4) '(1 2)) ;; => ()
(-common-prefix '(1 2) '(1 2 3) '(1 2 3 4)) ;; => (1 2)

-common-suffix `(&rest lists)`

Return the longest common suffix of lists.

(-common-suffix '(1)) ;; => (1)
(-common-suffix '(1 2) '(3 4) '(1 2)) ;; => ()
(-common-suffix '(1 2 3 4) '(2 3 4) '(3 4)) ;; => (3 4)

-min `(list)`

Return the smallest value from list of numbers or markers.

(-min '(0)) ;; => 0
(-min '(3 2 1)) ;; => 1
(-min '(1 2 3)) ;; => 1

-min-by `(comparator list)`

Take a comparison function comparator and a list and return the least element of the list by the comparison function.

See also combinator -on which can transform the values before comparing them.

(-min-by '> '(4 3 6 1)) ;; => 1
(--min-by (> (car it) (car other)) '((1 2 3) (2) (3 2))) ;; => (1 2 3)
(--min-by (> (length it) (length other)) '((1 2 3) (2) (3 2))) ;; => (2)

-max `(list)`

Return the largest value from list of numbers or markers.

(-max '(0)) ;; => 0
(-max '(3 2 1)) ;; => 3
(-max '(1 2 3)) ;; => 3

-max-by `(comparator list)`

Take a comparison function comparator and a list and return the greatest element of the list by the comparison function.

See also combinator -on which can transform the values before comparing them.

(-max-by '> '(4 3 6 1)) ;; => 6
(--max-by (> (car it) (car other)) '((1 2 3) (2) (3 2))) ;; => (3 2)
(--max-by (> (length it) (length other)) '((1 2 3) (2) (3 2))) ;; => (1 2 3)

-frequencies `(list)`

Count the occurrences of each distinct element of list.

Return an alist of (element . n), where each element occurs n times in list.

The test for equality is done with equal, or with -compare-fn if that is non-nil.

Unfolding

Operations dual to reductions, building lists from a seed value rather than consuming a list to produce a single value.

-iterate `(fun init n)`

Return a list of iterated applications of fun to init.

This means a list of the form:

(`init` (`fun` `init`) (`fun` (`fun` `init`)) ...)

n is the length of the returned list.

(-iterate #'1+ 1 10) ;; => (1 2 3 4 5 6 7 8 9 10)
(-iterate (lambda (x) (+ x x)) 2 5) ;; => (2 4 8 16 32)
(--iterate (* it it) 2 5) ;; => (2 4 16 256 65536)

-unfold `(fun seed)`

Build a list from seed using fun.

This is "dual" operation to -reduce-r: while -reduce-r consumes a list to produce a single value, -unfold takes a seed value and builds a (potentially infinite!) list.

fun should return nil to stop the generating process, or a cons (a . b), where a will be prepended to the result and b is the new seed.

(-unfold (lambda (x) (unless (= x 0) (cons x (1- x)))) 10) ;; => (10 9 8 7 6 5 4 3 2 1)
(--unfold (when it (cons it (cdr it))) '(1 2 3 4)) ;; => ((1 2 3 4) (2 3 4) (3 4) (4))
(--unfold (when it (cons it (butlast it))) '(1 2 3 4)) ;; => ((1 2 3 4) (1 2 3) (1 2) (1))

-repeat `(n x)`

Return a new list of length n with each element being x. Return nil if n is less than 1.

(-repeat 3 :a) ;; => (:a :a :a)
(-repeat 1 :a) ;; => (:a)
(-repeat 0 :a) ;; => ()

-cycle `(list)`

Return an infinite circular copy of list. The returned list cycles through the elements of list and repeats from the beginning.

(-take 5 (-cycle '(1 2 3))) ;; => (1 2 3 1 2)
(-take 7 (-cycle '(1 "and" 3))) ;; => (1 "and" 3 1 "and" 3 1)
(-zip-lists (-cycle '(3)) '(1 2)) ;; => ((3 1) (3 2))

Predicates

Reductions of one or more lists to a boolean value.

-some `(pred list)`

Return (pred x) for the first list item where (pred x) is non-nil, else nil.

Alias: -any.

This function's anaphoric counterpart is --some.

(-some #'stringp '(1 "2" 3)) ;; => t
(--some (string-match-p "x" it) '("foo" "axe" "xor")) ;; => 1
(--some (= it-index 3) '(0 1 2)) ;; => nil

-every `(pred list)`

Return non-nil if pred returns non-nil for all items in list. If so, return the last such result of pred. Otherwise, once an item is reached for which pred returns nil, return nil without calling pred on any further list elements.

This function is like -every-p, but on success returns the last non-nil result of pred instead of just t.

This function's anaphoric counterpart is --every.

(-every #'numberp '(1 2 3)) ;; => t
(--every (string-match-p "x" it) '("axe" "xor")) ;; => 0
(--every (= it it-index) '(0 1 3)) ;; => nil

-any? `(pred list)`

Return t if (pred x) is non-nil for any x in list, else nil.

Alias: -any-p, -some?, -some-p

(-any? #'numberp '(nil 0 t)) ;; => t
(-any? #'numberp '(nil t t)) ;; => nil
(-any? #'null '(1 3 5)) ;; => nil

-all? `(pred list)`

Return t if (pred x) is non-nil for all x in list, else nil. In the latter case, stop after the first x for which (pred x) is nil, without calling pred on any subsequent elements of list.

The similar function -every is more widely useful, since it returns the last non-nil result of pred instead of just t on success.

Alias: -all-p, -every-p, -every?.

This function's anaphoric counterpart is --all?.

(-all? #'numberp '(1 2 3)) ;; => t
(-all? #'numberp '(2 t 6)) ;; => nil
(--all? (= 0 (% it 2)) '(2 4 6)) ;; => t

-none? `(pred list)`

Return t if (pred x) is nil for all x in list, else nil.

Alias: -none-p

(-none? 'even? '(1 2 3)) ;; => nil
(-none? 'even? '(1 3 5)) ;; => t
(--none? (= 0 (% it 2)) '(1 2 3)) ;; => nil

-only-some? `(pred list)`

Return t if different list items both satisfy and do not satisfy pred. That is, if pred returns both nil for at least one item, and non-nil for at least one other item in list. Return nil if all items satisfy the predicate or none of them do.

Alias: -only-some-p

(-only-some? 'even? '(1 2 3)) ;; => t
(-only-some? 'even? '(1 3 5)) ;; => nil
(-only-some? 'even? '(2 4 6)) ;; => nil

-contains? `(list element)`

Return non-nil if list contains element.

The test for equality is done with equal, or with -compare-fn if that is non-nil. As with member, the return value is actually the tail of list whose car is element.

Alias: -contains-p.

(-contains? '(1 2 3) 1) ;; => (1 2 3)
(-contains? '(1 2 3) 2) ;; => (2 3)
(-contains? '(1 2 3) 4) ;; => ()

-is-prefix? `(prefix list)`

Return non-nil if prefix is a prefix of list.

Alias: -is-prefix-p.

(-is-prefix? '(1 2 3) '(1 2 3 4 5)) ;; => t
(-is-prefix? '(1 2 3 4 5) '(1 2 3)) ;; => nil
(-is-prefix? '(1 3) '(1 2 3 4 5)) ;; => nil

-is-suffix? `(suffix list)`

Return non-nil if suffix is a suffix of list.

Alias: -is-suffix-p.

(-is-suffix? '(3 4 5) '(1 2 3 4 5)) ;; => t
(-is-suffix? '(1 2 3 4 5) '(3 4 5)) ;; => nil
(-is-suffix? '(3 5) '(1 2 3 4 5)) ;; => nil

-is-infix? `(infix list)`

Return non-nil if infix is infix of list.

This operation runs in O(n^2) time

Alias: -is-infix-p

(-is-infix? '(1 2 3) '(1 2 3 4 5)) ;; => t
(-is-infix? '(2 3 4) '(1 2 3 4 5)) ;; => t
(-is-infix? '(3 4 5) '(1 2 3 4 5)) ;; => t

-cons-pair? `(obj)`

Return non-nil if obj is a true cons pair. That is, a cons (a . b) where b is not a list.

Alias: -cons-pair-p.

(-cons-pair? '(1 . 2)) ;; => t
(-cons-pair? '(1 2)) ;; => nil
(-cons-pair? '(1)) ;; => nil

Partitioning

Functions partitioning the input list into a list of lists.

-split-at `(n list)`

Split list into two sublists after the nth element. The result is a list of two elements (take drop) where take is a new list of the first n elements of list, and drop is the remaining elements of list (not a copy). take and drop are like the results of -take and -drop, respectively, but the split is done in a single list traversal.

(-split-at 3 '(1 2 3 4 5)) ;; => ((1 2 3) (4 5))
(-split-at 17 '(1 2 3 4 5)) ;; => ((1 2 3 4 5) nil)
(-split-at 0 '(1 2 3 4 5)) ;; => (nil (1 2 3 4 5))

-split-with `(pred list)`

Split list into a prefix satisfying pred, and the rest. The first sublist is the prefix of list with successive elements satisfying pred, and the second sublist is the remaining elements that do not. The result is like performing

((-take-while `pred` `list`) (-drop-while `pred` `list`))

but in no more than a single pass through list.

(-split-with 'even? '(1 2 3 4)) ;; => (nil (1 2 3 4))
(-split-with 'even? '(2 4 5 6)) ;; => ((2 4) (5 6))
(--split-with (< it 4) '(1 2 3 4 3 2 1)) ;; => ((1 2 3) (4 3 2 1))

-split-on `(item list)`

Split the list each time item is found.

Unlike -partition-by, the item is discarded from the results. Empty lists are also removed from the result.

Comparison is done by equal.

-split-when `(fn list)`

Split the list on each element where fn returns non-nil.

Unlike -partition-by, the "matched" element is discarded from the results. Empty lists are also removed from the result.

This function can be thought of as a generalization of split-string.

(-split-when 'even? '(1 2 3 4 5 6)) ;; => ((1) (3) (5))
(-split-when 'even? '(1 2 3 4 6 8 9)) ;; => ((1) (3) (9))
(--split-when (memq it '(&optional &rest)) '(a b &optional c d &rest args)) ;; => ((a b) (c d) (args))

-separate `(pred list)`

Split list into two sublists based on whether items satisfy pred. The result is like performing

((-filter `pred` `list`) (-remove `pred` `list`))

but in a single pass through list.

(-separate (lambda (num) (= 0 (% num 2))) '(1 2 3 4 5 6 7)) ;; => ((2 4 6) (1 3 5 7))
(--separate (< it 5) '(3 7 5 9 3 2 1 4 6)) ;; => ((3 3 2 1 4) (7 5 9 6))
(-separate 'cdr '((1 2) (1) (1 2 3) (4))) ;; => (((1 2) (1 2 3)) ((1) (4)))

-partition `(n list)`

Return a new list with the items in list grouped into n-sized sublists. If there are not enough items to make the last group n-sized, those items are discarded.

(-partition 2 '(1 2 3 4 5 6)) ;; => ((1 2) (3 4) (5 6))
(-partition 2 '(1 2 3 4 5 6 7)) ;; => ((1 2) (3 4) (5 6))
(-partition 3 '(1 2 3 4 5 6 7)) ;; => ((1 2 3) (4 5 6))

-partition-all `(n list)`

Return a new list with the items in list grouped into n-sized sublists. The last group may contain less than n items.

(-partition-all 2 '(1 2 3 4 5 6)) ;; => ((1 2) (3 4) (5 6))
(-partition-all 2 '(1 2 3 4 5 6 7)) ;; => ((1 2) (3 4) (5 6) (7))
(-partition-all 3 '(1 2 3 4 5 6 7)) ;; => ((1 2 3) (4 5 6) (7))

-partition-in-steps `(n step list)`

Partition list into sublists of length n that are step items apart. Like -partition-all-in-steps, but if there are not enough items to make the last group n-sized, those items are discarded.

(-partition-in-steps 2 1 '(1 2 3 4)) ;; => ((1 2) (2 3) (3 4))
(-partition-in-steps 3 2 '(1 2 3 4)) ;; => ((1 2 3))
(-partition-in-steps 3 2 '(1 2 3 4 5)) ;; => ((1 2 3) (3 4 5))

-partition-all-in-steps `(n step list)`

Partition list into sublists of length n that are step items apart. Adjacent groups may overlap if n exceeds the step stride. Trailing groups may contain less than n items.

(-partition-all-in-steps 2 1 '(1 2 3 4)) ;; => ((1 2) (2 3) (3 4) (4))
(-partition-all-in-steps 3 2 '(1 2 3 4)) ;; => ((1 2 3) (3 4))
(-partition-all-in-steps 3 2 '(1 2 3 4 5)) ;; => ((1 2 3) (3 4 5) (5))

-partition-by `(fn list)`

Apply fn to each item in list, splitting it each time fn returns a new value.

(-partition-by 'even? ()) ;; => ()
(-partition-by 'even? '(1 1 2 2 2 3 4 6 8)) ;; => ((1 1) (2 2 2) (3) (4 6 8))
(--partition-by (< it 3) '(1 2 3 4 3 2 1)) ;; => ((1 2) (3 4 3) (2 1))

-partition-by-header `(fn list)`

Apply fn to the first item in list. That is the header value. Apply fn to each item in list, splitting it each time fn returns the header value, but only after seeing at least one other value (the body).

(--partition-by-header (= it 1) '(1 2 3 1 2 1 2 3 4)) ;; => ((1 2 3) (1 2) (1 2 3 4))
(--partition-by-header (> it 0) '(1 2 0 1 0 1 2 3 0)) ;; => ((1 2 0) (1 0) (1 2 3 0))
(-partition-by-header 'even? '(2 1 1 1 4 1 3 5 6 6 1)) ;; => ((2 1 1 1) (4 1 3 5) (6 6 1))

-partition-after-pred `(pred list)`

Partition list after each element for which pred returns non-nil.

This function's anaphoric counterpart is --partition-after-pred.

(-partition-after-pred #'booleanp ()) ;; => ()
(-partition-after-pred #'booleanp '(t t)) ;; => ((t) (t))
(-partition-after-pred #'booleanp '(0 0 t t 0 t)) ;; => ((0 0 t) (t) (0 t))

-partition-before-pred `(pred list)`

Partition directly before each time pred is true on an element of list.

(-partition-before-pred #'booleanp ()) ;; => ()
(-partition-before-pred #'booleanp '(0 t)) ;; => ((0) (t))
(-partition-before-pred #'booleanp '(0 0 t 0 t t)) ;; => ((0 0) (t 0) (t) (t))

-partition-before-item `(item list)`

Partition directly before each time item appears in list.

(-partition-before-item 3 ()) ;; => ()
(-partition-before-item 3 '(1)) ;; => ((1))
(-partition-before-item 3 '(3)) ;; => ((3))

-partition-after-item `(item list)`

Partition directly after each time item appears in list.

(-partition-after-item 3 ()) ;; => ()
(-partition-after-item 3 '(1)) ;; => ((1))
(-partition-after-item 3 '(3)) ;; => ((3))

-group-by `(fn list)`

Separate list into an alist whose keys are fn applied to the elements of list. Keys are compared by equal.

(-group-by 'even? ()) ;; => ()
(-group-by 'even? '(1 1 2 2 2 3 4 6 8)) ;; => ((nil 1 1 3) (t 2 2 2 4 6 8))
(--group-by (car (split-string it "/")) '("a/b" "c/d" "a/e")) ;; => (("a" "a/b" "a/e") ("c" "c/d"))

Indexing

Functions retrieving or sorting based on list indices and related predicates.

-elem-index `(elem list)`

Return the first index of elem in list. That is, the index within list of the first element that is equal to elem. Return nil if there is no such element.

-elem-indices `(elem list)`

Return the list of indices at which elem appears in list. That is, the indices of all elements of list equal to elem, in the same ascending order as they appear in list.

(-elem-indices 2 '(6 7 8 3 4 1)) ;; => ()
(-elem-indices "bar" '("foo" "bar" "baz")) ;; => (1)
(-elem-indices '(1 2) '((3) (1 2) (5 6) (1 2) nil)) ;; => (1 3)

-find-index `(pred list)`

Return the index of the first item satisfying pred in list. Return nil if no such item is found.

pred is called with one argument, the current list element, until it returns non-nil, at which point the search terminates.

This function's anaphoric counterpart is --find-index.

-find-last-index `(pred list)`

Return the index of the last item satisfying pred in list. Return nil if no such item is found.

Predicate pred is called with one argument each time, namely the current list element.

This function's anaphoric counterpart is --find-last-index.

-find-indices `(pred list)`

Return the list of indices in list satisfying pred.

Each element of list in turn is passed to pred. If the result is non-nil, the index of that element in list is included in the result. The returned indices are in ascending order, i.e., in the same order as they appear in list.

This function's anaphoric counterpart is --find-indices.

See also: -find-index, -elem-indices.

(-find-indices #'numberp '(a b c)) ;; => ()
(-find-indices #'numberp '(8 1 d 2 b c a 3)) ;; => (0 1 3 7)
(--find-indices (> it 5) '(2 4 1 6 3 3 5 8)) ;; => (3 7)

-grade-up `(comparator list)`

Grade elements of list using comparator relation. This yields a permutation vector such that applying this permutation to list sorts it in ascending order.

(-grade-up #'< '(3 1 4 2 1 3 3)) ;; => (1 4 3 0 5 6 2)
(let ((l '(3 1 4 2 1 3 3))) (-select-by-indices (-grade-up #'< l) l)) ;; => (1 1 2 3 3 3 4)

-grade-down `(comparator list)`

Grade elements of list using comparator relation. This yields a permutation vector such that applying this permutation to list sorts it in descending order.

(-grade-down #'< '(3 1 4 2 1 3 3)) ;; => (2 0 5 6 3 1 4)
(let ((l '(3 1 4 2 1 3 3))) (-select-by-indices (-grade-down #'< l) l)) ;; => (4 3 3 3 2 1 1)

Set operations

Operations pretending lists are sets.

-union `(list1 list2)`

Return a new list of distinct elements appearing in either list1 or list2.

The test for equality is done with equal, or with -compare-fn if that is non-nil.

(-union '(1 2 3) '(3 4 5)) ;; => (1 2 3 4 5)
(-union '(1 2 2 4) ()) ;; => (1 2 4)
(-union '(1 1 2 2) '(4 4 3 2 1)) ;; => (1 2 4 3)

-difference `(list1 list2)`

Return a new list with the distinct members of list1 that are not in list2.

The test for equality is done with equal, or with -compare-fn if that is non-nil.

(-difference () ()) ;; => ()
(-difference '(1 2 3) '(4 5 6)) ;; => (1 2 3)
(-difference '(1 2 3 4) '(3 4 5 6)) ;; => (1 2)

-intersection `(list1 list2)`

Return a new list of distinct elements appearing in both list1 and list2.

The test for equality is done with equal, or with -compare-fn if that is non-nil.

(-intersection () ()) ;; => ()
(-intersection '(1 2 3) '(4 5 6)) ;; => ()
(-intersection '(1 2 2 3) '(4 3 3 2)) ;; => (2 3)

-powerset `(list)`

Return the power set of list.

(-powerset ()) ;; => (nil)
(-powerset '(x y)) ;; => ((x y) (x) (y) nil)
(-powerset '(x y z)) ;; => ((x y z) (x y) (x z) (x) (y z) (y) (z) nil)

-permutations `(list)`

Return the distinct permutations of list.

Duplicate elements of list are determined by equal, or by -compare-fn if that is non-nil.

(-permutations ()) ;; => (nil)
(-permutations '(a a b)) ;; => ((a a b) (a b a) (b a a))
(-permutations '(a b c)) ;; => ((a b c) (a c b) (b a c) (b c a) (c a b) (c b a))

-distinct `(list)`

Return a copy of list with all duplicate elements removed.

The test for equality is done with equal, or with -compare-fn if that is non-nil.

Alias: -uniq.

(-distinct ()) ;; => ()
(-distinct '(1 1 2 3 3)) ;; => (1 2 3)
(-distinct '(t t t)) ;; => (t)

-same-items? `(list1 list2)`

Return non-nil if list1 and list2 have the same distinct elements.

The order of the elements in the lists does not matter. The lists may be of different lengths, i.e., contain duplicate elements. The test for equality is done with equal, or with -compare-fn if that is non-nil.

Alias: -same-items-p.

(-same-items? '(1 2 3) '(1 2 3)) ;; => t
(-same-items? '(1 1 2 3) '(3 3 2 1)) ;; => t
(-same-items? '(1 2 3) '(1 2 3 4)) ;; => nil

Other list operations

Other list functions not fit to be classified elsewhere.

-rotate `(n list)`

Rotate list n places to the right (left if n is negative). The time complexity is O(n).

(-rotate 3 '(1 2 3 4 5 6 7)) ;; => (5 6 7 1 2 3 4)
(-rotate -3 '(1 2 3 4 5 6 7)) ;; => (4 5 6 7 1 2 3)
(-rotate 16 '(1 2 3 4 5 6 7)) ;; => (6 7 1 2 3 4 5)

-cons* `(&rest args)`

Make a new list from the elements of args. The last 2 elements of args are used as the final cons of the result, so if the final element of args is not a list, the result is a dotted list. With no args, return nil.

(-cons* 1 2) ;; => (1 . 2)
(-cons* 1 2 3) ;; => (1 2 . 3)
(-cons* 1) ;; => 1

-snoc `(list elem &rest elements)`

Append elem to the end of the list.

This is like cons, but operates on the end of list.

If any elements are given, append them to the list as well.

(-snoc '(1 2 3) 4) ;; => (1 2 3 4)
(-snoc '(1 2 3) 4 5 6) ;; => (1 2 3 4 5 6)
(-snoc '(1 2 3) '(4 5 6)) ;; => (1 2 3 (4 5 6))

-interpose `(sep list)`

Return a new list of all elements in list separated by sep.

(-interpose "-" ()) ;; => ()
(-interpose "-" '("a")) ;; => ("a")
(-interpose "-" '("a" "b" "c")) ;; => ("a" "-" "b" "-" "c")

-interleave `(&rest lists)`

Return a new list of the first item in each list, then the second etc.

(-interleave '(1 2) '("a" "b")) ;; => (1 "a" 2 "b")
(-interleave '(1 2) '("a" "b") '("A" "B")) ;; => (1 "a" "A" 2 "b" "B")
(-interleave '(1 2 3) '("a" "b")) ;; => (1 "a" 2 "b")

-iota `(count &optional start step)`

Return a list containing count numbers. Starts from start and adds step each time. The default start is zero, the default step is 1. This function takes its name from the corresponding primitive in the apl language.

(-iota 6) ;; => (0 1 2 3 4 5)
(-iota 4 2.5 -2) ;; => (2.5 0.5 -1.5 -3.5)
(-iota -1) ;; Wrong type argument: natnump, -1

-zip-with `(fn list1 list2)`

Zip list1 and list2 into a new list using the function fn. That is, apply fn pairwise taking as first argument the next element of list1 and as second argument the next element of list2 at the corresponding position. The result is as long as the shorter list.

This function's anaphoric counterpart is --zip-with.

For other zips, see also -zip-lists and -zip-fill.

(-zip-with #'+ '(1 2 3 4) '(5 6 7)) ;; => (6 8 10)
(-zip-with #'cons '(1 2 3) '(4 5 6 7)) ;; => ((1 . 4) (2 . 5) (3 . 6))
(--zip-with (format "%s & %s" it other) '(Batman Jekyll) '(Robin Hyde)) ;; => ("Batman & Robin" "Jekyll & Hyde")

-zip-pair `(list1 list2)`

Zip list1 and list2 together.

Make a pair with the head of each list, followed by a pair with the second element of each list, and so on. The number of pairs returned is equal to the length of the shorter input list.

-zip-lists `(&rest lists)`

Zip lists together.

Group the head of each list, followed by the second element of each list, and so on. The number of returned groupings is equal to the length of the shortest input list, and the length of each grouping is equal to the number of input lists.

The return value is always a list of proper lists, in contrast to -zip which returns a list of dotted pairs when only two input lists are provided.

-zip-lists-fill `(fill-value &rest lists)`

Zip lists together, padding shorter lists with fill-value. This is like -zip-lists (which see), except it retains all elements at positions beyond the end of the shortest list. The number of returned groupings is equal to the length of the longest input list, and the length of each grouping is equal to the number of input lists.

(-zip-lists-fill 0 '(1 2) '(3 4 5) '(6)) ;; => ((1 3 6) (2 4 0) (0 5 0))
(-zip-lists-fill 0 '(1 2) '(3 4) '(5 6)) ;; => ((1 3 5) (2 4 6))
(-zip-lists-fill 0 '(1 2 3) nil) ;; => ((1 0) (2 0) (3 0))

-zip `(&rest lists)`

Zip lists together.

Group the head of each list, followed by the second element of each list, and so on. The number of returned groupings is equal to the length of the shortest input list, and the number of items in each grouping is equal to the number of input lists.

If only two lists are provided as arguments, return the groupings as a list of dotted pairs. Otherwise, return the groupings as a list of proper lists.

Since the return value changes form depending on the number of arguments, it is generally recommended to use -zip-lists instead, or -zip-pair if a list of dotted pairs is desired.

-zip-fill `(fill-value &rest lists)`

Zip lists together, padding shorter lists with fill-value. This is like -zip (which see), except it retains all elements at positions beyond the end of the shortest list. The number of returned groupings is equal to the length of the longest input list, and the length of each grouping is equal to the number of input lists.

Since the return value changes form depending on the number of arguments, it is generally recommended to use -zip-lists-fill instead, unless a list of dotted pairs is explicitly desired.

(-zip-fill 0 '(1 2 3) '(4 5)) ;; => ((1 . 4) (2 . 5) (3 . 0))
(-zip-fill 0 () '(1 2 3)) ;; => ((0 . 1) (0 . 2) (0 . 3))
(-zip-fill 0 '(1 2) '(3 4) '(5 6)) ;; => ((1 3 5) (2 4 6))

-unzip-lists `(lists)`

Unzip lists.

This works just like -zip-lists (which see), but takes a list of lists instead of a variable number of arguments, such that

(-unzip-lists (-zip-lists `args`...))

is identity (given that the lists comprising args are of the same length).

(-unzip-lists (-zip-lists '(1 2) '(3 4) '(5 6))) ;; => ((1 2) (3 4) (5 6))
(-unzip-lists '((1 2 3) (4 5) (6 7) (8 9))) ;; => ((1 4 6 8) (2 5 7 9))
(-unzip-lists '((1 2 3) (4 5 6))) ;; => ((1 4) (2 5) (3 6))

-unzip `(lists)`

Unzip lists.

This works just like -zip (which see), but takes a list of lists instead of a variable number of arguments, such that

(-unzip (-zip `l1` `l2` `l3` ...))

is identity (given that the lists are of the same length, and that -zip is not called with two arguments, because of the caveat described in its docstring).

Note in particular that calling -unzip on a list of two lists will return a list of dotted pairs.

Since the return value changes form depending on the number of lists, it is generally recommended to use -unzip-lists instead.

(-unzip (-zip '(1 2) '(3 4) '(5 6))) ;; => ((1 . 2) (3 . 4) (5 . 6))
(-unzip '((1 2 3) (4 5 6))) ;; => ((1 . 4) (2 . 5) (3 . 6))
(-unzip '((1 2 3) (4 5) (6 7) (8 9))) ;; => ((1 4 6 8) (2 5 7 9))

-pad `(fill-value &rest lists)`

Pad each of lists with fill-value until they all have equal lengths.

Ensure all lists are as long as the longest one by repeatedly appending fill-value to the shorter lists, and return the resulting lists.

(-pad 0 ()) ;; => (nil)
(-pad 0 '(1 2) '(3 4)) ;; => ((1 2) (3 4))
(-pad 0 '(1 2) '(3 4 5 6) '(7 8 9)) ;; => ((1 2 0 0) (3 4 5 6) (7 8 9 0))

-table `(fn &rest lists)`

Compute outer product of lists using function fn.

The function fn should have the same arity as the number of supplied lists.

The outer product is computed by applying fn to all possible combinations created by taking one element from each list in order. The dimension of the result is (length lists).

-table-flat `(fn &rest lists)`

Compute flat outer product of lists using function fn.

The function fn should have the same arity as the number of supplied lists.

The outer product is computed by applying fn to all possible combinations created by taking one element from each list in order. The results are flattened, ignoring the tensor structure of the result. This is equivalent to calling:

(-flatten-n (1- (length lists)) (apply '-table fn lists))

but the implementation here is much more efficient.

-first `(pred list)`

Return the first item in list for which pred returns non-nil. Return nil if no such element is found.

To get the first item in the list no questions asked, use -first-item.

Alias: -find.

This function's anaphoric counterpart is --first.

(-first #'natnump '(-1 0 1)) ;; => 0
(-first #'null '(1 2 3)) ;; => nil
(--first (> it 2) '(1 2 3)) ;; => 3

-last `(pred list)`

Return the last x in list where (pred x) is non-nil, else nil.

(-last 'even? '(1 2 3 4 5 6 3 3 3)) ;; => 6
(-last 'even? '(1 3 7 5 9)) ;; => nil
(--last (> (length it) 3) '("a" "looong" "word" "and" "short" "one")) ;; => "short"

-first-item `(list)`

Return the first item of list, or nil on an empty list.

See also: -second-item, -last-item, etc.

(-first-item ()) ;; => ()
(-first-item '(1 2 3 4 5)) ;; => 1
(let ((list (list 1 2 3))) (setf (-first-item list) 5) list) ;; => (5 2 3)

-second-item `(list)`

Return the second item of list, or nil if list is too short.

See also: -first-item, -third-item, etc.

(-second-item ()) ;; => ()
(-second-item '(1 2 3 4 5)) ;; => 2
(let ((list (list 1 2))) (setf (-second-item list) 5) list) ;; => (1 5)

-third-item `(list)`

Return the third item of list, or nil if list is too short.

See also: -second-item, -fourth-item, etc.

(-third-item ()) ;; => ()
(-third-item '(1 2)) ;; => ()
(-third-item '(1 2 3 4 5)) ;; => 3

-fourth-item `(list)`

Return the fourth item of list, or nil if list is too short.

See also: -third-item, -fifth-item, etc.

(-fourth-item ()) ;; => ()
(-fourth-item '(1 2 3)) ;; => ()
(-fourth-item '(1 2 3 4 5)) ;; => 4

-fifth-item `(list)`

Return the fifth item of list, or nil if list is too short.

See also: -fourth-item, -last-item, etc.

(-fifth-item ()) ;; => ()
(-fifth-item '(1 2 3 4)) ;; => ()
(-fifth-item '(1 2 3 4 5)) ;; => 5

-last-item `(list)`

Return the last item of list, or nil on an empty list.

-butlast `(list)`

Return a list of all items in list except for the last.

(-butlast '(1 2 3)) ;; => (1 2)
(-butlast '(1 2)) ;; => (1)
(-butlast '(1)) ;; => nil

-sort `(comparator list)`

Sort list, stably, comparing elements using comparator. Return the sorted list. list is not modified by side effects. comparator is called with two elements of list, and should return non-nil if the first element should sort before the second.

(-sort #'< '(3 1 2)) ;; => (1 2 3)
(-sort #'> '(3 1 2)) ;; => (3 2 1)
(--sort (< it other) '(3 1 2)) ;; => (1 2 3)

-list `(arg)`

Ensure arg is a list. If arg is already a list, return it as is (not a copy). Otherwise, return a new list with arg as its only element.

Another supported calling convention is (-list &rest args). In this case, if arg is not a list, a new list with all of args as elements is returned. This use is supported for backward compatibility and is otherwise deprecated.

(-list 1) ;; => (1)
(-list ()) ;; => ()
(-list '(1 2 3)) ;; => (1 2 3)

-fix `(fn list)`

Compute the (least) fixpoint of fn with initial input list.

fn is called at least once, results are compared with equal.

(-fix (lambda (l) (-non-nil (--mapcat (-split-at (/ (length it) 2) it) l))) '((1 2 3))) ;; => ((1) (2) (3))
(let ((l '((starwars scifi) (jedi starwars warrior)))) (--fix (-uniq (--mapcat (cons it (cdr (assq it l))) it)) '(jedi book))) ;; => (jedi starwars warrior scifi book)

Tree operations

Functions pretending lists are trees.

-tree-seq `(branch children tree)`

Return a sequence of the nodes in tree, in depth-first search order.

branch is a predicate of one argument that returns non-nil if the passed argument is a branch, that is, a node that can have children.

children is a function of one argument that returns the children of the passed branch node.

Non-branch nodes are simply copied.

(-tree-seq 'listp 'identity '(1 (2 3) 4 (5 (6 7)))) ;; => ((1 (2 3) 4 (5 (6 7))) 1 (2 3) 2 3 4 (5 (6 7)) 5 (6 7) 6 7)
(-tree-seq 'listp 'reverse '(1 (2 3) 4 (5 (6 7)))) ;; => ((1 (2 3) 4 (5 (6 7))) (5 (6 7)) (6 7) 7 6 5 4 (2 3) 3 2 1)
(--tree-seq (vectorp it) (append it nil) [1 [2 3] 4 [5 [6 7]]]) ;; => ([1 [2 3] 4 [5 [6 7]]] 1 [2 3] 2 3 4 [5 [6 7]] 5 [6 7] 6 7)

-tree-map `(fn tree)`

Apply fn to each element of tree while preserving the tree structure.

(-tree-map '1+ '(1 (2 3) (4 (5 6) 7))) ;; => (2 (3 4) (5 (6 7) 8))
(-tree-map '(lambda (x) (cons x (expt 2 x))) '(1 (2 3) 4)) ;; => ((1 . 2) ((2 . 4) (3 . 8)) (4 . 16))
(--tree-map (length it) '("<body>" ("<p>" "text" "</p>") "</body>")) ;; => (6 (3 4 4) 7)

-tree-map-nodes `(pred fun tree)`

Call fun on each node of tree that satisfies pred.

If pred returns nil, continue descending down this node. If pred returns non-nil, apply fun to this node and do not descend further.

(-tree-map-nodes 'vectorp (lambda (x) (-sum (append x nil))) '(1 [2 3] 4 (5 [6 7] 8))) ;; => (1 5 4 (5 13 8))
(-tree-map-nodes 'keywordp (lambda (x) (symbol-name x)) '(1 :foo 4 ((5 6 :bar) :baz 8))) ;; => (1 ":foo" 4 ((5 6 ":bar") ":baz" 8))
(--tree-map-nodes (eq (car-safe it) 'add-mode) (-concat it (list :mode 'emacs-lisp-mode)) '(with-mode emacs-lisp-mode (foo bar) (add-mode a b) (baz (add-mode c d)))) ;; => (with-mode emacs-lisp-mode (foo bar) (add-mode a b :mode emacs-lisp-mode) (baz (add-mode c d :mode emacs-lisp-mode)))

-tree-reduce `(fn tree)`

Use fn to reduce elements of list tree. If elements of tree are lists themselves, apply the reduction recursively.

fn is first applied to first element of the list and second element, then on this result and third element from the list etc.

See -reduce-r for how exactly are lists of zero or one element handled.

(-tree-reduce '+ '(1 (2 3) (4 5))) ;; => 15
(-tree-reduce 'concat '("strings" (" on" " various") ((" levels")))) ;; => "strings on various levels"
(--tree-reduce (cond ((stringp it) (concat it " " acc)) (t (let ((sn (symbol-name it))) (concat "<" sn ">" acc "</" sn ">")))) '(body (p "some words") (div "more" (b "bold") "words"))) ;; => "<body><p>some words</p> <div>more <b>bold</b> words</div></body>"

-tree-reduce-from `(fn init-value tree)`

Use fn to reduce elements of list tree. If elements of tree are lists themselves, apply the reduction recursively.

fn is first applied to init-value and first element of the list, then on this result and second element from the list etc.

The initial value is ignored on cons pairs as they always contain two elements.

(-tree-reduce-from '+ 1 '(1 (1 1) ((1)))) ;; => 8
(--tree-reduce-from (-concat acc (list it)) nil '(1 (2 3 (4 5)) (6 7))) ;; => ((7 6) ((5 4) 3 2) 1)

-tree-mapreduce `(fn folder tree)`

Apply fn to each element of tree, and make a list of the results. If elements of tree are lists themselves, apply fn recursively to elements of these nested lists.

Then reduce the resulting lists using folder and initial value init-value. See -reduce-r-from.

This is the same as calling -tree-reduce after -tree-map but is twice as fast as it only traverse the structure once.

(-tree-mapreduce 'list 'append '(1 (2 (3 4) (5 6)) (7 (8 9)))) ;; => (1 2 3 4 5 6 7 8 9)
(--tree-mapreduce 1 (+ it acc) '(1 (2 (4 9) (2 1)) (7 (4 3)))) ;; => 9
(--tree-mapreduce 0 (max acc (1+ it)) '(1 (2 (4 9) (2 1)) (7 (4 3)))) ;; => 3

-tree-mapreduce-from `(fn folder init-value tree)`

Apply fn to each element of tree, and make a list of the results. If elements of tree are lists themselves, apply fn recursively to elements of these nested lists.

Then reduce the resulting lists using folder and initial value init-value. See -reduce-r-from.

This is the same as calling -tree-reduce-from after -tree-map but is twice as fast as it only traverse the structure once.

(-tree-mapreduce-from 'identity '* 1 '(1 (2 (3 4) (5 6)) (7 (8 9)))) ;; => 362880
(--tree-mapreduce-from (+ it it) (cons it acc) nil '(1 (2 (4 9) (2 1)) (7 (4 3)))) ;; => (2 (4 (8 18) (4 2)) (14 (8 6)))
(concat "{" (--tree-mapreduce-from (cond ((-cons-pair? it) (concat (symbol-name (car it)) " -> " (symbol-name (cdr it)))) (t (concat (symbol-name it) " : {"))) (concat it (unless (or (equal acc "}") (equal (substring it (1- (length it))) "{")) ", ") acc) "}" '((elisp-mode (foo (bar . booze)) (baz . qux)) (c-mode (foo . bla) (bum . bam))))) ;; => "{elisp-mode : {foo : {bar -> booze}, baz -> qux}, c-mode : {foo -> bla, bum -> bam}}"

-clone `(list)`

Create a deep copy of list. The new list has the same elements and structure but all cons are replaced with new ones. This is useful when you need to clone a structure such as plist or alist.

(let* ((a (list (list 1))) (b (-clone a))) (setcar (car a) 2) b) ;; => ((1))

Threading macros

Macros that conditionally combine sequential forms for brevity or readability.

-> `(x &optional form &rest more)`

Thread the expr through the forms. Insert x as the second item in the first form, making a list of it if it is not a list already. If there are more forms, insert the first form as the second item in second form, etc.

(-> '(2 3 5)) ;; => (2 3 5)
(-> '(2 3 5) (append '(8 13))) ;; => (2 3 5 8 13)
(-> '(2 3 5) (append '(8 13)) (-slice 1 -1)) ;; => (3 5 8)

->> `(x &optional form &rest more)`

Thread the expr through the forms. Insert x as the last item in the first form, making a list of it if it is not a list already. If there are more forms, insert the first form as the last item in second form, etc.

(->> '(1 2 3) (-map 'square)) ;; => (1 4 9)
(->> '(1 2 3) (-map 'square) (-remove 'even?)) ;; => (1 9)
(->> '(1 2 3) (-map 'square) (-reduce '+)) ;; => 14

--> `(x &rest forms)`

Starting with the value of x, thread each expression through forms.

Insert x at the position signified by the symbol it in the first form. If there are more forms, insert the first form at the position signified by it in the second form, etc.

(--> "def" (concat "abc" it "ghi")) ;; => "abcdefghi"
(--> "def" (concat "abc" it "ghi") (upcase it)) ;; => "ABCDEFGHI"
(--> "def" (concat "abc" it "ghi") upcase) ;; => "ABCDEFGHI"

-as-> `(value variable &rest forms)`

Starting with value, thread variable through forms.

In the first form, bind variable to value. In the second form, bind variable to the result of the first form, and so forth.

(-as-> 3 my-var (1+ my-var) (list my-var) (mapcar (lambda (ele) (* 2 ele)) my-var)) ;; => (8)
(-as-> 3 my-var 1+) ;; => 4
(-as-> 3 my-var) ;; => 3

-some-> `(x &optional form &rest more)`

When expr is non-nil, thread it through the first form (via ->), and when that result is non-nil, through the next form, etc.

(-some-> '(2 3 5)) ;; => (2 3 5)
(-some-> 5 square) ;; => 25
(-some-> 5 even? square) ;; => nil

-some->> `(x &optional form &rest more)`

When expr is non-nil, thread it through the first form (via ->>), and when that result is non-nil, through the next form, etc.

(-some->> '(1 2 3) (-map 'square)) ;; => (1 4 9)
(-some->> '(1 3 5) (-last 'even?) (+ 100)) ;; => nil
(-some->> '(2 4 6) (-last 'even?) (+ 100)) ;; => 106

-some--> `(expr &rest forms)`

Thread expr through forms via -->, while the result is non-nil. When expr evaluates to non-nil, thread the result through the first of forms, and when that result is non-nil, thread it through the next form, etc.

(-some--> "def" (concat "abc" it "ghi")) ;; => "abcdefghi"
(-some--> nil (concat "abc" it "ghi")) ;; => nil
(-some--> '(0 1) (-remove #'natnump it) (append it it) (-map #'1+ it)) ;; => ()

-doto `(init &rest forms)`

Evaluate init and pass it as argument to forms with ->. The result of evaluating init is threaded through each of forms individually using ->, which see. The return value is result, which forms may have modified by side effect.

(-doto (list 1 2 3) pop pop) ;; => (3)
(-doto (cons 1 2) (setcar 3) (setcdr 4)) ;; => (3 . 4)
(gethash 'k (--doto (make-hash-table) (puthash 'k 'v it))) ;; => v

Binding

Macros that combine let and let* with destructuring and flow control.

-when-let `((var val) &rest body)`

If val evaluates to non-nil, bind it to var and execute body.

Note: binding is done according to -let.

(-when-let (match-index (string-match "d" "abcd")) (+ match-index 2)) ;; => 5
(-when-let ((&plist :foo foo) (list :foo "foo")) foo) ;; => "foo"
(-when-let ((&plist :foo foo) (list :bar "bar")) foo) ;; => nil

-when-let* `(vars-vals &rest body)`

If all vals evaluate to true, bind them to their corresponding vars and execute body. vars-vals should be a list of (var val) pairs.

Note: binding is done according to -let*. vals are evaluated sequentially, and evaluation stops after the first nil val is encountered.

(-when-let* ((x 5) (y 3) (z (+ y 4))) (+ x y z)) ;; => 15
(-when-let* ((x 5) (y nil) (z 7)) (+ x y z)) ;; => nil

-if-let `((var val) then &rest else)`

If val evaluates to non-nil, bind it to var and do then, otherwise do else.

Note: binding is done according to -let.

(-if-let (match-index (string-match "d" "abc")) (+ match-index 3) 7) ;; => 7
(--if-let (even? 4) it nil) ;; => t

-if-let* `(vars-vals then &rest else)`

If all vals evaluate to true, bind them to their corresponding vars and do then, otherwise do else. vars-vals should be a list of (var val) pairs.

Note: binding is done according to -let*. vals are evaluated sequentially, and evaluation stops after the first nil val is encountered.

(-if-let* ((x 5) (y 3) (z 7)) (+ x y z) "foo") ;; => 15
(-if-let* ((x 5) (y nil) (z 7)) (+ x y z) "foo") ;; => "foo"
(-if-let* (((_ _ x) '(nil nil 7))) x) ;; => 7

-let `(varlist &rest body)`

Bind variables according to varlist then eval body.

varlist is a list of lists of the form (pattern source). Each pattern is matched against the source "structurally". source is only evaluated once for each pattern. Each pattern is matched recursively, and can therefore contain sub-patterns which are matched against corresponding sub-expressions of source.

All the SOURCEs are evalled before any symbols are bound (i.e. "in parallel").

If varlist only contains one (pattern source) element, you can optionally specify it using a vector and discarding the outer-most parens. Thus

(-let ((`pattern` `source`)) ...)

becomes

(-let [`pattern` `source`] ...).

-let uses a convention of not binding places (symbols) starting with _ whenever it's possible. You can use this to skip over entries you don't care about. However, this is not always possible (as a result of implementation) and these symbols might get bound to undefined values.

Following is the overview of supported patterns. Remember that patterns can be matched recursively, so every a, b, aK in the following can be a matching construct and not necessarily a symbol/variable.

Symbol:

a - bind the `source` to `a`.  This is just like regular `let`.

Conses and lists:

(a) - bind `car` of cons/list to `a`

(a . b) - bind car of cons to `a` and `cdr` to `b`

(a b) - bind car of list to `a` and `cadr` to `b`

(a1 a2 a3 ...) - bind 0th car of list to `a1`, 1st to `a2`, 2nd to `a3`...

(a1 a2 a3 ... aN . rest) - as above, but bind the `n`th cdr to `rest`.

Vectors:

[a] - bind 0th element of a non-list sequence to `a` (works with
      vectors, strings, bit arrays...)

[a1 a2 a3 ...] - bind 0th element of non-list sequence to `a0`, 1st to
                 `a1`, 2nd to `a2`, ...
                 If the `pattern` is shorter than `source`, the values at
                 places not in `pattern` are ignored.
                 If the `pattern` is longer than `source`, an `error` is
                 thrown.

[a1 a2 a3 ... &rest rest] - as above, but bind the rest of
                            the sequence to `rest`.  This is
                            conceptually the same as improper list
                            matching (a1 a2 ... aN . rest)

Key/value stores:

(&plist key0 a0 ... keyN aN) - bind value mapped by keyK in the
                               `source` plist to aK.  If the
                               value is not found, aK is `nil`.
                               Uses `plist-get` to fetch values.

(&alist key0 a0 ... keyN aN) - bind value mapped by keyK in the
                               `source` alist to aK.  If the
                               value is not found, aK is `nil`.
                               Uses `assoc` to fetch values.

(&hash key0 a0 ... keyN aN) - bind value mapped by keyK in the
                              `source` hash table to aK.  If the
                              value is not found, aK is `nil`.
                              Uses `gethash` to fetch values.

Further, special keyword &keys supports "inline" matching of plist-like key-value pairs, similarly to &keys keyword of cl-defun.

(a1 a2 ... aN &keys key1 b1 ... keyN bK)

This binds n values from the list to a1 ... aN, then interprets the cdr as a plist (see key/value matching above).

a shorthand notation for kv-destructuring exists which allows the patterns be optionally left out and derived from the key name in the following fashion:

a key :foo is converted into foo pattern,
a key 'bar is converted into bar pattern,
a key "baz" is converted into baz pattern.

That is, the entire value under the key is bound to the derived variable without any further destructuring.

This is possible only when the form following the key is not a valid pattern (i.e. not a symbol, a cons cell or a vector). Otherwise the matching proceeds as usual and in case of an invalid spec fails with an error.

Thus the patterns are normalized as follows:

 ;; derive all the missing patterns
 (&plist :foo 'bar "baz") => (&plist :foo foo 'bar bar "baz" baz)

 ;; we can specify some but not others
 (&plist :foo 'bar explicit-bar) => (&plist :foo foo 'bar explicit-bar)

 ;; nothing happens, we store :foo in x
 (&plist :foo x) => (&plist :foo x)

 ;; nothing happens, we match recursively
 (&plist :foo (a b c)) => (&plist :foo (a b c))

You can name the source using the syntax symbol &as pattern. This syntax works with lists (proper or improper), vectors and all types of maps.

(list &as a b c) (list 1 2 3)

binds a to 1, b to 2, c to 3 and list to (1 2 3).

Similarly:

(bounds &as beg . end) (cons 1 2)

binds beg to 1, end to 2 and bounds to (1 . 2).

(items &as first . rest) (list 1 2 3)

binds first to 1, rest to (2 3) and items to (1 2 3)

[vect &as _ b c] [1 2 3]

binds b to 2, c to 3 and vect to [1 2 3] (_ avoids binding as usual).

(plist &as &plist :b b) (list :a 1 :b 2 :c 3)

binds b to 2 and plist to (:a 1 :b 2 :c 3). Same for &alist and &hash.

This is especially useful when we want to capture the result of a computation and destructure at the same time. Consider the form (function-returning-complex-structure) returning a list of two vectors with two items each. We want to capture this entire result and pass it to another computation, but at the same time we want to get the second item from each vector. We can achieve it with pattern

(result &as [_ a] [_ b]) (function-returning-complex-structure)

Note: Clojure programmers may know this feature as the ":as binding". The difference is that we put the &as at the front because we need to support improper list binding.

(-let (([a (b c) d] [1 (2 3) 4])) (list a b c d)) ;; => (1 2 3 4)
(-let [(a b c . d) (list 1 2 3 4 5 6)] (list a b c d)) ;; => (1 2 3 (4 5 6))
(-let [(&plist :foo foo :bar bar) (list :baz 3 :foo 1 :qux 4 :bar 2)] (list foo bar)) ;; => (1 2)

-let* `(varlist &rest body)`

Bind variables according to varlist then eval body.

varlist is a list of lists of the form (pattern source). Each pattern is matched against the source structurally. source is only evaluated once for each pattern.

Each source can refer to the symbols already bound by this varlist. This is useful if you want to destructure source recursively but also want to name the intermediate structures.

See -let for the list of all possible patterns.

(-let* (((a . b) (cons 1 2)) ((c . d) (cons 3 4))) (list a b c d)) ;; => (1 2 3 4)
(-let* (((a . b) (cons 1 (cons 2 3))) ((c . d) b)) (list a b c d)) ;; => (1 (2 . 3) 2 3)
(-let* (((&alist "foo" foo "bar" bar) (list (cons "foo" 1) (cons "bar" (list 'a 'b 'c)))) ((a b c) bar)) (list foo a b c bar)) ;; => (1 a b c (a b c))

-lambda `(match-form &rest body)`

Return a lambda which destructures its input as match-form and executes body.

Note that you have to enclose the match-form in a pair of parens, such that:

(-lambda (x) body)
(-lambda (x y ...) body)

has the usual semantics of lambda. Furthermore, these get translated into normal lambda, so there is no performance penalty.

See -let for a description of the destructuring mechanism.

(-map (-lambda ((x y)) (+ x y)) '((1 2) (3 4) (5 6))) ;; => (3 7 11)
(-map (-lambda ([x y]) (+ x y)) '([1 2] [3 4] [5 6])) ;; => (3 7 11)
(funcall (-lambda ((_ . a) (_ . b)) (-concat a b)) '(1 2 3) '(4 5 6)) ;; => (2 3 5 6)

-setq `([match-form val] ...)`

Bind each match-form to the value of its val.

match-form destructuring is done according to the rules of -let.

This macro allows you to bind multiple variables by destructuring the value, so for example:

(-setq (a b) x
       (&plist :c c) plist)

expands roughly speaking to the following code

(setq a (car x)
      b (cadr x)
      c (plist-get plist :c))

Care is taken to only evaluate each val once so that in case of multiple assignments it does not cause unexpected side effects.

(let (a) (-setq a 1) a) ;; => 1
(let (a b) (-setq (a b) (list 1 2)) (list a b)) ;; => (1 2)
(let (c) (-setq (&plist :c c) (list :c "c")) c) ;; => "c"

Side effects

Functions iterating over lists for side effect only.

-each `(list fn)`

Call fn on each element of list. Return nil; this function is intended for side effects.

Its anaphoric counterpart is --each.

For access to the current element's index in list, see -each-indexed.

(let (l) (-each '(1 2 3) (lambda (x) (push x l))) l) ;; => (3 2 1)
(let (l) (--each '(1 2 3) (push it l)) l) ;; => (3 2 1)
(-each '(1 2 3) #'identity) ;; => nil

-each-while `(list pred fn)`

Call fn on each item in list, while (pred item) is non-nil. Once an item is reached for which pred returns nil, fn is no longer called. Return nil; this function is intended for side effects.

Its anaphoric counterpart is --each-while.

(let (l) (-each-while '(2 4 5 6) #'even? (lambda (x) (push x l))) l) ;; => (4 2)
(let (l) (--each-while '(1 2 3 4) (< it 3) (push it l)) l) ;; => (2 1)
(let ((s 0)) (--each-while '(1 3 4 5) (< it 5) (setq s (+ s it))) s) ;; => 8

-each-indexed `(list fn)`

Call fn on each index and element of list. For each item at index in list, call (funcall fn index item). Return nil; this function is intended for side effects.

-each-r `(list fn)`

Call fn on each element of list in reversed order. Return nil; this function is intended for side effects.

Its anaphoric counterpart is --each-r.

(let (l) (-each-r '(1 2 3) (lambda (x) (push x l))) l) ;; => (1 2 3)
(let (l) (--each-r '(1 2 3) (push it l)) l) ;; => (1 2 3)
(-each-r '(1 2 3) #'identity) ;; => nil

-each-r-while `(list pred fn)`

Call fn on each item in reversed list, while (pred item) is non-nil. Once an item is reached for which pred returns nil, fn is no longer called. Return nil; this function is intended for side effects.

Its anaphoric counterpart is --each-r-while.

(let (l) (-each-r-while '(2 4 5 6) #'even? (lambda (x) (push x l))) l) ;; => (6)
(let (l) (--each-r-while '(1 2 3 4) (>= it 3) (push it l)) l) ;; => (3 4)
(let ((s 0)) (--each-r-while '(1 2 3 5) (> it 1) (setq s (+ s it))) s) ;; => 10

-dotimes `(num fn)`

Call fn num times, presumably for side effects. fn is called with a single argument on successive integers running from 0, inclusive, to num, exclusive. fn is not called if num is less than 1.

This function's anaphoric counterpart is --dotimes.

(let (s) (-dotimes 3 (lambda (n) (push n s))) s) ;; => (2 1 0)
(let (s) (-dotimes 0 (lambda (n) (push n s))) s) ;; => ()
(let (s) (--dotimes 5 (push it s)) s) ;; => (4 3 2 1 0)

Destructive operations

Macros that modify variables holding lists.

!cons `(car cdr)`

Destructive: Set cdr to the cons of car and cdr.

(let (l) (!cons 5 l) l) ;; => (5)
(let ((l '(3))) (!cons 5 l) l) ;; => (5 3)

!cdr `(list)`

Destructive: Set list to the cdr of list.

(let ((l '(3))) (!cdr l) l) ;; => ()
(let ((l '(3 5))) (!cdr l) l) ;; => (5)

Function combinators

Functions that manipulate and compose other functions.

-partial `(fun &rest args)`

Return a function that is a partial application of fun to args. args is a list of the first n arguments to pass to fun. The result is a new function which does the same as fun, except that the first n arguments are fixed at the values with which this function was called.

(funcall (-partial #'+ 5)) ;; => 5
(funcall (-partial #'- 5) 3) ;; => 2
(funcall (-partial #'+ 5 2) 3) ;; => 10

-rpartial `(fn &rest args)`

Return a function that is a partial application of fn to args. args is a list of the last n arguments to pass to fn. The result is a new function which does the same as fn, except that the last n arguments are fixed at the values with which this function was called. This is like -partial, except the arguments are fixed starting from the right rather than the left.

(funcall (-rpartial #'- 5)) ;; => -5
(funcall (-rpartial #'- 5) 8) ;; => 3
(funcall (-rpartial #'- 5 2) 10) ;; => 3

-juxt `(&rest fns)`

Return a function that is the juxtaposition of fns. The returned function takes a variable number of args, applies each of fns in turn to args, and returns the list of results.

(funcall (-juxt) 1 2) ;; => ()
(funcall (-juxt #'+ #'- #'* #'/) 7 5) ;; => (12 2 35 1)
(mapcar (-juxt #'number-to-string #'1+) '(1 2)) ;; => (("1" 2) ("2" 3))

-compose `(&rest fns)`

Compose fns into a single composite function. Return a function that takes a variable number of args, applies the last function in fns to args, and returns the result of calling each remaining function on the result of the previous function, right-to-left. If no fns are given, return a variadic identity function.

(funcall (-compose #'- #'1+ #'+) 1 2 3) ;; => -7
(funcall (-compose #'identity #'1+) 3) ;; => 4
(mapcar (-compose #'not #'stringp) '(nil "")) ;; => (t nil)

-applify `(fn)`

Return a function that applies fn to a single list of args. This changes the arity of fn from taking n distinct arguments to taking 1 argument which is a list of n arguments.

(funcall (-applify #'+) nil) ;; => 0
(mapcar (-applify #'+) '((1 1 1) (1 2 3) (5 5 5))) ;; => (3 6 15)
(funcall (-applify #'<) '(3 6)) ;; => t

-on `(op trans)`

Return a function that calls trans on each arg and op on the results. The returned function takes a variable number of arguments, calls the function trans on each one in turn, and then passes those results as the list of arguments to op, in the same order.

For example, the following pairs of expressions are morally equivalent:

(funcall (-on #'+ #'1+) 1 2 3) = (+ (1+ 1) (1+ 2) (1+ 3))
(funcall (-on #'+ #'1+))       = (+)

(-sort (-on #'< #'length) '((1 2 3) (1) (1 2))) ;; => ((1) (1 2) (1 2 3))
(funcall (-on #'min #'string-to-number) "22" "2" "1" "12") ;; => 1
(-min-by (-on #'> #'length) '((1 2 3) (4) (1 2))) ;; => (4)

-flip `(fn)`

Return a function that calls fn with its arguments reversed. The returned function takes the same number of arguments as fn.

For example, the following two expressions are morally equivalent:

(funcall (-flip #'-) 1 2) = (- 2 1)

-rotate-args `(n fn)`

Return a function that calls fn with args rotated n places to the right. The returned function takes the same number of arguments as fn, rotates the list of arguments n places to the right (left if n is negative) just like -rotate, and applies fn to the result.

-const `(c)`

Return a function that returns c ignoring any additional arguments.

In types: a -> b -> a

(funcall (-const 2) 1 3 "foo") ;; => 2
(mapcar (-const 1) '("a" "b" "c" "d")) ;; => (1 1 1 1)
(-sum (mapcar (-const 1) '("a" "b" "c" "d"))) ;; => 4

-cut `(&rest params)`

Take n-ary function and n arguments and specialize some of them. Arguments denoted by <> will be left unspecialized.

See srfi-26 for detailed description.

(funcall (-cut list 1 <> 3 <> 5) 2 4) ;; => (1 2 3 4 5)
(-map (-cut funcall <> 5) `(1+ 1- ,(lambda (x) (/ 1.0 x)))) ;; => (6 4 0.2)
(-map (-cut <> 1 2 3) '(list vector string)) ;; => ((1 2 3) [1 2 3] "\1\2\3")

-not `(pred)`

Return a predicate that negates the result of pred. The returned predicate passes its arguments to pred. If pred returns nil, the result is non-nil; otherwise the result is nil.

-orfn `(&rest preds)`

Return a predicate that returns the first non-nil result of preds. The returned predicate takes a variable number of arguments, passes them to each predicate in preds in turn until one of them returns non-nil, and returns that non-nil result without calling the remaining preds. If all preds return nil, or if no preds are given, the returned predicate returns nil.

-andfn `(&rest preds)`

Return a predicate that returns non-nil if all preds do so. The returned predicate p takes a variable number of arguments and passes them to each predicate in preds in turn. If any one of preds returns nil, p also returns nil without calling the remaining preds. If all preds return non-nil, p returns the last such value. If no preds are given, p always returns non-nil.

-iteratefn `(fn n)`

Return a function fn composed n times with itself.

fn is a unary function. If you need to use a function of higher arity, use -applify first to turn it into a unary function.

With n = 0, this acts as identity function.

In types: (a -> a) -> Int -> a -> a.

This function satisfies the following law:

(funcall (-iteratefn fn n) init) = (-last-item (-iterate fn init (1+ n))).

(funcall (-iteratefn (lambda (x) (* x x)) 3) 2) ;; => 256
(funcall (-iteratefn '1+ 3) 1) ;; => 4
(funcall (-iteratefn 'cdr 3) '(1 2 3 4 5)) ;; => (4 5)

-fixfn `(fn &optional equal-test halt-test)`

Return a function that computes the (least) fixpoint of fn.

fn must be a unary function. The returned lambda takes a single argument, x, the initial value for the fixpoint iteration. The iteration halts when either of the following conditions is satisfied:

Iteration converges to the fixpoint, with equality being tested using equal-test. If equal-test is not specified, equal is used. For functions over the floating point numbers, it may be necessary to provide an appropriate approximate comparison test.
halt-test returns a non-nil value. halt-test defaults to a simple counter that returns t after -fixfn-max-iterations, to guard against infinite iteration. Otherwise, halt-test must be a function that accepts a single argument, the current value of x, and returns non-nil as long as iteration should continue. In this way, a more sophisticated convergence test may be supplied by the caller.

The return value of the lambda is either the fixpoint or, if iteration halted before converging, a cons with car halted and cdr the final output from halt-test.

In types: (a -> a) -> a -> a.

(funcall (-fixfn #'cos #'approx=) 0.7) ;; ~> 0.7390851332151607
(funcall (-fixfn (lambda (x) (expt (+ x 10) 0.25))) 2.0) ;; => 1.8555845286409378
(funcall (-fixfn #'sin #'approx=) 0.1) ;; => (halted . t)

-prodfn `(&rest fns)`

Return a function that applies each of fns to each of a list of arguments.

Takes a list of n functions and returns a function that takes a list of length n, applying ith function to ith element of the input list. Returns a list of length n.

In types (for n=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d)

This function satisfies the following laws:

  (-compose (-prodfn f g ...)
            (-prodfn f' g' ...))
= (-prodfn (-compose f f')
           (-compose g g')
           ...)

  (-prodfn f g ...)
= (-juxt (-compose f (-partial #'nth 0))
         (-compose g (-partial #'nth 1))
         ...)

  (-compose (-prodfn f g ...)
            (-juxt f' g' ...))
= (-juxt (-compose f f')
         (-compose g g')
         ...)

  (-compose (-partial #'nth n)
            (-prod f1 f2 ...))
= (-compose fn (-partial #'nth n))

(funcall (-prodfn #'1+ #'1- #'number-to-string) '(1 2 3)) ;; => (2 1 "3")
(-map (-prodfn #'1- #'1+) '((1 2) (3 4) (5 6))) ;; => ((0 3) (2 5) (4 7))
(apply #'+ (funcall (-prodfn #'length #'string-to-number) '((t) "5"))) ;; => 6

Contribute

Yes, please do. Pure functions in the list manipulation realm only, please. There’s a suite of examples/tests in dev/examples.el, so remember to add tests for your additions, or I might break them later.

You’ll find the repo at:

https://github.com/magnars/dash.el

Run the tests with:

make check

Regenerate the docs with:

make docs

I highly recommend that you install these as a pre-commit hook, so that the tests are always running and the docs are always in sync:

cp dev/pre-commit.sh .git/hooks/pre-commit

Oh, and don’t edit README.md or dash.texi directly; they are auto-generated. Change readme-template.md or dash-template.texi instead, respectively.

To ensure that dash.el can be distributed with GNU ELPA or Emacs, we require that all contributors assign copyright to the Free Software Foundation. For more on this, see (info "(emacs) Copyright Assignment").

Contributors

Matus Goljer contributed lots of features and functions.
Takafumi Arakaki contributed -group-by.
tali713 is the author of -applify.
Víctor M. Valenzuela contributed -repeat.
Nic Ferrier contributed -cons*.
Wilfred Hughes contributed -slice, -first-item, and -last-item.
Emanuel Evans contributed -if-let, -when-let, and -insert-at.
Johan Andersson contributed -sum, -product, and -same-items?.
Christina Whyte contributed -compose.
Steve Lamb contributed -cycle, -pad, -annotate, -zip-fill, and a variadic version of -zip.
Fredrik Bergroth made the -if-let family use -let destructuring and improved the script for generating documentation.
Mark Oteiza contributed -iota and the script to create an Info manual.
Vasilij Schneidermann contributed -some.
William West made -fixfn more robust at handling floats.
Cam Saul contributed -some->, -some->>, and -some-->.
Basil L. Contovounesios contributed -common-prefix, -common-suffix, and various other improvements.
Paul Pogonyshev contributed -each-r and -each-r-while.

Thanks!

New contributors are very welcome. See the Contribute section above.

License

Author: Magnar Sveen magnars@gmail.com

This program 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.

This program 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 this program. 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!

akermu/emacs-libvterm

Emacs libvterm integration

Introduction

Emacs-libvterm (vterm) is fully-fledged terminal emulator inside GNU Emacs based on libvterm, a C library. As a result of using compiled code (instead of elisp), emacs-libvterm is fully capable, fast, and it can seamlessly handle large outputs.

Warning

This package is in active development and, while being stable enough to be used as a daily-driver, it is currently in alpha stage. This means that occasionally the public interface will change (for example names of options or functions). A list of recent breaking changes is in appendix. Moreover, emacs-libvterm deals directly with some low-level operations, hence, bugs can lead to segmentation faults and crashes. If that happens, please report the problem.

Given that eshell, shell, and (ansi-)term are Emacs built-in, why should I use vterm?

The short answer is: unparalleled performance and compatibility with standard command-line tools.

For the long answer, let us discuss the differences between eshell, shell, term and vterm:

eshell: it is a shell completely implemented in Emacs Lisp. It is well-integrated in Emacs and it runs on Windows. It does not support command line tools that require terminal manipulation capabilities (e.g., ncdu, nmtui, ...).
shell: it interfaces with a standard shell (e.g., bash). It reads an input from Emacs, sends it to the shell, and reports back the output from the shell. As such, like eshell, it does not support interactive commands, especially those that directly handle how the output should be displayed (e.g., htop).
term: it is a terminal emulator written in elisp. term runs a shell (similarly to other terminal emulators like Gnome Terminal) and programs can directly manipulate the output using escape codes. Hence, many interactive applications (like the one aforementioned) work with term. However, term and ansi-term do not implement all the escapes codes needed, so some programs do not work properly. Moreover, term has inferior performance compared to standalone terminals, especially with large bursts of output.
vterm: like term it is a terminal emulator. Unlike term, the core of vterm is an external library written in C, libvterm. For this reason, vterm outperforms term and has a nearly universal compatibility with terminal applications.

Vterm is not for you if you are using Windows, or if you cannot set up Emacs with support for modules. Otherwise, you should try vterm, as it provides a superior terminal experience in Emacs.

Using vterm is like using Gnome Terminal inside Emacs: Vterm is fully-featured and fast, but is not as well integrated in Emacs as eshell (yet), so some of the editing keybinding you are used to using may not work. For example, evil-mode is currently not supported (though, users can enable VI emulation in their shells). This is because keys are sent directly to the shell. We are constantly working to improve this.

Installation

Requirements

Before installing emacs-libvterm, you need to make sure you have installed

GNU Emacs (>= 25.1) with module support. You can check that, by verifying that module-file-suffix is not nil.
cmake (>= 3.11)
libtool-bin (related issues: #66 #85)
OPTIONAL: libvterm (>= 0.2). This library can be found in the official repositories of most distributions (e.g., Arch, Debian, Fedora, Gentoo, openSUSE, Ubuntu). Typical names are libvterm (Arch, Fedora, Gentoo, openSUSE), or libvterm-dev (Debian, Ubuntu). If not available, libvterm will be downloaded during the compilation process. Some distributions (e.g. Ubuntu < 20.04, Debian < 11) have versions of libvterm that are too old. If you find compilation errors related to VTERM_COLOR, you should not use your system libvterm. See FAQ for more details.

From MELPA

vterm is available on MELPA, and it can be installed as a normal package. If the requirements are satisfied (mainly, Emacs was built with support for modules), vterm will compile the module the first time it is run. This is the recommended way to install vterm.

vterm can be installed from MELPA with use-package by adding the following lines to your init.el:

(use-package vterm
    :ensure t)

To take full advantage of the capabilities of vterm, you should configure your shell too. Read about this in the section shell-side configuration.

Manual installation

Clone the repository:

git clone https://github.com/akermu/emacs-libvterm.git

By default, vterm will try to find if libvterm is installed. If it is not found, emacs-libvterm will download the latest version available of libvterm (from here), compile it, and use it. If you always want to use the vendored version as opposed to the one on you system, set USE_SYSTEM_LIBVTERM to no. To do this, change cmake .. with cmake -DUSE_SYSTEM_LIBVTERM=no .. in the following instructions.

Build the module with:

cd emacs-libvterm
mkdir -p build
cd build
cmake ..
make

And add this to your init.el:

(add-to-list 'load-path "path/to/emacs-libvterm")
(require 'vterm)

Or, with use-package:

(use-package vterm
  :load-path  "path/to/emacs-libvterm/")

vterm and Ubuntu

20.04

Using vterm on Ubuntu requires additional steps. The latest LTS version (20.04) ships without CMake installed and Emacs27 is not yet available from Ubuntu's package repository.

The basic steps for getting vterm to work on Ubuntu 20.04 are:

Ensure Emacs27 is installed
Install cmake, libtool, and libtool-bin

There are a few options for installing Emacs27 on Ubuntu 20.04:

Compile Emacs27 from source
Install Emacs27 from Snap
Install Emacs27 from Kevin Kelley's PPA

In any case, if you have an older Emacs version you will need to purge it before proceeding:

Purge Emacs

sudo apt --purge remove emacs
sudo apt autoremove

Installing Emacs27 from Kevin Kelley PPA

sudo add-apt-repository ppa:kelleyk/emacs
sudo apt install emacs27

If you get an error about emacs27_common during the install process:

Errors were encountered while processing:
 /tmp/apt-dpkg-install-RVK8CA/064-emacs27-common_27.1~1.git86d8d76aa3-kk2+20.04_all.deb

run

sudo apt --purge remove emacs-common
sudo apt --fix-broken install

Installing Emacs27 from Snap

I hesitate to include SNAP here, because I ran into a number of GTK Theme parsing errors, and Fontconfig errors when I tested it, and reverted to installing from Kevin Kelley's PPA. YMMV

sudo snap install emacs --classic

Install CMake and Libtool

In Ubuntu 20.04 CMake (v3.16.3-1ubuntu1) and Libtool can be installed with

sudo apt install cmake
sudo apt install libtool
sudo apt install libtool-bin

18.04

Using vterm on Ubuntu 18.04 requires additional steps. 18.04 ships with a version of CMake that is too old for vterm and GNU Emacs is not compiled with support for dynamical module loading.

It is possible to install GNU Emacs with module support from Kevin Kelley's PPA. The binary in Ubuntu Emacs Lisp PPA is currently broken and leads to segmentation faults (see #185). In case Emacs is already on the system, you need to purge it before proceeding with the following commands.

sudo add-apt-repository ppa:kelleyk/emacs
sudo apt update
sudo apt-get install emacs26

A way to install a recent version of CMake (>= 3.11) is with linuxbrew.

brew install cmake

In some cases, /bin/sh needs to be relinked to /bin/bash for the compilation to work (see, #216).

Pull requests to improve support for Ubuntu are welcome (e.g., simplifying the installation).

Some releases of Ubuntu (e.g., 18.04) ship with a old version of libvterm that can lead to compilation errors. If you have this problem, see the FAQ for a solution.

GNU Guix

vterm and its dependencies are available in GNU Guix as emacs-vterm. The package can be installed with guix package -i emacs-vterm.

Shell-side configuration

Some of the most useful features in vterm (e.g., directory-tracking and prompt-tracking or message passing) require shell-side configurations. The main goal of these additional functions is to enable the shell to send information to vterm via properly escaped sequences. A function that helps in this task, vterm_printf, is defined below. This function is widely used throughout this readme.

For bash or zsh, put this in your .zshrc or .bashrc

vterm_printf() {
    if [ -n "$TMUX" ] \
        && { [ "${TERM%%-*}" = "tmux" ] \
            || [ "${TERM%%-*}" = "screen" ]; }; then
        # Tell tmux to pass the escape sequences through
        printf "\ePtmux;\e\e]%s\007\e\\" "$1"
    elif [ "${TERM%%-*}" = "screen" ]; then
        # GNU screen (screen, screen-256color, screen-256color-bce)
        printf "\eP\e]%s\007\e\\" "$1"
    else
        printf "\e]%s\e\\" "$1"
    fi
}

This works also for dash.

For fish put this in your ~/.config/fish/config.fish:

function vterm_printf;
    if begin; [  -n "$TMUX" ]  ; and  string match -q -r "screen|tmux" "$TERM"; end
        # tell tmux to pass the escape sequences through
        printf "\ePtmux;\e\e]%s\007\e\\" "$argv"
    else if string match -q -- "screen*" "$TERM"
        # GNU screen (screen, screen-256color, screen-256color-bce)
        printf "\eP\e]%s\007\e\\" "$argv"
    else
        printf "\e]%s\e\\" "$argv"
    end
end

Debugging and testing

If you have successfully built the module, you can test it by executing the following command in the build directory:

make run

Usage

`vterm`

Open a terminal in the current window.

`vterm-other-window`

Open a terminal in another window.

`vterm-copy-mode`

When you enable vterm-copy-mode, the terminal buffer behaves like a normal read-only text buffer: you can search, copy text, etc. The default keybinding to toggle vterm-copy-mode is C-c C-t. When a region is selected, it is possible to copy the text and leave vterm-copy-mode with the enter key.

If no region is selected when the enter key is pressed it will copy the current line from start to end. If vterm-copy-exclude-prompt is true it will skip the prompt and not include it in the copy.

`vterm-clear-scrollback`

vterm-clear-scrollback does exactly what the name suggests: it clears the current buffer from the data that it is not currently visible. vterm-clear-scrollback is bound to C-c C-l. This function is typically used with the clear function provided by the shell to clear both screen and scrollback. In order to achieve this behavior, you need to add a new shell alias.

For zsh, put this in your .zshrc:

if [[ "$INSIDE_EMACS" = 'vterm' ]]; then
    alias clear='vterm_printf "51;Evterm-clear-scrollback";tput clear'
fi

For bash, put this in your .bashrc:

if [ "$INSIDE_EMACS" = 'vterm' ]; then
    clear() {
        vterm_printf "51;Evterm-clear-scrollback";
        tput clear;
    }
fi

For fish:

if [ "$INSIDE_EMACS" = 'vterm' ]
    function clear
        vterm_printf "51;Evterm-clear-scrollback";
        tput clear;
    end
end

These aliases take advantage of the fact that vterm can execute elisp commands, as explained below.

If it possible to automatically clear the scrollback when the screen is cleared by setting the variable vterm-clear-scrollback-when-clearing: When vterm-clear-scrollback-when-clearing is non nil, C-l clears both the screen and the scrollback. When is nil, C-l only clears the screen. The opposite behavior can be achieved by using the universal prefix (i.e., calling C-u C-l).

Customization

`vterm-shell`

Shell to run in a new vterm. It defaults to $SHELL.

`vterm-environment`

To add more environment variables there is the custom vterm-environment which has a similar format to the internal Emacs variable process-environment. You can check the documentation with C-h v process-environment for more details.

`vterm-term-environment-variable`

Value for the TERM environment variable. It defaults to xterm-256color. If eterm-256color is installed, setting vterm-term-environment-variable to eterm-color improves the rendering of colors in some systems.

`vterm-kill-buffer-on-exit`

If set to t, buffers are killed when the associated process is terminated (for example, by logging out the shell). Keeping buffers around it is useful if you need to copy or manipulate the content.

`vterm-module-cmake-args`

Compilation flags and arguments to be given to CMake when compiling the module. This string is directly passed to CMake, so it uses the same syntax. At the moment, its main use is for compiling vterm using the system libvterm instead of the one downloaded from GitHub. You can find all the arguments and flags available with cmake -LA in the build directory.

`vterm-copy-exclude-prompt`

Controls whether or not to exclude the prompt when copying a line in vterm-copy-mode. Using the universal prefix before calling vterm-copy-mode-done will invert the value for that call, allowing you to temporarily override the setting. When a prompt is not found, the whole line is copied.

`vterm-use-vterm-prompt-detection-method`

The variable vterm-use-vterm-prompt-detection-method determines whether to use the vterm prompt tracking, if false it use the regexp in vterm-copy-prompt-regexp to search for the prompt.

`vterm-enable-manipulate-selection-data-by-osc52`

Vterm support copy text to Emacs kill ring and system clipboard by using OSC 52. See https://invisible-island.net/xterm/ctlseqs/ctlseqs.html for more info about OSC 52. For example: send "blabla" to kill ring: printf "\033]52;c;$(printf "%s" "blabla" | base64)\a"

tmux can share its copy buffer to terminals by supporting OSC 52 (like iterm2 and xterm), you can enable this feature for tmux by:

set -g set-clipboard on         #osc 52 copy paste share with iterm
set -ga terminal-overrides ',xterm*:XT:Ms=\E]52;%p1%s;%p2%s\007'
set -ga terminal-overrides ',screen*:XT:Ms=\E]52;%p1%s;%p2%s\007'

The clipboard querying/clearing functionality offered by OSC 52 is not implemented here, And for security reason, this feature is disabled by default.

This feature needs the new way of handling strings with a struct VTermStringFragment in libvterm. You'd better compile emacs-libvterm with cmake -DUSE_SYSTEM_LIBVTERM=no ... If you don't do that, when the content you want to copy is too long, it would be truncated by a bug in libvterm.

`vterm-buffer-name-string`

When vterm-buffer-name-string is not nil, vterm renames automatically its own buffers with vterm-buffer-name-string. This string can contain the character %s, which is substituted with the title (as defined by the shell, see below). A possible value for vterm-buffer-name-string is vterm %s, according to which all the vterm buffers will be named "vterm TITLE".

This requires some shell-side configuration to print the title. For example to set the name "HOSTNAME:PWD", you can use the following:

For zsh,

autoload -U add-zsh-hook
add-zsh-hook -Uz chpwd (){ print -Pn "\e]2;%m:%2~\a" }

For bash,

PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND; }"'echo -ne "\033]0;${HOSTNAME}:${PWD}\007"'

For fish,

function fish_title
    hostname
    echo ":"
    prompt_pwd
end

See zsh and bash and fish documentations.

`vterm-always-compile-module`

Vterm needs vterm-module to work. This can be compiled externally, or vterm will ask the user whether to build the module when vterm is first called. To avoid this question and always compile the module, set vterm-always-compile-module to t.

`vterm-copy-mode-remove-fake-newlines`

When not-nil fake newlines are removed on entering copy mode. vterm inserts fake-newlines purely for rendering. When using vterm-copy-mode these are in conflict with many emacs functions like isearch-forward. if this variable is not-nil the fake-newlines are removed on entering copy-mode and re-inserted on leaving copy mode. Also truncate-lines is set to t on entering copy-mode and set to nil on leaving.

`vterm-tramp-shells`

The shell that gets run in the vterm for tramp.

This has to be a list of pairs of the format: (TRAMP-METHOD SHELL)

The TRAMP-METHOD is a method string as used by tramp (e.g., "ssh"). Use t as TRAMP-METHOD to specify a default shell for all methods. Specific methods always take precedence over t.

Set SHELL to 'login-shell to use the user's login shell on the remote host. The login-shell detection currently works for POSIX-compliant remote hosts that have the getent command (regular GNU/Linux distros, *BSDs, but not MacOS X unfortunately). You can specify an additional second SHELL command as a fallback that is used when the login-shell detection fails, e.g., '(("ssh" login-shell "/bin/bash") ...) If no second SHELL command is specified with 'login-shell, vterm will fall back to tramp's shell.

Examples:

Use the default login shell for all methods, except for docker. '((t login-shell) ("docker" "/bin/sh"))
Use the default login shell for ssh and scp, fall back to "/bin/bash". Use tramp's default shell for all other methods. '(("ssh" login-shell "/bin/bash") ("scp" login-shell "/bin/bash"))

Keybindings

If you want a key to be sent to the terminal, bind it to vterm--self-insert, or remove it from vterm-mode-map. By default, vterm.el binds most of the C-<char> and M-<char> keys, <f1> through <f12> and some special keys like <backspace> and <return>. Sending a keyboard interrupt is bound to C-c C-c.

In order to send a keypress that is already recognized by Emacs, such as C-g, use the interactive function vterm-send-next-key. This can be bound to a key in the vterm-mode-map like C-q, in which case pressing C-q C-g will send a C-g key to the terminal, and so on for other modified keys:

(define-key vterm-mode-map (kbd "C-q") #'vterm-send-next-key)

This can be useful for controlling an application running in the terminal, such as Emacs or Nano.

Fonts

You can change the font (the face) used in a vterm with the following code:

(add-hook 'vterm-mode-hook
          (lambda ()
            (set (make-local-variable 'buffer-face-mode-face) 'fixed-pitch)
                 (buffer-face-mode t)))

Where instead of 'fixed-pitch you specify the face you want to use. The example reported here can be used to force vterm to use a mono-spaced font (the fixed-pitch face). This is useful when your default font in Emacs is a proportional font.

In addition to that, you can disable some text properties (bold, underline, reverse video) setting the relative option to t (vterm-disable-bold, vterm-disable-underline, or vterm-disable-inverse-video).

You can use another font for vterm buffer

(add-hook 'vterm-mode-hook
          (lambda ()
               (set (make-local-variable 'buffer-face-mode-face) '(:family "IosevkaTerm Nerd Font"))
               (buffer-face-mode t))

Blink cursor

When vterm-ignore-blink-cursor is t, vterm will ignore request from application to turn on or off cursor blink.

If nil, cursor in any window may begin to blink or not blink because blink-cursor-mode is a global minor mode in Emacs, you can use M-x blink-cursor-mode to toggle.

Colors

Customize the following faces to your liking. It is possible to specify different colors for foreground and background via the :foreground and :background attributes.

vterm-color-black
vterm-color-red
vterm-color-green
vterm-color-yellow
vterm-color-blue
vterm-color-magenta
vterm-color-cyan
vterm-color-white
vterm-color-bright-black
vterm-color-bright-red
vterm-color-bright-green
vterm-color-bright-yellow
vterm-color-bright-blue
vterm-color-bright-magenta
vterm-color-bright-cyan
vterm-color-bright-white

Directory tracking and Prompt tracking

vterm supports directory tracking. If this feature is enabled, the default directory in Emacs and the current working directory in vterm are synced. As a result, interactive functions that ask for a path or a file (e.g., dired or find-file) will do so starting from the current location.

And vterm supports prompt tracking. If this feature is enabled, Emacs knows where the prompt ends, you needn't customize term-prompt-regexp any more. Then you can use vterm-next-prompt and vterm-previous-prompt moving to end of next/previous prompt. The default keybinding is C-c C-n and C-c C-p.

And vterm-beginning-of-line would move the point to the first character after the shell prompt on this line. If the point is already there, move to the beginning of the line. The default keybinding is C-a in vterm-copy-mode.

And vterm--at-prompt-p would check whether the cursor is at the point just after the shell prompt.

Directory tracking and Prompt tracking requires some configuration, as the shell has to be instructed to share the relevant information with Emacs. The following pieces of code assume that you have the function vterm_printf as defined in section shell-side configuration.

For zsh, put this at the end of your .zshrc:

vterm_prompt_end() {
    vterm_printf "51;A$(whoami)@$(hostname):$(pwd)"
}
setopt PROMPT_SUBST
PROMPT=$PROMPT'%{$(vterm_prompt_end)%}'

For bash, put this at the end of your .bashrc:

vterm_prompt_end(){
    vterm_printf "51;A$(whoami)@$(hostname):$(pwd)"
}
PS1=$PS1'\[$(vterm_prompt_end)\]'

For fish, put this in your ~/.config/fish/config.fish:

function vterm_prompt_end;
    vterm_printf '51;A'(whoami)'@'(hostname)':'(pwd)
end
functions --copy fish_prompt vterm_old_fish_prompt
function fish_prompt --description 'Write out the prompt; do not replace this. Instead, put this at end of your file.'
    # Remove the trailing newline from the original prompt. This is done
    # using the string builtin from fish, but to make sure any escape codes
    # are correctly interpreted, use %b for printf.
    printf "%b" (string join "\n" (vterm_old_fish_prompt))
    vterm_prompt_end
end

Here we are using the function vterm_printf that we have discussed above, so make sure that this function is defined in your configuration file.

Directory tracking works on remote servers too. In case the hostname of your remote machine does not match the actual hostname needed to connect to that server, change $(hostname) with the correct one. For example, if the correct hostname is foo and the username is bar, you should have something like

HOSTNAME=foo
USER=baz
vterm_printf "51;A$USER@$HOSTNAME:$(pwd)"

Message passing

vterm can read and execute commands. At the moment, a command is passed by providing a specific escape sequence. For example, to evaluate

(message "Hello!")

use

printf "\e]51;Emessage \"Hello\!\"\e\\"
# or
vterm_printf "51;Emessage \"Hello\!\""

The commands that are understood are defined in the setting vterm-eval-cmds.

As split-string-and-unquote is used the parse the passed string, double quotes and backslashes need to be escaped via backslash. A convenient shell function to automate the substitution is

bash or zsh:

vterm_cmd() {
    local vterm_elisp
    vterm_elisp=""
    while [ $# -gt 0 ]; do
        vterm_elisp="$vterm_elisp""$(printf '"%s" ' "$(printf "%s" "$1" | sed -e 's|\\|\\\\|g' -e 's|"|\\"|g')")"
        shift
    done
    vterm_printf "51;E$vterm_elisp"
}

fish:

function vterm_cmd --description 'Run an Emacs command among the ones been defined in vterm-eval-cmds.'
    set -l vterm_elisp ()
    for arg in $argv
        set -a vterm_elisp (printf '"%s" ' (string replace -a -r '([\\\\"])' '\\\\\\\\$1' $arg))
    end
    vterm_printf '51;E'(string join '' $vterm_elisp)
end

Now we can write shell functions to call the ones defined in vterm-eval-cmds.

find_file() {
    vterm_cmd find-file "$(realpath "${@:-.}")"
}

say() {
    vterm_cmd message "%s" "$*"
}

Or for fish:

function find_file
    set -q argv[1]; or set argv[1] "."
    vterm_cmd find-file (realpath "$argv")
end

function say
    vterm_cmd message "%s" "$argv"
end

This newly defined find_file function can now be used inside vterm as

find_file name_of_file_in_local_directory

If you call find_file without specifying any file (you just execute find_file in your shell), dired will open with the current directory.

As an example, say you like having files opened below the current window. You could add the command to do it on the lisp side like so:

(push (list "find-file-below"
            (lambda (path)
              (if-let* ((buf (find-file-noselect path))
                        (window (display-buffer-below-selected buf nil)))
                  (select-window window)
                (message "Failed to open file: %s" path))))
      vterm-eval-cmds)

Then add the command in your .bashrc file.

open_file_below() {
    vterm_cmd find-file-below "$(realpath "${@:-.}")"
}

Then you can open any file from inside your shell.

open_file_below ~/Documents

Shell-side configuration files

The configurations described in earlier sections are combined in etc/. These can be appended to or loaded into your user configuration file. Alternatively, they can be installed system-wide, for example in /etc/bash/bashrc.d/, /etc/profile.d/ (for zsh), or /etc/fish/conf.d/ for fish.

When using vterm Emacs sets the environment variable INSIDE_EMACS in the subshell to ‘vterm’. Usually the programs check this variable to determine whether they are running inside Emacs.

Vterm also sets an extra variable EMACS_VTERM_PATH to the place where the vterm library is installed. This is very useful because when vterm is installed from melpa the Shell-side configuration files are in the EMACS_VTERM_PATH inside the /etc sub-directory. After a package update, the directory name changes, so, a code like this in your bashrc could be enough to load always the latest version of the file from the right location without coping any file manually.

if [[ "$INSIDE_EMACS" = 'vterm' ]] \
    && [[ -n ${EMACS_VTERM_PATH} ]] \
    && [[ -f ${EMACS_VTERM_PATH}/etc/emacs-vterm-bash.sh ]]; then
	source ${EMACS_VTERM_PATH}/etc/emacs-vterm-bash.sh
fi

Frequently Asked Questions and Problems

How can I increase the size of the scrollback?

By default, the scrollback can contain up to 1000 lines per each vterm buffer. You can increase this up to 100000 by changing the variable vterm-max-scrollback. If you want to increase it further, you have to edit the file vterm-module.h, change the variable SB_MAX, and set the new value for vterm-max-scrollback. The potential maximum memory consumption of vterm buffers increases with vterm-max-scrollback, so setting SB_MAX to extreme values may lead to system instabilities and crashes.

How can I automatically close vterm buffers when the process is terminated?

There is an option for that: set vterm-kill-buffer-on-exit to t.

The package does not compile, I have errors related to `VTERM_COLOR`.

The version of libvterm installed on your system is too old. You should let emacs-libvterm download libvterm for you. You can either uninstall your libvterm, or instruct Emacs to ignore the system libvterm. If you are compiling from Emacs, you can do this by setting:

(setq vterm-module-cmake-args "-DUSE_SYSTEM_LIBVTERM=no")

and compile again. If you are compiling with CMake, use the flag -DUSE_SYSTEM_LIBVTERM=no.

`<C-backspace>` doesn't kill previous word.

This can be fixed by rebinding the key to what C-w does:

(define-key vterm-mode-map (kbd "<C-backspace>")
    (lambda () (interactive) (vterm-send-key (kbd "C-w"))))

`counsel-yank-pop` doesn't work.

Add this piece of code to your configuration file to make counsel use the correct function to yank in vterm buffers.

(defun vterm-counsel-yank-pop-action (orig-fun &rest args)
  (if (equal major-mode 'vterm-mode)
      (let ((inhibit-read-only t)
            (yank-undo-function (lambda (_start _end) (vterm-undo))))
        (cl-letf (((symbol-function 'insert-for-yank)
               (lambda (str) (vterm-send-string str t))))
            (apply orig-fun args)))
    (apply orig-fun args)))

(advice-add 'counsel-yank-pop-action :around #'vterm-counsel-yank-pop-action)

How can I get the local directory without shell-side configuration?

We recommend that you set up shell-side configuration for reliable directory tracking. If you cannot do it, a possible workaround is the following.

On most GNU/Linux systems, you can read current directory from /proc:

(defun vterm-directory-sync ()
  "Synchronize current working directory."
  (interactive)
  (when vterm--process
    (let* ((pid (process-id vterm--process))
           (dir (file-truename (format "/proc/%d/cwd/" pid))))
      (setq default-directory dir))))

A possible application of this function is in combination with find-file:

(advice-add #'find-file :before #'vterm-directory-sync)

This method does not work on remote machines.

How can I get the directory tracking in a more understandable way?

If you looked at the recommended way to set-up directory tracking, you will have noticed that it requires printing obscure code like \e]2;%m:%2~\a (unless you are using fish).

There is another way to achieve this behavior. Define a shell function, on a local host you can simply use

vterm_set_directory() {
    vterm_cmd update-pwd "$PWD/"
}

On a remote one, use instead

vterm_set_directory() {
    vterm_cmd update-pwd "/-:""$USER""@""$HOSTNAME"":""$PWD/"
}

Then, for zsh, add this function to the chpwd hook:

autoload -U add-zsh-hook
add-zsh-hook -Uz chpwd (){ vterm_set_directory }

For bash, append it to the prompt:

PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND; }vterm_set_directory"

Finally, add update-pwd to the list of commands that Emacs is allowed to execute from vterm:

(add-to-list 'vterm-eval-cmds '("update-pwd" (lambda (path) (setq default-directory path))))

When evil-mode is enabled, the cursor moves back in normal state, and this messes directory tracking

evil-collection provides a solution for this problem. If you do not want to use evil-collection, you can add the following code:

(defun evil-collection-vterm-escape-stay ()
"Go back to normal state but don't move
cursor backwards. Moving cursor backwards is the default vim behavior but it is
not appropriate in some cases like terminals."
(setq-local evil-move-cursor-back nil))

(add-hook 'vterm-mode-hook #'evil-collection-vterm-escape-stay)

Related packages

vterm-toggle: Toggles between a vterm and the current buffer
multi-libvterm: Multiterm for emacs-libvterm

Appendix

Breaking changes

Obsolete variables will be removed in version 0.1.

August 2022

vterm-send-C-[a-z] vterm-send-M-[a-z] vterm-define-key vterm-send-{up/down/left/right/prior/next/meta-dot/meta-comma/ctrl-slash} were obsolete, please use vterm-send or vterm-send-key or vterm--self-insert instead.

October 2020

vterm-disable-bold-font was renamed to vterm-disable-bold to uniform it with the other similar options.

July 2020

vterm-use-vterm-prompt was renamed to vterm-use-vterm-prompt-detection-method.
vterm-kill-buffer-on-exit is set to t by default.

April 2020

vterm-clear-scrollback was renamed to vterm-clear-scrollback-when-clearning.
vterm-set-title-functions was removed. In its place, there is a new custom option vterm-buffer-name-string. See vterm-buffer-name-string for documentation.

renzmann/treesit-auto

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

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

#+html:

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

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

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

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

Installation ~treesit-auto~ is available from [[https://melpa.org/][MELPA]]. After following [[https://melpa.org/#/getting-started][their setup]], you can use your preferred package manager. If that's the default =package.el=, simply =M-x package-refresh-contents= and then

#+begin_example M-x package-install RET treesit-auto #+end_example

If you want a local clone of the repository, rather than just a copy of the source, you might instead use =package-vc-install=

#+begin_src example M-x package-vc-install RET https://github.com/renzmann/treesit-auto.git #+end_src

Then, in your Emacs configuration file (=~/.emacs.d/init.el=),

#+begin_src emacs-lisp (use-package treesit-auto :config (global-treesit-auto-mode)) #+end_src

For most users, this will be enough. There are some nifty things you might want to enable, though, which are covered in the "Configuration" section below.

Configuration example This is how I configure =treesit-auto= for my own personal use.

#+begin_src emacs-lisp (use-package treesit-auto :custom (treesit-auto-install 'prompt) :config (treesit-auto-add-to-auto-mode-alist 'all) (global-treesit-auto-mode)) #+end_src

What this package does Emacs 29, while featuring =treesit.el= and a convenient =treesit-install-language-grammar=, [[https://archive.casouri.cc/note/2023/tree-sitter-in-emacs-29/index.html][will not feature an intelligent way to choose]] between a default mode, such as =python-mode=, and its tree-sitter enhanced version, =python-ts-mode=. This package attempts to remedy that by adjusting the =major-mode-remap-alist= and =treesit-language-source-alist= variables in order to get the following behavior:

1. If the grammar is installed, then switch to the appropriate tree-sitter mode:

In this case, assuming we open a Python buffer, and the [[https://github.com/tree-sitter/tree-sitter-python][Python tree-sitter grammar]] is installed, then Emacs will use =python-ts-mode= instead of =python-mode=.

2. The grammar is NOT installed and treesit-auto-install is non-nil:

When the grammar is not installed and ~treesit-auto-install~ is t, then upon activating any major mode that has a corresponding tree-sitter mode, the grammar will be downloaded and compiled using ~treesit-install-language-grammar~. Emacs will then activate the tree-sitter major mode for that buffer.

~prompt~ is like t, except a message will be displayed in the echo area asking for a yes/no response before attempting the installation.

As an example for both cases: if I visit a Python file and didn't already have the grammar installed, I wind up with an installed grammar and a buffer using ~python-ts-mode~.

Otherwise, when ~treesit-auto-install~ is nil, it will try to fall back to another major mode as described in the following two rules.

3. If the grammar is NOT installed, and a fallback is specified

Most languages will have a fallback mode specified, such as =python-ts-mode= falling back to =python-mode=, if the grammar is not installed. If you ever need to double-check what that fallback will be, you can double check what's in the recipe for that language like this:

#+begin_example (treesit-auto-recipe-remap (alist-get 'python treesit-auto-lang-recipe-alist)) ⇒ python-mode #+end_example

See "Configuration/Configuring behavior for a specific language" in case you would like to specify different fallback modes than the default.

4. The grammar is installed, but there is no fallback mode

You can optionally use the =treesit-auto-add-to-auto-mode-alist= function to ensure that your installed tree-sitter languages have their corresponding =...-ts-mode= added to =auto-mode-alist=, so that Emacs opens the buffer in that =...-ts-mode=, rather than the default =Fundamental= mode.

Supposing for instance we don't have =typescript-mode= installed, then even if we /do/ have =typescript-ts-mode= installed along with the typescript grammar compiled in =~/.emacs.d/tree-sitter/=, Emacs still won't use =typescript-ts-mode= unless you also added ='("\.ts\'" . typescript-ts-mode)= to =auto-mode-alist=. By calling =(treesit-auto-add-to-auto-mode-alist)= in your configuration, this modification to =auto-mode-alist= is done automatically for you.

5. All other cases...

This is the most general case, where the grammar is not installed, ~treesit-auto-install~ is nil, and no fallback mode is specified in the language recipe present on =treesit-auto-recipe-list=. In this case, we still gain the benefit of quickly installing grammars through =treesit-install-language-grammar= without having the build the recipe interactively, but =treesit-auto= will make no attempt to switch away from the tree-sitter mode.

Configuration If you have modified =treesit-language-source-alist= through =setq=, then it is recommended to put any configuration of this package AFTER that =setq=.

** Choose which languages =treesit-auto= should consider

You can globally alter the behavior of =treesit-auto= to only consider a specific set of languages by setting the =treesit-auto-langs= list to a set of language symbols. By default, this list includes every possible language that =treesit-auto= supports, so you can use =M-x describe-variable RET treesit-auto-langs= to see what the options are.

One way to use this variable is to just set it manually:

#+begin_src emacs-lisp (setq treesit-auto-langs '(python rust go)) #+end_src

Now, =treesit-auto= features will only ever affect Python, Rust, and Go files. Running =treesit-auto-install-all= will only install these three grammars, and no automatic prompting/installation will occur when visiting a buffer that is not one of these three, either.

Another method is to disable specific languages by just removing them from this list:

#+begin_src emacs-lisp (delete 'awk treesit-auto-langs) #+end_src

Here, =treesit-auto= behaves as it normally would for all languages /except/ AWK.

** Automatically install grammars if they are missing The =treesit-auto-install= variable controls whether a grammar should be installed automatically when activating a major mode compatible with tree-sitter.

=nil=, the default, means =treesit-auto= won't try to install anything, and will rely on the fallback logic outlined above
=t= means =treesit-auto= should always try to clone and install a grammar when missing
~prompt~ will cause a yes/no prompt to appear in the minibuffer before attempting installation

#+begin_src emacs-lisp (setq treesit-auto-install 'prompt) #+end_src

Then, supposing I don't have =libtree-sitter-python.so= (or its mac/Windows equivalent) under =~/.emacs.d/tree-sitter= (or anywhere else in =treesit-extra-load-path=), visiting a Python file or calling =M-x python-ts-mode= will generate this prompt:

#+begin_example Tree-sitter grammar for python is missing. Would you like to install it from https://github.com/tree-sitter/tree-sitter-python? (y or n) #+end_example

Responding with "yes" will use =treesit-install-language-grammar= to go fetch and compile the missing grammar.

The other function that respects this variable is =treesit-auto-install-all=. When =treesit-auto-install= is t, using =M-x treesit-auto-install-all= will skip all prompts. Otherwise, it will ask before attempting the installation.

** Configuring behavior for a specific language The variable =treesit-auto-recipe-list= keeps track of all the language "recipes." These control how =treesit-auto= decides which modes to upgrade/downgrade to/from, where the source code of the language grammar is hosted, and which C/C++ compiler to use. Each recipe can take these arguments:

#+begin_example :lang :ts-mode :remap :url :revision :abi14-revision :requires :source-dir :cc :c++ #+end_example

To create a recipe, use =make-treesit-auto-recipe=:

#+begin_src elisp (setq my-js-tsauto-config (make-treesit-auto-recipe :lang 'javascript :ts-mode 'js-ts-mode :remap '(js2-mode js-mode javascript-mode) :url "https://github.com/tree-sitter/tree-sitter-javascript" :revision "master" :source-dir "src" :ext "\.js\'"))

(add-to-list 'treesit-auto-recipe-list my-js-tsauto-config) #+end_src

Here, we've specified that the tree-sitter compiler will be creating a file named =libtree-sitter-javascript.so= (or =.dylib= or =.dll=), based on the =:lang= field. The corresponding tree-sitter mode in Emacs is called =js-ts-mode=, and all of =js2-mode=, =js-mode=, and =javascript-mode= should attempt switching to the =js-ts-mode=, if possible.

Moreover, since =js-2-mode= is first under the =:remap= section, that is the "primary fallback." Meaning that if the tree-sitter grammar is not available, it will be the first mode tried. If that doesn't work, it will try =js-mode=, and =javascript-mode=, in that order, until one /does/ work. If only one fallback needs to be specified, a single quoted symbol is also acceptable. For instance, =python-ts-mode= just uses =:remap 'python-mode= in this argument position.

If a grammar mandates any other grammars be installed as a dependency, the =:requires= keyword can specify a language symbol or list of symbols that should be installed. One example of this is found in the TypeScript recipe, which specifies =:requires 'tsx=, since activating =typescript-ts-mode= on some Emacs builds will attempt to load the TSX grammar.

The =:url=, =:revision=, =:source-dir=, =:cc=, and =:c++= arguments are all documented under =treesit-language-source-alist=, which is part of base Emacs, not this package.

*** =:abi14-revision= and =version-mismatch= errors If treesit reports reports =(treesit): The installed language grammar for foo cannot be located or has problems (version-mismatch): 15= it means that the grammar is using ABI 15, but Emacs only supports earlier versions (e.g. Emacs 30.1 supports ABI versions 13 and 14). To fix this, set =:abi14-revision= to a git tag that corresponds to an ABI 14 version in the grammar repository.

Finding the right tag can require some trial and error, by checking out different revisions of the grammar and building them. Once you've built a grammar you can use the script =check_treesit_abi.py= to print its ABI version.

Once you find the tag for the ABI 14 revision of a grammar, please submit a pull request to add it to the default value of =treesit-auto-recipe-list=.

Setting =:abi14-revision= is preferable to changing =:revision=, because changing =:revision= would force the ABI 14 version even after Emacs starts supporting ABI 15.

** Keep track of your hooks This package does not modify any of your major mode hooks. That is, if you have functions in =python-mode-hook=, but not in =python-ts-mode-hook=, then your hook from =python-mode= will not be applied, assuming =python-ts-mode= is what gets loaded. For major modes in which this is a concern, the current recommendation is to address this as part of your configuration.

#+begin_src emacs-lisp (setq rust-ts-mode-hook rust-mode-hook) #+end_src

Some modes have a shared base, such as =python-ts-mode= and =python-mode= both deriving from =python-base-mode=. For these languages, you can opt to hook into =python-base-mode-hook= instead of explicitly setting the tree-sitter mode's hook.

** Automatically register extensions for =auto-mode-alist= You can register tree-sitter modes to =auto-mode-alist= by calling =treesit-auto-add-to-auto-mode-alist=. Depending on the optional argument =langs=, this function can behave in three different ways:

=nil=, the default - Only add tree-sitter modes to =auto-mode-alist= if the tree-sitter mode is available to Emacs /and/ the grammar is installed.
='all= - For every tree-sitter mode available to Emacs and in =treesit-auto-langs=, add it to =auto-mode-alist= regardless of whether the grammar is installed. This has the beneficial side effect of installing grammars for you when opening files that have a tree-sitter mode that comes with Emacs, but have no fallback mode. Examples of this are =rust-ts-mode=, =go-ts-mode=, and a few others in Emacs 29+.
A list of language symbols - behaves like ='all=, but only for the listed languages

For instance, you might run this function as:

#+begin_src emacs-lisp (treesit-auto-add-to-auto-mode-alist '(rust go toml)) #+end_src

This registers your tree-sitter modes according to the common file extension for Rust, Go, and TOML, but no other modes. Most users will probably want to use =(treesit-auto-add-to-auto-mode-alist 'all)= for the easiest general behavior; always prompting/installing grammars when we can.

A rough vanilla equivalent I find it a good practice to be skeptical of adding any new dependency to my Emacs configuration. So, what would you have to do to get similar behavior in your Emacs configuration without the =treesit-auto= package?

We'll take two examples: TypeScript and Python.

Emacs 29 ships with =typescript-ts-mode= and =tsx-ts-mode=, but no equivalent =typescript-mode= or =tsx-mode=. =python-ts-mode= and =python-mode=, on the other hand, are both available out of the box. If you wanted these grammars to automatically install on launch, and then use the tree-sitter modes instead of the base modes for every file, you'd need the following code in your init file:

#+begin_src emacs-lisp (setq treesit-language-source-alist '((typescript . ("https://github.com/tree-sitter/tree-sitter-typescript" "master" "typescript/src")) (tsx . ("https://github.com/tree-sitter/tree-sitter-typescript" "master" "tsx/src")) (python . ("https://github.com/tree-sitter/tree-sitter-python"))))

(dolist (source treesit-language-source-alist) (unless (treesit-ready-p (car source)) (treesit-install-language-grammar (car source))))

(add-to-list 'auto-mode-alist '("\.ts\'" . typescript-ts-mode)) (add-to-list 'auto-mode-alist '("\.tsx\'" . tsx-ts-mode)) (add-to-list 'major-mode-remap-alist '(python-mode . python-ts-mode))

#+end_src

There are plenty of reasons why some users would prefer to take this type of hand-tuned approach to their tree-sitter modes. For most Emacs people, though, you can see the natural progression of where a config like the above would go:

You need to maintain a library of language symbols (which /must/ match the language's =grammar.js=), URLs, revisions, and sub-directories for =treesit-language-source-alist=. Additionally, you'd need to know that =typescript-ts-mode= relies on the tree-sitter grammar for =tsx=, which must be installed alongside the grammar for TypeScript. This is probably the main value proposition of this package, since all of this information is stored under the community-contributed =treesit-auto-recipe-list=
You need to be aware of when to use =auto-mode-alist= and =major-mode-remap-alist=, depending on what modes are installed into Emacs
If you want lazy installation of grammars, rather than installing them all up-front in your =init.el=, you'd need to write some hooks or derived modes to check =treesit-ready-p= for the current buffer, and install the language before loading the main tree-sitter mode
After a certain number of langauges, it becomes unweildy to do these =add-to-list= calls for every single one, and it's better to programmatically operate on a list of selected languages

If you were to follow this chain yourself, you'd probably wind up with something in your =init.el= that looks very similar to the code in this package.

All in all, this is a small package. Roughly half of it is just maintaining a library of information for =treesit-language-source-alist=, and the other half works through the logic of handling edge cases related to the remaining bullets above.

Caveats This package is, admittedly, a hack. =treesit.el= provides an excellent foundation to incremental source code parsing for Emacs 29, and over time that foundation /will/ expand into an improved core editing experience. With that in mind, I fully expect this package to eventually be obsolesced by the default options in Emacs 30 and beyond. That does not preclude us from adding a few quality of life improvements to Emacs 29, though, and so it still seems prudent to have this plugin available in the meantime.
Known bugs =treesit-auto= doesn't play super well with Org-babel, since Org has its own methods of hooking into and using languages. In particular, you may need to set =org-src-lang-modes= yourself to get tree-sitter modes working correctly.

Another side behavior you may encounter is when opening an Org document with shell scripts inside and =treesit-auto-install= is non-nil, then =treesit-auto= will prompt to install the Bash grammar, but won't display the prompt until you interact with Emacs in some way, such as using =next-line= (=C-n= by default) or hovering over Emacs with your mouse.

Contributing Bug reports, feature requests, and contributions are most welcome. Even though this is a small project, there is always room for improvement. I also appreciate "nitpicky" contributions, such as formatting, conventions, variable naming, code simplification, and improvements to language in documentation.

Issues are tracked on [[https://github.com/renzmann/treesit-auto/issues][GitHub]], which is also where patches and pull requests should be submitted.

If you would like to submit a new language recipe to be distributed as part of this package, see [[CONTRIBUTING.org][CONTRIBUTING.org]] for a quick guide on how to write and submit the new recipe.

magit/magit

It's Magit! A Git Porcelain inside Emacs.

A Git Porcelain inside Emacs

homepage | manual | faq | wiki | mastodon

Magit is an interface to the version control system Git, implemented as an Emacs package. Magit aspires to be a complete Git porcelain. While we cannot (yet) claim that Magit wraps and improves upon each and every Git command, it is complete enough to allow even experienced Git users to perform almost all of their daily version control tasks directly from within Emacs. While many fine Git clients exist, only Magit and Git itself deserve to be called porcelains.

Keeping its users this excited is a lot of work. If Magit makes you
more productive too, then please consider making a donation.

Thank you! — Jonas Bernoulli

Some alternative donation methods are available.

Getting Started

If you are new to Magit, then either one of the following two articles should help understanding how it differs from other Git clients.

Visual Magit walk-through

If you are completely new to Magit, then this article is a good visual introduction.

Almost everything that you see in Magit can be acted on by pressing some key, but that's not obvious from just seeing how Magit looks. The screenshots and accompanying text of this article explain how to perform a variety of actions on Magit's output.

Magit, the magical Git interface

Magit differs significantly from other Git interfaces, and its advantages are not immediately obvious simply from looking at a few screenshots as presented in the preceding article.

This article discusses Magit's properties in somewhat more abstract terms.

Video introductions

If you prefer video introductions, head over to that page, where find a collection of such introductions and other videos about Magit, by various creators.

Support and Contributing

Magit has many users and very few maintainers, so we kindly ask to read the appropriate guidelines before getting in contact. — Thanks!

Please use your own words. No stochastic parrots.

We use discussions (not issues) for feature requests. Please consider asking other users for help, where ever you like to hang out with other Emacs users. not every question can only be answered by the maintainer.

Please consider supporting the maintainer, who makes a living maintaining this and other packages, with a donation. — Thanks!

Acknowledgments

Magit was started by Marius Vollmer, and is now maintained by Jonas Bernoulli and Kyle Meyer. Former maintainers are Nicolas Dudebout, Noam Postavsky, Peter J. Weisberg, Phil Jackson, Rémi Vanicat and Yann Hodique. Many more people have contributed code, suggested features or made monetary contributions.

abo-abo/avy

Jump to things in Emacs tree-style

Introduction

avy is a GNU Emacs package for jumping to visible text using a char-based decision tree. See also ace-jump-mode and vim-easymotion - avy uses the same idea.

Command overview

You can bind some of these useful commands in your config.

`avy-goto-char`

Input one char, jump to it with a tree.

(global-set-key (kbd "C-:") 'avy-goto-char)

After C-: b:

`avy-goto-char-2`

Input two consecutive chars, jump to the first one with a tree.

The advantage over the previous one is less candidates for the tree search. And it's not too inconvenient to enter two consecutive chars instead of one.

(global-set-key (kbd "C-'") 'avy-goto-char-2)

After C-' bu:

`avy-goto-char-timer`

Input an arbitrary amount of consecutive chars, jump to the first one with a tree.

This is a more flexible version of avy-goto-char-2. First part works similarly to isearch: you type a query and it's highlighted dynamically on the screen. When you stop typing for avy-timeout-seconds (0.5s by default), you'll be able to select one of the candidates with avy. As you're inputting characters, you can use C-h (backspace) or DEL (delete) to forget the last typed character and RET to end the input sequence immediately and select a candidate.

`avy-goto-line`

Input zero chars, jump to a line start with a tree.

(global-set-key (kbd "M-g f") 'avy-goto-line)

After M-g f:

You can actually replace the M-g g binding of goto-line, since if you enter a digit for avy-goto-line, it will switch to goto-line with that digit already entered.

`avy-goto-word-1`

Input one char at word start, jump to a word start with a tree.

(global-set-key (kbd "M-g w") 'avy-goto-word-1)

After M-g wb:

`avy-goto-word-0`

Input zero chars, jump to a word start with a tree.

Compared to avy-goto-word-1, there are a lot more candidates. But at a least there's not need to input the initial char.

(global-set-key (kbd "M-g e") 'avy-goto-word-0)

After M-g e:

Org-mode commands

avy-org-goto-heading-timer: Type part of an Org heading. When you stop typing, if only one heading on the screen matches, it will be jumped to; if more than one matches, you can jump to a heading with Avy. This is like avy-goto-char-timer but for Org headings.
avy-org-refile-as-child: With point in an entry you want to refile, run this command, select a heading with Avy, and the entry will be refiled as its first child heading. This makes it quick and easy to refile to headings that are visible on-screen, even to other windows or buffers.

Other commands

There are some more commands which you can explore yourself by looking at the code.

Bindings

You add this to your config to bind some stuff:

(avy-setup-default)
(global-set-key (kbd "C-c C-j") 'avy-resume)

It will bind, for example, avy-isearch to C-' in isearch-mode-map, so that you can select one of the currently visible isearch candidates using avy.

Customization

See the comprehensive custom variable list on the defcustom wiki page.

See how to write your own avy commands on the custom-commands wiki page.

Contributing

Copyright Assignment

Avy is subject to the same copyright assignment policy as Emacs itself, org-mode, CEDET and other packages in GNU ELPA. Any legally significant contributions can only be accepted after the author has completed their paperwork. Please see the request form if you want to proceed.

The copyright assignment isn't a big deal, it just says that the copyright for your submitted changes to Emacs belongs to the FSF. This assignment works for all projects related to Emacs. To obtain it, you need to send one email, then send one letter (if you live in the US, it's digital), and wait for some time (in my case, I had to wait for one month).

Style

The basic code style guide is to use (setq indent-tabs-mode nil). It is provided for you in .dir-locals.el, please obey it.

Before submitting the change, run make compile and make test to make sure that it doesn't introduce new compile warnings or test failures. Also run make checkdoc to see that your changes obey the documentation guidelines.

Use your own judgment for the commit messages, I recommend a verbose style using magit-commit-add-log.

doomemacs/modules

Official module library for Doom Emacs

Doom Emacs Official Modules

This repository houses Doom Emacs' official starter kit: a library of official modules that can serve as a foundation for your Emacs configuration by:

Pre-configuring support for a variety of programming languages, tools, and operating systems,
Fixing common issues with Emacs packages or their interopability with other packages.
Optimizing Emacs and third party packages,
Providing sensible defaults for packages and features to spare you the months, maybe years, you'd otherwise spend discovering yourself.

Modules here are carefully curated by Doom's author and core maintainers.

Important

Each module possesses their own documentation, accessible within Doom via M-x doom/help-modules (or M-x +lookup/documentation while your cursor is on a module's name in $DOOMDIR/init.el).

Install

Until Doom core v3 is released, this repo exists as a git submodule of doomemacs/core and doesn't need to be directly installed (yet).

xenodium/agent-shell

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

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

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

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

[[file:agent-shell.png]]

This project needs your funding

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

Thank you!

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

agent-shell

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

With agent-shell, you can interact with any ACP-driven agent like:

[[https://code.claude.com/docs/en/overview][Claude Agent]] (Anthropic)
[[https://github.com/agentclientprotocol/codex-acp][Codex]] (OpenAI)
[[https://github.com/google-gemini/gemini-cli][Gemini CLI]] (Google)
[[https://goose-docs.ai/docs/getting-started/installation][Goose]]
[[https://cursor.com/docs/cli][Cursor]]
[[https://www.kimi.com/code][Kimi Code CLI]]
[[https://www.codebuddy.ai][CodeBuddy]]
[[https://kiro.dev][Kiro CLI]]
[[https://github.com/QwenLM/qwen-code][Qwen Code]]
[[https://docs.augmentcode.com/cli/overview][Auggie]]
[[https://github.com/mistralai/mistral-vibe][Mistral Vibe]]
[[https://factory.ai][Factory Droid]]
[[https://github.com/svkozak/pi-acp][Pi]]
[[https://github.com/can1357/oh-my-pi][Oh My Pi]]
[[https://opencode.ai][Opencode]]

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

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

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

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

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

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

[[https://www.youtube.com/watch?v=7fdHeUoRRgg][Bending Emacs Episode 14: Prototyping iOS apps with agent-shell, artist-mode, and Claude Skills - YouTube]]

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

News

Do take a look at all these blog posts as they showcase most =agent-shell= features.

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

Related projects

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

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

[[https://github.com/xenodium/emacs-skills][emacs-skills]]: Claude Agent skills for Emacs.
[[https://github.com/ElleNajt/agent-shell-to-go][agent-shell-to-go]]: Interact with =agent-shell= sessions from your mobile or any other device via Slack.
[[https://github.com/Embedded-Focus/agent-circus][agent-circus]]: Run AI coding agents in sandboxed Docker containers.
[[https://github.com/cmacrae/agent-shell-sidebar][agent-shell-sidebar]]: A sidebar add-on for =agent-shell=.
[[https://github.com/dcluna/agent-shell-bookmark][agent-shell-bookmark]]: Bookmark support for agent-shell sessions.
[[https://github.com/gveres/agent-shell-workspace][agent-shell-workspace]]: Dedicated tab-bar workspace for managing multiple =agent-shell= sessions.
[[https://github.com/jethrokuan/agent-shell-manager][agent-shell-manager]]: Tabulated view and management of =agent-shell= buffers.
[[https://github.com/nineluj/agent-review][agent-review]]: Code review interface for =agent-shell=.
[[https://github.com/ultronozm/agent-shell-attention.el][agent-shell-attention.el]]: Mode-line attention tracker for =agent-shell=.
[[https://github.com/xenodium/agent-shell-knockknock][agent-shell-knockknock]]: Notifications for =agent-shell= via [[https://github.com/konrad1977/knockknock][knockknock.el]].
[[https://github.com/zackattackz/agent-shell-notifications][agent-shell-notifications]]: Desktop notifications for =agent-shell= events.
[[https://github.com/ElleNajt/meta-agent-shell][meta-agent-shell]]: Multi-agent coordination system for =agent-shell= with inter-agent communication, task tracking, and project-level dispatching.
[[https://github.com/cxa/agent-shell-macext][agent-shell-macext]]: macOS-specific enhancements for =agent-shell=.
[[https://github.com/lllShamanlll/agent-shell-org-transcript][agent-shell-org-transcript]]: Org-mode transcripts for =agent-shell= sessions, with org-roam integration.
[[https://github.com/eddof13/ob-agent-shell][ob-agent-shell]]: Org Babel backend for executing =agent-shell= source blocks.
[[https://github.com/Marx-A00/agent-recall][agent-recall]]: Search, browse, and resume =agent-shell= conversation transcripts.
[[https://github.com/lgmoneda/agent-shell-pet][agent-shell-pet]]: Codex-like pets that broadcast agent-shell session states.
[[https://github.com/alberti42/agent-shell-math-renderer][agent-shell-math-renderer]]: Render LaTeX math equations as SVGs in =agent-shell=.
[[https://github.com/junyi-hou/agent-shell-tramp][agent-shell-tramp]]: Tramp integration for =agent-shell=.
[[https://github.com/nohzafk/agent-shell-hud][agent-shell-hud]]: Real-time =agent-shell= status overlay via a floating dashboard.
[[https://github.com/timfel/agent-shell-desktop.el][agent-shell-desktop]]: Desktop save mode integration for =agent-shell=. Saves and resumes shells by folder, config, and session id.
[[https://github.com/ultronozm/agent-shell-links.el][agent-shell-links.el]]: Bookmarks and Org links for =agent-shell= sessions.
[[https://github.com/wandersoncferreira/agent-shell-dashboard][agent-shell-dashboard]]: A landing page for =agent-shell=.

Articles

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

Icons

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

Setup

** External dependencies

*** Claude Agent SDK

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

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

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

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

*** Codex

For OpenAI's Codex, install [[https://github.com/agentclientprotocol/codex-acp][@agentclientprotocol/codex-acp]] (=npm install -g @agentclientprotocol/codex-acp=) and ensure the =codex-acp= executable is in PATH.

*** Gemini CLI

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

*** Goose

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

*** Cursor

For Cursor agent, install the official [[https://cursor.com/docs/cli][Cursor CLI]] and ensure the =agent= executable is in PATH. =agent-shell= uses its official ACP server (=agent acp=).

A recent Cursor CLI is required (the =acp= subcommand was added in 2026). Older CLIs won't expose =agent acp=.

*** Kimi Code CLI

For Kimi Code CLI, install with:

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

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

*** CodeBuddy

For CodeBuddy agent, install the CodeBuddy CLI and ensure ACP mode is available. For example:

#+begin_src bash codebuddy --acp #+end_src

See https://www.codebuddy.ai/docs/zh/ide/Getting-Started/Installation for details.

*** Kiro CLI

For Kiro CLI, install with:

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

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

*** Qwen Code

For Qwen Code, install with:

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

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

*** Auggie

For Auggie CLI, install with:

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

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

For Mistral Vibe, install with:

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

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

*** Factory Droid

For Factory Droid, install Droid:

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

See https://factory.ai for details.

*** Pi

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

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

See https://github.com/svkozak/pi-acp for details. *** Oh My Pi (=omp=)

For the =omp= agent, install with:

#+begin_src bash bun install -g @oh-my-pi/pi-coding-agent #+end_src

See https://github.com/can1357/oh-my-pi for details.

*** Opencode + local ollama models

For opencode coding agent, install with:

#+begin_src bash curl -fsSL https://opencode.ai/install | bash #+end_src

See https://opencode.ai/ for details.

For local ollama models, sudo permission is needed to initialize ~ollama.service~. The following will install ollama and a local Qwen2.5:7b model.

#+begin_src bash curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:7b #+end_src

If you are behind a network proxy, ~ollama pull~ will timeout. You then need to add proxy settings inside ~/etc/systemd/system/ollama.service~

See https://ollama.com/ for details

** Installation

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

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

You can install via:

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

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

*** Optional: image utilities

Pasting images from the clipboard (=agent-shell-send-clipboard-image= or =yank= or =C-y=) and capturing screenshots (=agent-shell-send-screenshot=) rely on external tools. Install the ones for your platform:

| Platform | Clipboard paste | Screenshot capture | |-----------------+------------------------------------------+------------------------------| | macOS | =brew install pngpaste= | =screencapture= (preinstalled) | | Linux (Wayland) | =wl-paste= (e.g. =apt install wl-clipboard=) | =import= (from ImageMagick) | | Linux (X11) | =apt install xclip= | =import= (from ImageMagick) | | Windows | =powershell= | (not bundled) |

Handlers are detected at runtime via =executable-find=. See =agent-shell-clipboard-image-handlers= and =agent-shell-screenshot-command= to customize.

*** Doom Emacs

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

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

Run =doom sync= and restart.

Include =require= before configuration:

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

** Configuration

Configure authentication for the agent providers you want to use.

*** Environment variables

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

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

**** Inheriting environment variables

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

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

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

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

**** Loading environment variables from files

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

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

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

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

*** Anthropic Claude

For login-based authentication (default):

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

For API key authentication:

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

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

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

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

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

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

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

*** Google Gemini

For login-based authentication (default):

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

For API key authentication:

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

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

For Vertex AI authentication:

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

*** OpenAI Codex

For login-based authentication (default):

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

For API key authentication:

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

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

*** Goose

By default, authentication is handled by Goose's built-in configuration. This needs no =agent-shell= configuration.

Optionally, pass an OpenAI API key from =agent-shell= instead:

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

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

*** Qwen Code

For OAuth login-based authentication:

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

For an OpenAI-compatible provider (for example OpenRouter), pass the API key and set the base URL and model via =agent-shell-qwen-environment=:

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

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

(setq agent-shell-qwen-environment (agent-shell-make-environment-variables "OPENAI_BASE_URL" "https://openrouter.ai/api/v1" "OPENAI_MODEL" "x-ai/grok-4.3")) #+end_src

*** Cursor

By default authentication is handled externally: run =agent login= once outside Emacs and agent-shell uses that existing login (it sends no ACP authenticate request). This needs no configuration.

Optionally, have agent-shell drive login-based authentication (=cursor_login=):

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

For API key authentication (passed via the =CURSOR_API_KEY= environment variable):

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

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

For auth token authentication (passed via the =CURSOR_AUTH_TOKEN= environment variable):

#+begin_src emacs-lisp (setq agent-shell-cursor-authentication (agent-shell-cursor-make-authentication :auth-token "your-cursor-auth-token")) #+end_src

For no authentication (already authenticated externally):

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

*** Auggie

For login-based authentication (default):

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

For no authentication (when using alternative authentication methods):

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

*** Mistral Vibe

For API key authentication:

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

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

*** Opencode + local ollama Qwen2.5

If ~opencode~ is not found by ~agent-shell~, you can add it to the search path

#+begin_src emacs-lisp (use-package agent-shell :ensure t :config (add-to-list 'exec-path "~/.opencode/bin/")) #+end_src

To register the local Qwen2.5:7b model in opencode, two files needs to be edited:

~/.config/opencode/opencode.json~ #+BEGIN_SRC js { "$schema": "https://opencode.ai/config.json", "permission": { "edit": "ask", "bash": "ask", "webfetch": "allow" }, "provider": { "ollama": { "name": "qwen2.5:7b", "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "qwen2.5:7b": { "name": "Qwen2.5 7b" } } } } } #+END_SRC

and a dummy auth file ~/.local/share/opencode/auth.json~

#+begin_src js { "ollama": { "type": "api", "key": "ollama" } } #+end_src

Huge thanks for /gdindi/ for finding and and describing this in https://github.com/xenodium/agent-shell/issues/526

*** Customizing Available Agents

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

** Usage

*** Quick Start

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

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

*** Specific Agent Commands

Start a specific agent shell session directly:

=M-x agent-shell-anthropic-start-claude-code= - Start a Claude Agent session
=M-x agent-shell-auggie-start-agent= - Start an Auggie agent session
=M-x agent-shell-codebuddy-start-agent= - Start a CodeBuddy agent session
=M-x agent-shell-openai-start-codex= - Start a Codex agent session
=M-x agent-shell-google-start-gemini= - Start a Gemini agent session
=M-x agent-shell-goose-start-agent= - Start a Goose agent session
=M-x agent-shell-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. If you configure =agent-shell-dot-subdir-function= to store data outside the project =.agent-shell/= directory, agent-shell will not update the project's =.gitignore=.

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

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

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

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

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

*** Screenshots from clipboard

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

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

*** Inhibiting minor modes during file writes

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

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

*** Keeping the system awake during long turns

Long agent turns can outlast the system idle-sleep timeout, suspending the machine (and the agent) before the turn completes. On Emacs 31.1 or later, =agent-shell-inhibit-system-sleep= (enabled by default) keeps the system awake for the duration of each turn and releases the block once the turn finishes, so the system is only kept awake while there is work in progress (the display is still allowed to blank). This relies on the built-in [[https://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/system-sleep.el][=system-sleep=]] library and has no effect on earlier Emacs versions. It does not prevent "hard" sleep such as closing a laptop lid.

To turn it off:

#+begin_src emacs-lisp (setopt agent-shell-inhibit-system-sleep nil) #+end_src

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

** Key bindings

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

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

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

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

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

*** Session controls

When the active agent advertises the corresponding session option, you can switch it from the shell buffer:

=C-c C-v= - Set model.
=C-c C-m= - Set session mode.
=C-c C-t= - Set thought level (reasoning effort).
=C- = - Cycle session mode.

The current selections are shown in the header right after the agent name; click any segment to open a popup menu. The thought level segment only appears for models that expose it (e.g. Claude Sonnet/Opus with effort levels; Codex's reasoning_effort).

From the viewport (=agent-shell-viewport-view-mode= / =agent-shell-viewport-edit-mode=), the same controls are bound to:

View mode: =v= (model), =s= (mode), =t= (thought level).
Edit mode: =C-c C-v=, =C-c C-m=, =C-c C-t=.

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

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

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

#+end_src

Customizations

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

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

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. | | r | agent-shell-quote-region | Quote the active region into the shell's latest prompt. | | | agent-shell-qwen-start | Start an interactive Qwen Code CLI agent shell. | | | 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 | Toggle fragment fold at or near point. | | | agent-shell-ui-toggle-all-fragments | Toggle global fold state: all-expanded ↔ all-collapsed. | | | agent-shell-version | Show agent-shell' mode version. | | | agent-shell-view-acp-logs | View agent shell ACP logs buffer. | | | agent-shell-view-traffic | View agent shell traffic buffer. | | | agent-shell-viewport-compose-cancel | Cancel prompt composition. | | | agent-shell-viewport-compose-send | Send the viewport composed prompt to the agent shell. | | | agent-shell-viewport-compose-send-and-kill | Send the viewport composed prompt to the agent shell and kill compose buffer. | | | agent-shell-viewport-compose-send-and-wait-for-response | Send the viewport composed prompt and display response in viewport. | | | agent-shell-viewport-cycle-session-mode | Cycle through available session modes. | | | agent-shell-viewport-edit-mode | Major mode for composing agent shell prompts. | | | agent-shell-viewport-interrupt | Interrupt active agent shell request. | | | agent-shell-viewport-next-item | Go to next item. | | | agent-shell-viewport-next-page | Show next interaction (request / response). | | | agent-shell-viewport-previous-item | Go to previous item. | | | agent-shell-viewport-previous-page | Show previous interaction (request / response). | | | agent-shell-viewport-refresh | Refresh viewport buffer content with current item from shell. | | | agent-shell-viewport-reply | Reply as a follow-up and compose another prompt/query. | | | agent-shell-viewport-quote-reply | Reply with the entire response block-quoted. | | | agent-shell-viewport-set-session-mode | Set session mode. | | | agent-shell-viewport-set-session-model | Set session model. | | | agent-shell-viewport-view-last | Display the last request/response interaction. | | | agent-shell-viewport-view-mode | Major mode for viewing agent shell prompts (read-only). |

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

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

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

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

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

[[file:slash-commands.png]]

** Can you add support for another agent?

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

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

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

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

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

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

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

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

[[file:traffic.png]]

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

** Where should I file bug or feature request?

*** Agent issues or feature requests

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

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

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

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

*** Not sure where to file an issue?

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

Contributing

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

Contributors

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

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

dgutov/diff-hl

Emacs package for highlighting uncommitted changes

About

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

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

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

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

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

The package also contains auxiliary modes:

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

Usage

Put this into your init script:

(global-diff-hl-mode)

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

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

Screenshots

diff-hl-mode

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

diff-hl-dired-mode

diff-hl-margin-mode

Requirements

Emacs 27.1+.

Notes

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

Integration

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

psvn

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

Magit

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

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

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

Tramp

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

GitHub Emacs Lisp Daily Trending

dakra/ghostel

Ghostel

Quick Start

A fuller example

Extensions

Evil

Shell integration

Input modes

Documentation

doomemacs/core

Doom Emacs

Table of Contents

Introduction

Features

Prerequisites

Install

Roadmap

Getting help

Contribute

emacs-mirror/emacs

melpa/melpa

MELPA

Table of Contents

Usage

MELPA Stable

Contributing

Recipe Format

Example: Single File Repository

Example: Multiple Packages in one Repository

Example: Multiple Files in Multiple Directories

Build Scripts

API

Functions

Variables

Configuration

Mirrors

About

karthink/gptel

Media support

#+html:

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

#+html:

Multi-LLM support demo:

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

TODO Remove this when writing the manual.

Local Variables:

toc-org-max-depth: 4

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

End:

rainstormstudio/nerd-icons.el

google-coral/coralnpu

Coral NPU

Coral NPU Features

System Requirements

Verification & Testing

Quick Start

radian-software/apheleia

Apheleia

Installation

Dependencies

User guide

Formatter configuration

Troubleshooting

Known issues

Contributing

Adding a formatter

Acknowledgements

purcell/exec-path-from-shell

exec-path-from-shell

Motivation

Compatibility

Installation

Usage

Setting up your shell startup files correctly

Making exec-path-from-shell faster

Further help

company-mode/company-mode

Fanael/rainbow-delimiters

rainbow-delimiters

Making `exec-path-from-shell` faster

-map `(fn list)`

-map-when `(pred rep list)`

-map-first `(pred rep list)`

-map-last `(pred rep list)`

-map-indexed `(fn list)`

-annotate `(fn list)`

-splice `(pred fun list)`

-splice-list `(pred new-list list)`

-mapcat `(fn list)`

-copy `(list)`

-filter `(pred list)`

-remove `(pred list)`

-remove-first `(pred list)`

-remove-last `(pred list)`

-remove-item `(item list)`

-non-nil `(list)`

-slice `(list from &optional to step)`

-take `(n list)`

-take-last `(n list)`

-drop `(n list)`

-drop-last `(n list)`

-take-while `(pred list)`

-drop-while `(pred list)`

-select-by-indices `(indices list)`

-select-columns `(columns table)`

-select-column `(column table)`

-keep `(fn list)`

-concat `(&rest sequences)`

-flatten `(l)`

-flatten-n `(num list)`

-replace `(old new list)`

-replace-first `(old new list)`

-replace-last `(old new list)`

-insert-at `(n x list)`

-replace-at `(n x list)`

-update-at `(n func list)`

-remove-at `(n list)`

-remove-at-indices `(indices list)`