tomatocream/doom

Fork 0

Files

T

tomatocream c23a1ba64a aeuaeo

2025-11-07 01:26:43 +08:00

6.8 KiB

Raw Blame History

gptel Configuration Guide

🎉 What Was Configured

Your Doom Emacs now has a comprehensive gptel setup with:

✅ Installed Packages

gptel - Main LLM client
gptel-quick - Quick lookups in popup
gptel-extensions - Extra utility functions
gptel-autocomplete - Inline code completion

✅ Configured Features

✨ OpenRouter backend with multiple models (Gemini, Claude)
📝 Org-mode as default (better for saving conversations)
⌨️ Comprehensive keybindings under SPC a prefix
🎨 5 task-specific presets (coder, explain, refactor, quick, docs)
🤖 Auto-completion in programming modes
🛠️ Custom helper functions for quick explanations and proofreading

🔐 IMPORTANT: Secure Your API Key

⚠️ WARNING: Your OpenRouter API key is currently hardcoded in ai.el. This is a security risk!

Recommended Setup: Use auth-source

Create encrypted credentials file:

touch ~/.authinfo.gpg
chmod 600 ~/.authinfo.gpg

Add your API key to ~/.authinfo.gpg:
```
machine openrouter.ai login apikey password sk-or-v1-YOUR_KEY_HERE
```
Emacs will prompt for a password to encrypt this file.

Update ~/.config/doom/ai.el:

Replace the :key line in the gptel-make-openai section:

;; BEFORE (insecure):
:key "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"

;; AFTER (secure):
:key (auth-source-pick-first-password :host "openrouter.ai")

Reload Doom:
```
doom sync
```

⌨️ Keybindings Reference

All gptel commands are under SPC A (uppercase A - AI prefix):

Keybinding	Command	Description
`SPC A g`	`gptel`	Open gptel chat buffer
`SPC A s`	`gptel-send`	Send prompt to LLM
`SPC A m`	`gptel-menu`	Open transient menu (change model, backend, etc)
`SPC A r`	`gptel-rewrite`	Rewrite selected region with AI
`SPC A c`	`gptel-add`	Add region/buffer to context
`SPC A f`	`gptel-add-file`	Add file to context
`SPC A q`	`gptel-quick`	Quick lookup in popup (word/region)
`SPC A l`	Load buffer into session	Send whole buffer as context
`SPC A b`	Send whole buffer	Send entire buffer to AI
`SPC A R`	Refactor region	Refactor selected code
`SPC A e`	Quick explain	Explain selected code quickly
`SPC A p`	Proofread text	Fix grammar/spelling in selection
`SPC A C`	Complete at point	Trigger AI code completion
`SPC A a`	Accept completion	Accept displayed ghost text completion

In gptel buffer:

C-c RET - Send message
C-c C-c - Open menu
C-c C-k - Abort request

Auto-completion (in programming modes):

M-TAB or C-c TAB - Trigger completion (gptel-complete)
C-c C-a - Accept completion (gptel-accept-completion)

🎨 Using Presets

Presets let you switch AI behavior for specific tasks:

Open gptel menu: SPC A m or C-c C-c
Select "Preset" option
Choose from:
- coder - Expert coding assistant (uses Claude Sonnet 4.5)
- explain - Explain code to beginners
- refactor - Code refactoring expert
- quick - Quick, concise answers (uses fast Gemini Flash)
- docs - Documentation writer

Or use C-u SPC A s to adjust settings on-the-fly!

🚀 Quick Start Workflows

1. Chat with AI

SPC A g          → Opens gptel buffer
Type question    → Write your prompt
C-c RET         → Send (or SPC A s)

2. Rewrite Code

1. Select code region (visual mode)
2. SPC A r
3. Type instruction: "Add error handling"
4. Review changes and accept

3. Add Context (Multi-file awareness)

1. Open reference file
2. SPC A c (adds buffer to context)
3. Open gptel: SPC A g
4. Now AI knows about the reference file!

4. Quick Explanations

1. Hover over word or select code
2. SPC A q
3. See explanation in popup!

5. Code Completion

Start typing code...
M-TAB or SPC A C    → Request AI completion (shows as ghost text)
C-c C-a or SPC A a  → Accept the completion

🏠 Local Models with Ollama (Optional)

Want to run AI locally for privacy?

Install Ollama:

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama
ollama serve

Pull models:

ollama pull qwen2.5-coder:latest
ollama pull mistral:latest

Uncomment Ollama config in ai.el:

Look for the "Optional: Add Ollama" section around line 126 and uncomment:

(after! gptel
  (gptel-make-ollama "Ollama"
    :host "localhost:11434"
    :stream t
    :models '(qwen2.5-coder:latest
              mistral:latest
              llama3.2:latest)))

To make Ollama default, uncomment lines 136-141 as well
Reload: doom sync
Switch backends: SPC a m → Select "Backend" → Choose "Ollama"

🎯 Pro Tips

Save conversations: gptel uses org-mode by default, so just save the buffer!
Switch models on-the-fly: C-u SPC A s before sending
Context management:
- Add files in Dired: Mark files → SPC A c
- Remove context: SPC A m → Manage context
Org-mode features:
- Each heading can be a separate conversation branch
- Set properties: M-x gptel-org-set-properties
- Set topic: M-x gptel-org-set-topic
Custom instructions: Use SPC A r on selected code and give specific instructions
Programmatic use: See helper functions at bottom of ai.el for examples

📚 Next Steps

Secure your API key (see section above)
Run: doom sync to install packages
Restart Emacs
Try: SPC A g to start chatting!
Watch: "Every LLM in Emacs, with gptel" video (17 min)

🐛 Troubleshooting

Packages not loading?

doom sync
doom build

Transient version error?

;; Add to ai.el before gptel config:
(setq package-install-upgrade-built-in t)

Then: M-x package-install RET transient RET

API key not working?

Check ~/.authinfo.gpg format
Ensure proper encryption password
Test: (auth-source-pick-first-password :host "openrouter.ai")

Autocomplete not working?

Trigger manually: M-x gptel-complete or M-TAB
Accept completion: M-x gptel-accept-completion or C-c C-a
Note: There's no auto-mode - you trigger completions on-demand
Check gptel is configured and working first (SPC A g)
Adjust context size if needed (see gptel-autocomplete-*-context-lines variables)

📖 Resources

Enjoy your AI-powered Emacs! 🎉

6.8 KiB Raw Blame History