gptel: an LLM client that lives inside your Emacs buffers

The problem gptel solves for Emacs users

Most LLM clients are separate applications. You copy text out of your editor, paste it into a chat window, copy the answer back, and lose the connection between the prompt and the file it came from. gptel takes the opposite position: the client is an Emacs package, and it is available "at any time and uniformly in any buffer," as the README puts it. That means you can send a region, a buffer, or a shell line to a model without leaving the editing context you were already in. The intended audience is narrow and specific. It is for people who already run Emacs as their primary environment and who are comfortable with Emacs Lisp configuration. The README's own framing is telling: gptel "works in the spirit of Emacs." If that sentence means nothing to you, the package is probably not for you. If it means a lot, the rest of the design follows from it. Responses arrive as Markdown or Org markup, chats are saved as ordinary Markdown, Org, or text files, and you can edit a previous prompt or a previous model response and have the edited version fed back to the model.

How gptel routes a prompt to a backend

The repository layout shows the architecture more clearly than the README does. gptel.el is the core, and the backend-specific files sit beside it: gptel-openai.el, gptel-anthropic.el, gptel-gemini.el, gptel-ollama.el, gptel-bedrock.el, gptel-kagi.el, and gptel-gh.el. There are also gptel-request.el for request handling, gptel-context.el for gathering context, gptel-rewrite.el for the rewrite workflow, gptel-org.el for Org mode conveniences, and gptel-transient.el for the transient menu. That file split is the design: a shared request path with per-provider translation layers. gptel-openai-responses.el and gptel-openai-oauth.el suggest that the OpenAI integration alone has enough variation to need its own files. On the transport side, the README states that gptel uses Curl if available but falls back to the built-in url-retrieve to work without external dependencies. That fallback is a real design decision worth noting: it means gptel can function on a bare Emacs install, but it also means the network path you get depends on what is present on the machine, which complicates debugging when a request fails. The README also describes introspection, so you can see exactly what will be sent, and pause multi-stage requests at an intermediate stage and resume them later. Those two features are the ones that make the request path inspectable rather than opaque.

Installing gptel and sending a first prompt

The README documents four installation routes: Straight, Manual, Doom Emacs, and Spacemacs. The package is published on GNU ELPA, GNU ELPA Devel, MELPA Stable, and MELPA, as the four badges at the top of the README indicate. The README's setup section starts with OpenAI, and its optional subsections cover securing API keys with authinfo and reading API keys from environment variables. Those two routes are the ones to prefer if your configuration is version-controlled, since the alternative is a key sitting in plain text in your init file. With a backend configured, the README's usage section separates two entry points: prompting in any buffer, and prompting in a dedicated chat buffer. The distinction matters. The first is a one-off interaction against the current buffer or region. The second maintains a conversation that you can save and resume later. The README also documents including media (images, documents or plain-text files) with requests, and handling reasoning content in LLM responses. For a first real use, open a file, select a region, and invoke gptel's send command; the response is inserted as Markdown or Org markup depending on the buffer. The README's FAQ addresses the two things you will want to change immediately: making the window scroll automatically as the response is inserted, and moving the cursor to the next prompt after the response is inserted.

Tool use and MCP are where gptel stops being a chat box

The README lists tool use and Model Context Protocol integration as first-class features, and the repository reflects that with dedicated sections on defining gptel tools, selecting tools, and LLM tool collections. MCP integration goes through mcp.el, a separate package by lizqwerscott, so it is not built into gptel itself. That is worth understanding before you plan around it: enabling MCP means adding a dependency outside the gptel repository, and the gptel README points at that project rather than documenting the protocol handling itself. Tool use is the more self-contained feature. The README's structure implies a workflow where you define tools, select which ones are active, and group them into collections. The README's own FAQ acknowledges the friction this creates: one entry asks how to set gptel options for a single buffer, and another asks how to make transient menu options persist so they only need to be set once. Those questions exist because the default model is per-invocation configuration. If you expect tool selection to be a global setting you configure once and forget, the FAQ entries suggest otherwise.

Where gptel is the wrong tool

The most obvious limitation is the one the README does not need to state: gptel requires Emacs. There is no standalone binary, no web interface, and no mobile client. If a teammate does not use Emacs, they cannot use your gptel setup, and any shared prompt library you build in Org files is only accessible to people who can open Org files in Emacs. A second limitation is configuration surface. The README documents roughly two dozen backends, each with its own setup subsection and its own quirks. The presence of separate files for OpenAI responses and OpenAI OAuth shows that a single provider can require multiple integration paths. Multi-modal input, reasoning content, and tool use each add their own configuration. This is a package that rewards reading the manual and punishes guessing. A third limitation concerns the transport fallback. Because gptel uses Curl when available and url-retrieve otherwise, two machines with the same gptel configuration can behave differently on the network path. The README does not document rollback, so if a release changes behaviour you disagree with, your options are to pin a version or to read NEWS and adjust. Finally, the README's FAQ includes an entry about a Doom Emacs key conflict when sending a query from the gptel menu. Keybinding collisions with other packages are a normal Emacs problem, but they are a real cost of installing a client that binds keys globally.

gptel against a standalone LLM client

The natural alternative is a standalone desktop or browser chat client that talks to the same backends. The difference is not the model access; both can reach OpenAI, Anthropic, or a local Ollama instance. The difference is where the text lives. A standalone client owns its own document store, and moving text between it and your source files is a manual copy. gptel has no document store of its own beyond the buffers and files you already have. Chats are saved as regular Markdown, Org, or text files, which means they are diffable, greppable, and version-controllable with the same tools you use for code. For someone whose work product is already text files in a repository, that is a meaningful difference. For someone who wants a persistent sidebar, a conversation history browser, and a graphical interface, the standalone client wins on ergonomics and gptel offers nothing comparable. The choice is really about whether your editor should be the client. gptel's answer is yes, and every design decision in the README follows from that answer.

Maintenance, releases, and the GPL-3.0 licence

gptel is licensed GPL-3.0. If you are embedding it in a larger Emacs configuration for personal use, that is unremarkable. If you are redistributing a modified gptel or bundling it into a distributed product, GPL-3.0 carries obligations that differ from permissive licences, and you should read the LICENSE file rather than rely on a summary. This is not legal advice; it is a pointer to the file that governs. On maintenance, the repository is not archived and the last push was on 2026-09-09. The release cadence visible in the release list is irregular: v0.9.9.6 arrived on 2026-09-06, v0.9.9.5 on 2026-05-04, and v0.9.9.4 on 2026-02-22. That is roughly one release every few months, with the version numbers suggesting incremental rather than major changes. The practical upgrade cost is the NEWS file at the repository root. Because gptel integrates with so many backends, a change to one provider's API can land in a release that also touches unrelated parts of the package. Reading NEWS before upgrading is cheaper than debugging a backend that stopped working. The four package archives (GNU ELPA, GNU ELPA Devel, MELPA Stable, MELPA) also give you a choice between tracking stable and tracking development, which is a lever worth using if you depend on the package daily.

Editorial conclusion

Adopt gptel if your work already happens in Emacs buffers and Org files and you want prompts to travel through the same editing surface. Do not adopt it if you want a standalone chat application with a graphical interface, or if you are not prepared to configure a backend and an API key yourself. Before committing, verify that the backend you intend to use appears in the README's backend list, check whether your Emacs installation has Curl available or will fall back to url-retrieve, and read the NEWS file for breaking changes between releases.

Frequently asked questions

Official sources

1. Issues
2. karthink/gptel on GitHub
3. License: GPL-3.0
4. README
5. Releases