@kliebhan/pi-prompt-autocomplete

Inline AI completions for the Pi coding agent, rendered as unobtrusive ghost text in the prompt editor.

Watch the demo

Install

Review the source before installing: Pi extensions execute with your user permissions.

pi install npm:@kliebhan/pi-prompt-autocomplete

Try the package for one run without installing it permanently:

pi -e npm:@kliebhan/pi-prompt-autocomplete --prompt-autocomplete

Prompt Autocomplete is disabled by default. Enable it explicitly for a process:

pi --prompt-autocomplete

Or enable it for the current interactive session:

/prompt-autocomplete on

Usage

Action	Key or command
Accept the full suggestion	Tab
Accept the next word or chunk	Ctrl+Space
Next alternative / manual one-shot	Ctrl+.
Previous alternative	Ctrl+,
Dismiss the suggestion for this draft	Escape
Enable, disable, or inspect configuration	/prompt-autocomplete on|off|toggle|status
Show current-session effectiveness and cost	/prompt-autocomplete stats
Toggle streamed response previews	/prompt-autocomplete stream on|off|toggle
Set and persist the minimum draft length	/prompt-autocomplete min-chars <n>

Legacy fallbacks are available for terminals that forward them: Ctrl+Tab, Alt+[, and Alt+].

Built-in slash-command and file/path completion keeps precedence over ghost suggestions.

Configuration

pi \
  --prompt-autocomplete \
  --prompt-autocomplete-model openai/gpt-5.4-mini \
  --prompt-autocomplete-stream on \
  --prompt-autocomplete-min-chars 1 \
  --prompt-autocomplete-debounce-ms 250 \
  --prompt-autocomplete-max-chars 240 \
  --prompt-autocomplete-max-alternatives 3

• The active Pi model is used unless --prompt-autocomplete-model provider/model selects a dedicated authenticated model; active selects the session model explicitly. An explicitly requested model is never substituted: if it is unknown, unauthenticated, or malformed, autocomplete stays inactive and reports why.
• Automatic suggestions require at least one non-whitespace draft character by default. Set --prompt-autocomplete-min-chars 0 or /prompt-autocomplete min-chars 0 (persisted) to opt into empty-draft suggestions.
• Provider responses stream into the first ghost-text suggestion by default. Use --prompt-autocomplete-stream off or /prompt-autocomplete stream off to wait for complete responses instead. This changes rendering only: each suggestion request still uses the same context and token budget.
• Changing /prompt-autocomplete stream cancels active autocomplete work but does not start a replacement request; the selected path applies to the next edit or manual one-shot.
• Partial text advances monotonically: Latin text waits for complete word boundaries, while CJK and other no-space scripts remain grapheme-safe. Alternatives appear only after the response finishes.
• Tab accepts all partial text currently visible. Ctrl+Space accepts only its next visible word/chunk. Both cancel that stream, and unlike accepting a completed suggestion, neither automatically starts another paid request.
• Suggestions pause while the main agent is streaming by default. This is separate from streamed autocomplete responses. Use --prompt-autocomplete-while-streaming or /prompt-autocomplete while-streaming on to change that behavior.
• Ctrl+. with no active suggestion is an explicit one-shot request and may bypass the main-agent-streaming, cooldown, and minimum-length gates. Model, authentication, slash-command, and path safety checks still apply.
• Use --prompt-autocomplete-debug or /prompt-autocomplete debug-on for troubleshooting.

Slash-command toggles (on, off, stream, while-streaming, debug-*) outrank the CLI flags for the rest of the process, including in sessions started later. status labels each toggle with its source, (flag), (saved), or (session). Settings you never toggled keep following their flag.

Persistent settings

/prompt-autocomplete on, off, and min-chars <n> are durable: the decision is saved to $XDG_CONFIG_HOME/pi-prompt-autocomplete/settings.json (falling back to ~/.config; override the location with PI_PROMPT_AUTOCOMPLETE_SETTINGS) and applies to later processes without any CLI flag. An explicit CLI flag still outranks the saved value for that invocation — for min-chars, passing the default (1) is indistinguishable from not passing the flag and defers to the saved value. An enable decision is only recorded when the host actually installs the editor. The file stores nothing but these decisions; deleting it restores flag-only behaviour. status labels each value with its source.

Usage and cost accounting

/prompt-autocomplete stats gives the current session a dedicated, readable report:

