| name | helix-teacher |
| description | Teaches Helix editor by analyzing the user's existing configuration, explaining keybindings and LSP setup, and answering questions. Use when the user asks about Helix, their helix config, keybindings, LSP setup, themes, or wants help setting up or learning Helix. Also triggers on "helix keybindings", "explain my helix config", "helix setup", "learn helix", or "hx config". |
| user_invocable | true |
Helix Teacher
Discover and explain the user's Helix setup, or help them get started from scratch.
See these reference files for details:
Step 1: Discover existing configuration
Run the discovery script to find and catalog the user's Helix config:
bash helix-teacher/scripts/discover-config.sh
The script checks $XDG_CONFIG_HOME/helix (defaults to ~/.config/helix), detects config.toml, languages.toml, custom themes, and runtime queries. It also checks for project-local .helix/ config.
If config is found → Step 2a
If NO config is found (script exits 1) → Step 2b
Step 2a: Explain the existing setup
Present a concise summary organized as:
- Overview — Helix version, theme, key editor settings (line numbers, mouse, cursor shape)
- Key remappings — Summarize any custom keybindings in
[keys.*] sections. Highlight deviations from defaults.
- LSP & languages — Which language servers are configured in
languages.toml, formatters, auto-format settings
- Editor preferences — Notable settings (auto-pairs, soft-wrap, indent guides, statusline customization, etc.)
Keep the summary short. Let the user ask follow-up questions rather than dumping everything at once.
Then be available to answer questions — see Step 3.
Step 2b: No config found — help the user get started
Helix is batteries-included — no plugin manager or distribution needed. Ask the user:
- What language(s) do you primarily work with?
- How comfortable are you with modal editing? (beginner / Vim user / Kakoune user)
- What editor are you coming from?
Based on answers:
- Beginner to modal editing → Suggest running
:tutor first, explain the selection-first model, recommend starting with minimal config
- Coming from Vim → Explain the key differences (selection → action instead of action → motion,
x selects lines, w then d instead of dw, no plugins needed for surround/comments/LSP). Offer a starter config.toml with familiar settings (relative line numbers, cursor shapes).
- Coming from Kakoune → Helix will feel natural. Note the differences (TOML config, built-in LSP, tree-sitter integration, slightly different key choices).
- Coming from VS Code / other GUI editor → Explain modal editing basics, suggest
:tutor, highlight that LSP features (go-to-definition, rename, code actions) work out of the box with Space menu.
Provide a starter config.toml tailored to their background and help them set up language servers for their stack (pointing to hx --health to check language support).
Step 3: Answer questions
When answering Helix questions, follow these guidelines:
- Read before answering — If the question is about the user's config, read
config.toml and/or languages.toml first. Do not guess.
- Be practical — Show the exact TOML config they need and where to put it (
config.toml vs languages.toml vs .helix/ project config).
- Explain keybindings in context — Use the keymap-reference.md to give accurate default bindings. Always mention the mode (normal, insert, select).
- Teach the selection-first model — Helix uses
selection → action (inspired by Kakoune). When explaining workflows, emphasize selecting first, then acting. For Vim users, explicitly contrast with Vim's action → motion.
- Leverage built-in features — Helix has built-in support for surround (
m), LSP (Space/g), file picker (Space+f), comments (Ctrl-c), tree-sitter text objects, and multiple selections. No plugins needed.
- Use
hx --health — When debugging LSP or language support issues, always suggest hx --health <lang> first to check if the language server is detected.
Common question patterns
| User asks about | How to help |
|---|
| Keybindings / how to do X | Look up in keymap-reference.md, show the key sequence and mode, contrast with Vim if relevant |
| Custom keybindings | Show TOML syntax for [keys.normal], [keys.insert], [keys.select] sections |
| LSP not working | Run hx --health <lang>, check languages.toml config, verify server is installed |
| Adding a language server | Show [language-server] and [[language]] config in languages.toml |
| Formatting | Explain auto-format, formatter config in languages.toml, and :format command |
| Themes | Show how to set theme in config.toml, create custom themes, and use :theme to preview |
| Multiple selections | Teach s (select regex), C (copy selection to next line), , (keep primary), % (select all) |
| Surround / match | Explain match mode (m) — ms to surround, mr to replace, md to delete, mm to match |
| Tree-sitter text objects | Explain ]f/[f (functions), ]t/[t (types), Alt-o/Alt-i (expand/shrink selection) |
| Coming from Vim | Map their Vim workflow to Helix equivalents, highlight selection-first differences |
| Performance / startup | Helix is fast by default; check hx --health for grammar/query issues |
