gptel

A Large Language Model (LLM) is a neural network trained on a large corpus of information to generate text or audio-visual output data based on input. The input can be in many formats as well, including audio-visual data. In this manual we are primarily interested in textual input and output. A subclass of these models are trained to generate text to convincingly simulate the format of a back-and-forth conversation. gptel provides an Emacs interface to use these so-called “instruct” models. In this manual LLM refers only to “instruct” models.

LLMs are categorized by the information they were trained with, tasks they are trained for, by their capabilities, and by their size. Their size is typically measured in billions of network parameters, where the smallest models (1-120 billion parameters) can run on today’s consumer hardware. The larger models typically consist of hundreds of billions of parameters, and require clusters or supercomputers to run.

Some LLMs – typically the smaller ones – are permissively licensed and free. Most larger models are proprietary and only available as a service that charges by the word.

gptel does not provide or run these models. Instead, it only acts as a client, sending and receiving conversation text over HTTP. To run free models on your hardware, you can use software such as llama.cpp or Ollama. Larger and more capable models typically require paid API access.

Presently, gptel works only with “chat” models, which are trained to respond to input in a manner resembling a conversational reply. Such models (nicknamed “instruct models”) are among the most popular and easy to use without additional tooling, as the interaction format prescribes an interface by itself.

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

Clone or download this repository and run M-x package-install-file⏎ on the repository directory.

In packages.el

(package! gptel :recipe (:nonrecursive t))

In config.el

(use-package! gptel
 :config
 (setq! gptel-api-key "your key"))

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

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

(llm-client :variables
            llm-client-enable-gptel t)

Procure an 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 [BROKEN LINK: optional-securing-api-keys-with-authinfo])

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

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

(gptel-make-anthropic "Claude" :stream t :key gptel-api-key)

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.

1. 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.
2. If a region is selected, the conversation will be limited to its contents.
3. 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.

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 [BROKEN LINK: option-presets] below.

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

1. 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.
2. In the gptel buffer, send your prompt with M-x gptel-send, bound to C-c RET.
3. Set chat parameters (LLM provider, model, directives etc) for the session by calling gptel-send with a prefix argument (C-u C-c RET):

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 [BROKEN LINK: option-presets] below.

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 [BROKEN LINK: additional-configuration]. Chat buffer-specific options are also available via the header-line in chat buffers.

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.

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:

And then browse through or remove context from the context buffer:

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.

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.

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:

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

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.

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

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

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:

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

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:

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

gptel offers a few extra conveniences in Org mode.

Set gptel-expert-commands to t to display additional options in gptel’s transient menu.

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.

gptel-send works uniformly in any buffer in Emacs, and you are encouraged to use it without requiring a context switch to a dedicated interface. However, it does provide the option to create a buffer dedicated to chatting with an LLM with the gptel command.

Function gptel

Arguments: (NAME &optional _ INITIAL INTERACTIVEP)

Switch to or create a chat session with NAME.

If region is active, use it as the INITIAL prompt. Return the buffer created or switched to.

INTERACTIVEP is t when gptel is called interactively.

Running gptel interactively will prompt you for an API key if one is needed, and switch you to a dedicated chat buffer (the “gptel buffer”). In the gptel buffer, gptel-send is bound to C-c RET by default.

The gptel buffer is a normal Emacs buffer in all respects, but with some extra niceties for chat interaction.

Variable gptel-default-mode

The major mode used in gptel buffers. It is one of markdown-mode, org-mode and text-mode. It uses markdown-mode if available, and defaults to text-mode.

gptel offers a few extra conveniences in Org mode.

The following flowchart provides an overview of the most common user options and hooks available for customizing the behavior of gptel-send. The left and right columns show user options and hooks respectively. The central column illustrates the control flow of gptel-send, and where in the pipeline the user options or hooks are applied.

      (USER OPTIONS, TASKS)                GPTEL-SEND                   (HOOKS)
              ║                                │                           ║
              v                                v                           v
 ╭───────────────────────────╮    ╭────────────┴─────────────╮
 │      (Org mode only)      │    │       Copy region        │
 │ gptel-org-ignore-elements │    │ (or buffer above cursor) │
 │gptel-org-branching-context├───>┤   to a temporary buffer  │
 ╰───────────────────────────╯    ╰────────────┬─────────────╯
 ╭──────────────────────────╮                  │·╶─╴·╶─╴·╶─╴gptel-prompt-transform-functions
 │   gptel-track-response   ├──╮               v                            │
 ╰──────────────────────────╯  │  ╭────────────┴──────────────╮ ╭───────────┴───────-────╮
 ╭───────────────────────────╮ │  │  Create messages array,   │ │     Apply @presets     │
 │ Add base64-encoded media  │ ├─>┤ Assign user and LLM roles │ │                        │
 │        from links         ├─╯  │         to text           │ │Add regions, buffers and│
 │     gptel-track-media     │    ╰────────────┬──────────────╯ │files from gptel-context│
 ╰───────────────────────────╯                 │                │    gptel-use-context   │
  ╭─────────────────────────╮                  │                ╰────────────────────────╯
  │      gptel-model        ├──╮               │
  ╰─────────────────────────╯  │               v
  ╭─────────────────────────╮  │     ╭─────────┴──────────╮
  │    Backend parameters   │  │     │                    │
  │      gptel-backend      ├──┼────>│   Create payload   │
  │   gptel--request-params │  │     │                    │
  ╰─────────────────────────╯  │     ╰─────────┬──────────╯
  ╭─────────────────────────╮  │               v
  │  Run and add directive  │  │     ╔═════════╧══════════╗
  │    gptel-directives     ├──┤     ║    Send request    ║
  │  gptel--system-message  │  │     ╚═════════╤══════════╝
  │      gptel--schema      │  │               │·╶─╴·╶─╴·╶─╴· gptel-post-request-hook
  ╰─────────────────────────╯  │               │
  ╭─────────────────────────╮  │               │
  │      Prepare tools      │  │               v
  │     gptel-use-tools     ├──┤            ╶──┴──╴
  │       gptel-tools       │  │          ╭ ─ ─ ─ ─ ─╮
  ╰─────────────────────────╯  │           ASYNC WAIT
  ╭────────────────────────╮   │          ╰ ─ ─ ─ ─  ╯
