pi-ghost-text 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Vaughan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# pi-ghost-text
+
+Ghost-text prompt suggestions for the [pi coding agent](https://github.com/earendil-works/pi) — like Claude Code's inline autocomplete for the prompt box.
+
+As you type (or after the agent finishes and the input is empty), a dimmed prediction of the likely next prompt appears after the cursor. Accept it, cycle alternatives, or keep typing.
+
+## Requirements
+
+- **Interactive TUI mode.** Suggestions are an editor feature and only appear in the interactive terminal (`pi` with no mode flag). They do not run in `-p`/`--print`, `--mode json`, or `--mode rpc`.
+- **A model with a configured API key.** With the default `"model": "auto"`, the extension scans the available models for a fast/cheap one, in priority order: `haiku`, then `gpt-*mini`, then `flash`, then `nano`. If none match — or if an explicit `provider/model-id` isn't found — it falls back to the active session model. Set a specific model with `/suggest-model`.
+
+## Install
+
+```bash
+pi install /path/to/pi-ghost-text
+```
+
+Try it without installing:
+
+```bash
+pi -e /path/to/pi-ghost-text/src/index.ts
+```
+
+Remove it:
+
+```bash
+pi remove /path/to/pi-ghost-text
+```
+
+## Using it
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Cycle to the next candidate; accept when it's the last (or only) one |
+| `→` (right arrow, cursor at end) | Accept the current suggestion |
+| `Esc` | Dismiss the ghost, keeping what you've typed |
+| Move the cursor away from the end | Dismiss |
+| Keep typing | Shrink the ghost while it still matches, otherwise regenerate |
+
+`Tab` only applies to the ghost when the file/command autocomplete dropdown is **not** open. Accepting inserts the suggestion into the editor for you to edit; press `Enter` to send it.
+
+When `candidates` is `1` (the default), `Tab` simply accepts. Set `candidates` to `2` or `3` to fetch alternatives and cycle them.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/suggest` | Choose mode: `both`, `while-typing`, `after-turn`, or `off` |
+| `/suggest-model` | Pick the suggestion model (or `auto` to prefer a fast, cheap one) |
+| `/suggest-context` | Set the context window (messages × chars per message) |
+
+## Configuration
+
+Stored as JSON, resolved `defaults ← global ← project`:
+
+- global: `~/.pi/agent/prompt-suggestions.json`
+- project: `.pi/prompt-suggestions.json`
+
+```json
+{
+  "model": "auto",
+  "mode": "both",
+  "candidates": 1,
+  "streaming": true,
+  "contextMessages": 8,
+  "contextChars": 600,
+  "maxPerTurn": 0,
+  "debug": false
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `model` | `"auto"` | `"auto"` (prefer a fast, cheap model) or an explicit `provider/model-id` |
+| `mode` | `"both"` | `"both"`, `"while-typing"`, `"after-turn"`, or `"off"` |
+| `candidates` | `1` | Alternatives to fetch (1–3); `Tab` cycles them |
+| `streaming` | `true` | Stream the single suggestion token-by-token (ignored when `candidates > 1`) |
+| `contextMessages` | `8` | Recent messages included in the suggestion prompt (`0` = none) |
+| `contextChars` | `600` | Chars kept per message |
+| `maxPerTurn` | `0` | Max suggestions shown per agent turn (`0` = unlimited) |
+| `debug` | `false` | Append diagnostic lines to `~/.pi/agent/prompt-suggestions.log` |
+
+`mode`, `model`, `contextMessages`, and `contextChars` are settable from the commands above; `candidates`, `streaming`, `maxPerTurn`, and `debug` are JSON-only. Commands write to the **global** scope, so a project override in `.pi/prompt-suggestions.json` takes precedence over a command-set value.
+
+## Privacy
+
+When enabled, the suggestion model receives only:
+
+- the text you have typed so far, and
+- the last `contextMessages` user/assistant messages, each trimmed to `contextChars` characters.
+
+It is **never** sent:
+
+- the full conversation transcript,
+- tool outputs,
+- file contents,
+- project or session metadata.
+
+Suggestions are advisory and best-effort; failures are never surfaced in the UI. With `"debug": true` they are logged to `~/.pi/agent/prompt-suggestions.log` with a stable category (`timeout` / `error` / `no-suggestion`).
+
+## Troubleshooting
+
+If no suggestion appears:
+
+1. Confirm the mode is not `off` — run `/suggest`.
+2. Confirm the suggestion model has an API key configured (or, for `auto`, that one of the fast/cheap models does). `/suggest-model` shows what's available. An explicit `model` that isn't found silently falls back to the active session model, so check the spelling as `provider/model-id`.
+3. **While-typing suggestions** need ≥4 chars of plain text (not starting with `/` or `!`, not an `@file` completion in progress), a ~700ms pause, and the agent must be idle (not mid-response).
+4. **After-turn suggestions** only appear when the editor is empty right after the agent settles.
+5. If `maxPerTurn` is set, you may have hit the per-turn cap.
+6. Set `"debug": true` and check `~/.pi/agent/prompt-suggestions.log` for `[prompt-suggestions]` lines — they state the reason (`timeout`, `error`, `no-suggestion`).
+7. If the ghost flakes with streaming enabled, set `"streaming": false` to force the non-streaming path.
+
+## Development
+
+```bash
+npm test   # node --test, no dependencies (requires Node ≥ 23.6)
+```
+
+## Prior art
+
+Inspired by [supi-prompt-suggestions](https://pi.dev/packages/@mrclrchtr/supi-prompt-suggestions?name=supi). This adds inline while-typing autocomplete (prefix-anchored, shrink-on-type), multi-candidate cycling, streaming ghost text, scoped global/project config, and explicit modes on top of the empty-box next-prompt suggestion.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "pi-ghost-text",
+  "version": "0.1.0",
+  "description": "Ghost-text prompt suggestions (inline autocomplete + next-prompt) for the pi coding agent",
+  "license": "MIT",
+  "author": "Chris Vaughan",
+  "type": "module",
+  "engines": {
+    "node": ">=23.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jcv/pi-ghost-text.git"
+  },
+  "homepage": "https://github.com/jcv/pi-ghost-text#readme",
+  "bugs": {
+    "url": "https://github.com/jcv/pi-ghost-text/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "prompt-suggestions",
+    "prompt",
+    "suggestions",
+    "ghost-text",
+    "autocomplete"
+  ],
+  "files": [
+    "src"
+  ],
+  "pi": {
+    "extensions": ["./src/index.ts"],
+    "image": "https://raw.githubusercontent.com/jcv/pi-ghost-text/main/assets/social-preview.png"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/client.ts

@@ -0,0 +1,59 @@
+/**
+ * Suggestion model client — prompt and completion options, plus response
+ * classification.
+ *
+ * Only `import type` from pi packages, so `classifyResponse` is testable
+ * with plain Node.
+ *
+ * @module
+ */
+
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+
+export const GENERATION_TIMEOUT_MS = 8_000;
+export const MAX_TOKENS = 150;
+export const TEMPERATURE = 0.3;
+
+export const SYSTEM_PROMPT = `You complete prompts in an AI coding assistant's input box, like ghost-text autocomplete.
+
+Given the recent conversation and the text the user has typed so far, predict the full prompt the user is most likely to submit.
+
+Rules:
+- Output ONLY the predicted prompt text. No quotes, no explanation, no markdown.
+- If partial input is provided, your output MUST begin with that exact text, unchanged.
+- Keep it short: one line, at most two sentences.
+- Be specific to the conversation. Prefer concrete next steps (run the tests, commit, fix the file just discussed) over generic requests.
+- If there is no confident prediction, output exactly: NONE`;
+
+export type ResponseClass =
+	| { ok: true; text: string }
+	| { ok: false; reason: "error" | "no-content" | "no-text"; message?: string };
+
+/**
+ * Classify a completion response into usable suggestion text or a structured
+ * failure reason. Extracts only visible text content.
+ */
+export function classifyResponse(response: AssistantMessage): ResponseClass {
+	if (response.stopReason === "error") {
+		return { ok: false, reason: "error", message: response.errorMessage ?? response.stopReason };
+	}
+	if (!response.content || response.content.length === 0) {
+		return { ok: false, reason: "no-content" };
+	}
+	const text = response.content
+		.filter((c) => c.type === "text")
+		.map((c) => c.text ?? "")
+		.join("");
+	if (!text.trim()) {
+		return { ok: false, reason: "no-text" };
+	}
+	return { ok: true, text };
+}
+
+/** System prompt for one suggestion, or for several delimited alternatives. */
+export function systemPromptFor(candidates: number): string {
+	if (candidates <= 1) return SYSTEM_PROMPT;
+	return `${SYSTEM_PROMPT}
+
+Additional instruction: provide ${candidates} clearly DIFFERENT alternatives. Output each alternative with no numbering or bullets, separated by a line containing only "---". Each alternative must independently satisfy all the rules above.`;
+}

package/src/config.ts

@@ -0,0 +1,114 @@
+/**
+ * Scoped config for prompt suggestions.
+ *
+ * Resolved as `defaults <- global <- project`:
+ * - global:  ~/.pi/agent/prompt-suggestions.json
+ * - project: .pi/prompt-suggestions.json
+ *
+ * @module
+ */
+
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isMode, type SuggestMode } from "./mode.ts";
+
+export type { SuggestMode } from "./mode.ts";
+
+export interface Config {
+	/** "auto" = auto-pick a fast model, or an explicit "provider/model-id". */
+	model: string;
+	/** Which suggestion behaviors are active. */
+	mode: SuggestMode;
+	/** Number of alternative suggestions to fetch (1..3). */
+	candidates: number;
+	/** Stream the single suggestion token-by-token (only when candidates === 1). */
+	streaming: boolean;
+	/** Number of recent messages included in the suggestion context. */
+	contextMessages: number;
+	/** Chars kept per message in the suggestion context. */
+	contextChars: number;
+	/** Max suggestions shown per agent turn (0 = unlimited). */
+	maxPerTurn: number;
+	/** Append debug lines to ~/.pi/agent/prompt-suggestions.log. */
+	debug: boolean;
+}
+
+export const DEFAULT_CONFIG: Config = {
+	model: "auto",
+	mode: "both",
+	candidates: 1,
+	streaming: true,
+	contextMessages: 8,
+	contextChars: 600,
+	maxPerTurn: 0,
+	debug: false,
+};
+
+function clampInt(value: unknown, min: number, max: number): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return min;
+	return Math.min(max, Math.max(min, Math.floor(value)));
+}
+
+export function globalConfigPath(): string {
+	return path.join(os.homedir(), CONFIG_DIR_NAME, "agent", "prompt-suggestions.json");
+}
+
+export function projectConfigPath(cwd: string): string {
+	return path.join(cwd, CONFIG_DIR_NAME, "prompt-suggestions.json");
+}
+
+export function readJsonFile(filePath: string): Record<string, unknown> | null {
+	try {
+		const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			return parsed as Record<string, unknown>;
+		}
+	} catch {
+		// Missing or invalid config is not an error.
+	}
+	return null;
+}
+
+export function readConfig(cwd: string): Config {
+	const merged: Config = { ...DEFAULT_CONFIG };
+	let modeSeen = false;
+	let legacyEnabled: boolean | undefined;
+
+	for (const filePath of [globalConfigPath(), projectConfigPath(cwd)]) {
+		const raw = readJsonFile(filePath);
+		if (!raw) continue;
+		if (typeof raw.model === "string" && raw.model) merged.model = raw.model;
+		if (typeof raw.mode === "string" && isMode(raw.mode)) {
+			merged.mode = raw.mode;
+			modeSeen = true;
+		}
+		if (typeof raw.candidates !== "undefined") merged.candidates = clampInt(raw.candidates, 1, 3);
+		if (typeof raw.streaming === "boolean") merged.streaming = raw.streaming;
+		if (typeof raw.contextMessages !== "undefined") {
+			merged.contextMessages = clampInt(raw.contextMessages, 0, 50);
+		}
+		if (typeof raw.contextChars !== "undefined") {
+			merged.contextChars = clampInt(raw.contextChars, 0, 10_000);
+		}
+		if (typeof raw.maxPerTurn !== "undefined") {
+			merged.maxPerTurn = clampInt(raw.maxPerTurn, 0, 1_000);
+		}
+		if (typeof raw.debug === "boolean") merged.debug = raw.debug;
+		if (typeof raw.enabled === "boolean") legacyEnabled = raw.enabled;
+	}
+
+	// Legacy migration: before `mode` existed, `enabled: false` meant off.
+	if (!modeSeen) merged.mode = legacyEnabled === false ? "off" : "both";
+	return merged;
+}
+
+export function writeGlobalConfig(partial: Partial<Config>): void {
+	const filePath = globalConfigPath();
+	const existing = readJsonFile(filePath) ?? {};
+	delete existing.enabled; // superseded by `mode`
+	const next = { ...existing, ...partial };
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+}

package/src/context.ts

@@ -0,0 +1,75 @@
+/**
+ * Conversation context for suggestion prompts.
+ *
+ * Only `import type` from pi packages, so `digestMessages` is unit-testable
+ * with plain Node.
+ *
+ * @module
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { UserMessage } from "@earendil-works/pi-ai";
+
+export interface ContextWindow {
+	messages: number;
+	chars: number;
+}
+
+export function extractTextContent(
+	content: string | Array<{ type: string; text?: string }> | undefined,
+): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((c) => c.type === "text")
+		.map((c) => c.text ?? "")
+		.join("\n");
+}
+
+/**
+ * Build a trimmed digest of the last few user/assistant messages, oldest first.
+ * Pure over a session branch's entries so it can be unit-tested.
+ */
+export function digestMessages(entries: readonly unknown[], opts: ContextWindow): string {
+	const parts: string[] = [];
+	for (let i = entries.length - 1; i >= 0 && parts.length < opts.messages; i--) {
+		const entry = entries[i] as {
+			type?: string;
+			message?: { role?: string; content?: string | Array<{ type: string; text?: string }> };
+		};
+		if (!entry || entry.type !== "message") continue;
+		const msg = entry.message;
+		if (!msg || typeof msg !== "object" || !("role" in msg)) continue;
+		if (msg.role !== "user" && msg.role !== "assistant") continue;
+		const text = extractTextContent(msg.content).trim();
+		if (!text) continue;
+		const label = msg.role === "user" ? "User" : "Assistant";
+		parts.unshift(`${label}: ${text.slice(0, opts.chars)}`);
+	}
+	return parts.join("\n\n");
+}
+
+export function conversationDigest(ctx: ExtensionContext, opts: ContextWindow): string {
+	return digestMessages(ctx.sessionManager.getBranch(), opts);
+}
+
+export function buildUserMessage(
+	ctx: ExtensionContext,
+	partial: string,
+	opts: ContextWindow,
+): UserMessage {
+	const digest = conversationDigest(ctx, opts) || "(no conversation yet)";
+	const inputSection = partial
+		? `Partial input (must be the exact start of your output):\n"""${partial}"""`
+		: `The input box is empty. Predict the user's next prompt.`;
+	return {
+		role: "user",
+		content: [
+			{
+				type: "text",
+				text: `Recent conversation (oldest first):\n${digest}\n\n${inputSection}`,
+			},
+		],
+		timestamp: Date.now(),
+	};
+}

package/src/debug.ts

@@ -0,0 +1,51 @@
+/**
+ * Opt-in debug logging for prompt suggestions.
+ *
+ * Suggestions are advisory, so failures are never surfaced to the user as
+ * errors. Logging is off by default — pi's TUI captures console output and
+ * shows it in the chat area, so even stderr logging is user-visible noise.
+ * Enable it with `"debug": true` in the config; lines are then appended to
+ * the configured log file (default ~/.pi/agent/prompt-suggestions.log) so
+ * "no suggestion appeared" can be diagnosed after the fact.
+ *
+ * No pi imports — this module is unit-testable with plain Node.
+ *
+ * Categories:
+ * - "timeout"       generation exceeded the timeout
+ * - "error"         model/network error, or model reported stopReason error
+ * - "no-suggestion" model returned nothing usable (NONE, empty, rejected)
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export type DebugCategory = "timeout" | "error" | "no-suggestion";
+
+const PREFIX = "[prompt-suggestions]";
+
+let enabled = false;
+let logFile: string | null = null;
+
+export function configureDebug(options: { enabled: boolean; logFile?: string }): void {
+	enabled = options.enabled;
+	if (options.logFile) logFile = options.logFile;
+	// Marker line so an existing log confirms debug is wired up; an absent
+	// log then unambiguously means the extension/config never loaded.
+	if (enabled) write("enabled");
+}
+
+export function debug(category: DebugCategory, detail?: string): void {
+	if (!enabled) return;
+	write(detail ? `${category}: ${detail}` : category);
+}
+
+function write(message: string): void {
+	if (!logFile) return;
+	const line = `${new Date().toISOString()} ${PREFIX} ${message}\n`;
+	try {
+		fs.mkdirSync(path.dirname(logFile), { recursive: true });
+		fs.appendFileSync(logFile, line, "utf8");
+	} catch {
+		// Debug logging must never break suggestions.
+	}
+}

package/src/editor.ts

@@ -0,0 +1,385 @@
+/**
+ * The ghost-text editor component.
+ *
+ * Extends pi's CustomEditor and renders suggestions as dim ghost text after
+ * the cursor. Owns debounce, in-flight cancellation, streaming, multi-candidate
+ * cycling, and a per-turn cost guard.
+ *
+ * @module
+ */
+
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext, KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import { streamSimple } from "@earendil-works/pi-ai/compat";
+import type { Model } from "@earendil-works/pi-ai";
+import { CURSOR_MARKER, Key, matchesKey, visibleWidth } from "@earendil-works/pi-tui";
+import type { EditorTheme, TUI } from "@earendil-works/pi-tui";
+import type { Config } from "./config.ts";
+import { afterTurnEnabled, whileTypingEnabled } from "./mode.ts";
+import { resolveSuggestionModel } from "./model-selection.ts";
+import { buildUserMessage, type ContextWindow } from "./context.ts";
+import {
+	classifyResponse,
+	GENERATION_TIMEOUT_MS,
+	MAX_TOKENS,
+	SYSTEM_PROMPT,
+	TEMPERATURE,
+	systemPromptFor,
+} from "./client.ts";
+import { extractSuggestion, fitSuggestionToWidth, isEligible, parseCandidates } from "./normalize.ts";
+import { debug } from "./debug.ts";
+
+const DEBOUNCE_MS = 700;
+const STATUS_KEY = "prompt-suggestions";
+
+export class SuggestingEditor extends CustomEditor {
+	private ghost: string | null = null; // visible remainder shown dimmed
+	private suggestionFull: string | null = null; // currently shown full suggestion
+	private candidates: string[] = []; // all fetched candidates
+	private candidateIndex = 0; // which candidate is shown
+	private baseText = ""; // editor text the suggestion was generated for
+	private debounceTimer: ReturnType<typeof setTimeout> | undefined;
+	private abort: AbortController | undefined;
+	private requestSeq = 0;
+	private hintShown = false;
+	private shownThisTurn = 0; // cost/energy guard counter
+	private dim: (s: string) => string;
+
+	constructor(
+		tui: TUI,
+		theme: EditorTheme,
+		keybindings: KeybindingsManager,
+		private readonly ctx: ExtensionContext,
+		private readonly getConfig: () => Config,
+	) {
+		super(tui, theme, keybindings);
+		this.dim = (s: string) => ctx.ui.theme.fg("dim", s);
+	}
+
+	dispose(): void {
+		clearTimeout(this.debounceTimer);
+		this.abort?.abort();
+		this.clearGhost();
+		this.ctx.ui.setStatus(STATUS_KEY, undefined);
+	}
+
+	/** Agent has settled: reset the per-turn guard and offer a next prompt. */
+	onAgentSettled(): void {
+		this.shownThisTurn = 0;
+		this.suggestIfEmpty();
+	}
+
+	suggestIfEmpty(): void {
+		if (!afterTurnEnabled(this.getConfig().mode)) return;
+		if (this.getText().trim().length !== 0) return;
+		void this.requestSuggestion(true);
+	}
+
+	clearGhost(): void {
+		if (this.ghost === null && this.suggestionFull === null) return;
+		this.ghost = null;
+		this.suggestionFull = null;
+		this.candidates = [];
+		this.candidateIndex = 0;
+		this.tui.requestRender();
+	}
+
+	private cursorAtEnd(): boolean {
+		const lines = this.getLines();
+		const cursor = this.getCursor();
+		return (
+			cursor.line === lines.length - 1 && cursor.col >= (lines[lines.length - 1] ?? "").length
+		);
+	}
+
+	private contextOpts(): ContextWindow {
+		const c = this.getConfig();
+		return { messages: c.contextMessages, chars: c.contextChars };
+	}
+
+	private acceptSuggestion(): void {
+		if (!this.suggestionFull) return;
+		if (this.baseText) {
+			this.insertTextAtCursor(this.suggestionFull.slice(this.baseText.length));
+		} else {
+			this.setText(this.suggestionFull);
+		}
+		this.requestSeq++; // ignore any in-flight result
+		this.abort?.abort();
+		this.clearGhost();
+	}
+
+	/** Tab: cycle to the next candidate, else accept. Right arrow accepts directly. */
+	private cycleOrAccept(): void {
+		if (this.candidates.length > 1) {
+			const now = this.getText();
+			for (let i = this.candidateIndex + 1; i < this.candidates.length; i++) {
+				const candidate = this.candidates[i]!;
+				if (!now || candidate.startsWith(now)) {
+					this.candidateIndex = i;
+					this.baseText = now;
+					this.suggestionFull = candidate;
+					this.ghost = candidate.slice(now.length);
+					this.tui.requestRender();
+					return;
+				}
+			}
+		}
+		this.acceptSuggestion();
+	}
+
+	override handleInput(data: string): void {
+		if (this.ghost) {
+			if (matchesKey(data, Key.tab) && !this.isShowingAutocomplete()) {
+				this.cycleOrAccept();
+				return;
+			}
+			if (matchesKey(data, Key.right) && this.cursorAtEnd()) {
+				this.acceptSuggestion();
+				return;
+			}
+			if (matchesKey(data, Key.escape)) {
+				this.clearGhost();
+				return;
+			}
+		}
+
+		const before = this.getText();
+		super.handleInput(data);
+		const after = this.getText();
+
+		if (after !== before) {
+			this.onTextChanged(after);
+		} else if (this.ghost && !this.cursorAtEnd()) {
+			this.clearGhost();
+		}
+	}
+
+	private onTextChanged(text: string): void {
+		// Shrink the ghost locally while the typed text still prefixes the suggestion.
+		if (
+			this.suggestionFull &&
+			this.baseText &&
+			text.startsWith(this.baseText) &&
+			this.suggestionFull.startsWith(text)
+		) {
+			this.baseText = text;
+			this.ghost = this.suggestionFull.slice(text.length);
+			if (!this.ghost.trim()) {
+				this.clearGhost();
+			} else {
+				this.tui.requestRender();
+			}
+		} else {
+			this.clearGhost();
+		}
+		this.schedule();
+	}
+
+	private schedule(): void {
+		clearTimeout(this.debounceTimer);
+		this.abort?.abort(); // in-flight result is for stale text
+		this.debounceTimer = setTimeout(() => void this.requestSuggestion(false), DEBOUNCE_MS);
+	}
+
+	private async requestSuggestion(allowEmpty: boolean): Promise<void> {
+		const config = this.getConfig();
+		if (allowEmpty ? !afterTurnEnabled(config.mode) : !whileTypingEnabled(config.mode)) return;
+		if (!this.ctx.isIdle()) return; // skip while the agent is streaming
+		if (config.maxPerTurn > 0 && this.shownThisTurn >= config.maxPerTurn) return;
+
+		const text = this.getText();
+		if (!isEligible(text, allowEmpty)) return;
+
+		const model = resolveSuggestionModel(this.ctx, config.model);
+		if (!model) return;
+
+		const seq = ++this.requestSeq;
+		const ac = new AbortController();
+		this.abort = ac;
+		this.ctx.ui.setStatus(STATUS_KEY, "suggesting…");
+
+		try {
+			const suggestions = await this.generateSuggestions(model, text, ac.signal, config);
+			if (seq !== this.requestSeq || ac.signal.aborted) return;
+			this.commitSuggestions(suggestions, text);
+		} catch (err) {
+			if (seq !== this.requestSeq || ac.signal.aborted) return;
+			const message = err instanceof Error ? err.message : String(err);
+			const isTimeout = /timeout|timed ?out/i.test(message);
+			debug(isTimeout ? "timeout" : "error", message);
+			this.clearGhost();
+		} finally {
+			if (seq === this.requestSeq) {
+				this.ctx.ui.setStatus(STATUS_KEY, undefined);
+			}
+		}
+	}
+
+	// ── Generation ────────────────────────────────────────────────────────
+
+	private async generateSuggestions(
+		model: Model<any>,
+		text: string,
+		signal: AbortSignal,
+		config: Config,
+	): Promise<string[]> {
+		if (config.candidates === 1 && config.streaming) {
+			try {
+				return [await this.streamSingle(model, text, signal)];
+			} catch (err) {
+				if (signal.aborted) throw err; // interrupted by a newer keystroke, not a stream failure
+				const message = err instanceof Error ? err.message : String(err);
+				debug("error", `streaming failed, falling back to complete: ${message}`);
+				this.clearGhost();
+				return this.completeCandidates(model, text, signal, 1);
+			}
+		}
+		return this.completeCandidates(model, text, signal, config.candidates);
+	}
+
+	private async streamSingle(model: Model<any>, text: string, signal: AbortSignal): Promise<string> {
+		const auth = await this.ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok) throw new Error(auth.error);
+
+		const stream = streamSimple(model, {
+			systemPrompt: SYSTEM_PROMPT,
+			messages: [buildUserMessage(this.ctx, text, this.contextOpts())],
+		}, {
+			apiKey: auth.apiKey ?? "",
+			headers: auth.headers,
+			env: auth.env,
+			signal,
+			maxTokens: MAX_TOKENS,
+			temperature: TEMPERATURE,
+			timeoutMs: GENERATION_TIMEOUT_MS,
+		});
+
+		let acc = "";
+		for await (const event of stream) {
+			if (signal.aborted) throw new Error("aborted");
+			if (event.type === "text_delta") {
+				acc += event.delta;
+				this.updateStreamingGhost(acc, text);
+			} else if (event.type === "text_end") {
+				acc = event.content;
+			} else if (event.type === "error") {
+				throw new Error(event.error?.errorMessage ?? event.reason ?? "stream error");
+			}
+		}
+		return acc;
+	}
+
+	private async completeCandidates(
+		model: Model<any>,
+		text: string,
+		signal: AbortSignal,
+		count: number,
+	): Promise<string[]> {
+		const response = await this.ctx.modelRegistry.complete(model, {
+			systemPrompt: systemPromptFor(count),
+			messages: [buildUserMessage(this.ctx, text, this.contextOpts())],
+		}, {
+			signal,
+			maxTokens: MAX_TOKENS * count,
+			temperature: TEMPERATURE,
+			timeoutMs: GENERATION_TIMEOUT_MS,
+		});
+
+		const classified = classifyResponse(response);
+		if (!classified.ok) {
+			debug(classified.reason === "error" ? "error" : "no-suggestion", classified.message);
+			return [];
+		}
+		return parseCandidates(classified.text, count);
+	}
+
+	/** Show the accumulated text as a partial ghost while streaming. */
+	private updateStreamingGhost(acc: string, baseText: string): void {
+		if (this.getText() !== baseText) return; // user typed more; ignore this stream
+		if (!acc.startsWith(baseText)) return; // model deviated; wait for final validation
+		const remainder = acc.slice(baseText.length);
+		if (!remainder) return;
+		this.baseText = baseText;
+		this.suggestionFull = acc;
+		this.ghost = remainder;
+		this.tui.requestRender();
+	}
+
+	// ── Commit ────────────────────────────────────────────────────────────
+
+	private commitSuggestions(raw: string[], text: string): void {
+		const now = this.getText();
+		const candidates: string[] = [];
+		for (const rawCandidate of raw) {
+			const suggestion = extractSuggestion(rawCandidate, text);
+			if (!suggestion) continue;
+			if (now !== text) {
+				// The user typed more while the request was in flight.
+				if (!now || !suggestion.startsWith(now) || suggestion.length <= now.length) continue;
+			}
+			if (!candidates.includes(suggestion)) candidates.push(suggestion);
+		}
+
+		if (candidates.length === 0) {
+			debug("no-suggestion");
+			this.clearGhost();
+			return;
+		}
+
+		const baseText = now !== text ? now : text;
+		this.candidates = candidates;
+		this.candidateIndex = 0;
+		this.baseText = baseText;
+		this.suggestionFull = candidates[0]!;
+		this.ghost = candidates[0]!.slice(baseText.length);
+
+		if (!this.ghost || !this.cursorAtEnd()) {
+			this.clearGhost();
+			return;
+		}
+
+		this.shownThisTurn++;
+		if (!this.hintShown) {
+			this.hintShown = true;
+			this.ctx.ui.notify("Prompt suggestions: Tab or → to accept, /suggest to configure", "info");
+		}
+		this.tui.requestRender();
+	}
+
+	override render(width: number): string[] {
+		const lines = super.render(width);
+		if (!this.ghost) return lines;
+
+		// The focused editor emits CURSOR_MARKER right before the fake cursor.
+		// Inserting the ghost after the cursor keeps this independent of the
+		// editor's internal wrap/scroll layout.
+		const idx = lines.findIndex((l) => l.includes(CURSOR_MARKER));
+		if (idx === -1) return lines;
+
+		const line = lines[idx]!;
+		const markerPos = line.indexOf(CURSOR_MARKER);
+		let pos = markerPos + CURSOR_MARKER.length;
+
+		// Skip over the inverse-video cursor glyph that follows the marker.
+		const rest = line.slice(pos);
+		if (rest.startsWith("\x1b[7m")) {
+			const end = rest.indexOf("\x1b[27m");
+			if (end !== -1) pos += end + "\x1b[27m".length;
+		}
+
+		const before = line.slice(0, pos);
+		const after = line.slice(pos);
+		if (visibleWidth(after) > 0) return lines; // only ghost at end of content
+
+		const room = width - visibleWidth(before) - 1;
+		if (room < 6) return lines;
+
+		const shown = fitSuggestionToWidth(this.ghost.replace(/\s+/g, " "), room, visibleWidth);
+
+		// Replace an equal amount of trailing padding so the line stays within width.
+		const shownWidth = visibleWidth(shown);
+		lines[idx] = before + this.dim(shown) + after.slice(shownWidth);
+		return lines;
+	}
+}

