add
This commit is contained in:
+254
@@ -0,0 +1,254 @@
|
||||
# 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! 🎉**
|
||||
Reference in New Issue
Block a user