╭>┤    Merge available     ├───╯            ╶──┬──╴
│ │   tool call results    │                   v
│ ╰────────────────────────╯                   ├·╶─╴·╶─╴·╶─╴· gptel-pre-response-hook
│ ╭──────────────────────────╮     ╭───────────────────────╮
│ │    Handle "Reasoning"    ├────>┤                       │
│ │ gptel-include-reasoning  │ ╭─<─┤ Parse partial response├<─────╮
│ ╰──────────────────────────╯ │╭<─┤                       │<╮    │
│                              ││  ╰───────────────────────╯ │    ╵
│                              ││                            ├·╶─gptel-post-stream-hook
│                              ││  ╭───────────────────────╮ │    ╷
│                              │╰──┤ Insert response chunk ├─╯    │
│                              │   ╰───────────────────────╯      │
│                              │   ╭───────────────────────╮      │
│                              ╰──>┤                       │      │
╰─<───────────────────────────────<┤     Run tool calls    │      │
 ╭──────────────────────────╮  ╭──>┤                       │      │
 │ gptel-confirm-tool-calls ├──╯   ╰───────────┬───────────╯      │
 ╰──────────────────────────╯      ╭───────────┴───────────╮      │
 ╭──────────────────────────╮  ╭──>┤  Insert tool results  ├>─────╯
 │gptel-include-tool-results├──╯   ╰───────────┬───────────╯
 ╰──────────────────────────╯                  │
                                               v·╶─╴·╶─╴·╶─╴· gptel-post-response-functions
                                            ╶──┴──╴

gptel-send works by (i) building a backend-appropriate request payload from the provided text, context, tools and active gptel configuration, (ii) sending the request and (iii) inserting or otherwise dispatching on the response as necessary. A detailed description of gptel-send’s processing pipeline and concomitant customization options follows.

1. Copy the text up to the cursor (or the selected region) from the “request buffer” to a temporary buffer. This serves as the primary prompt to be sent to the LLM.

2. If the request is sent from an Org mode buffer, this region may be modified in two different ways. If gptel-org-branching-context is non-nil, copy only the lineage of the current Org entry to the temporary buffer. Additionally, remove Org elements of the types in gptel-org-ignore-elements from this text. By default, the latter is used to strip Org PROPERTIES blocks from the text before sending. See 9.2.1 for more details.

3. Run the hook gptel-prompt-transform-functions in this buffer, with the cursor at the end. This can be used to modify the prompt text or local environment as required. By default, this hook serves a couple of functions:

   • If gptel-use-context is non-nil, add the contents of regions, buffers and files explicitly added to gptel’s context by the user. How exactly this is added to the request payload depends on the value of gptel-use-context, see 9.6.
   • Apply any presets specified in the prompt text via the @preset cookie (see 9.8.1).

   gptel-prompt-transform-functions can be used for arbitrarily complex prompt transformations. A typical example would be to search for occurrences of the pattern $(cmd) and replace it with the output of the shell command cmd, making it easy to send dynamically generated shell command output. It is described in more detail in 10.2.

4. Parse this buffer and collect text, sorting it into user and LLM role buckets in an array of messages. gptel uses text-properties to track the provenance of buffer text. If the user option gptel-track-response is non-nil, ignore the distinction between user and LLM roles and treat the entire buffer as a user prompt. If the user option gptel-track-media is non-nil, scan hyperlinks to files in this buffer and check if their MIME types are supported by the LLM (see 9.5). If they are, base64-encode them and include them in the messages array.
5. Build the payload using parameters specified by gptel-backend and gptel-model. The former can include preferences like response streaming, LLM prompt caching, temperature etc. There are dozens of parameters governing backend API behavior and LLM output, and gptel provides user options for only a few of them, such as gptel-temperature and gptel-cache. To specify arbitrary LLM/backend API parameters, see 9.4.

6. Create the system message and possible conversation template from gptel--system-message, and include it in the payload. If this variable is a string, it is included as is. If it is a function, the system message is generated dynamically. If it is a list of strings, the first element is treated as the system message, and the remaining elements are considered alternating user and LLM messages to be prepended to the messages array. See 9.3 for details.

7. If gptel-use-tools is non-nil and gptel-tools contains a list of gptel tools (See 9.7), include the tools in the payload.

8. Make a HTTP request with this payload. The address, port and API key (if required) for the request are included in the gptel-backend struct. Run gptel-post-request-hook immediately after starting the request. This hook may be used to do any cleanup or resetting – gptel uses this hook to reset user preferences after firing a “oneshot” request, see 8.

9. gptel-send then waits for a response. When a response is received, do some basic error handling. If the response has HTTP code 200/201, first run gptel-pre-response-hook in the buffer from which the request was sent. This hook can be used to prepare the buffer for the response however you would like.

10. Streaming responses only: Insert each chunk into the request buffer (or elsewhere if the output has been redirected, see 8.) After each insertion, run gptel-post-stream-hook. This hook runs in the request buffer and may be used for immediate actions such as recentering the view or scrolling the window with the response.

11. If gptel-include-reasoning is non-nil and the model responds with a “thinking” or reasoning “block” of text, handle it according to this user option. Typically this involves formatting it specially.

12. If the LLM responds with a tool call, either run the tool automatically or insert a prompt into the request buffer seeking confirmation from the user. This depends on both the value of gptel-confirm-tool-calls and the tool’s :confirm slot. If the output has been redirected to a non-buffer destination, tool call confirmation is sought from the minibuffer instead.

