255 lines
6.3 KiB
Markdown
255 lines
6.3 KiB
Markdown
# gptel Configuration Guide
|
|
|
|
## 🎉 What Was Configured
|
|
|
|
Your Doom Emacs now has a comprehensive gptel setup with:
|
|
|
|
### ✅ Installed Packages
|
|
1. **gptel** - Main LLM client
|
|
2. **gptel-quick** - Quick lookups in popup
|
|
3. **gptel-extensions** - Extra utility functions
|
|
4. **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
|
|
|
|
1. **Create encrypted credentials file:**
|
|
```bash
|
|
touch ~/.authinfo.gpg
|
|
chmod 600 ~/.authinfo.gpg
|
|
```
|
|
|
|
2. **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.
|
|
|
|
3. **Update `~/.config/doom/ai.el`:**
|
|
|
|
Replace the `:key` line in the `gptel-make-openai` section:
|
|
```elisp
|
|
;; BEFORE (insecure):
|
|
:key "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"
|
|
|
|
;; AFTER (secure):
|
|
:key (auth-source-pick-first-password :host "openrouter.ai")
|
|
```
|
|
|
|
4. **Reload Doom:**
|
|
```bash
|
|
doom sync
|
|
```
|
|
|
|
---
|
|
|
|
## ⌨️ Keybindings Reference
|
|
|
|
All gptel commands are under `SPC 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 |
|
|
|
|
### 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
|
|
|
|
---
|
|
|
|
## 🎨 Using Presets
|
|
|
|
Presets let you switch AI behavior for specific tasks:
|
|
|
|
1. Open gptel menu: `SPC a m` or `C-c C-c`
|
|
2. Select "Preset" option
|
|
3. 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 → Shows AI completion as ghost text
|
|
TAB → Accept completion
|
|
```
|
|
|
|
---
|
|
|
|
## 🏠 Local Models with Ollama (Optional)
|
|
|
|
Want to run AI locally for privacy?
|
|
|
|
1. **Install Ollama:**
|
|
```bash
|
|
# Linux
|
|
curl -fsSL https://ollama.com/install.sh | sh
|
|
|
|
# Start Ollama
|
|
ollama serve
|
|
```
|
|
|
|
2. **Pull models:**
|
|
```bash
|
|
ollama pull qwen2.5-coder:latest
|
|
ollama pull mistral:latest
|
|
```
|
|
|
|
3. **Uncomment Ollama config in `ai.el`:**
|
|
|
|
Look for the "Optional: Add Ollama" section around line 126 and uncomment:
|
|
```elisp
|
|
(after! gptel
|
|
(gptel-make-ollama "Ollama"
|
|
:host "localhost:11434"
|
|
:stream t
|
|
:models '(qwen2.5-coder:latest
|
|
mistral:latest
|
|
llama3.2:latest)))
|
|
```
|
|
|
|
4. **To make Ollama default**, uncomment lines 136-141 as well
|
|
|
|
5. **Reload:** `doom sync`
|
|
|
|
6. **Switch backends:** `SPC a m` → Select "Backend" → Choose "Ollama"
|
|
|
|
---
|
|
|
|
## 🎯 Pro Tips
|
|
|
|
1. **Save conversations**: gptel uses org-mode by default, so just save the buffer!
|
|
|
|
2. **Switch models on-the-fly**: `C-u SPC a s` before sending
|
|
|
|
3. **Context management**:
|
|
- Add files in Dired: Mark files → `SPC a c`
|
|
- Remove context: `SPC a m` → Manage context
|
|
|
|
4. **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`
|
|
|
|
5. **Custom instructions**: Use `SPC a r` on selected code and give specific instructions
|
|
|
|
6. **Programmatic use**: See helper functions at bottom of `ai.el` for examples
|
|
|
|
---
|
|
|
|
## 📚 Next Steps
|
|
|
|
1. **Secure your API key** (see section above)
|
|
2. **Run:** `doom sync` to install packages
|
|
3. **Restart Emacs**
|
|
4. **Try:** `SPC a g` to start chatting!
|
|
5. **Watch:** "Every LLM in Emacs, with gptel" video (17 min)
|
|
|
|
---
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Packages not loading?
|
|
```bash
|
|
doom sync
|
|
doom build
|
|
```
|
|
|
|
### Transient version error?
|
|
```elisp
|
|
;; 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 showing?
|
|
- Enable manually: `M-x gptel-autocomplete-mode`
|
|
- Check if in prog-mode buffer
|
|
- May need specific model configuration
|
|
|
|
---
|
|
|
|
## 📖 Resources
|
|
|
|
- [gptel GitHub](https://github.com/karthink/gptel)
|
|
- [gptel Manual](https://gptel.org/manual.html)
|
|
- [OpenRouter Docs](https://openrouter.ai/docs)
|
|
- [Ollama Models](https://ollama.com/library)
|
|
|
|
---
|
|
|
|
**Enjoy your AI-powered Emacs! 🎉**
|