Prompt Autocomplete — current session
Requests: 4 issued, 1 failed
Cache: 5 hits (2 exact, 3 prefix)
Suggestions: 8 offered, 3 accepted (2 full, 1 word/chunk)
Usage: 1832 tokens, estimated cost ~$0.00214
Mean provider latency: 410 ms (4 samples)

/prompt-autocomplete status keeps its existing compact usage=4 req, 5 cached, … field for configuration troubleshooting.

• issued counts provider calls actually made. Cache hits add no provider request, tokens, cost, or latency sample.
• Cache hits distinguish exact-draft results from prefix reuse while you type through a cached suggestion.
• offered counts active ghost-text suggestions handed to the editor. Streamed revisions of the same active suggestion do not inflate it; cycling to another alternative counts a new offer. A terminal that is too narrow to draw ghost text can still count an offer.
• Full and word/chunk acceptance are counted separately, including acceptance of visible streamed partials.
• failed includes provider errors and aborted requests. Tokens from a failed response are counted when the provider returns its terminal usage report within the bounded cancellation drain; otherwise tok+/est+ marks the totals incomplete.
• Mean provider latency measures local elapsed time from each actual provider invocation until it resolves or rejects; cache hits are excluded.
• Token counts come from the provider.
• The cost is an estimate, not an invoice. Pi derives it locally by multiplying the reported tokens with its own model price table, so it can disagree with what your provider actually bills.
• A trailing + (1832 tokens+, estimated cost ~$0.00214+; compact status: 1832 tok+, ~$0.00214 est+) means at least one request did not report that metric, so the true total may be higher than shown. Tokens and cost are marked independently, because a response can report tokens without a cost figure.
• Counters live only in memory, are scoped to the current session, and reset when a new session starts.

Privacy, providers, and cost

Enabling Prompt Autocomplete permits additional model requests. Streaming changes only when the same response becomes visible; it does not add a second request. A request can contain:

• the current prompt draft or its bounded tail,
• the latest user and assistant messages,
• a bounded recent-conversation summary.

The active conversation leaf identity is used only in the local in-memory cache key and is not sent to the provider.

By default, requests use the active model. A dedicated --prompt-autocomplete-model may send this context to a different provider, so an explicitly requested model that cannot be used suppresses requests instead of falling back to the active one. Requests can incur token charges and consume provider rate limits.

Provider errors, raw responses, model identifiers, and host diagnostics are stripped of terminal control sequences and of bidirectional or invisible formatting characters before they are displayed, so untrusted text cannot repaint the terminal, hide output, drive OSC clipboard and hyperlink escapes, or misrepresent what it names.

Successful results are cached only in memory for up to 60 seconds; a terminal entry retains its base draft in process memory for the prefix comparison. If the draft then grows by an exact prefix of a cached suggestion, Prompt Autocomplete removes the text you typed and shows the remaining suffix locally instead of issuing another provider request. Prefix reuse is forward-only, stays scoped to the same conversation leaf, model, bounded context and output configuration, and never uses partial streamed text. Divergence, expiry or any context change falls through to a fresh request. The caches are bounded and are cleared on session reset or when the extension is disabled. Provider failures are not cached.

The extension makes no autocomplete request while disabled. Automatic empty-draft requests are also disabled by default.

Compatibility and editor ownership

• Supported baseline: Pi 0.80.6, Node.js 22.19.0 or newer.
• Interactive ghost text requires Pi's TUI mode. RPC, JSON, and print modes do not install a custom editor.
• Forks of Pi's extension API whose ExtensionContext predates mode, such as prime-agent, are supported. For those hosts the extension first requires UI availability and a custom-editor slot, and then verifies that the host actually installed the editor. A front-end that accepts an editor factory without installing it, as forked RPC and daemon modes do, is detected on the first attempt and stays inactive: it is not retried, not left enabled, and can neither render ghost text nor issue a provider request.
• The simple completion API is imported from the @earendil-works/pi-ai root specifier, which Pi maps to its compat entrypoint and such forks export directly. If a host exposes that module without streamSimple, the extension uses the completion path instead of failing requests.
• Prompt Autocomplete requires exclusive ownership of Pi's custom-editor slot. It refuses to replace another custom editor and never removes a later replacement editor.

Development

From the repository root:

npm ci
npm run test:prompt-autocomplete
npm run typecheck:prompt-autocomplete
npm run test:package

The package smoke test packs this directory, verifies the exact tarball contents, installs it into a clean temporary consumer, and discovers it with the supported Pi version.

License

MIT