13. If a tool has been run (automatically or after confirmation), conditionally insert the result into the request buffer, depending on the value of gptel-include-tool-results and the tool’s :include slot.
14. If a tool has been run: add the tool call result to the messages array and resend it to the LLM. Goto step 9.
15. After the response ends, run the hook gptel-post-response-functions in the request buffer. This hook can be used for cleanup, formatting or modifying the LLM output, etc. Note that this hook always runs, even if the response fails.

After the request ends, you can examine a pretty-printed view of the state and details of the last request sent from the buffer at any time via the function gptel--inspect-fsm. In chat buffers, you can click on the status text in the header-line instead. This is primarily intended for introspection and debugging.

Alternatively, you can inspect the variable gptel--fsm-last, which always contains the last request as a gptel state-machine object (see gptel’s state machine).

In addition to the text in your buffer, LLMs can be prompted with instructions on how they should respond. They are prioritized and treated specially by most LLMs, and is one of the primary levers for configuring its behavior. In popular use these instructions are referred to as the “system message”, “system prompt” or “directives”. gptel refers to them as the “system message” and “directives”.

The system message can be used to specify the LLM’s general tone and tenor, output format, structure or restrictions, as well as general objectives it should work towards in its interactions with the user.

The following is a brief system message describing the tone and proscribing certain common LLM behaviors.

To assist: Be terse. Do not offer unprompted advice or clarifications. Speak in specific, topic relevant terminology. Do NOT hedge or qualify. Speak directly and be willing to make creative guesses.

Explain your reasoning. if you don’t know, say you don’t know. Be willing to reference less reputable sources for ideas.

Do NOT summarize your answers. Never apologize. Ask questions when unsure.

Here is another example, this time specifying an objective for the LLM to work towards:

You are a tutor and domain expert in the domain of my questions. You will lead me to discover the answer myself by providing hints. Your instructions are as follows:

• If the question or notation is not clear to you, ask for clarifying details.
• At first your hints should be general and vague.
• If I fail to make progress, provide more explicit hints.
• Never provide the answer itself unless I explicitly ask you to. If my answer is wrong, again provide only hints to correct it.
• If you use LaTeX notation, enclose math in \( and \) or \[ and \] delimiters.

In practice system messages can be document-length, composed of several sections that provide both instructions and a generous amount of context required to accomplish a task.

You can control system message gptel uses via the variable gptel--system-message. This is most commonly a string containing the text of the instructions. But it can also be a directive - a function or a list of strings, as explained below.

While you can set gptel--system-message to any string, gptel provides the alist gptel-directives as a registry of directives.

gptel’s idea of the directive is more general than a static string. A directive in gptel-directives can be

• A string, interpreted as the system message.
• A list of strings, whose first (possibly nil) element is interpreted as the system message, and the remaining elements as (possibly nil) alternating user prompts and LLM responses. This can be used to template the initial part of a conversation.
• A function that returns a string or a list of strings, interpreted as the above. This can be used to dynamically generate a system message and/or conversation template based on the current context. (See the definition of gptel--rewrite-directive-default for an example.)

Each entry in gptel-directives maps a symbol naming the directive to the directive itself. By default, gptel uses the directive with the key default, so you should set this to what gptel should use out of the box:

