feat(ui): inline ghost-text suggestion of the user's likely next message

After each idle moment the agent has, fire a one-shot side call on
the main model that re-uses the parent's system prompt + conversation
prefix and asks for a 2-12 word prediction of what the user would
type next. The shared prefix lets native prompt-cache layers
(Anthropic, OpenAI) hit on the parent's cached prefix so cost is
roughly the suggestion's output tokens; Codebase Auto is zero
marginal cost regardless.

Ghost text renders dim after the prompt cursor with a small 'tab'
affordance. Tab on an empty buffer accepts (fills with the
suggestion); any other keystroke dismisses it. Disable via
CODEBASE_NO_SUGGESTIONS=1.

Prompt text and filter list are original — the technique itself is
generic but we don't ship anyone else's wording.

Author: halfaipg

src/agent/prompt-suggestion.ts

@@ -0,0 +1,149 @@
+import { completeSimple } from "@earendil-works/pi-ai";
+import type { AgentBundle } from "./agent.js";
+
+/**
+ * Prompt-suggestion ghost-text generation. After the agent goes idle,
+ * we issue a one-shot side call on the user's main model that reuses
+ * the parent's system prompt + conversation prefix and asks the model
+ * to predict the user's next input as a short string. The matching
+ * prefix lets the upstream's prompt cache reuse the parent's work, so
+ * the marginal cost is approximately the suggestion's own output
+ * tokens.
+ *
+ * Cost notes by provider:
+ *   - Codebase Auto: zero marginal cost (in-house inference).
+ *   - Anthropic / OpenAI: small (native prompt caching hits the prefix).
+ *   - Other BYOK upstreams (Groq, Mistral, …): a small uncached call
+ *     per suggestion. Disable via CODEBASE_NO_SUGGESTIONS=1.
+ */
+
+/**
+ * Instructions appended as a final user message. The *technique* —
+ * meta-prompting an assistant to predict the next user input — is a
+ * common pattern across coding tools, but the wording below is
+ * original to this project (Claude Code uses a similar idea with
+ * different words; we're not copying that text).
+ */
+const SUGGESTION_PROMPT = `Switching to autocomplete mode for one reply.
+
+Reread the conversation so far and forecast the user's next message — the words they themselves would type into the input box, not advice about what they should do.
+
+Calibration: if the user would read your reply and think "yeah, I was about to send that," you nailed it. If they'd read it and think "the assistant is talking to me," you missed.
+
+Guideline patterns:
+- After a job that finished cleanly, the next ask is usually the obvious follow-through: run the tests, push the commit, open the PR, ship it.
+- When you (the assistant) listed options, prefer the one the user clearly wants given the thread above.
+- When you asked a yes/no, pick the answer their tone implies.
+- When the last assistant turn was a stack trace, a clarifying question, or anything where the user needs a beat to react: produce nothing.
+
+Things that disqualify a suggestion:
+- Anything in your own voice ("I'll handle it", "Let me check", "Here's a plan").
+- Praise or filler the user would never type to drive forward ("nice", "looks great", "thanks").
+- Open-ended questions thrown back at you ("what do you think?").
+- A pivot to a new topic the user didn't ask about.
+- More than one sentence; more than about a dozen words.
+
+Output: just the predicted user message, no quotes, no preamble, no trailing punctuation flourish. If nothing fits, return an empty reply.`;
+
+/** Don't suggest before this many assistant turns — needs context to predict from. */
+const MIN_ASSISTANT_TURNS = 2;
+
+/** Cap output so a runaway model can't burn tokens. 60 ≈ 12 words × 5 token/word, with slack. */
+const MAX_SUGGESTION_TOKENS = 60;
+
+/**
+ * Try to produce a suggestion for the current conversation. Returns null
+ * when we shouldn't suggest (early turn, last response was an error,
+ * abort fired, model returned empty or filtered text).
+ */
+export async function generateSuggestion(
+	bundle: AgentBundle,
+	options: { signal?: AbortSignal } = {},
+): Promise<string | null> {
+	const agentState = bundle.agent.state;
+	const messages = agentState.messages;
+
+	// Need at least a couple assistant turns to predict from — anything
+	// less and the suggestion is guessing into the void.
+	const assistantTurnCount = messages.reduce((n, m) => n + (m.role === "assistant" ? 1 : 0), 0);
+	if (assistantTurnCount < MIN_ASSISTANT_TURNS) return null;
+
+	// If the latest assistant message errored, the user should read/react,
+	// not be nudged to type more.
+	const lastAssistant = [...messages].reverse().find((m) => m.role === "assistant");
+	if (lastAssistant && "errorMessage" in lastAssistant && lastAssistant.errorMessage) return null;
+
+	const suggestionMessages = [
+		...messages,
+		{
+			role: "user" as const,
+			content: SUGGESTION_PROMPT,
+			timestamp: Date.now(),
+		},
+	];
+
+	let assistantMessage: Awaited<ReturnType<typeof completeSimple>>;
+	try {
+		assistantMessage = await completeSimple(
+			agentState.model,
+			{
+				systemPrompt: agentState.systemPrompt,
+				messages: suggestionMessages,
+			},
+			{
+				signal: options.signal,
+				maxTokens: MAX_SUGGESTION_TOKENS,
+				temperature: 0.7,
+				// `cacheRetention: "short"` is pi-ai's default — keeps the
+				// suggestion fork from extending the parent's cache TTL,
+				// which the agent loop manages on its own.
+			},
+		);
+	} catch {
+		return null;
+	}
+
+	const text = extractText(assistantMessage).trim();
+	if (!text) return null;
+	if (shouldFilterSuggestion(text)) return null;
+
+	return text;
+}
+
+function extractText(message: Awaited<ReturnType<typeof completeSimple>>): string {
+	if (typeof message.content === "string") return message.content;
+	if (!Array.isArray(message.content)) return "";
+	const parts: string[] = [];
+	for (const block of message.content) {
+		if (block.type === "text" && typeof block.text === "string") {
+			parts.push(block.text);
+		}
+	}
+	return parts.join("");
+}
+
+/**
+ * Filter out suggestions that don't look like real user input. The list
+ * is a pragmatic subset of Claude Code's filters — anything the model
+ * tends to emit when it doesn't know what to suggest but isn't quite
+ * willing to say nothing.
+ */
+function shouldFilterSuggestion(text: string): boolean {
+	const lower = text.toLowerCase();
+	if (lower === "done" || lower === "done.") return true;
+	if (lower === "nothing found" || lower === "nothing found.") return true;
+	if (lower.startsWith("nothing to suggest") || lower.startsWith("no suggestion")) return true;
+	if (/\bstay(s|ing)? silent\b|\bsilence is\b/.test(lower)) return true;
+	if (/^\W*silence\W*$/.test(lower)) return true;
+	// Assistant-voice slippage — model addresses the user as if it were
+	// replying in-character instead of predicting their input.
+	if (/^(let me|i('|\s)ll|here('|\s)s|i can|i('|\s)d)\b/i.test(text)) return true;
+	// Evaluative one-liners — these aren't actions, they're chitchat the
+	// user wouldn't typically type to drive forward.
+	if (/^(looks good|thanks|nice|great|ok|okay|yes)\.?$/i.test(text.trim())) return true;
+	// Too long — keep ghost-text legible (12 words is the cap CC uses).
+	if (text.split(/\s+/).length > 12) return true;
+	// Multi-sentence — pick a single utterance.
+	if (/[.!?]\s+\S/.test(text)) return true;
+	return false;
+}

src/ui/App.tsx

@@ -5,6 +5,7 @@ import { useEffect, useMemo, useReducer, useRef, useState } from "react";
 import { type AgentBundle, createAgent } from "../agent/agent.js";
 import { ConfigError } from "../agent/config.js";
 import { initialState, reducer } from "../agent/events.js";
+import { generateSuggestion } from "../agent/prompt-suggestion.js";
 import { routeUserInput } from "../agent/router.js";
 import { BUILTIN_COMMANDS } from "../commands/builtins.js";
 import { CommandRegistry } from "../commands/registry.js";
@@ -211,6 +212,46 @@ function ChatApp({ bundle, onExit }: ChatAppProps) {
 
 	const busy = state.status === "thinking" || state.status === "streaming" || state.status === "tool";
 
+	// Inline prompt-suggestion ghost text. Schedules a single forecast
+	// call when the agent goes idle; cancels the prior call on every new
+	// state change so we never race two suggestions or show a stale one
+	// after the user starts a new turn. 500ms debounce lets idle settle
+	// (e.g. agent finishes, a quick status emit follows, we don't want to
+	// fire twice). Disabled via env so users on metered BYOK providers
+	// can opt out.
+	const [suggestion, setSuggestion] = useState<string | null>(null);
+	const suggestionAbortRef = useRef<AbortController | null>(null);
+	useEffect(() => {
+		// Always clear any active suggestion on state change — it was
+		// computed for the previous turn and the user has moved on.
+		setSuggestion(null);
+		suggestionAbortRef.current?.abort();
+		suggestionAbortRef.current = null;
+
+		if (process.env.CODEBASE_NO_SUGGESTIONS === "1") return;
+		if (state.status !== "idle") return;
+		if (state.messages.length < 2) return;
+
+		const ac = new AbortController();
+		suggestionAbortRef.current = ac;
+		const timer = setTimeout(async () => {
+			if (ac.signal.aborted) return;
+			try {
+				const text = await generateSuggestion(bundle, { signal: ac.signal });
+				if (ac.signal.aborted) return;
+				if (text) setSuggestion(text);
+			} catch {
+				// Suggestion failures are silent — they're a nicety, not load-bearing.
+			}
+		}, 500);
+
+		return () => {
+			clearTimeout(timer);
+			ac.abort();
+			if (suggestionAbortRef.current === ac) suggestionAbortRef.current = null;
+		};
+	}, [bundle, state.status, state.messages.length]);
+
 	const handleSubmit = async (text: string) => {
 		// `!cmd` runs a shell command directly — the CC convention for
 		// "I just want to check something real quick" without involving
@@ -426,6 +467,8 @@ function ChatApp({ bundle, onExit }: ChatAppProps) {
 					commands={commandSuggestions}
 					history={inputHistory}
 					cwd={bundle.toolContext.cwd}
+					suggestion={suggestion}
+					onSuggestionDismiss={() => setSuggestion(null)}
 				/>
 			)}
 		</Box>

src/ui/Input.tsx

@@ -37,6 +37,14 @@ interface InputProps {
 	history?: readonly string[];
 	/** Working directory used to resolve @-token Tab completion. */
 	cwd?: string;
+	/**
+	 * Inline ghost-text suggestion to render after an empty input prompt.
+	 * Tab accepts (fills the buffer); typing anything else dismisses it.
+	 * Null when no suggestion is active.
+	 */
+	suggestion?: string | null;
+	/** Called when the suggestion should clear (user typed or accepted it). */
+	onSuggestionDismiss?: () => void;
 }
 
 const MAX_SUGGESTIONS = 6;
@@ -84,7 +92,16 @@ function pickPlaceholder(hasHistory: boolean): string {
  *   Ctrl-Z          undo
  *   Ctrl-C          busy → cancel turn (stay in app); double-tap → exit
  */
-export function Input({ disabled, onSubmit, onAbort, commands, history, cwd }: InputProps) {
+export function Input({
+	disabled,
+	onSubmit,
+	onAbort,
+	commands,
+	history,
+	cwd,
+	suggestion,
+	onSuggestionDismiss,
+}: InputProps) {
 	const [state, setState] = useState(initialInputState());
 	const [suggestionIdx, setSuggestionIdx] = useState(0);
 	/**
@@ -132,6 +149,32 @@ export function Input({ disabled, onSubmit, onAbort, commands, history, cwd }: I
 
 		if (disabled) return;
 
+		// Ghost-text suggestion accept. Only fires when there's no slash
+		// or @-path completion in flight AND the buffer is empty (the
+		// suggestion is contextual to the conversation, not to whatever
+		// the user is mid-typing). Tab fills the buffer and clears the
+		// suggestion. Any other keystroke dismisses the suggestion so it
+		// doesn't keep flashing after the user has started a fresh idea.
+		if (suggestion && state.buffer.length === 0) {
+			if (key.tab && !autocompleteActive) {
+				setState({ ...initialInputState(), buffer: suggestion, cursor: suggestion.length });
+				onSuggestionDismiss?.();
+				return;
+			}
+			// Anything user-driven that isn't bare cursor navigation should
+			// kill the ghost — they've moved on.
+			const isPassThrough =
+				key.upArrow ||
+				key.downArrow ||
+				key.leftArrow ||
+				key.rightArrow ||
+				key.escape ||
+				(key.ctrl && (input === "c" || input === "d"));
+			if (!isPassThrough) {
+				onSuggestionDismiss?.();
+			}
+		}
+
 		// Autocomplete navigation runs BEFORE generic input handling so Tab
 		// doesn't insert a literal tab and arrow keys don't fight cursor
 		// movement when we have a suggestion list to navigate.
@@ -333,7 +376,15 @@ export function Input({ disabled, onSubmit, onAbort, commands, history, cwd }: I
 				) : state.buffer.length === 0 ? (
 					<>
 						<Text color="cyan">▎</Text>
-						<Text dimColor>{placeholderRef.current}</Text>
+						{suggestion ? (
+							<>
+								<Text dimColor>{suggestion}</Text>
+								<Text dimColor>{"  "}</Text>
+								<Text dimColor>↹ tab</Text>
+							</>
+						) : (
+							<Text dimColor>{placeholderRef.current}</Text>
+						)}
 					</>
 				) : (
 					<RenderedBuffer buffer={state.buffer} cursor={state.cursor} />