@pentoshi/clai 0.11.2 → 0.13.0

package/dist/prompts/index.js

@@ -10,14 +10,15 @@ For every user request, respond with:
 4. Security caveats, OPSEC notes, and safer alternatives where applicable
 
 When advising on pentesting, follow standard methodology (recon → enumeration → exploitation → post-exploitation). Always note which phase the user is in and suggest logical next steps.`;
-const agentPrompt = `You are clai, a terminal AI agent specialized in cybersecurity, pentesting, and sysadmin.
+const agentPrompt = `You are clai, a terminal AI agent. You are a capable software engineer AND a cybersecurity/pentesting/sysadmin specialist. You can write code, scaffold and modify projects, edit files, run commands, and do recon/enumeration/exploitation work — like a coding agent (Claude Code / opencode) fused with a security toolkit.
 OS: {{os}} | Shell: {{shell}} | CWD: {{cwd}}
 Current date/time: {{datetime}}
 
 TOOLS (use EXACT arg names — wrong names = failure):
 - shell.exec: {"command":"<cmd>"} — run any shell command. Optional: {"command":"...","cwd":"/path","timeoutMs":300000}
 - fs.read: {"path":"<file>"} — read a file
-- fs.write: {"path":"<file>","content":"<data>"} — write a file
+- fs.write: {"path":"<file>","content":"<data>"} — write a single file
+- fs.writeMany: {"files":[{"path":"<file>","content":"<data>"}, ...]} — write MANY files in ONE call (up to 50). USE THIS to scaffold a project (e.g. a React/Express app) instead of one fs.write per file — it saves steps and is the preferred way to create multiple files at once. Parent dirs are auto-created.
 - fs.list: {"path":"<dir>"} — list directory
 - fs.search: {"pattern":"<regex>","path":"<dir>"} — search file CONTENTS (NOT filenames)
 - pkg.install: {"tool":"<name>"} — install package (only if user asks or command not found)
@@ -133,12 +134,67 @@ RESILIENT ERROR HANDLING:
 - Chain: fail → diagnose → fix/adapt → retry. Never stop at the first error.
 
 TASK PLANNING:
-- For complex multi-step tasks, break the work into logical steps yourself.
-  Execute them one by one. You own the plan — nothing is predetermined.
-- For simple tasks (single command, quick lookup), just execute immediately.
-- If a step fails, adapt your plan. Don't rigidly follow a broken path.
+- BEFORE acting on any non-trivial task, decide: is this one quick step, or multiple steps?
+  · Simple (single command, quick lookup, one file) → just execute immediately, no plan.
+  · Multi-step (scaffold a project, refactor across files, full recon, build a feature) → FIRST
+    write a short numbered plan (3-7 steps) in plain text, THEN execute the steps one by one.
+- State the plan to the user before the first tool call so they can follow along. Example:
+    Plan:
+    1. Inspect the current directory to understand what's here
+    2. Read package.json / key files for context
+    3. Scaffold the missing files
+    4. Verify it builds/runs
+  Then proceed with step 1. Keep the plan concise — do not over-plan trivial work.
+- As you finish steps, briefly note progress ("done 1-2, starting 3"). Adapt the plan if a step fails.
+- You OWN the plan — nothing is predetermined. This applies to BOTH coding and security tasks
+  (e.g. a layered recon → enumeration → reporting flow is a plan too).
 
-LOCAL NETWORK DISCOVERY:
+WORKING ON CODE & PROJECTS (act like a coding agent):
+- "create X here" / "build X" / "add Y to this project" means work in the CURRENT directory ({{cwd}}).
+- UNDERSTAND BEFORE YOU WRITE. Do not dump a generic template. First gather just enough context:
+  · fs.list the current directory (and key subdirs) to see what already exists.
+  · fs.read the files that matter (package.json, config, entry points, the file being changed).
+  · Use tool.batch to read several files at once instead of many sequential reads.
+  · Detect the existing stack/tooling (e.g. Vite vs CRA, the framework, the package manager) and
+    MATCH it. Never replace a project's tooling with a different one unless asked.
+- Keep context lean: read what you need, not the whole tree. Skip node_modules, dist, .git, lockfiles.
+- For a brand-new project, pick sensible modern defaults and say which you chose (e.g. "scaffolding
+  with Vite + React" ) — then create a MINIMAL working skeleton, not an overstuffed boilerplate.
+- fs.write creates parent directories automatically — you can write "src/App.jsx" directly without a
+  separate mkdir. Do NOT call mkdir before fs.write.
+- SCAFFOLD WITH fs.writeMany: when a task needs several files (a React app, an Express server, a CLI),
+  create them ALL in ONE fs.writeMany call instead of many fs.write calls. This is faster and avoids
+  running out of steps mid-build.
+- NEVER rewrite a file you already wrote with identical content. After a file is saved, move to the
+  NEXT file or step. Re-writing the same file wastes steps and the build guard will block it.
+- DO NOT claim work you did not do. Only say "dependencies installed" after pkg.install / npm install
+  actually ran and succeeded; only say "the dev server is running" after shell.start actually started
+  it. If you have not run those steps, tell the user the exact commands to run instead.
+- After writing files, verify when practical: list the tree you created, and if there's a build/test
+  command, run it (or tell the user the exact command to run, e.g. \`npm install && npm run dev\`).
+- Prefer fs.edit for changing existing files; use fs.write for new files or full rewrites.
+- For multi-file scaffolds: 1) give a one-line structure overview, 2) create the minimal files, 3) summarize.
+
+MODERN TOOLING & DEPENDENCIES (avoid deprecated/legacy setups):
+- PREFER OFFICIAL SCAFFOLDERS over hand-writing build configs. They pull current, non-deprecated
+  dependencies and need far fewer files:
+  · React / Vue / Svelte / vanilla frontend → \`npm create vite@latest <name> -- --template react\`
+    (or react-ts, vue, svelte, etc). Do NOT hand-roll webpack + babel-loader — that drags in
+    deprecated transitive deps (inflight, rimraf@3, glob@7, old uuid) and dozens of extra packages.
+  · Next.js → \`npx create-next-app@latest\`. Vue → \`npm create vue@latest\`. Astro → \`npm create astro@latest\`.
+  · Node/Express API → a small package.json with \`"type":"module"\`, Express 5, and ES module imports.
+- Use \`@latest\` (or a recent known-good major) when invoking scaffolders so the user gets current
+  versions, not whatever is cached.
+- When you DO write package.json by hand, pin to current major versions and avoid abandoned packages
+  (e.g. use the built-in \`node:crypto\` randomUUID instead of the \`uuid\` package; \`rimraf\`/\`glob\` are
+  rarely needed in app code). Use ESM (\`import\`) and \`"type":"module"\` for new Node projects.
+- Use current, non-deprecated APIs in generated code: \`createRoot\` (not \`ReactDOM.render\`), the native
+  \`fetch\` (not \`request\`/\`node-fetch\` on modern Node), \`node:\` prefixed core imports, \`Buffer.subarray\`
+  (not \`Buffer.slice\`), and \`String.prototype.replaceAll\`/\`slice\` (not \`substr\`).
+- If a scaffolder CLI is the right move, run it with shell.exec (or shell.start for its dev server),
+  then adapt the generated files — don't fight the tool by recreating its output by hand.
+- After install, if you see deprecation warnings for transitive deps you control, prefer a newer
+  direct dependency that doesn't pull them in rather than ignoring them.
 - "scan my network" / "find devices" / "what's on my LAN" → net.context FIRST (gets interfaces+CIDR), then net.pingSweep with discovered CIDR.
 - Do NOT guess 192.168.1.0/24 or any range. Always discover it via net.context.
 - Do NOT use shell.exec for ping sweeps. Use net.pingSweep which has intelligent fallback.

package/dist/prompts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,SAAS,GAAG;;;;;;;;;;0LAUwK,CAAC;AAE3L,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+MAsK2L,CAAC;AAEhN,SAAS,MAAM,CAAC,QAAgB,EAAE,MAA8B;IAC9D,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAClC,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC,EAClE,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE;IACrD,MAAM,KAAK,GAAG,GAAG,CAAC,cAAc,CAAC,SAAS,EAAE;QAC1C,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,MAAM;QACb,GAAG,EAAE,SAAS;QACd,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,SAAS;QACjB,YAAY,EAAE,OAAO;KACtB,CAAC,CAAC;IACH,OAAO,GAAG,KAAK,UAAU,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C,MAAM,UAAU,qBAAqB;IACnC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,OAAO,MAAM,CAAC,SAAS,EAAE;QACvB,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE;QACvD,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,QAAQ,EAAE,sBAAsB,EAAE;QAClC,SAAS,EAAE,MAAM;KAClB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,OAAO,MAAM,CAAC,WAAW,EAAE;QACzB,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE;QACvD,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,QAAQ,EAAE,sBAAsB,EAAE;QAClC,SAAS,EAAE,QAAQ;KACpB,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,SAAS,GAAG;;;;;;;;;;0LAUwK,CAAC;AAE3L,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+MA8N2L,CAAC;AAEhN,SAAS,MAAM,CAAC,QAAgB,EAAE,MAA8B;IAC9D,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAClC,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC,EAClE,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE;IACrD,MAAM,KAAK,GAAG,GAAG,CAAC,cAAc,CAAC,SAAS,EAAE;QAC1C,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,MAAM;QACb,GAAG,EAAE,SAAS;QACd,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,SAAS;QACjB,YAAY,EAAE,OAAO;KACtB,CAAC,CAAC;IACH,OAAO,GAAG,KAAK,UAAU,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C,MAAM,UAAU,qBAAqB;IACnC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,OAAO,MAAM,CAAC,SAAS,EAAE;QACvB,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE;QACvD,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,QAAQ,EAAE,sBAAsB,EAAE;QAClC,SAAS,EAAE,MAAM;KAClB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,OAAO,MAAM,CAAC,WAAW,EAAE;QACzB,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE;QACvD,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,QAAQ,EAAE,sBAAsB,EAAE;QAClC,SAAS,EAAE,QAAQ;KACpB,CAAC,CAAC;AACL,CAAC"}

package/dist/repl.d.ts

@@ -1,4 +1,5 @@
 import type { Mode, ProviderId } from "./types.js";
+import { type FileSuggestion } from "./ui/mentions.js";
 export interface ReplOptions {
     mode?: Mode | undefined;
     provider?: ProviderId | undefined;
@@ -13,4 +14,5 @@ export interface SlashCommand {
 export declare function getKnownModels(provider: string): string[];
 export declare function getSlashCommandSuggestions(line: string): SlashCommand[];
 export declare function renderSlashCommandMenu(line: string, suggestions: SlashCommand[], selectedIndex: number): string[];
+export declare function renderFileMentionMenu(query: string, suggestions: FileSuggestion[], selectedIndex: number): string[];
 export declare function startRepl(options?: ReplOptions): Promise<void>;

package/dist/repl.js

@@ -16,6 +16,7 @@ import { modelSupportsThinking } from "./llm/capabilities.js";
 import { clearViewports, getLastViewport, getViewport, isPagerActive, listViewports, openViewportPager, toggleViewport, } from "./ui/output-pane.js";
 import { compactMessages, estimateMessagesTokens, } from "./agent/context-manager.js";
 import { isCtrlC, isCtrlO, isCtrlT, isEscape } from "./ui/keys.js";
+import { getMentionQuery, findFileSuggestions, expandMentions, } from "./ui/mentions.js";
 const slashCommands = [
     { command: "/ask", description: "switch to ask mode" },
     { command: "/agent", description: "switch to agent mode" },
@@ -303,6 +304,31 @@ export function renderSlashCommandMenu(line, suggestions, selectedIndex) {
     }
     return items;
 }
+export function renderFileMentionMenu(query, suggestions, selectedIndex) {
+    const cols = terminalColumns();
+    const maxWidth = Math.max(1, cols - 1);
+    if (suggestions.length === 0) {
+        return [
+            chalk.dim(fitPlain(`  no files matching @${query}`, maxWidth)),
+        ];
+    }
+    const termRows = process.stdout.rows || 24;
+    const maxVisible = Math.max(5, termRows - 4);
+    const visible = suggestions.slice(0, maxVisible);
+    const items = visible.map((suggestion, index) => {
+        const markerPlain = index === selectedIndex ? "›" : " ";
+        const marker = index === selectedIndex ? chalk.magenta("›") : " ";
+        const prefix = `  ${markerPlain} `;
+        const labelBudget = Math.max(1, maxWidth - prefix.length);
+        const label = fitPlain(suggestion.label, labelBudget);
+        const colored = suggestion.isDir ? chalk.cyan(label) : chalk.white(label);
+        return `  ${marker} ${colored}`;
+    });
+    if (suggestions.length > maxVisible) {
+        items.push(chalk.dim(fitPlain(`  … ${suggestions.length - maxVisible} more`, maxWidth)));
+    }
+    return items;
+}
 function isPrintableSequence(sequence) {
     return sequence !== undefined && /^[^\x00-\x1f\x7f]+$/u.test(sequence);
 }
@@ -353,6 +379,7 @@ async function readPromptLine(options) {
         let selectedIndex = 0;
         let menuNavigated = false;
         let dismissedSlashLine = null;
+        let mentionDismissed = false;
         let historyIndex = null;
         let historyDraft = "";
         let lastCtrlCAt = 0;
@@ -369,12 +396,57 @@ async function readPromptLine(options) {
                 selectedIndex = 0;
             return { visible: true, suggestions };
         };
+        // File @-mention autocomplete: active when the cursor sits inside an
+        // `@partial/path` token. Mutually exclusive with the slash menu (slash
+        // requires the line to start with "/" and contain no whitespace).
+        const getMentionState = () => {
+            if (mentionDismissed || line.startsWith("/")) {
+                return { visible: false, query: "", start: 0, suggestions: [] };
+            }
+            const q = getMentionQuery(line, cursor);
+            if (!q)
+                return { visible: false, query: "", start: 0, suggestions: [] };
+            const suggestions = findFileSuggestions(q.query);
+            if (suggestions.length === 0) {
+                return { visible: false, query: q.query, start: q.start, suggestions };
+            }
+            if (selectedIndex >= suggestions.length)
+                selectedIndex = 0;
+            return { visible: true, query: q.query, start: q.start, suggestions };
+        };
+        const applyMention = (suggestion, start) => {
+            const before = line.slice(0, start);
+            const after = line.slice(cursor);
+            let insert = `@${suggestion.value}`;
+            let newCursor = before.length + insert.length;
+            if (!suggestion.isDir) {
+                // Completed a file — add a trailing space and close the menu so the
+                // user can keep typing their request.
+                insert += " ";
+                newCursor = before.length + insert.length;
+                mentionDismissed = true;
+            }
+            else {
+                // Completed a directory — keep the menu open so the user drills in.
+                mentionDismissed = false;
+            }
+            line = before + insert + after;
+            cursor = newCursor;
+            selectedIndex = 0;
+            menuNavigated = false;
+            refresh();
+        };
         const refresh = () => {
             const cols = terminalColumns();
             const menu = getMenuState();
+            const mention = menu.visible
+                ? { visible: false, query: "", start: 0, suggestions: [] }
+                : getMentionState();
             const menuLines = menu.visible
                 ? renderSlashCommandMenu(line, menu.suggestions, selectedIndex)
-                : [];
+                : mention.visible
+                    ? renderFileMentionMenu(mention.query, mention.suggestions, selectedIndex)
+                    : [];
             const promptRows = buildPromptRows(line, cols, true);
             const target = promptCursorPosition(cursor, cols);
             const blockRows = [...promptRows, ...menuLines];
@@ -402,6 +474,7 @@ async function readPromptLine(options) {
             selectedIndex = 0;
             menuNavigated = false;
             dismissedSlashLine = null;
+            mentionDismissed = false;
             historyIndex = null;
             refresh();
         };
@@ -446,6 +519,9 @@ async function readPromptLine(options) {
             if (isPagerActive())
                 return;
             const menu = getMenuState();
+            const mention = menu.visible
+                ? { visible: false, query: "", start: 0, suggestions: [] }
+                : getMentionState();
             // Cmd+C on macOS terminals is handled by the OS (it never reaches us),
             // but some Linux terminals forward Meta+C. Treat that as a no-op so
             // selecting + copying never breaks the REPL.
@@ -485,6 +561,10 @@ async function readPromptLine(options) {
                 return;
             }
             if (key.name === "return" || key.name === "enter") {
+                if (mention.visible && mention.suggestions.length > 0) {
+                    applyMention(mention.suggestions[selectedIndex] ?? mention.suggestions[0], mention.start);
+                    return;
+                }
                 const useSelection = menu.visible && (line !== "/" || menuNavigated);
                 const selectedCommand = useSelection
                     ? menu.suggestions[selectedIndex]
@@ -493,6 +573,10 @@ async function readPromptLine(options) {
                 return;
             }
             if (key.name === "tab") {
+                if (mention.visible && mention.suggestions.length > 0) {
+                    applyMention(mention.suggestions[selectedIndex] ?? mention.suggestions[0], mention.start);
+                    return;
+                }
                 if (menu.visible && menu.suggestions.length > 0) {
                     const target = menu.suggestions[selectedIndex] ?? menu.suggestions[0];
                     editLine(target.command, target.command.length);
@@ -500,6 +584,11 @@ async function readPromptLine(options) {
                 return;
             }
             if (isEscape(key)) {
+                if (mention.visible) {
+                    mentionDismissed = true;
+                    refresh();
+                    return;
+                }
                 if (menu.visible) {
                     dismissedSlashLine = line;
                     refresh();
@@ -507,6 +596,14 @@ async function readPromptLine(options) {
                 return;
             }
             if (key.name === "up") {
+                if (mention.visible && mention.suggestions.length > 0) {
+                    selectedIndex =
+                        (selectedIndex - 1 + mention.suggestions.length) %
+                            mention.suggestions.length;
+                    menuNavigated = true;
+                    refresh();
+                    return;
+                }
                 if (menu.visible && menu.suggestions.length > 0) {
                     selectedIndex =
                         (selectedIndex - 1 + menu.suggestions.length) %
@@ -532,6 +629,12 @@ async function readPromptLine(options) {
                 return;
             }
             if (key.name === "down") {
+                if (mention.visible && mention.suggestions.length > 0) {
+                    selectedIndex = (selectedIndex + 1) % mention.suggestions.length;
+                    menuNavigated = true;
+                    refresh();
+                    return;
+                }
                 if (menu.visible && menu.suggestions.length > 0) {
                     selectedIndex = (selectedIndex + 1) % menu.suggestions.length;
                     menuNavigated = true;
@@ -1480,7 +1583,7 @@ async function handleSlash(line, state) {
                 mode: state.mode,
             }));
             console.log(renderSuggestions());
-            console.log(chalk.dim("  ESC abort  │  Ctrl+C clears input  │  Ctrl+T or /think for thinking  │  Ctrl+O opens full tool output (q to close)\n"));
+            console.log(chalk.dim("  ESC abort  │  Ctrl+C clears input  │  @ to attach files  │  Ctrl+T thinking  │  Ctrl+O tool output (q to close)\n"));
             return true;
         }
         case "/update":
@@ -1635,7 +1738,7 @@ export async function startRepl(options = {}) {
         mode: state.mode,
     }));
     console.log(renderSuggestions());
-    console.log(chalk.dim("  ESC abort  │  Ctrl+C clears input  │  Ctrl+T or /think for thinking  │  Ctrl+O opens full tool output (q to close)\n"));
+    console.log(chalk.dim("  ESC abort  │  Ctrl+C clears input  │  @ to attach files  │  Ctrl+T thinking  │  Ctrl+O tool output (q to close)\n"));
     // Hint thinking-capable users that the toggle exists. We default it to
     // off for speed, since on NIM many models route through a much slower
     // chat-template path when reasoning is enabled.
@@ -1684,9 +1787,26 @@ export async function startRepl(options = {}) {
                 clearThinking();
                 abortPressCount = 0;
                 let assistantContent = "";
+                // Expand @file mentions and drag-and-dropped paths into real context.
+                // The user-visible `line` stays readable in history; the model gets
+                // the line plus an appended block of file contents / path notes.
+                const expansion = expandMentions(line);
+                const modelInput = expansion.contextBlock.length > 0
+                    ? `${line}\n\n${expansion.contextBlock}`
+                    : line;
+                if (expansion.attachments.length > 0) {
+                    for (const att of expansion.attachments) {
+                        const tag = att.kind === "text"
+                            ? chalk.green("attached")
+                            : att.kind === "missing"
+                                ? chalk.red("not found")
+                                : chalk.yellow(att.kind);
+                        console.log(chalk.dim(`  ↳ ${tag}: `) + chalk.dim(att.path));
+                    }
+                }
                 if (state.mode === "ask") {
                     assistantContent = await withAbortableInput(async (signal) => streamWithAbort(async (runSignal, onToken) => {
-                        return await runAskStream(line, onToken, {
+                        return await runAskStream(modelInput, onToken, {
                             provider: state.provider,
                             model: state.model,
                             history: state.messages,
@@ -1696,7 +1816,7 @@ export async function startRepl(options = {}) {
                     process.stdout.write("\n");
                 }
                 else {
-                    assistantContent = await withAbortableInput(async (signal) => runAgent(line, {
+                    assistantContent = await withAbortableInput(async (signal) => runAgent(modelInput, {
                         provider: state.provider,
                         model: state.model,
                         history: state.messages,
@@ -1705,7 +1825,7 @@ export async function startRepl(options = {}) {
                     }));
                 }
                 console.log();
-                state.messages.push({ role: "user", content: line }, { role: "assistant", content: assistantContent });
+                state.messages.push({ role: "user", content: modelInput }, { role: "assistant", content: assistantContent });
             }
             catch (error) {
                 if (error instanceof AbortRunError) {