feat(cli): @ file selector for the interactive REPL

[agjs]

Press @ at a word boundary to open a compact inline dropdown above the input row (conversation stays visible, like the Claude Code @ menu): recency-ordered workspace files, type to fuzzy-filter, Enter/Tab to select. The picked path is inserted after the @; at send time @path mentions expand to the file's contents (or a MAP when large) prepended to the message — no extra round-trip.

Implementation

• lib/fs: listWorkspaceFiles (mtime-desc recency order)
• render/file-menu: filterFiles (cap 8, stable sort keeps recency on ties), truncatePath, formatCompletionRows, pickFileInline (inline, via IPickerView — no alternate screen), shouldOpenAtPicker boundary guard
• render/status-bar: setOverlay/clearOverlay + pure buildOverlayFrame paint a transient popup above the input row
• loop/prompt/at-mention: parseAtPaths/resolveAtMentions/composeMessage; boundary-anchored so ag@host / mid-word @ don't match
• cli: @ trigger beside / (gated on the input row); runSend expands mentions

History: the first cut was a full-screen alternate-screen dump and was reworked to this inline dropdown.

Verification

Full bun run validate green: 1359 pass / 14 skip / 0 fail. Pure-builder + FakeTerm tests for the picker/overlay; flip-and-confirm-fail on overlay alignment, recency, @-strip, and boundary guard. Live-tested in a real terminal.

[gemini-code-assist]

Code Review

This pull request introduces an interactive @ file picker to the CLI, allowing users to search and select workspace files inline, which are then resolved and prepended to the message. Feedback focuses on improving the robustness and user experience of this feature. Key suggestions include updating the @-mention regex to avoid capturing trailing punctuation, providing a fallback for process.stdout.columns to ensure type safety, introducing a BACKSPACE_CLOSE signal to automatically delete the leading @ when backspacing out of the picker, and restoring keypress listeners directly to preserve their original references.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If a user mentions a file at the end of a sentence or clause (e.g., Please check @src/foo.ts.), the trailing punctuation (like ., ,, ?, !) is captured as part of the filename by the [^\s@]+ regex. This causes the file resolution to fail because no such file exists on disk. We can fix this by updating the regex to capture trailing punctuation separately and appending it back during the replacement phase.

const AT_MENTION = /(^|\s)@([^\s@]*?[^\s@.,;:!?])([.,;:!?]*)(?=\s|$)/gu;

/** The unique candidate paths `@`-mentioned in a line, in first-seen order. */
export function parseAtPaths(line: string): string[] {
  const seen = new Set<string>();

  for (const m of line.matchAll(AT_MENTION)) {
    const path = m[2];

    if (path !== undefined) {
      seen.add(path);
    }
  }

  return [...seen];
}

/**
 * Resolve the `@`-mentions in a user line to file views. Each `@path` that names a
 * readable workspace file is read; the `@` is stripped from those (recognized)
 * tokens in the returned text so the model reads a clean path, while unrecognized
 * `@`-tokens (typos, decorators, non-files) are left untouched. Returns the cleaned
 * text plus the resolved views (empty when nothing matched).
 */
export async function resolveAtMentions(
  cwd: string,
  line: string
): Promise<{ text: string; views: IFileView[] }> {
  const paths = parseAtPaths(line);

  if (paths.length === 0) {
    return { text: line, views: [] };
  }

  const views = await readFiles(cwd, paths);
  const found = new Set(views.map((v) => v.path));

  const text = line.replace(AT_MENTION, (whole, pre: string, path: string, post: string) =>
    found.has(path) ? `${pre}${path}${post}` : whole
  );

  return { text, views };
}

[gemini-code-assist]

process.stdout.columns can be undefined in certain terminal environments or when output is redirected. Since formatCompletionRows expects a strict number for the columns parameter, passing undefined will cause a TypeScript compilation error under strict null checks. Defaulting it to a fallback value (e.g., 80) ensures type safety.

            process.stdout.columns ?? 80,

[gemini-code-assist]

Import BACKSPACE_CLOSE from file-menu to handle deleting the @ character when the picker is closed via backspace.

import {
  pickFileInline,
  formatCompletionRows,
  shouldOpenAtPicker,
  BACKSPACE_CLOSE,
  type IPickerView,
} from "./render/file-menu";

[gemini-code-assist]

When the file picker is closed by backspacing past the empty query, the @ character is left in the readline buffer because the backspace keypress was intercepted. To make this feel natural, we should detect the BACKSPACE_CLOSE signal and trigger a backspace on the readline interface to delete the @.

      try {
        const files = await listWorkspaceFiles(args.dir);
        const picked = await pickFileInline(files, view);

        if (picked === BACKSPACE_CLOSE) {
          rl.write(null, { name: "backspace" });
        } else if (picked !== null) {
          rl.write(`${picked} `); // append after the already-typed `@`
        }

[gemini-code-assist]

Export a BACKSPACE_CLOSE symbol and update the return type of pickFileInline to allow returning it when the picker is closed via backspace.

Suggested change

	export function pickFileInline(
	files: readonly string[],
	view: IPickerView
	): Promise<string | null> {
	export const BACKSPACE_CLOSE = Symbol("BACKSPACE_CLOSE");
	export function pickFileInline(
	files: readonly string[],
	view: IPickerView
	): Promise<string | null | typeof BACKSPACE_CLOSE> {

[gemini-code-assist]

Return BACKSPACE_CLOSE instead of null when backspacing past the empty query to signal to the caller that the @ character should be deleted.

Suggested change

	if (query.length === 0) {
	finish(null); // backspace past the `@` closes the picker
	} else {
	} else if (key.name === "backspace") {
	if (query.length === 0) {
	finish(BACKSPACE_CLOSE); // backspace past the `@` closes the picker

[gemini-code-assist]

Wrapping the restored keypress listeners in an anonymous function changes their references. If any other part of the application tries to remove their listener later using stdin.removeListener("keypress", originalListener), it will fail because the registered listener is now the anonymous wrapper. Restoring the listeners directly preserves their references and prevents potential memory leaks or broken event cleanups.

      for (const l of saved) {
        stdin.on("keypress", l as any);
      }