package/src/index.ts

@@ -0,0 +1,164 @@
+/**
+ * Prompt Suggestion - Claude Code-style ghost text in the prompt editor.
+ *
+ * As you type (or when the agent finishes and the input box is empty), a dimmed
+ * suggestion of the likely prompt appears after the cursor.
+ *
+ * - Tab cycles candidates (or accepts) · Right arrow accepts
+ * - Keep typing: the ghost shrinks if it still matches, otherwise it regenerates
+ * - Escape / cursor movement away from the end: dismiss
+ * - /suggest: choose mode (off / after-turn / while-typing / both)
+ * - /suggest-model: pick the model used for suggestions
+ * - /suggest-context: set context window (messages + chars per message)
+ *
+ * Config (resolved defaults <- global <- project):
+ *   global:  ~/.pi/agent/prompt-suggestions.json
+ *   project: .pi/prompt-suggestions.json
+ *
+ * Install as a pi package: pi install /path/to/pi-ghost-text
+ * Quick test: pi -e ./src/index.ts
+ *
+ * @module
+ */
+
+import {
+	CONFIG_DIR_NAME,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+	DEFAULT_CONFIG,
+	readConfig,
+	writeGlobalConfig,
+	type Config,
+} from "./config.ts";
+import type { SuggestMode } from "./mode.ts";
+import { scopedOrAvailable } from "./model-selection.ts";
+import { configureDebug } from "./debug.ts";
+import { extractTextContent } from "./context.ts";
+import { SuggestingEditor } from "./editor.ts";
+
+const MODES: Array<{ label: string; value: SuggestMode }> = [
+	{ label: "both (while typing + after turn)", value: "both" },
+	{ label: "while-typing (inline autocomplete)", value: "while-typing" },
+	{ label: "after-turn (next prompt when empty)", value: "after-turn" },
+	{ label: "off", value: "off" },
+];
+
+export default function (pi: ExtensionAPI): void {
+	let config: Config = DEFAULT_CONFIG;
+	let editor: SuggestingEditor | null = null;
+
+	pi.registerCommand("suggest", {
+		description: "Choose when prompt suggestions appear",
+		handler: async (_args, ctx) => {
+			const choice = await ctx.ui.select(
+				"Suggestion mode:",
+				MODES.map((m) => m.label),
+			);
+			if (!choice) return;
+			const mode = MODES.find((m) => m.label === choice)?.value ?? "off";
+			config.mode = mode;
+			writeGlobalConfig({ mode });
+			if (!whileTypingOrAfterTurn(mode)) editor?.clearGhost();
+			ctx.ui.notify(`Prompt suggestions: ${mode}`, "info");
+		},
+	});
+
+	pi.registerCommand("suggest-model", {
+		description: "Choose the model used for prompt suggestions",
+		handler: async (_args, ctx) => {
+			const pool = scopedOrAvailable(ctx);
+			const entries = [
+				{ label: "auto (auto-pick a fast, cheap model)", value: "auto" },
+				...pool.map((m) => ({ label: `${m.provider}/${m.id}`, value: `${m.provider}/${m.id}` })),
+			];
+			const choice = await ctx.ui.select("Suggestion model:", entries.map((e) => e.label));
+			if (!choice) return;
+			const picked = entries.find((e) => e.label === choice);
+			const value = picked ? picked.value : "auto";
+			config.model = value;
+			writeGlobalConfig({ model: value });
+			ctx.ui.notify(`Suggestion model: ${value}`, "info");
+		},
+	});
+
+	pi.registerCommand("suggest-context", {
+		description: "Set the conversation context window for suggestions",
+		handler: async (_args, ctx) => {
+			const messages = await ctx.ui.input(
+				"Context: number of recent messages",
+				String(config.contextMessages),
+			);
+			if (messages === undefined) return;
+			const chars = await ctx.ui.input(
+				"Context: chars kept per message",
+				String(config.contextChars),
+			);
+			if (chars === undefined) return;
+
+			const messagesCount = clampInt(Number(messages), 0, 50, config.contextMessages);
+			const charsCount = clampInt(Number(chars), 0, 10_000, config.contextChars);
+			config.contextMessages = messagesCount;
+			config.contextChars = charsCount;
+			writeGlobalConfig({ contextMessages: messagesCount, contextChars: charsCount });
+			ctx.ui.notify(`Suggestion context: ${messagesCount} messages × ${charsCount} chars`, "info");
+		},
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		config = readConfig(ctx.cwd);
+		configureDebug({ enabled: config.debug, logFile: defaultLogFile() });
+		if (ctx.mode !== "tui") return;
+		ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+			editor = new SuggestingEditor(tui, theme, keybindings, ctx, () => config);
+			seedHistoryFromSession(editor, ctx);
+			return editor;
+		});
+	});
+
+	// Suggest a next prompt when the agent finishes and the input box is empty.
+	pi.on("agent_settled", (_event, ctx) => {
+		if (ctx.mode !== "tui") return;
+		editor?.onAgentSettled();
+	});
+
+	pi.on("before_agent_start", () => {
+		editor?.clearGhost();
+	});
+
+	pi.on("session_shutdown", () => {
+		editor?.dispose();
+		editor = null;
+	});
+}
+
+function whileTypingOrAfterTurn(mode: SuggestMode): boolean {
+	return mode !== "off";
+}
+
+function defaultLogFile(): string {
+	return path.join(os.homedir(), CONFIG_DIR_NAME, "agent", "prompt-suggestions.log");
+}
+
+function clampInt(value: number, min: number, max: number, fallback: number): number {
+	if (!Number.isFinite(value)) return fallback;
+	return Math.min(max, Math.max(min, Math.floor(value)));
+}
+
+/**
+ * Repopulate the editor's UP-arrow history from the session branch so it
+ * survives `/reload` (which reinstantiates the editor with empty history).
+ */
+function seedHistoryFromSession(editor: SuggestingEditor, ctx: ExtensionContext): void {
+	const branch = ctx.sessionManager.getBranch();
+	for (const entry of branch) {
+		if (entry.type !== "message") continue;
+		const msg = entry.message;
+		if (!("role" in msg) || msg.role !== "user") continue;
+		const text = extractTextContent(msg.content).trim();
+		if (text) editor.addToHistory(text);
+	}
+}