(setf (alist-get 'default gptel-directives)
      "My default system message here.")

A gptel-backend is an object containing LLM connection, authentication, model information and other request parameters.

To determine how to construct an LLM query, gptel uses the backend that is “active” in the Emacs buffer from which the query originates. Only one backend can be “active” in a buffer at a time, and each Emacs buffer can use a different backend.

The current backend is controlled by the variable gptel-backend. It holds a gptel-backend object.

The backend may be set interactively from gptel-menu:

-m Model

Set the gptel backend and model to use. Note that the gptel’s scope action is available in this menu, so the backend and model may be specified globally, buffer-locally or for the next request only.

gptel includes a pre-defined backend for ChatGPT, and methods to simplify creating backends for several supported LLM providers (See 2 and 4.)

Every gptel backend may include the following keys, although some may be left unspecified:

NAME

Name of the backend, can be any string

Connection information:

PROTOCOL

used to communicate with the provider, typically “http” or “https”.

HOST

hostname of the provider, typically a domain or IP address.

ENDPOINT

API endpoint for chat completion requests, such as /v1/chat/completions.

HEADER

An alist or function that returns an alist specifying additional headers to send with each request. The Content-Type header is set to application/json by gptel automatically and need not be specified. (See url-request-extra-headers for more details.)

CURL-ARGS

(List of strings) When using Curl, add these command line arguments to the Curl process in addition to the ones gptel uses by default. This can also be set globally instead of per-backend instance via gptel-curl-extra-args. gptel’s use of Curl for requests is determined by gptel-use-curl.

Authentication (if required):

KEY

A string, variable (symbol) or function to retrieve an API key for requests. How this is included in the request depends on the implementation.

Models provided by the backend:

MODELS

A list of symbols representing LLM names. Each symbol can also include model metadata and capabilities, see 9.5 for details.

Request parameters (optional):

STREAM

(Boolean) Stream responses when using this backend, if supported.

REQUEST-PARAMS

A plist of additional request parameters (as plist keys) and their values supported by the API. Its contents are API-specific, and can be used to set parameters that gptel does not provide user options for. It will be converted to JSON and included with all requests made with this backend.

Here is an annotated example of a full backend specification. In practice gptel provides several specialized backend-creation functions (gptel-make-*) that handle most of this for you, as described in 4.

;; We use -openai since Openrouter provides an OpenAI-compatible API
(gptel-make-openai "Openrouter-example" ;NAME, for your reference

  ;; Connection information
  :protocol "https"
  :host "openrouter.ai"                 ;Only domain name
  :endpoint "/api/v1/chat/completions"  ;Only endpoint
  :header                               ;Adds KEY to HTTP header
  (lambda ()
    (when-let* ((key (gptel--get-api-key)))
      `(("Authorization" . ,(concat "Bearer " key)))))

  ;; Wait for up to an hour for the response, and use a proxy
  :curl-args '("--keepalive-time" "3600"
               "--proxy" "proxy.yourorg.com:80")

  ;; Authentication: fetch API key from Emacs' environment
  :key (lambda () (getenv "OPENROUTER_API_KEY"))

  :models
  '(;; Specified as MODEL-NAME, a symbol 
    deepseek/deepseek-r1-distill-llama-70b

    ;; Alternatively, a model can be (MODEL-NAME . METADATA-PLIST)
    ;; See the Models section for details
    (openai/gpt-oss-120b
     :description "OpenAI's most powerful open-weight model"
     :context-window 131
     :capabilities (reasoning json tool-use)))

  ;; Request parameters
  :stream t                             ;Enable response streaming
  :request-params                       ;API-specific parameters, do not copy!
  '( :top_p 0.80                        ;Adjust sampling
     :top_k 20                          ;Adjust sampling
     :max_tokens 1024))                 ;Fix max response size

When a backend is defined, it is added to gptel’s registry of defined backends. A backend object can be accessed by name via gptel-get-backend:

Function gptel-get-backend

Arguments: (NAME)

Retrieve the backend object with NAME.

Fields of a gptel backend can be obtained via accessors. For example, the :request-params of the active backend can be obtained via (gptel-backend-request-params gptel-backend), and that of a backend with name “Openrouter-example” (as above) can be obtained as

(gptel-backend-request-params
 (gptel-get-backend "Openrouter-example"))

All gptel backend fields can be modified in place. To add a model to the list of models in the above backend, for example, you can use

(push 'qwen3/qwen3-coder
      (gptel-backend-models (gptel-get-backend "Openrouter-example")))

A model in gptel is a symbol denoting a specific LLM, whose name is as expected by the active LLM provider’s API.

Along with the active backend (see 9.4), gptel uses the value of the user option gptel-model as the LLM to query. Only one model can be “active” in an Emacs buffer at a time, and each buffer can use a different model.

The model may be set interactively from gptel-menu:

-m Model

Set the gptel backend and model to use. Note that the gptel’s scope action is available in this menu, so the backend and model may be specified globally, buffer-locally or for the next request only.

Each gptel backend is typically associated with a list of available models. When defining the backend, each model in this list can be specified with additional metadata if required, as (MODEL-NAME . METADATA-PLIST).

Here is an example:

(claude-sonnet-4-20250514               ;model name
 :description "High-performance model with exceptional reasoning and efficiency"
 :capabilities (media tool-use cache)
 :mime-types ("image/jpeg" "image/png" "image/gif" "image/webp" "application/pdf")
 :context-window 200
 :input-cost 3
 :output-cost 15
 :cutoff-date "2025-03"
 :request-params (:thinking (:type "enabled" :budget_tokens 2048)))

This metadata is displayed when selecting models interactively. It is also used internally by gptel to assess model capabilities such as its ability to parse binary file formats.

The following metadata keys are recognized:

Model information only:

DESCRIPTION

For your reference.

CONTEXT-WINDOW

Size in thousands of tokens of the context window of the model.

INPUT-COST and OUTPUT-COST

Cost per million input/output tokens. The currency is indeterminate and left to your interpretation.

CUTOFF-DATE

Cutoff date for the data the model was trained on.

Keys used by gptel:

CAPABILITIES

It is assumed that any model that gptel communicates with can ingest and generate text. This is a list of symbols denoting additional capabilities the model possesses:

• tool-use: The model is capable of using tools
• json: The model can produce output structured according to a specified schema
• reasoning: The model can produce a stream of “reasoning tokens”, separate from its final response.
• nostream: The model or API cannot produce streaming responses. This denotes an incapability, since gptel’s default assumption is that all models can.
• media: The model can understand binary formats (input-only)

MIME-TYPES

List of MIME types a media capable model can parse.

REQUEST-PARAMS

A plist of additional request parameters (as plist keys) and their values supported by the API. Its contents are API-specific, and can be used to set parameters that gptel does not provide user options for. It will be converted to JSON and included with all requests made with this model.

gptel can provide the LLM with client-side elisp “tools”, or function specifications, along with the request. A “tool” is an elisp function along with metadata intended to describe its purpose, arguments and return value as you would to a human:

“This function is used to do X. It accepts two arguments, a string and a list of numbers, and returns Y.”

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.

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 tool specifications out of the box.

If you use several LLMs, system messages and tools for different LLM tasks, it can be tedious to set options like the backend, model, system message and included tools repeatedly for each task or in each buffer. This is one of the main points of friction with using gptel interactively.²

gptel allows bundles of compatible options to be to be pre-specified and applied together, making it feasible to switch rapidly between different kinds of LLM tasks. A collection of such options is referred to as a “preset”.

Once defined, there are two ways to use a preset:

• You can apply it to just this request by referring to it anywhere in your prompt, prefixed by the @ key:

  @editor review the following explanation: ...
  

  where editor is the name of a preset. This use is described below, 9.8.1.

• You can switch to a preset persistently from gptel’s transient menu (gptel-menu). This use is described in this section.

When a gptel preset is applied, the gptel options it specifies are set, and the ones it does not specify are simply left untouched. So you can layer several presets on top of each other, with later presets taking precedence over the ones applied earlier.

Presets can be applied globally (across the Emacs session), buffer-locally or for the next request only. This is controlled by the “Scope” option in gptel’s transient menus – see 8.

Depending on the task, options in a preset could be

• Basic ones like selecting the LLM provider, the model and system message.
• Tools to include with requests..
• Request parameters like the temperature, the maximum reply size and whether to stream responses,
• gptel-specific behavior like whether it should distinguish between user prompts and LLM responses in the prompt (gptel-track-response), include images and documents with the prompt (gptel-track-media).

A preset is not limited to these options. You can specify the value of any variable that begins with “gptel-”.

To define a preset, use gptel-make-preset.

Function gptel-make-preset

Arguments:

(NAME [KEY1 VALUE1] [KEY2 VALUE2] ...)

Register a gptel options preset with NAME.

A preset is a combination of gptel options intended to be applied and used together. Presets make it convenient to change multiple gptel settings on the fly.

Typically a preset will include a model, backend, system message and perhaps some tools, but any set of gptel options can be set this way.

NAME must be a symbol. KEYS is a plist of KEY and VALUE pairs corresponding to the options being set. Recognized keys include:

DESCRIPTION is a description of the preset, used when selecting a preset.

PARENTS is a preset name (or list of preset names) to apply before this one.

PRE and POST are functions to run before and after the preset is applied. They take no arguments.

BACKEND is the gptel-backend to set, or its name (like “ChatGPT”).

MODEL is the gptel-model.

SYSTEM is the directive. It can be

• the system message (a string),
• a list of strings (template)
• or a function (dynamic system message).
• It can also be a symbol naming a directive in gptel-directives.

TOOLS is a list of gptel-tools or tool names, like '("read_url" "read_buffer" ...)

Recognized keys are not limited to the above. Any other key, like :foo, corresponds to the value of either gptel-foo (prioritized) or gptel--foo.

• So TOOLS corresponds to gptel-tools,
• CONFIRM-TOOL-CALLS to gptel-confirm-tool-calls,
• TEMPERATURE to gptel-temperature and so on.

See gptel’s customization options for all available settings.

Presets can be used to set individual options. An example of a preset to set the system message (and do nothing else):

(gptel-make-preset 'explain
  :system "Explain what this code does to a novice programmer.")

Specifying the value of a key will set the corresponding gptel option to it. For example,

(gptel-make-preset 'websearch
  :tools '("search_web" "read_url")
  :system "Use the provided tools to search the web
              for up-to-date information")

will replace the currently active option gptel-tools and the system message.

Here are some more comprehensive examples of presets:

(gptel-make-preset 'coder
  :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

(gptel-make-preset 'editor      ;can also be a string, but symbols are preferred
  :description  "Preset for proofreading tasks"
  :backend      "ChatGPT"
  :system       'proofread         ;system message looked up in gptel-directives
  :model        'gpt-4.1-mini
  :tools        '("read_buffer" "spell_check" "grammar_check")
  :temperature  0.7)

The following is a preset that sets the temperature and max tokens, and specifies how context (attached regions, buffers or files) and “reasoning” text should be handled. Crucially, it does not set the model or the backend, so it is intended to be used as a “parent” of other more specific presets.

(gptel-make-preset 'misc
  :temperature       0.2                ;sets gptel-temperature
  :max-tokens        512                ;sets gptel-max-tokens
  :include-reasoning nil                ;sets gptel-include-reasoning
  :use-context       'system)           ;sets gptel-use-context

Often it is convenient for a preset to modify the current value of a gptel option instead of setting it.

• You can require that the value of an option be appended or prepended to the existing value instead of replacing it. This can be done by specifying the value as a plist instead with the keys :prepend or :append.

  (gptel-make-preset 'websearch
    :tools  '(:append ("search_web" "read_url"))
    :system '(:prepend "Use the provided tools to search the web
                        for up-to-date information."))
  

  This preset will add the specified tools to the currently selected set in gptel-tools, and prepend the provided string to the system message.

• You can dynamically compute the value for a key at the time the preset is applied with :eval or :function. This is mostly useful when using presets in the prompt, as @preset-name.

  An :eval form is evaluated when the preset is applied:

  (gptel-make-preset 'visible-buffers
    :description "Include the full text of all buffers visible in the
                 frame."
    :context '(:eval (mapcar #'window-buffer (window-list))))
  ; ▲                ▲
  ; │                ╰╴evaluated when preset is applied
  ; ╰╴sets `gptel-context'
  

  :function should take the current value of the key as an input and return the new value. Here we combine it with :append in the plist.

  (gptel-make-preset 'github-read-only
    :description "Provide read-only GitHub tools"
    :pre (lambda () (gptel-mcp-connect '("github") 'sync))
    :tools
    '( :append ("mcp-github")       ;Adds all github MCP tools
       :function (lambda (tools)
                   (cl-delete-if    ;Remove "write" access to GitHub
                    (lambda (tool)
                      (string-match-p "create_" (gptel-tool-name tool)))
                    tools))))
  

For programmatic use, you can use gptel-with-preset to send requests with presets temporarily applied.

Macro gptel-with-preset

Arguments: (NAME &REST BODY)

Run BODY with gptel preset NAME applied.

This macro can be used to create gptel-request command with settings from a gptel preset applied. NAME is the preset name, a symbol.

Consider the common case of needing to send an LLM query with specific parameters:

(let ((gptel-backend ...)
      (gptel-model ...)
      (gptel--system-message ...)
      (gptel-tools (mapcar #'gptel-get-tool ...))
      ...)
  (gptel-request "Prompt" :callback ...))

If the required configuration is available as a preset, you can instead run

(gptel-with-preset editor               ;name of preset
  (gptel-request "Prompt" :callback ...))

The heart of gptel is the function gptel-request. It offers an easy, flexible and comprehensive way to interact with LLMs, and is responsible for state handling and for every HTTP request made by gptel. All commands offered by gptel that involve sending and receiving prompts and replies work by calling gptel-request internally.

gptel-request can be used to extend gptel, or write your own functionality independent of that offered by gptel. Below is a schematic and the full documentation of gptel-request. You may prefer to learn from examples and modify them to suit your needs instead, in which case see the gptel cookbook.

╭────────────────────────────╮         GPTEL-REQUEST
│        Arguments           │               │
│                            │               v
│        (Payload)           │  ╭────────────┴──────────────╮
│ prompt, system, transforms │  │Single or multi-part PROMPT│
│                            ├─>┤                           │
│       (Emacs state)        │  │Single or multi-part SYSTEM│
│ context, buffer, position  │  ╰────────────┬──────────────╯
│                            │               v
│    (Response handling)     │               │
│   callback, stream, fsm    │               │
╰────────────────────────────╯     ╭─────────┴──────────╮
╭────────────────────────────╮     │   Create payload   ├·····>··
│        Environment         ├────>┤        INFO        │       ·
│                            │     ╰─────────┬──────────╯       ·
│ gptel-model                │               v                  ·
│ gptel-backend              │     ╔═════════╧══════════╗       ·
│ gptel--system-message      │     ║    Send request    ║       ·
│ gptel-use-tools            │     ╚═════════╤══════════╝       ·
│ gptel-tools                │               v                  ·
│ gptel--schema              │            ╶──┴──╴               ·
│ gptel-cache                │          ╭ ─ ─ ─ ─ ─╮            ·
│ gptel-include-reasoning    │           ASYNC WAIT             ·
│ gptel-track-response       │          ╰ ─ ─ ─ ─  ╯            ·
│                            │            ╶──┬──╴               ·
│ gptel-org-convert-response │               v                  ·
╰────────────────────────────╯  ╭────────────┴─────────────╮    ·
                                │          Call            │    ·
                                │ (CALLBACK response INFO) │··<··
                                ╰────────────┬─────────────╯
                                             v
                                          ╶──┴──╴

Function gptel-request

Arguments:

(&optional PROMPT
 &key      CALLBACK (BUFFER (current-buffer))
           POSITION CONTEXT DRY-RUN (STREAM nil)
           (IN-PLACE nil) (SYSTEM gptel--system-message)
           SCHEMA TRANSFORMS (FSM (gptel-make-fsm)))

Request a response from the current gptel-backend for PROMPT.

The request is asynchronous, this function returns immediately.

If PROMPT is

• a string, it is used to create a full prompt suitable for sending to the LLM.
• A list of strings, it is interpreted as a conversation, i.e. a series of alternating user prompts and LLM responses.
• nil but region is active, the region contents are used.
• nil, the current buffer’s contents up to (point) are used. Previous responses from the LLM are identified as responses.

Keyword arguments:

CALLBACK, if supplied, is a function of two arguments, called with the RESPONSE (usually a string) and INFO (a plist):

(funcall CALLBACK RESPONSE INFO)

RESPONSE is

• A string if the request was successful
• nil if there was no response or an error.

These are the only two cases you typically need to consider, unless you need to clean up after aborted requests, use LLM tools, handle “reasoning” content specially or stream responses (see STREAM). In these cases, RESPONSE can be

• The symbol abort if the request is aborted, see gptel-abort.

• A cons cell of the form

  (tool-call . ((TOOL ARGS CB) ...))
  

  where TOOL is a gptel-tool struct, ARGS is a plist of arguments, and CB is a function for handling the results. You can call CB with the result of calling the tool to continue the request.

• A cons cell of the form

  (tool-result . ((TOOL ARGS RESULT) ...))
  

  where TOOL is a gptel-tool struct, ARGS is a plist of arguments, and RESULT was returned from calling the tool function.

• A cons cell of the form

  (reasoning . text)
  

  where text is the contents of the reasoning block. (Also see STREAM if you are using streaming.)

See gptel--insert-response for an example callback handling all cases.

The INFO plist has (at least) the following keys: :data - The request data included with the query :position - marker at the point the request was sent, unless POSITION is specified. :buffer - The buffer current when the request was sent, unless BUFFER is specified. :status - Short string describing the result of the request, including possible HTTP errors.

Example of a callback that messages the user with the response and info:

(lambda (response info)
  (if (stringp response)
      (let ((posn (marker-position (plist-get info :position)))
            (buf  (buffer-name (plist-get info :buffer))))
        (message "Response for request from %S at %d: %s"
                 buf posn response))
    (message "gptel-request failed with message: %s"
             (plist-get info :status))))

Or, for just the response:

(lambda (response _)
  ;; Do something with response
  (and (stringp response)
       (message (rot13-string response))))

If CALLBACK is omitted, the response is inserted at the point the request was sent.

STREAM is a boolean that determines if the response should be streamed, as in gptel-stream. If the model or the backend does not support streaming, this will be ignored.

When streaming responses

• CALLBACK will be called repeatedly with each RESPONSE text chunk (a string) as it is received.
• When the HTTP request ends successfully, CALLBACK will be called with a RESPONSE argument of t to indicate success.
• Similarly, CALLBACK will be called with (reasoning . text-chunk) for each reasoning chunk, and (reasoning . t) to indicate the end of the reasoning block.

BUFFER and POSITION are the buffer and position (integer or marker) at which the response is inserted. If a CALLBACK is specified, no response is inserted and these arguments are ignored, but they are still available in the INFO plist passed to CALLBACK for you to use.

BUFFER defaults to the current buffer, and POSITION to the value of (point) or (region-end), depending on whether the region is active.

CONTEXT is any additional data needed for the callback to run. It is included in the INFO argument to the callback. Note: This is intended for storing Emacs state to be used by CALLBACK, and unrelated to the context supplied to the LLM.

SYSTEM is the system message or extended chat directive sent to the LLM. This can be a string, a list of strings or a function that returns either; see gptel-directives for more information. If SYSTEM is omitted, the value of gptel--system-message for the current buffer is used.

The following keywords are mainly for internal use:

IN-PLACE is a boolean used by the default callback when inserting the response to determine if delimiters are needed between the prompt and the response.

If DRY-RUN is non-nil, do not send the request. Construct and return a state machine object that can be introspected and resumed.

TRANSFORMS is a list of functions used to transform the prompt or query parameters dynamically. Each function is called in a temporary buffer containing the prompt to be sent, and can conditionally modify this buffer. This can include changing the (buffer-local) values of the model, backend or system prompt, or augmenting the prompt with additional information (such as from a RAG engine).

• Synchronous transformers are called with zero or one argument, the state machine for the request.
• Asynchronous transformers are called with two arguments, a callback and the state machine. It should run the callback after finishing its transformation.

See gptel-prompt-transform-functions for more.

If provided, SCHEMA forces the LLM to generate JSON output. Its value is a JSON schema, which can be provided as

• an elisp object, a nested plist structure.
• A JSON schema serialized to a string.
• A shorthand object/array description, see gptel--dispatch-schema-type.

Note: SCHEMA is presently experimental and subject to change, and not all providers support structured output.

FSM is the state machine driving the request. This can be used to define a custom request control flow, see 10.4 for details.

Note:

1. This function is not fully self-contained. Consider let-binding the parameters gptel-backend, gptel-model, gptel-use-tools, gptel-track-response and gptel-use-context around calls to it as required.
2. The return value of this function is a state machine object that may be used to rerun or continue the request at a later time. See 10.4.

gptel-request can force the LLM to generate output that follows a specified JSON schema. This can be useful when it is used as part of a data processing pipeline, or when gptel-request needs to be plugged into Elisp code that expects structured data.

NOTE(v0.9.8.5): JSON output is compatible with tool-use for all gptel backends except for Anthropic. Requests to Anthropic models cannot include both tools and a JSON schema.

Here is a frivolous example demonstrating this feature:

(gptel-request "Generate three quirky dogs"
  :system nil
  :schema "[name, age int, hobby, short_bio]")

This returns

{
  "items": [
    {
      "name": "Baxter",
      "age": 5,
      "hobby": "Chasing shadows and hoarding squeaky toys",
      "short_bio":
      "Baxter is the neighborhood's self-declared shadow detective."
    },
    {
      "name": "Peaches",
      "age": 3,
      "hobby": "Dancing on hind legs and stealing socks",
      "short_bio":
      "Peaches twirls through life with a sock in her mouth and a heart full of mischief."
    },
    {
      "name": "Ziggy",
      "age": 7,
      "hobby": "Sniffing out hidden treats and composing howling symphonies",
      "short_bio":
      "Ziggy is a gourmet snack seeker and an opera star in the canine world."
    }
  ]
}

A more useful example is generating diagnostics for an Emacs buffer. For example:

(save-excursion
  (goto-char (point-max))
  (gptel-request nil                    ;send whole buffer
    :system
    "Proofread this text buffer for stylistic errors, cliche and purple prose.
     Ignore parts that look like markup or code.
     Do NOT report text that is satisfactory."
    :schema
    "[start_line int: Starting line number of text to which this diagnostic applies
      text: Text to which this diagnostic applies
      problem: Short description of problem
      replacement: Exact replacement text or fix for diagnostic]"))

The list of diagnostics can be plugged into a linting interface such as Flymake, for example. (See flymake.)

The SCHEMA argument may be specified in many ways. From the easiest (and most restrictive) to the hardest (and most flexible), these are:

As a comma-separated list of keys with optional types. The following are equivalent ways of specifying a simple object, i.e. one that does not itself contain objects/arrays:

;; prop [type], prop [type], ...

  "name, age integer, hobby, short_bio" ;type is assumed to be string

Type defaults to string if not specified. Types can be shortened as long as they match a supported JSON schema type uniquely. (number, integer, string, boolean, null).

"name str, age int, hobby, short_bio str" ;with shortened types

gptel expands this to the schema

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" },
    "hobby": { "type": "string" },
    "short_bio": { "type": "string" }
  }
}

To specify an array of objects of this type, enclose the above specifications in [ and ]:

;; [prop [type], prop [type], ...]

  "[name, age integer, hobby, short_bio]"

gptel expands this to the schema³

{ "type": "array",
  "items": {
      "type": "object",
      "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "hobby": {"type": "string"},
          "short_bio": {"type": "string"}
      }
  }
}

Often it is useful to add a description to JSON object properties to help guide the LLM. You can do this by using a multi-line shorthand like the following:

;; key [type]: [description]
;; key [type]: [description]...

  "name: Name of the dog
   age int: Age of the dog in years
   hobby: What the dog likes to do
   short_bio: A one-sentence biography of the dog"

gptel expands this to

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name of the dog"
    },
    "age": {
      "type": "integer",
      "description": "Age of the dog in years"
    },
    "hobby": {
      "type": "string",
      "description": "What the dog likes to do"
    },
    "short_bio": {
      "type": "string",
      "description": "A one-sentence biography of the dog"
    }
  }
}

