gptel

name	gptel
description	Use when the user asks about gptel, the Emacs LLM client, or wants help understanding, using, configuring, customizing, debugging, or extending gptel. Covers backends, models, prompts, presets, context, tools, rewrite flows, MCP integration, gptel-request, and custom Emacs integrations. Also matches Chinese requests about 理解/使用/配置/定制/扩展 gptel.

gptel

Help with gptel by combining upstream documentation with the user's actual Emacs configuration. Prefer the smallest change that fits the user's package manager and config style.

Source of truth

• Treat the gptel manual and upstream repository as authoritative for package behavior.
• For anything version-sensitive or surprising, inspect the installed gptel source if present, then verify against upstream docs.
• Do not invent functions, variables, backends, or hook signatures. Search first if unsure.

Quick start

1. Identify the request type: explanation, setup, customization, extension, or debugging.
2. Inspect the user's local config before proposing edits when files are available. Search common paths such as ~/.emacs.d/, ~/.config/emacs/, Doom's config.el, or literate configs for gptel, use-package, backend setup, and keybindings.
3. Keep edits consistent with the local style: use-package, straight.el, package.el, Doom macros, or plain setq.
4. Prefer higher-level extension points before deeper surgery:
   • settings and presets
   • directives and one-shot prompt cookies
   • hooks like gptel-post-response-functions
   • tools via gptel-make-tool
   • direct API use with gptel-request
5. When debugging, turn on inspectable flows before rewriting config. See references/gptel-workflows.md.

Task map

Understanding gptel

Explain the mental model in this order:

1. A backend and model are selected.
2. A request is assembled from buffer text, context, tools, and directives.
3. gptel-send or gptel-request sends it asynchronously.
4. The response lands in a chat buffer, rewrite buffer, or callback.
5. Hooks, presets, and tools shape behavior before and after the request.

For beginner explanations, distinguish clearly between:

• interactive chat usage
• rewrite/refactor flows in an existing buffer
• programmatic use from Elisp

Using and configuring gptel

For setup and everyday usage:

• Start with the minimum working backend configuration.
• Show exact Elisp snippets, not pseudocode.
• Keep secrets out of files when possible; prefer environment variables or auth sources.
• Explain whether each setting is global, buffer-local, or request-local.
• For prompt behavior, prefer directives and presets over custom wrappers.
• For repeatable workflows, suggest named presets instead of duplicated setq blocks.

Customizing gptel

Common safe customization surfaces:

• gptel-model, backend selection, API endpoints
• gptel-directives
• presets and gptel-with-preset
• chat buffer modes and context collection
• rewrite behavior
• post-response hooks
• keybindings and transient/menu integration

When the user wants "make it feel like X", first map that desire onto one of:

• prompt discipline
• context discipline
• output post-processing
• buffer UX
• tool access

Extending gptel

For deeper integrations:

• Use gptel-request for custom commands, package integrations, or structured callbacks.
• Use gptel-make-tool when the model needs explicit callable tools.
• Mention MCP only when the user's version and setup support it and the task actually needs external tools.
• If building a reusable extension package, keep gptel-specific code behind small wrapper functions and avoid hard-coding user secrets or provider assumptions.

Read references/gptel-workflows.md for extension patterns and references/upstream-map.md when you need the right upstream section fast.

Debugging gptel

Debug in this order:

1. backend, auth, or model mismatch
2. request assembly and prompt content
3. buffer-local state or preset interference
4. hooks or advice mutating responses
5. provider-specific or tool-specific behavior

Prefer inspection over guesswork. Use:

• config search with rg
• source inspection for function and variable definitions
• minimal reproduction snippets
• request introspection via gptel--inspect-fsm when relevant

Output rules

• When editing config, preserve the user's existing Emacs style.
• Prefer one self-contained snippet over a long configuration essay.
• Say explicitly what the user should evaluate or restart, if anything.
• If you infer behavior from source instead of manual text, say so.
• When a change is risky, show the smallest reversible version first.

Reference map

Load only what you need:

• references/gptel-workflows.md for concrete configuration, customization, extension, and debugging playbooks.
• references/upstream-map.md for the shortest path to the relevant manual section or upstream topic.