package/src/mode.ts

@@ -0,0 +1,19 @@
+/**
+ * Suggestion modes — pure, no pi imports (unit-testable).
+ *
+ * @module
+ */
+
+export type SuggestMode = "off" | "after-turn" | "while-typing" | "both";
+
+export function afterTurnEnabled(mode: SuggestMode): boolean {
+	return mode === "after-turn" || mode === "both";
+}
+
+export function whileTypingEnabled(mode: SuggestMode): boolean {
+	return mode === "while-typing" || mode === "both";
+}
+
+export function isMode(value: unknown): value is SuggestMode {
+	return value === "off" || value === "after-turn" || value === "while-typing" || value === "both";
+}

package/src/model-selection.ts

@@ -0,0 +1,45 @@
+/**
+ * Suggestion model resolution.
+ *
+ * Only `import type` from pi packages, so the pure helpers here are
+ * unit-testable with plain Node.
+ *
+ * @module
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** Prefer a fast, cheap model for suggestions. */
+export const MODEL_PREFERENCES = [/haiku/i, /gpt-.*mini/i, /flash/i, /nano/i];
+
+/**
+ * Pick the first pool model matching a preference pattern, else the fallback.
+ */
+export function pickAutoModel(
+	pool: Model<any>[],
+	fallback: Model<any> | undefined,
+): Model<any> | undefined {
+	for (const pattern of MODEL_PREFERENCES) {
+		const match = pool.find((m) => pattern.test(m.id));
+		if (match) return match;
+	}
+	return fallback;
+}
+
+/** Scoped models when scoping is configured, else every available model. */
+export function scopedOrAvailable(ctx: ExtensionContext): Model<any>[] {
+	const scoped = ctx.scopedModels.map((s) => s.model);
+	return scoped.length > 0 ? scoped : ctx.modelRegistry.getAvailable();
+}
+
+export function resolveSuggestionModel(
+	ctx: ExtensionContext,
+	modelSetting: string,
+): Model<any> | undefined {
+	const pool = scopedOrAvailable(ctx);
+	if (modelSetting === "auto") return pickAutoModel(pool, ctx.model);
+
+	const match = pool.find((m) => `${m.provider}/${m.id}` === modelSetting);
+	return match ?? ctx.model;
+}

