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.

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.

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 8.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 8.6.
   • Apply any presets specified in the prompt text via the @preset cookie (see 8.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 9.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 8.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 8.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 8.3 for details.

7. If gptel-use-tools is non-nil and gptel-tools contains a list of gptel tools (See 8.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 7.

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

• gptel-prompt-prefix-alist

• gptel-response-prefix-alist

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 8.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 8.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, you can switch to a preset from gptel’s transient menu (gptel-menu). 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 7.

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.")

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

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

╭────────────────────────────╮         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 9.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 9.4.

gptel-request presents a versatile API, and its uses and arguments are specified in greater detail in the sections that follow.

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.

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

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.