@timmyjl12/pi-typeahead
PowerShell-style inline ghost-text autocomplete for the pi prompt editor, ported from oh-my-pi
Package details
Install @timmyjl12/pi-typeahead from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@timmyjl12/pi-typeahead- Package
@timmyjl12/pi-typeahead- Version
0.3.1- Published
- Nov 13, 2026
- Downloads
- 425/mo · 226/wk
- Author
- timmyjl12
- License
- MIT
- Types
- extension
- Size
- 228.4 KB
- Dependencies
- 0 dependencies · 2 peers
Pi manifest JSON
{
"extensions": [
"./index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-typeahead
PowerShell-style inline ghost text in pi's prompt editor: as you type, the next word of a
remembered line (or the rest of the current word) appears in dim grey after the caret. Rotate
through alternatives, dismiss it, or accept it one word at a time with Tab.
Ported from oh-my-pi. Everything is local by default: no model calls, no daemons, no network.
typed: run the tes▏ [2/3]
ghost: -----> ts
Keys
| Key | Action |
|---|---|
Tab |
accept the next word of the suggestion (repeat to walk the match word by word) |
ctrl+→ or alt+f |
accept one word (the same step Tab takes with the default word-only ghost) |
alt+. / alt+, |
next / previous candidate (multiple history matches) |
Esc |
dismiss until you edit the text again |
Why alt+./alt+, by default: ESC ] and ESC [ are the OSC and CSI introducers, so pi's
input buffer classifies them as the start of a terminal reply and only recovers them after its
sequence timeout — measured 65 ms per press versus 0 ms for alt+./alt+,
(evidence/probe-keys.ts). Braces (alt+}) are instant but need Shift, and Alt+Shift is a
keyboard-layout switch on Windows. All of it is configurable, and alt+]/alt+[ still work if you
prefer them.
Keys are consumed only where a ghost is actually painted:
- accepts fire only at the end of the buffer and only while a ghost is visible;
- cycling keys fire only when more than one candidate exists;
Escdismisses only while a ghost is showing and the agent is idle, soEscstill aborts a running turn;- while pi's own
/commanddropdown is open, the ghost steps aside entirely.
Everywhere else Tab keeps pi's slash-command and file completion: mid-buffer, in /command,
@file or path contexts (which never produce a ghost), or whenever nothing is suggested. On a
prose prompt with a live ghost, Tab accepts instead of opening pi's completion — dismiss with
Esc first if you want the dropdown. The accept is matched through pi's keybinding manager
(tui.input.tab), so rebinding that action moves accept and pi's completion together; Shift+Tab
is never treated as accept. All of the extension's own keys are configurable, including turning
any of them off with an empty string.
What is ported, and what is not
oh-my-pi has three different "typeahead" features; this extension ports the mechanism plus the two local engines.
| oh-my-pi | What it does | Status here |
|---|---|---|
WordCompletionProvider |
paints ghost text after the caret, accepts with Tab/→ | ported — src/ghost.ts, src/editor.ts |
spelling.autocomplete: auto/ngram |
local n-gram word completion from your history | ported — src/ngram.ts |
PSReadLine InlineView |
grey remainder of a command from history | ported — src/predict.ts |
ComposerPredictionController |
an LLM side-turn predicting your next message | replaced by the opt-in local assist below |
| SmolLM / Apple engines | bundled model inference + weights | not ported (needs a multi-GB runtime) |
Install
pi install npm:@timmyjl12/pi-typeahead
To develop on it, install a local checkout instead (pi install /path/to/pi-typeahead); keep only
one of the two. Requires pi 1.3.x. Interactive (tui) mode only.
Commands
| Command | Effect |
|---|---|
/typeahead |
open the settings panel: every setting, grouped, with inline editing (←/→ cycles, Enter edits), / search across all settings, Tab section |
/typeahead status |
one-line report, including the assist tier's resolved model and endpoint |
/typeahead on / off / toggle |
master switch (also alt+t) |
| /typeahead engine | hybrid, history, ngram or off |
| /typeahead scope session|global | apply later changes to this session only, or save them to the config file |
| /typeahead reload | rebuild the corpus from the configured sources (this session's prompts return from its session file when session learning is on) |
Engines:
hybrid(default) — history line completion first, then n-gram word completion.history— strict PSReadLine behaviour: line completion only.ngram— oh-my-pi's default: local word completion only.off— no free engine. (The assist tier is independent and still applies if enabled.)
Where the corpus comes from
- PowerShell PSReadLine history — so shell commands you already type get suggested the way
PowerShell's own predictive IntelliSense does:
%APPDATA%\Microsoft\Windows\PowerShell\PSReadLine\ConsoleHost_history.txt(PowerShell 5.1)%APPDATA%\Microsoft\PowerShell\PSReadLine\ConsoleHost_history.txt(PowerShell 6/7+)$XDG_DATA_HOME/powershell/PSReadLine/…and~/.config/powershell/PSReadLine/…elsewhere
- pi session prompts — user messages from
<agent-dir>/sessions/**/*.jsonl.
Ranking is recency only (newest match first). Bash-mode lines work too: !git st completes from
git status, because a leading !/!! is transparent to matching.
Learned state is cached at <agent-dir>/pi-typeahead/corpus.json (about 400 bytes per remembered
line; ~1.5 MB for 3 800 prompts). Both sources are append-only, so a warm start reads only the
bytes added since the last run; a partially written trailing line is left for the next start, and
a rewritten or shrunk file is re-read from the beginning. Prompts are remembered up to 400
characters — suggestions are capped at maxGhost anyway, and this keeps a huge pasted prompt from
inflating the learned model. Nothing is ever written back to your sessions or PSReadLine history.
Ingestion is cooperative: a scan parses at most 256 records or 128 KiB between event-loop turns,
and a replacement corpus is indexed/learned at most 64 prompts per turn. Oversized-cache restores
index only the retained corpus; bucket compaction and prompts arriving during a rebuild are also
reconciled in bounded turns before one atomic index swap. Discovery stamps are
reused, so an unchanged warm start does neither a second stat round trip nor a model rebuild,
and the predictor that is currently answering keeps answering from the old corpus until the
prepared replacement is adopted atomically. A reload or shutdown cancels obsolete scan and staging
work; nothing partial is adopted or persisted, and prompts typed while a valid replacement runs
are replayed onto it. One exception is inherent: a single JSON record (or cache blob) is parsed
atomically, so one giant record can still block briefly — there is no universal millisecond
ceiling for that case.
A failed reload keeps the surviving corpus usable: buffered prompts return to it and later prompts continue learning. Shutdown also replays input buffered by an unfinished reload before saving the last adopted corpus. If no corpus was safely adopted yet, shutdown does not overwrite the unread cache with a partial replacement. Superseded work cannot release another scan's buffer or notify a closed session.
Which sources are read is decided at session start: after changing includeSessions,
includeShellHistory, shellHistoryPaths or maxCorpusLines, run /typeahead reload (History →
Reload, or the command) to apply it without restarting.
Optional local-model assist
A third tier that fills the gaps the free engines leave, using a model you already run —
pi's own llama.cpp router, Ollama, LM Studio, or any local provider. No extra dependency, no
download, and it cannot reach a paid service unless you explicitly allow it.
It ships preconfigured and off: lmstudio/ternary-bonsai-2-9b with thinking effort off.
lmstudio is the provider id you give LM Studio in pi's models.json (pi documents LM Studio as a
compatible endpoint), so the default resolves as soon as that provider exists; /typeahead status
names the exact reason when it does not.
{
"assist": {
"enabled": true,
"provider": "lmstudio",
"model": "ternary-bonsai-2-9b",
"reasoning": "off",
"minPrefix": 6
}
}
Or set it up in the /typeahead panel (Assist group), which has the same fields plus the guard
switches and timing knobs.
Session or global. The panel's first row, Apply changes to, decides where every change lands:
global writes <agent-dir>/pi-typeahead.json, session keeps it in memory for this session
only. /typeahead scope session|global switches it too. Returning to global discards the
session overrides (they were temporary by design), and a pending global save can never carry a
session-only edit into the file. Behaviour:
- Off by default. It ships preconfigured with
lmstudio/ternary-bonsai-2-9band thinking effortoff, and turning it on is a single toggle. A configured provider and model never enable the tier by itself. - Asked only when you are typing. A request is scheduled only by an actual edit to the prompt.
Repaints (status line, streaming output, theme switch, history hydration finishing) never start
one, so an idle editor cannot generate model traffic. A prompt also has to reach
assist.minPrefixcharacters (default 6) before it is worth a round trip. - Never while the agent is running. Typing a follow-up during a response keeps the history and n-gram ghosts but leaves the local model alone, so it cannot compete with the turn itself.
- Debounced and cached. Requests fire after 350 ms of no further typing (
debounceMs), and an answered prompt is asked again only after the 128-entry answer cache rolls over; a newer edit cancels the previous request (and aborts it once it is in flight). - No auto-detection. Nothing is ever picked for you, so a stray config cannot start billing.
- Loopback only. The resolved endpoint must be
localhost/127.0.0.0/8/::1. A recognised provider id pointed at a LAN, private-range,.localor cloud endpoint is rejected, because those are other machines. Remote access needs bothrequireLocalProvider: falseandallowNonLoopbackEndpoints: true— one switch alone keeps the guard on./typeahead statusalways prints the resolved endpoint. - Cheap: one message,
temperature0, thinking effortoff(assist.reasoning:off..max), 350 ms debounce, 2.5 s timeout, aborted the moment you type or dismiss. With the default word-only ghost the request asks for one word and at most 8 tokens (whole-line ghosts use the configuredmaxTokens, default 24) — no words are generated that the display would throw away. Answers are cached per prefix; a request already in flight for an older prompt is cancelled. - Never on the render path:
peek()is a Map lookup, so a slow model cannot stall typing.
When no ghost appears
- the caret is not at the end of the buffer (including "end of line 1 but more lines below");
- the line starts with
/, or the active token starts with@or/, or contains a path separator (pi's file completion owns those); - the buffer is only whitespace, or shorter than
minPrefix; - pi's autocomplete dropdown is open;
- the match would be blank, multi-line, or a mid-word cut of a very long token;
- you dismissed it with
Escand have not edited since.
Multi-line prompts are learned (they feed word completion) but never suggested as a whole line, because placing their ghost needs the editor's wrapped layout.
Settings
<agent-dir>/pi-typeahead.json — the extension's config file (the same convention as
pi-todo.json, pi-advisor.json). Written by the /typeahead panel and safe to edit by hand.
Every key is optional; malformed JSON is reported and ignored rather than breaking the editor.
{
"enabled": true,
"engine": "hybrid",
"minPrefix": 2,
"maxGhost": 80,
"ghostWordOnly": true,
"acceptTab": true,
"acceptCtrlRightWord": true,
"acceptAltF": true,
"cycleNextKey": "alt+.",
"cyclePrevKey": "alt+,",
"dismissKey": "escape",
"includeSessions": true,
"includeShellHistory": true,
"shellHistoryPaths": [],
"maxCorpusLines": 20000,
"assist": {
"enabled": false,
"provider": "lmstudio",
"model": "ternary-bonsai-2-9b",
"reasoning": "off",
"requireLocalProvider": true,
"allowNonLoopbackEndpoints": false,
"onlyWhenNoLocalSuggestion": true,
"debounceMs": 350,
"maxTokens": 24,
"timeoutMs": 2500,
"maxChars": 160,
"contextPrompts": 3
}
}
Every one of those keys is editable from the panel (Assist → Status shows how the tier resolved). Invalid key syntax falls back to the default binding; an empty string disables that key. Numeric values are clamped to safe ranges.
assist.onlyWhenNoLocalSuggestion: false lets the model answer before the n-gram guess (never
before an exact history match), which is useful when the n-gram tier is noisy on your prompts.
How it works
pi-tui's Editor has no inline-hint hook, so the ghost is painted by rewriting the rendered line
that carries CURSOR_MARKER: the text is inserted immediately after the fake cursor cell and the
line is re-padded to exactly the render width, so the hardware cursor, IME placement and wrapping
are untouched (src/ghost.ts). The editor extends pi's public CustomEditor, so app shortcuts,
autocomplete, history, undo and the working indicator keep working.
Prediction reads only in-memory state: a bucket index over remembered lines (first two characters) plus the n-gram maps. Measured on a real ~3 800-line corpus: p50 0.10 ms, p95 1.1 ms per keystroke; corpus build ~50 ms once, cache restore ~25 ms off the interactive path.
Development
npm install
npm run check # typecheck + tests + performance budgets
npm run perf # measurements only
npm run perf:check # enforce performance-budgets.json
node scripts/bench.ts --history "$env:USERPROFILE/.pi/agent" # real-history reading
scripts/bench.ts also verifies that a restored cache reproduces every prediction exactly (0 of
300 differ on real history), so cache bugs cannot hide behind a fast number. It additionally drives
the production ingestion path (collectSources → refreshCorpus → Predictor.stage → adopt)
over one 120 000-record history file: a setImmediate heartbeat reports the longest event-loop gap
and the number of cooperative slices for ingest, staged rebuild and staged restore, and the staged
result is compared prediction-for-prediction with a direct build. Those gaps are a fairness
diagnostic, not a wall-time promise: a single JSON record or cache blob is parsed atomically.
Layout:
index.ts extension factory: lifecycle, persistence, commands, shortcut
src/settings.ts settings schema, defaults, key validation, atomic writes
src/corpus.ts PSReadLine + pi-session discovery, stamps, dedupe, cap
src/corpus-state.ts corpus ownership: buffering, generations, adoption decisions
src/ngram.ts bounded uni/bi/trigram model, tokenizer, completion
src/predict.ts candidate list: history line matching + n-gram fallback
src/assist.ts optional loopback-only local-model tier
src/assist-types.ts the predictor <-> assist contract
src/ghost.ts cursor-cell anchoring and width-exact ghost painting
src/editor.ts TypeaheadEditor (CustomEditor subclass): accept/cycle/dismiss
src/menu.ts /typeahead settings overlay
scripts/bench.ts performance harness with budgets
Limitations
- Interactive
tuimode only. - The ghost shows one word at a time by default (
ghostWordOnly); whole-remainder ghosts are one toggle away in the panel or the config file. - The ghost is not clickable.
- Word completion is n-gram only, so it predicts words it has already seen; the assist tier is the way to get novel prose, and it needs a local model server.
- A prediction that would split the last word is dropped instead of truncated.
- Multi-line prompts cannot be ghosted.
- The retained corpus is capped, but exact per-scan deduplication still tracks distinct new prompts until a scan finishes. A single giant JSON record or cache blob remains an atomic parse; these changes are not a strict heap cap or a universal latency guarantee.
License
MIT. Ghost-text mechanism and n-gram engine behaviour derived from
oh-my-pi (MIT). The interaction model (history-first ghost,
Esc dismiss, word accept, candidate cycling) follows zsh-autosuggestions and PowerShell
PSReadLine; no code was taken from pi-ghost-autocomplete (SSPL-1.0) or pi-shell-autocomplete
(unknown license).