@timmyjl12/pi-typeahead

PowerShell-style inline ghost-text autocomplete for the pi prompt editor, ported from oh-my-pi

Packages

Package details

extension

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;
  • Esc dismisses only while a ghost is showing and the agent is idle, so Esc still aborts a running turn;
  • while pi's own /command dropdown 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

  1. 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
  2. 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-9b and thinking effort off, 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.minPrefix characters (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, .local or cloud endpoint is rejected, because those are other machines. Remote access needs both requireLocalProvider: false and allowNonLoopbackEndpoints: true — one switch alone keeps the guard on. /typeahead status always prints the resolved endpoint.
  • Cheap: one message, temperature 0, thinking effort off (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 configured maxTokens, 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 Esc and 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 tui mode 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).