Repository navigation
Suggestion providers and predictive ghost text #137
Description
Goal
A provider-backed suggestion system with predictive ghost text, where NMSh owns rendering and acceptance.
Suggestions vs completions
| Suggestions (this issue) | Completions (#140) | |
|---|---|---|
| Purpose | Predict likely command text from behavior, history and context | Enumerate valid subcommands, flags, arguments and values |
| Trigger | Automatically while typing (or on an empty prompt) | Tab / completion menu |
| Presentation | Ghost text, optional ranked alternatives | Structured menu |
| Example | git st → ghost atus; empty prompt → npm test |
git ch → checkout, cherry-pick, … |
Current state
HistoryService.suggest() returns the most recent history entry that starts with the typed prefix. History comes from atuin history list --cmd-only if Atuin is installed, otherwise $HISTFILE.
Providers
| Provider | Role |
|---|---|
| NMSh Native | Default — #138 |
| Deja | External prediction engine — #139 |
| Zsh compatibility | Research below |
| None | No ghost text |
Shared suggestion architecture (first checkpoint)
-
SuggestionProviderinterface: query (buffer, cursor, cwd, previous commands, session) → ranked candidates with source metadata. Async and cancellable; stale results are discarded when the buffer changes. - NMSh renders ghost text and the alternatives list. Providers never draw.
- Acceptance actions: accept full, accept next word, cycle alternatives, dismiss/suppress. Key choices must not steal existing editor bindings.
- Latency budget per keystroke. A provider that misses the budget is skipped for that keystroke.
- Privacy: leading-space and
HISTORY_IGNOREcommands are never suggested. Data stays local. - Suggestions never execute anything.
Zsh suggestion compatibility (research)
NMSh owns its editor, so a ZLE plugin such as zsh-autosuggestions cannot render inside NMSh. The goal is to extract prediction value safely, not to give up editor ownership.
- zsh-autosuggestions
historyandmatch_prev_cmdstrategies can be reproduced natively; fold them into NMSh Native Suggestions v2 #138 if so. - Its
completionstrategy depends on zpty completion. Configured-zsh completion parity is parked in Configured-zsh completion parity and fzf-tab interoperability #52 and not reopened here. - Safely read the user's
ZSH_AUTOSUGGEST_*preferences (strategy, ignore patterns) without executing plugin UI code. - Decide whether a separate "Zsh compatibility" provider is warranted, or whether it becomes an option of Native.
Non-goals
- Structured completion menus (Rich completion and CLI IntelliSense system #140).
- Re-enabling ZLE UI plugins.
Dependencies / related
- Part of Provider framework and unified provider UX #134. Children: NMSh Native Suggestions v2 #138, Deja suggestion provider #139.
- Native parity with common zsh editor plugins #75 hands its suggestion-ranking scope to this issue. Rich history search and metadata #143 history metadata feeds ranking.
Research references
- zsh-autosuggestions: https://github.com/zsh-users/zsh-autosuggestions
- Deja: https://github.com/Giammarco-Ferranti/deja
Activity
raiseCatError commentedon Sep 27, 2026
Checkpoint merged to dev (PR #159): SuggestionProvider interface, SuggestionController (ghost text, alternatives, full/next-word accept, dismiss, stale discard, 150 ms budget, Native fallback), privacy (leading space, HISTORY_IGNORE), Ctrl+N/Ctrl+P alternatives, /settings provider panel. Zsh compatibility: the history and match_prev_cmd strategies are folded into Native (#138); the completion strategy stays parked with #52. Remaining: Native v2 (#138), Deja (#139).
raiseCatError commentedon Sep 27, 2026
Complete for v0.5: architecture (PR #159), Native v2 (#138, PR #160), Deja (#139, PR #161). Zsh compatibility is folded into Native; the zpty completion strategy stays with #52.