package/src/normalize.ts

@@ -0,0 +1,132 @@
+/**
+ * Pure text helpers for suggestion extraction and truncation.
+ *
+ * No pi imports — this module is unit-testable with plain Node.
+ *
+ * @module
+ */
+
+export const MAX_SUGGESTION_GRAPHEMES = 300;
+export const MIN_CHARS = 4;
+
+const NO_SUGGESTION = /^NONE$/i;
+
+// ── Grapheme helpers ───────────────────────────────────────────────────────
+
+export function splitGraphemes(text: string): string[] {
+	const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+	return Array.from(segmenter.segment(text), (segment) => segment.segment);
+}
+
+export function countGraphemes(text: string): number {
+	return splitGraphemes(text).length;
+}
+
+/** Truncate to at most `max` grapheme clusters without splitting any. */
+export function truncateGraphemes(text: string, max: number): string {
+	const graphemes = splitGraphemes(text);
+	if (graphemes.length <= max) return text;
+	return graphemes.slice(0, max).join("").trimEnd();
+}
+
+// ── Width-aware truncation ─────────────────────────────────────────────────
+
+/**
+ * Truncate to fit a visible-width budget, appending an ellipsis when cut.
+ *
+ * Widths are measured by the caller-supplied `measure` function so this stays
+ * pure and testable; the editor passes pi-tui's `visibleWidth`, which counts
+ * terminal columns (wide CJK chars = 2, combining marks = 0).
+ */
+export function truncateToWidth(
+	text: string,
+	maxWidth: number,
+	measure: (s: string) => number,
+	ellipsis = "…",
+): string {
+	if (measure(text) <= maxWidth) return text;
+
+	const graphemes = splitGraphemes(text);
+	let out = "";
+	for (const g of graphemes) {
+		if (measure(out + g) + measure(ellipsis) > maxWidth) break;
+		out += g;
+	}
+	return `${out.trimEnd()}${ellipsis}`;
+}
+
+/**
+ * Truncate a suggestion to fit `maxWidth`, preferring to break on a word
+ * boundary when the cut would otherwise happen mid-word (beyond `minWordKeep`).
+ */
+export function fitSuggestionToWidth(
+	text: string,
+	maxWidth: number,
+	measure: (s: string) => number,
+	minWordKeep = 10,
+): string {
+	if (measure(text) <= maxWidth) return text;
+
+	const truncated = truncateToWidth(text, maxWidth, measure);
+	const content = truncated.endsWith("…") ? truncated.slice(0, -1) : truncated;
+	const lastSpace = content.lastIndexOf(" ");
+	if (lastSpace > minWordKeep) {
+		return `${content.slice(0, lastSpace).trimEnd()}…`;
+	}
+	return truncated;
+}
+
+// ── Normalization & extraction ─────────────────────────────────────────────
+
+/**
+ * Normalize raw model output into a suggestion, or null when unusable.
+ *
+ * Trims, rejects the NONE sentinel, strips wrapping quotes/backticks, and
+ * applies the grapheme safety cap.
+ */
+export function normalizeSuggestionText(text: string): string | null {
+	let normalized = text.trim();
+	if (!normalized || NO_SUGGESTION.test(normalized)) return null;
+
+	normalized = normalized.replace(/^["'`]+|["'`]+$/g, "").trim();
+	if (!normalized || NO_SUGGESTION.test(normalized)) return null;
+
+	if (countGraphemes(normalized) > MAX_SUGGESTION_GRAPHEMES) return null;
+	return normalized;
+}
+
+/**
+ * Extract a suggestion from raw model text, validating the partial-input
+ * prefix contract. Returns null when there is no usable suggestion.
+ */
+export function extractSuggestion(rawText: string, partial: string): string | null {
+	const text = normalizeSuggestionText(rawText);
+	if (!text) return null;
+
+	if (partial) {
+		if (!text.startsWith(partial)) return null;
+		if (!text.slice(partial.length).trim()) return null;
+	}
+	return text;
+}
+
+/** Whether the current editor text is eligible for a suggestion. */
+export function isEligible(text: string, allowEmpty: boolean): boolean {
+	if (text.startsWith("/") || text.startsWith("!")) return false; // commands
+	if (/@[^\s]*$/.test(text)) return false; // @file completion in progress
+	if (text.trim().length === 0) return allowEmpty;
+	return text.length >= MIN_CHARS;
+}
+
+// ── Multi-candidate parsing ────────────────────────────────────────────────
+
+const CANDIDATE_SEPARATOR = /^\s*---\s*$/m;
+
+/** Split a multi-alternative model response into up to `count` raw candidates. */
+export function parseCandidates(rawText: string, count: number): string[] {
+	return rawText
+		.split(CANDIDATE_SEPARATOR)
+		.map((c) => c.trim())
+		.filter((c) => c.length > 0)
+		.slice(0, count);
+}