@zigai/pi-mention-project 0.2.0

package/README.md

@@ -0,0 +1,76 @@
+# Pi Mention Project
+
+[![npm version](https://img.shields.io/npm/v/@zigai/pi-mention-project.svg?color=blue)](https://www.npmjs.com/package/@zigai/pi-mention-project)
+[![npm downloads](https://img.shields.io/npm/dm/@zigai/pi-mention-project.svg)](https://www.npmjs.com/package/@zigai/pi-mention-project)
+[![license](https://img.shields.io/npm/l/@zigai/pi-mention-project.svg)](../../LICENSE)
+
+This Pi extension adds fuzzy project directory mentions that default to `#`.
+
+## Install
+
+```sh
+pi install npm:@zigai/pi-mention-project
+```
+
+## Features
+
+- Adds fuzzy autocomplete for project folders with `#` mentions.
+- Searches only the direct child folders inside configured project roots.
+- Defaults to Git repository folders and ignores dot-prefixed folders.
+- Expands project mentions before the model sees the prompt so the model gets each project's absolute path.
+
+## Usage
+
+Configure one or more project roots, then type `#` in the prompt editor and start typing a folder name.
+
+If `~/Projects` contains `pi-tweaks`, selecting `#pi-tweaks` adds that project mention. Before the model sees the prompt, the extension prepends project metadata with the absolute project path and removes the `#` sigil from the visible sentence.
+
+## Configuration
+
+Configuration lives in Pi settings: globally in `~/.pi/agent/settings.json`, or per trusted project in `.pi/settings.json`.
+
+Project roots default to an empty list. Set `mentionProjectRoots` to the directories whose direct child folders should be mentionable:
+
+```json
+{
+  "mentionProjectRoots": ["~/Projects", "~/Work"]
+}
+```
+
+Only immediate child directories are listed. For example, `~/Projects/app` is mentionable, but `~/Projects/app/packages/api` is not.
+
+By default, a child folder is listed only when it has a `.git` directory or worktree `.git` file, and folders whose names start with `.` are hidden. To include non-Git folders, set `mentionProjectGitReposOnly` to `false`:
+
+```json
+{
+  "mentionProjectGitReposOnly": false
+}
+```
+
+To include dot-prefixed folders, set `mentionProjectIncludeDotFolders` to `true`:
+
+```json
+{
+  "mentionProjectIncludeDotFolders": true
+}
+```
+
+For one-off runs, the same filters can be relaxed with CLI flags:
+
+```sh
+pi --mention-project-include-non-git --mention-project-include-dot-folders
+```
+
+The mention character defaults to `#`. To change it, set `mentionProjectTrigger` to a single non-whitespace character:
+
+```json
+{
+  "mentionProjectTrigger": "@"
+}
+```
+
+Folder names should be unique across configured roots. If the same folder name exists in multiple roots, the first configured root wins.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@zigai/pi-mention-project",
+  "version": "0.2.0",
+  "description": "Pi package that adds fuzzy project directory mentions.",
+  "keywords": [
+    "mention",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package",
+    "pi-tweaks",
+    "project"
+  ],
+  "homepage": "https://github.com/zigai/pi-tweaks/tree/main/packages/pi-mention-project#readme",
+  "bugs": {
+    "url": "https://github.com/zigai/pi-tweaks/issues"
+  },
+  "license": "MIT",
+  "author": "zigai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zigai/pi-tweaks.git",
+    "directory": "packages/pi-mention-project"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "typebox": "^1.1.38"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/autocomplete.ts

@@ -0,0 +1,111 @@
+import {
+    type AutocompleteItem,
+    type AutocompleteProvider,
+    type AutocompleteSuggestions,
+    fuzzyFilter,
+} from "@earendil-works/pi-tui";
+
+import { DEFAULT_MENTION_TRIGGER } from "./settings.ts";
+import { extractProjectMentionPrefix, formatProjectMention } from "./mention-syntax.ts";
+import type { MentionProjectSettings, ProjectDirectory } from "./types.ts";
+
+const MAX_SUGGESTIONS = 20;
+
+type ProjectLoader = () => Promise<ProjectDirectory[]>;
+
+function projectToItem(
+    project: ProjectDirectory,
+    trigger = DEFAULT_MENTION_TRIGGER,
+): AutocompleteItem {
+    const value = formatProjectMention(project.name, trigger);
+    return {
+        value,
+        label: project.name,
+        description: project.path,
+    };
+}
+
+function filterProjects(
+    projects: ProjectDirectory[],
+    query: string,
+    trigger: string,
+): AutocompleteItem[] {
+    if (query.length === 0) {
+        return projects.slice(0, MAX_SUGGESTIONS).map((project) => projectToItem(project, trigger));
+    }
+
+    return fuzzyFilter(projects, query, (project) => `${project.name} ${project.path}`)
+        .slice(0, MAX_SUGGESTIONS)
+        .map((project) => projectToItem(project, trigger));
+}
+
+export function createProjectMentionProvider(
+    current: AutocompleteProvider,
+    settings: MentionProjectSettings,
+    loadProjects: ProjectLoader,
+): AutocompleteProvider {
+    const { trigger } = settings;
+
+    const provider = {
+        triggerCharacters: [trigger],
+
+        async getSuggestions(
+            lines: string[],
+            cursorLine: number,
+            cursorCol: number,
+            options: { signal: AbortSignal; force?: boolean },
+        ): Promise<AutocompleteSuggestions | null> {
+            const line = lines[cursorLine] ?? "";
+            const beforeCursor = line.slice(0, cursorCol);
+            const mention = extractProjectMentionPrefix(beforeCursor, trigger);
+            if (mention === undefined) {
+                return current.getSuggestions(lines, cursorLine, cursorCol, options);
+            }
+
+            const projects = await loadProjects();
+            if (options.signal.aborted || projects.length === 0) {
+                return current.getSuggestions(lines, cursorLine, cursorCol, options);
+            }
+
+            const items = filterProjects(projects, mention.query, trigger);
+            if (items.length === 0) {
+                return current.getSuggestions(lines, cursorLine, cursorCol, options);
+            }
+            return { prefix: mention.prefix, items };
+        },
+
+        applyCompletion(
+            lines: string[],
+            cursorLine: number,
+            cursorCol: number,
+            item: AutocompleteItem,
+            prefix: string,
+        ) {
+            if (!prefix.startsWith(trigger)) {
+                return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+            }
+
+            const currentLine = lines[cursorLine] ?? "";
+            const beforePrefix = currentLine.slice(0, cursorCol - prefix.length);
+            const afterCursor = currentLine.slice(cursorCol);
+            const needsSpace = afterCursor.length === 0 || !/^\s/.test(afterCursor);
+            let suffix = "";
+            if (needsSpace) {
+                suffix = " ";
+            }
+            const newLines = [...lines];
+            newLines[cursorLine] = `${beforePrefix}${item.value}${suffix}${afterCursor}`;
+            return {
+                lines: newLines,
+                cursorLine,
+                cursorCol: beforePrefix.length + item.value.length + suffix.length,
+            };
+        },
+
+        shouldTriggerFileCompletion(lines: string[], cursorLine: number, cursorCol: number) {
+            return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+        },
+    };
+
+    return provider;
+}

package/src/editor.ts

@@ -0,0 +1,81 @@
+import { CustomEditor, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import {
+    autocompleteStartIndex,
+    colorProjectMentions,
+    isProjectMentionContext,
+} from "./rendering.ts";
+import type { EditorFactory, EditorLike, ProjectDirectory } from "./types.ts";
+
+const MENTION_FACTORY_BASE = Symbol.for("zigai.pi-mention-project.editor-factory-base");
+
+type WrappedEditorFactory = EditorFactory & {
+    [MENTION_FACTORY_BASE]?: EditorFactory | undefined;
+};
+
+type ProjectSnapshot = () => ProjectDirectory[];
+
+function shouldReactToInput(data: string, trigger: string): boolean {
+    if (data === trigger) return true;
+    if (data.length !== 1) return false;
+    return !/\s/.test(data);
+}
+
+function enhanceEditor(
+    editor: EditorLike,
+    ctx: ExtensionContext,
+    trigger: string,
+    getProjects: ProjectSnapshot,
+): EditorLike {
+    const originalHandleInput = editor.handleInput.bind(editor);
+    editor.handleInput = (data: string) => {
+        originalHandleInput(data);
+
+        if (!shouldReactToInput(data, trigger)) return;
+
+        const text = editor.getText();
+        const lines = text.split("\n");
+        const lastLine = lines[lines.length - 1];
+        let currentLine = "";
+        if (lastLine !== undefined) {
+            currentLine = lastLine;
+        }
+        if (!isProjectMentionContext(currentLine, trigger)) return;
+        if (editor.isShowingAutocomplete?.() === true) return;
+        editor.tryTriggerAutocomplete?.();
+    };
+
+    const originalRender = editor.render.bind(editor);
+    editor.render = (width: number) => {
+        const renderedLines = originalRender(width);
+        let colorThrough = renderedLines.length;
+        if (editor.isShowingAutocomplete?.() === true) {
+            colorThrough = autocompleteStartIndex(renderedLines);
+        }
+        return renderedLines.map((line, index) => {
+            if (index >= colorThrough) return line;
+            return colorProjectMentions(line, ctx, trigger, getProjects());
+        });
+    };
+
+    return editor;
+}
+
+export function applyMentionProjectEditor(
+    ctx: ExtensionContext,
+    trigger: string,
+    getProjects: ProjectSnapshot,
+): void {
+    if (!ctx.hasUI) return;
+
+    const existing = ctx.ui.getEditorComponent() as WrappedEditorFactory | undefined;
+    const baseFactory = existing?.[MENTION_FACTORY_BASE] ?? existing;
+    const factory = ((tui, theme, keybindings) => {
+        const editor = (baseFactory?.(tui, theme, keybindings) ??
+            new CustomEditor(tui, theme, keybindings)) as unknown as EditorLike;
+        return enhanceEditor(editor, ctx, trigger, getProjects);
+    }) as WrappedEditorFactory;
+    factory[MENTION_FACTORY_BASE] = baseFactory;
+
+    ctx.ui.setEditorComponent(factory);
+}

package/src/expand-mentions.ts

@@ -0,0 +1,180 @@
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+
+import {
+    parseProjectMentionName,
+    projectMentionPattern,
+    projectNameSet,
+} from "./mention-syntax.ts";
+import type { ProjectDirectory } from "./types.ts";
+
+function escapeXmlText(value: string): string {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function escapeXmlAttribute(value: string): string {
+    return escapeXmlText(value).replace(/"/g, "&quot;");
+}
+
+function formatProjectBlock(project: ProjectDirectory): string {
+    const name = escapeXmlAttribute(project.name);
+    const projectPath = escapeXmlAttribute(project.path);
+    const root = escapeXmlAttribute(project.root);
+    return `<project name="${name}" path="${projectPath}" root="${root}">\nDirectory: ${escapeXmlText(project.path)}\n</project>`;
+}
+
+function formatCombinedProjectBlock(projects: ProjectDirectory[]): string {
+    if (projects.length === 1) {
+        const project = projects[0];
+        if (project !== undefined) return formatProjectBlock(project);
+    }
+
+    const content = projects.map((project) => formatProjectBlock(project)).join("\n\n");
+    return `<projects>\n${content}\n</projects>`;
+}
+
+function projectMap(projects: ProjectDirectory[]): Map<string, ProjectDirectory> {
+    const byName = new Map<string, ProjectDirectory>();
+    for (const project of projects) {
+        if (byName.has(project.name)) continue;
+        byName.set(project.name, project);
+    }
+    return byName;
+}
+
+function mentionedProjectNames(
+    text: string,
+    projects: ProjectDirectory[],
+    trigger: string,
+): Set<string> {
+    const names = new Set<string>();
+    const knownNames = projectNameSet(projects);
+
+    for (const match of text.matchAll(projectMentionPattern(trigger))) {
+        const parsed = parseProjectMentionName(match[2], match[3], knownNames);
+        if (parsed !== undefined) {
+            names.add(parsed.name);
+        }
+    }
+
+    return names;
+}
+
+function removeProjectMentionSigils(
+    text: string,
+    projects: ProjectDirectory[],
+    trigger: string,
+): string {
+    const knownNames = projectNameSet(projects);
+    return text
+        .replace(
+            projectMentionPattern(trigger),
+            (
+                match: string,
+                leading: string,
+                quotedName: string | undefined,
+                unquotedName: string | undefined,
+            ) => {
+                const parsed = parseProjectMentionName(quotedName, unquotedName, knownNames);
+                if (parsed === undefined) return match;
+                return `${leading}${parsed.name}${parsed.suffix}`;
+            },
+        )
+        .trim();
+}
+
+export function expandProjectMentions(
+    text: string,
+    projects: ProjectDirectory[],
+    trigger: string,
+): string {
+    const byName = projectMap(projects);
+    const names = mentionedProjectNames(text, projects, trigger);
+    if (names.size === 0) return text;
+
+    const loaded: ProjectDirectory[] = [];
+    for (const name of names) {
+        const project = byName.get(name);
+        if (project !== undefined) {
+            loaded.push(project);
+        }
+    }
+    if (loaded.length === 0) return text;
+
+    const projectBlock = formatCombinedProjectBlock(loaded);
+    const userMessage = removeProjectMentionSigils(text, projects, trigger);
+    if (userMessage.length === 0) return projectBlock;
+    return `${projectBlock}\n\n${userMessage}`;
+}
+
+type ContextMessage = ContextEvent["messages"][number];
+type UserContextMessage = Extract<ContextMessage, { role: "user" }>;
+type UserContentBlock = Exclude<UserContextMessage["content"], string>[number];
+type UserTextContentBlock = Extract<UserContentBlock, { type: "text" }>;
+
+function isUserTextContentBlock(block: UserContentBlock): block is UserTextContentBlock {
+    return block.type === "text";
+}
+
+function shouldExpandContextText(text: string, trigger: string): boolean {
+    if (!text.includes(trigger)) return false;
+    const trimmed = text.trimStart();
+    if (trimmed.startsWith("<project ")) return false;
+    return !trimmed.startsWith("<projects>");
+}
+
+function expandProjectMentionsInUserMessage(
+    message: UserContextMessage,
+    projects: ProjectDirectory[],
+    trigger: string,
+): UserContextMessage {
+    if (typeof message.content === "string") {
+        if (!shouldExpandContextText(message.content, trigger)) return message;
+        const expanded = expandProjectMentions(message.content, projects, trigger);
+        if (expanded === message.content) return message;
+        return { ...message, content: expanded };
+    }
+
+    let changed = false;
+    const content: UserContentBlock[] = [];
+    for (const block of message.content) {
+        if (!isUserTextContentBlock(block) || !shouldExpandContextText(block.text, trigger)) {
+            content.push(block);
+            continue;
+        }
+
+        const expanded = expandProjectMentions(block.text, projects, trigger);
+        if (expanded === block.text) {
+            content.push(block);
+            continue;
+        }
+
+        changed = true;
+        content.push({ ...block, text: expanded });
+    }
+
+    if (!changed) return message;
+    return { ...message, content };
+}
+
+export function expandProjectMentionsInMessages(
+    messages: ContextEvent["messages"],
+    projects: ProjectDirectory[],
+    trigger: string,
+): ContextEvent["messages"] {
+    let changed = false;
+    const expandedMessages: ContextEvent["messages"] = [];
+
+    for (const message of messages) {
+        if (message.role !== "user") {
+            expandedMessages.push(message);
+            continue;
+        }
+
+        const expanded = expandProjectMentionsInUserMessage(message, projects, trigger);
+        if (expanded !== message) changed = true;
+        expandedMessages.push(expanded);
+    }
+
+    if (!changed) return messages;
+    return expandedMessages;
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { createProjectMentionProvider } from "./autocomplete.ts";
+import { applyMentionProjectEditor } from "./editor.ts";
+import { expandProjectMentions, expandProjectMentionsInMessages } from "./expand-mentions.ts";
+import { createProjectDirectorySource, listProjectDirectories } from "./projects.ts";
+import {
+    applyMentionProjectCliFlags,
+    configuredMentionProjectSettings,
+    INCLUDE_DOT_FOLDERS_FLAG,
+    INCLUDE_NON_GIT_FLAG,
+} from "./settings.ts";
+import type { MentionProjectSettings } from "./types.ts";
+
+function mentionProjectSettings(pi: ExtensionAPI, ctx: ExtensionContext): MentionProjectSettings {
+    return applyMentionProjectCliFlags(configuredMentionProjectSettings(ctx), {
+        includeNonGit: pi.getFlag(INCLUDE_NON_GIT_FLAG),
+        includeDotFolders: pi.getFlag(INCLUDE_DOT_FOLDERS_FLAG),
+    });
+}
+
+export default function (pi: ExtensionAPI): void {
+    pi.registerFlag(INCLUDE_NON_GIT_FLAG, {
+        description: "Include non-Git child folders in pi-mention-project suggestions.",
+        type: "boolean",
+        default: false,
+    });
+    pi.registerFlag(INCLUDE_DOT_FOLDERS_FLAG, {
+        description: "Include dot-prefixed child folders in pi-mention-project suggestions.",
+        type: "boolean",
+        default: false,
+    });
+
+    pi.on("session_start", async (_event, ctx) => {
+        if (!ctx.hasUI) return;
+        const settings = mentionProjectSettings(pi, ctx);
+        const projectSource = createProjectDirectorySource(settings, ctx.cwd);
+        void projectSource.refresh();
+
+        applyMentionProjectEditor(ctx, settings.trigger, () => projectSource.getCachedProjects());
+        ctx.ui.addAutocompleteProvider((current) =>
+            createProjectMentionProvider(current, settings, () => projectSource.getProjects()),
+        );
+    });
+
+    pi.on("input", async (event, ctx) => {
+        const settings = mentionProjectSettings(pi, ctx);
+        if (!event.text.includes(settings.trigger)) return { action: "continue" };
+
+        if (event.streamingBehavior !== undefined) {
+            return { action: "continue" };
+        }
+
+        const projects = await listProjectDirectories(settings, ctx.cwd);
+        const expanded = expandProjectMentions(event.text, projects, settings.trigger);
+        if (expanded === event.text) return { action: "continue" };
+        return { action: "transform", text: expanded, images: event.images };
+    });
+
+    pi.on("context", async (event, ctx) => {
+        const settings = mentionProjectSettings(pi, ctx);
+        const projects = await listProjectDirectories(settings, ctx.cwd);
+        const messages = expandProjectMentionsInMessages(
+            event.messages,
+            projects,
+            settings.trigger,
+        );
+        if (messages === event.messages) return;
+        return { messages };
+    });
+}

package/src/mention-syntax.ts

@@ -0,0 +1,103 @@
+import type { ProjectDirectory } from "./types.ts";
+import { escapeRegExp } from "./util.ts";
+
+const TRAILING_PUNCTUATION = new Set([".", ",", ";", ":", "!", "?", ")", "}", "]"]);
+
+export type ParsedProjectMention = {
+    name: string;
+    suffix: string;
+};
+
+export type ProjectMentionPrefix = {
+    prefix: string;
+    query: string;
+};
+
+export function projectMentionPattern(trigger: string): RegExp {
+    return new RegExp(`(^|\\s)${escapeRegExp(trigger)}(?:"((?:\\\\.|[^"\\\\])*)"|([^\\s]+))`, "g");
+}
+
+function unescapeQuotedName(value: string): string {
+    return value.replace(/\\(["\\])/g, "$1");
+}
+
+function escapeQuotedName(value: string): string {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function isBareProjectName(name: string, trigger: string): boolean {
+    if (name.length === 0) return false;
+    if (name.includes(trigger)) return false;
+    return /^[^\s"'/]+$/.test(name);
+}
+
+export function formatProjectMention(name: string, trigger: string): string {
+    if (isBareProjectName(name, trigger)) return `${trigger}${name}`;
+    return `${trigger}"${escapeQuotedName(name)}"`;
+}
+
+function parseUnquotedName(
+    rawName: string,
+    knownNames: Set<string>,
+): ParsedProjectMention | undefined {
+    if (knownNames.has(rawName)) {
+        return { name: rawName, suffix: "" };
+    }
+
+    let end = rawName.length;
+    while (end > 0) {
+        const last = rawName[end - 1];
+        if (last === undefined || !TRAILING_PUNCTUATION.has(last)) break;
+        end -= 1;
+        const candidate = rawName.slice(0, end);
+        if (knownNames.has(candidate)) {
+            return { name: candidate, suffix: rawName.slice(end) };
+        }
+    }
+
+    return undefined;
+}
+
+export function parseProjectMentionName(
+    quotedName: string | undefined,
+    unquotedName: string | undefined,
+    knownNames: Set<string>,
+): ParsedProjectMention | undefined {
+    if (quotedName !== undefined) {
+        const name = unescapeQuotedName(quotedName);
+        if (!knownNames.has(name)) return undefined;
+        return { name, suffix: "" };
+    }
+
+    if (unquotedName === undefined) return undefined;
+    return parseUnquotedName(unquotedName, knownNames);
+}
+
+export function projectNameSet(projects: ProjectDirectory[]): Set<string> {
+    return new Set(projects.map((project) => project.name));
+}
+
+export function extractProjectMentionPrefix(
+    textBeforeCursor: string,
+    trigger: string,
+): ProjectMentionPrefix | undefined {
+    const escapedTrigger = escapeRegExp(trigger);
+    const quotedMatch = new RegExp(`(?:^|\\s)(${escapedTrigger}"([^"]*)$)`).exec(textBeforeCursor);
+    if (quotedMatch?.[1] !== undefined && quotedMatch[2] !== undefined) {
+        return { prefix: quotedMatch[1], query: quotedMatch[2] };
+    }
+
+    const match = new RegExp(`(?:^|\\s)(${escapedTrigger}([^\\s"]*)$)`).exec(textBeforeCursor);
+    if (match?.[1] !== undefined && match[2] !== undefined) {
+        return { prefix: match[1], query: match[2] };
+    }
+    return undefined;
+}
+
+export function extractProjectToken(textBeforeCursor: string, trigger: string): string | undefined {
+    return extractProjectMentionPrefix(textBeforeCursor, trigger)?.query;
+}
+
+export function isProjectMentionContext(text: string, trigger: string): boolean {
+    return extractProjectMentionPrefix(text, trigger) !== undefined;
+}

package/src/projects.ts

@@ -0,0 +1,141 @@
+import type { Dirent } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import type { MentionProjectSettings, ProjectDirectory } from "./types.ts";
+import { compareProjectNames } from "./util.ts";
+
+export type ProjectDirectorySource = {
+    getCachedProjects(): ProjectDirectory[];
+    getProjects(): Promise<ProjectDirectory[]>;
+    refresh(): Promise<ProjectDirectory[]>;
+};
+
+function expandHome(root: string): string {
+    if (root === "~") return os.homedir();
+    if (root.startsWith("~/") || root.startsWith("~\\")) {
+        return path.join(os.homedir(), root.slice(2));
+    }
+    return root;
+}
+
+export function resolveProjectRoot(root: string, cwd: string): string {
+    const expanded = expandHome(root.trim());
+    if (path.isAbsolute(expanded)) return path.resolve(expanded);
+    return path.resolve(cwd, expanded);
+}
+
+function uniqueResolvedRoots(roots: string[], cwd: string): string[] {
+    const seen = new Set<string>();
+    const resolved: string[] = [];
+
+    for (const root of roots) {
+        const directory = resolveProjectRoot(root, cwd);
+        if (seen.has(directory)) continue;
+        seen.add(directory);
+        resolved.push(directory);
+    }
+
+    return resolved;
+}
+
+async function directoryEntryIsDirectory(root: string, entry: Dirent): Promise<boolean> {
+    if (entry.isDirectory()) return true;
+    if (!entry.isSymbolicLink()) return false;
+
+    try {
+        const stats = await fs.stat(path.join(root, entry.name));
+        return stats.isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+async function isGitRepository(projectPath: string): Promise<boolean> {
+    try {
+        const stats = await fs.stat(path.join(projectPath, ".git"));
+        return stats.isDirectory() || stats.isFile();
+    } catch {
+        return false;
+    }
+}
+
+async function directoryEntryMatchesSettings(
+    root: string,
+    entry: Dirent,
+    settings: MentionProjectSettings,
+): Promise<boolean> {
+    if (!settings.includeDotFolders && entry.name.startsWith(".")) return false;
+    if (!(await directoryEntryIsDirectory(root, entry))) return false;
+    if (!settings.gitReposOnly) return true;
+    return isGitRepository(path.join(root, entry.name));
+}
+
+async function listRootProjectDirectories(
+    root: string,
+    settings: MentionProjectSettings,
+): Promise<ProjectDirectory[]> {
+    let entries: Dirent[];
+    try {
+        entries = await fs.readdir(root, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+
+    const projects: ProjectDirectory[] = [];
+    for (const entry of entries) {
+        if (!(await directoryEntryMatchesSettings(root, entry, settings))) continue;
+        const projectPath = path.join(root, entry.name);
+        projects.push({ name: entry.name, path: projectPath, root });
+    }
+
+    projects.sort((left, right) => compareProjectNames(left.name, right.name));
+    return projects;
+}
+
+export function uniqueProjectsByName(projects: ProjectDirectory[]): ProjectDirectory[] {
+    const seen = new Set<string>();
+    const unique: ProjectDirectory[] = [];
+
+    for (const project of projects) {
+        if (seen.has(project.name)) continue;
+        seen.add(project.name);
+        unique.push(project);
+    }
+
+    return unique;
+}
+
+export async function listProjectDirectories(
+    settings: MentionProjectSettings,
+    cwd: string,
+): Promise<ProjectDirectory[]> {
+    const projects: ProjectDirectory[] = [];
+    for (const root of uniqueResolvedRoots(settings.roots, cwd)) {
+        projects.push(...(await listRootProjectDirectories(root, settings)));
+    }
+    return uniqueProjectsByName(projects);
+}
+
+export function createProjectDirectorySource(
+    settings: MentionProjectSettings,
+    cwd: string,
+): ProjectDirectorySource {
+    let cachedProjects: ProjectDirectory[] = [];
+
+    const refresh = async (): Promise<ProjectDirectory[]> => {
+        cachedProjects = await listProjectDirectories(settings, cwd);
+        return [...cachedProjects];
+    };
+
+    return {
+        getCachedProjects() {
+            return [...cachedProjects];
+        },
+        getProjects() {
+            return refresh();
+        },
+        refresh,
+    };
+}

package/src/rendering.ts

@@ -0,0 +1,55 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import {
+    isProjectMentionContext,
+    parseProjectMentionName,
+    projectMentionPattern,
+    projectNameSet,
+} from "./mention-syntax.ts";
+import type { ProjectDirectory } from "./types.ts";
+
+export { isProjectMentionContext };
+
+export function colorProjectMentions(
+    line: string,
+    ctx: ExtensionContext,
+    trigger: string,
+    projects: ProjectDirectory[],
+): string {
+    const knownNames = projectNameSet(projects);
+    if (knownNames.size === 0 || !line.includes(trigger)) return line;
+
+    return line.replace(
+        projectMentionPattern(trigger),
+        (
+            match: string,
+            leading: string,
+            quotedName: string | undefined,
+            unquotedName: string | undefined,
+        ) => {
+            const parsed = parseProjectMentionName(quotedName, unquotedName, knownNames);
+            if (parsed === undefined) return match;
+
+            const mentionEnd = match.length - parsed.suffix.length;
+            const mentionText = match.slice(leading.length, mentionEnd);
+            return `${leading}${ctx.ui.theme.fg("accent", mentionText)}${parsed.suffix}`;
+        },
+    );
+}
+
+const ANSI_ESCAPE_PATTERN = new RegExp(
+    `${String.fromCharCode(27)}(?:[@-Z\\\\-_]|\\[[0-?]*[ -/]*[@-~])`,
+    "g",
+);
+
+function stripAnsi(value: string): string {
+    return value.replace(ANSI_ESCAPE_PATTERN, "");
+}
+
+export function autocompleteStartIndex(renderedLines: string[]): number {
+    for (let index = renderedLines.length - 1; index >= 0; index -= 1) {
+        const line = renderedLines[index];
+        if (line !== undefined && stripAnsi(line).startsWith("─")) return index + 1;
+    }
+    return renderedLines.length;
+}

package/src/settings.ts

@@ -0,0 +1,124 @@
+import {
+    getAgentDir,
+    SettingsManager,
+    type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Type, type TSchema } from "typebox";
+import { Value } from "typebox/value";
+
+import type { MentionProjectSettings } from "./types.ts";
+
+export const DEFAULT_MENTION_TRIGGER = "#";
+export const INCLUDE_NON_GIT_FLAG = "mention-project-include-non-git";
+export const INCLUDE_DOT_FOLDERS_FLAG = "mention-project-include-dot-folders";
+
+const TRIGGER_SETTINGS_KEY = "mentionProjectTrigger";
+const ROOTS_SETTINGS_KEY = "mentionProjectRoots";
+const GIT_REPOS_ONLY_SETTINGS_KEY = "mentionProjectGitReposOnly";
+const INCLUDE_DOT_FOLDERS_SETTINGS_KEY = "mentionProjectIncludeDotFolders";
+
+const MentionTriggerSchema = Type.String({ minLength: 1, maxLength: 1, pattern: "^[^/\\s]$" });
+const ProjectRootsSchema = Type.Array(Type.String({ minLength: 1 }));
+const BooleanSchema = Type.Boolean();
+
+type ProjectTrustContext = ExtensionContext & {
+    isProjectTrusted?: () => boolean;
+};
+
+function isProjectTrusted(ctx: ExtensionContext): boolean {
+    return (ctx as ProjectTrustContext).isProjectTrusted?.() ?? true;
+}
+
+function parseOptionalString(schema: TSchema, value: unknown): string | undefined {
+    if (value === undefined) return undefined;
+    if (!Value.Check(schema, value)) return undefined;
+    const parsed: unknown = Value.Parse(schema, value);
+    if (typeof parsed === "string") return parsed;
+    return undefined;
+}
+
+function parseOptionalBoolean(schema: TSchema, value: unknown): boolean | undefined {
+    if (value === undefined) return undefined;
+    if (!Value.Check(schema, value)) return undefined;
+    const parsed: unknown = Value.Parse(schema, value);
+    if (typeof parsed === "boolean") return parsed;
+    return undefined;
+}
+
+function parseOptionalRoots(value: unknown): string[] | undefined {
+    if (value === undefined) return undefined;
+
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.length === 0) return undefined;
+        return [trimmed];
+    }
+
+    if (!Value.Check(ProjectRootsSchema, value)) return undefined;
+    const parsed: unknown = Value.Parse(ProjectRootsSchema, value);
+    if (!Array.isArray(parsed)) return undefined;
+
+    const roots = parsed.filter((entry): entry is string => {
+        return typeof entry === "string" && entry.trim().length > 0;
+    });
+    if (roots.length === 0 && parsed.length > 0) return undefined;
+    return roots;
+}
+
+function applyMentionProjectSettings(
+    settings: Record<string, unknown>,
+    target: MentionProjectSettings,
+): void {
+    const trigger = parseOptionalString(MentionTriggerSchema, settings[TRIGGER_SETTINGS_KEY]);
+    if (trigger !== undefined) {
+        target.trigger = trigger;
+    }
+
+    const roots = parseOptionalRoots(settings[ROOTS_SETTINGS_KEY]);
+    if (roots !== undefined) {
+        target.roots = roots;
+    }
+
+    const gitReposOnly = parseOptionalBoolean(BooleanSchema, settings[GIT_REPOS_ONLY_SETTINGS_KEY]);
+    if (gitReposOnly !== undefined) {
+        target.gitReposOnly = gitReposOnly;
+    }
+
+    const includeDotFolders = parseOptionalBoolean(
+        BooleanSchema,
+        settings[INCLUDE_DOT_FOLDERS_SETTINGS_KEY],
+    );
+    if (includeDotFolders !== undefined) {
+        target.includeDotFolders = includeDotFolders;
+    }
+}
+
+export function configuredMentionProjectSettings(ctx: ExtensionContext): MentionProjectSettings {
+    const loaded: MentionProjectSettings = {
+        trigger: DEFAULT_MENTION_TRIGGER,
+        roots: [],
+        gitReposOnly: true,
+        includeDotFolders: false,
+    };
+
+    const manager = SettingsManager.create(ctx.cwd, getAgentDir(), {
+        projectTrusted: isProjectTrusted(ctx),
+    });
+    applyMentionProjectSettings(manager.getGlobalSettings() as Record<string, unknown>, loaded);
+    applyMentionProjectSettings(manager.getProjectSettings() as Record<string, unknown>, loaded);
+    return loaded;
+}
+
+export function applyMentionProjectCliFlags(
+    settings: MentionProjectSettings,
+    flags: { includeNonGit: unknown; includeDotFolders: unknown },
+): MentionProjectSettings {
+    const loaded = { ...settings };
+    if (flags.includeNonGit === true) {
+        loaded.gitReposOnly = false;
+    }
+    if (flags.includeDotFolders === true) {
+        loaded.includeDotFolders = true;
+    }
+    return loaded;
+}

package/src/types.ts

@@ -0,0 +1,24 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type EditorFactory = NonNullable<ReturnType<ExtensionContext["ui"]["getEditorComponent"]>>;
+
+export type EditorLike = {
+    getText(): string;
+    handleInput(data: string): void;
+    render(width: number): string[];
+    isShowingAutocomplete?(): boolean;
+    tryTriggerAutocomplete?(explicitTab?: boolean): void;
+};
+
+export type ProjectDirectory = {
+    name: string;
+    path: string;
+    root: string;
+};
+
+export type MentionProjectSettings = {
+    trigger: string;
+    roots: string[];
+    gitReposOnly: boolean;
+    includeDotFolders: boolean;
+};

package/src/util.ts

@@ -0,0 +1,7 @@
+export function escapeRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function compareProjectNames(left: string, right: string): number {
+    return left.localeCompare(right, undefined, { sensitivity: "base" });
+}