Whitespace between fields is not significant. The type, separator ":" and the description are all optional, so this is valid:

"name:
 age int: Age of the dog in years
 hobby
 short_bio: A one-sentence biography of the dog"

As before, to specify an array of objects of this type you can enclose the text in [ and ]:

"[name:
  age int: Age of the dog in years
  hobby
  short_bio: A one-sentence biography of the dog]"

More complex schema (with enums, optional entries etc) can be specified in two ways.

If you have the JSON schema at hand, you can instead supply it directly as a serialized string:

(gptel-request "Generate a quirky dog"
  :system nil
  :schema "{\"type\":\"object\",\"properties\":
           {\"name\":{\"type\":\"string\"},
            \"age\":{\"type\":\"integer\"},
            \"hobby\":{\"type\":\"string\"},
            \"short_bio\":{\"type\":\"string\"}}}")

Otherwise, it must be specified as a plist, similar to how tool arguments are, see 9.7.2.1.

gptel’s elisp specification object and array versions of the above examples are, for instance:

( :type object                        ;Object version
  :properties
  ( :name ( :type string)
    :age ( :type integer
           :description "Age of the dog in years")
    :hobby ( :type string)
    :short_bio ( :type string
                 :description "A one-sentence biography of the dog")))

( :type array                         ;Array of objects version
  :items
  ( :type object
    :properties
    ( :name ( :type string)
      :age ( :type integer
             :description "Age of the dog in years")
      :hobby ( :type string)
      :short_bio ( :type string
                   :description "A one-sentence biography of the dog"))))

gptel’s interactions with LLMs are typically limited to a query followed a response, but can involve several back-and-forth exchanges when tool calls or custom behavior is involved. Under the hood, gptel uses a Finite State Machine (FSM) to manage the lifecycle of all LLM interactions.

Datatype gptel-fsm

Fields:

STATE TABLE HANDLERS INFO

A finite state machine object consists of the fields STATE, TABLE, HANDLERS and INFO.

FSMs may be created by the constructor gptel-make-fsm.

Function gptel-make-fsm

Arguments:

(&key STATE TABLE HANDLERS INFO)

STATE: The current state of the machine, can be any symbol.

TABLE: Alist mapping states to possible next states along with predicates to determine the next state. See gptel-request--transitions for an example.

HANDLERS: Alist mapping states to state handler functions. Handlers are called when entering each state. See gptel-request--handlers for an example

INFO: The state machine’s current context. This is a plist holding all the information required for the ongoing request, and can be used to tweak and resume a paused request. (This should be called “context”, but context means too many things already in gptel.)

Each gptel request is passed an instance of this state machine and driven by it.

The FSM is in one of several possible states, and collects contextual information in its INFO plist.

Its transition table (TABLE) encodes possible states and predicates that are used to decide which state to switch to next. This is an example of a transition table:

((INIT . ((t                    . WAIT)))
 (WAIT . ((t                    . TYPE)))
 (TYPE . ((gptel--error-p       . ERRS)
          (gptel--tool-use-p    . TOOL)
          (t                    . DONE)))
 (TOOL . ((gptel--error-p       . ERRS)
          (gptel--tool-result-p . WAIT)
          (t                    . DONE))))

The possible states of the FSM in this example are INIT, WAIT, TYPE, TOOL, ERRS and DONE. These are gptel’s default FSM states and denoted by upper-case symbols here. But there is no special significance to them, and they can be arbitrary identifiers.

Each state in this table maps to a list of conses of the form (predicate . NEXT-STATE).

Function gptel--fsm-next

Arguments: (MACHINE)

Determine the next state for MACHINE. Run through the predicates for the current state in the transition table, calling each one with INFO until one succeeds. A predicate of t is treated as always true. Return the corresponding state.

The FSM’s HANDLERS is a list of functions that are run upon entering a new state. This is an example of FSM handlers:

((WAIT gptel--handle-wait)
 (TOOL gptel--handle-tool-use))

Both the WAIT and TOOL states have one handler each, and other states do not have any handlers associated with them.

The state handler is the workhorse: its job is to produce the side effects required for the LLM request, such as inserting responses into buffers, updating the UI, running tools and so on. Handlers also upate the FSM’s INFO as necessary, capturing information for the transition-table predicates to use, and transition the FSM to the next state.

Function gptel--fsm-transition

Arguments:

(MACHINE &optional NEW-STATE)

Transition MACHINE to NEW-STATE or its natural next state. Run the HANDLERS corresponding to that state.

Handlers can be asynchronous, in that the call to gptel--fsm-transition can occur in a process sentinel or some other kind of delayed callback.

A typical state sequence for a gptel request can thus look like

INIT -> WAIT -> TYPE -> TOOL -> WAIT -> TYPE -> DONE

corresponding to a query that resulted in a tool call, followed by sending the tool result back to the LLM to be interpreted, and then a final response.

The buffer-local variable gptel--fsm-last stores the FSM for the latest gptel request, and is updated as it changes. You can inspect this at any time to track what gptel is up to in that buffer. gptel provides a helper function that visualizes the state of the FSM:

Function gptel--inspect-fsm

Pop up a buffer to inspect the latest (possibly in-progress) gptel request in the current buffer.

In between conversation turns or calls to gptel-request, gptel is mostly stateless. However it maintains a limited amount of state in the buffer text itself via text-properties. This state is used only to assign user/LLM/tool roles to the text, and may be persisted to the file. No other history is maintained, and gptel--fsm-last is overwritten when another request is started from the same buffer.

A “chat buffer” is any text, Markdown or Org mode buffer where gptel-mode is turned on. This is a regular Emacs buffer and is freely editable.

While gptel provides a few knobs for modifying its behavior in chat buffers (9.2), it makes minimal assumptions about the format of the chat or the structure, layout of chat buffers. In particular, it does not add any automatic behavior. This section provides recipes for some quality of life improvements to gptel chat buffer behavior.

gptel does not modify or post-process LLM responses to gptel-send commands in any way except one: when in an Org mode buffer, it converts (possibly) Markdown output to Org mode. (9.2.1)

There are several commonly requested modifications that fall under the umbrella of “sanitizing” the response. This section explains how to apply them when using gptel-send via the gptel-post-response-functions hook.

Further below we cover more involved response transformations you can do by reaching into the guts of gptel’s state machine.

The entry point to the request library is the gptel-request function, which presents a unified way to interact with any LLM that gptel supports. It can be used as a building block for custom commands that live in your configuration, for custom workflows, or even to build complex packages.

If you intend to use gptel-request to write specialized LLM interaction commands or build a different UI, you can require only the gptel-request feature:

(require 'gptel-request)

This way you avoid loading unnecessary code, such as gptel’s chat buffer UI or Transient menus.

By way of examples, this chapter describes how to do these things with gptel-request.

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

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

• gptel-aibo: A writing assistant system built on top of gptel.
• Evedel: Instructed LLM Programmer/Assistant.
• Elysium: Request AI-generated changes as you code.
• gptel-watch: Automatically call gptel when typing lines that indicate intent.

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

• Macher: Project-aware multi-file LLM editing for Emacs.

Text completion

• gptel-autocomplete: Inline completions using gptel.

Integration with major-modes

• ob-gptel: Org-babel backend for running gptel queries.
• ai-blog.el: Streamline generation of blog posts in Hugo.
• gptel-commit: Generate commit messages using gptel.
• magit-gptcommit: Generate commit messages within magit-status Buffer using gptel.
• gptel-magit: Generate commit messages for magit using gptel.

Chat interface addons

• Corsair: Helps gather text to populate LLM prompts for gptel.
• 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

• consult-omni: Versatile multi-source search package. It includes gptel as one of its many sources.

gptel configuration management

• gptel-prompts: System prompt manager for gptel.