🗂️ pi-file-context — Browse and Attach Exact File Context

Browse project files inside Pi, select exact lines or Git changes, and review every snapshot before it is attached to the next prompt.

✨ Features

• Opens from /file-context or a configurable shortcut that defaults to Ctrl+Shift+X.
• Browses discovered project folders hierarchically, searches file names or contents globally, and previews bounded text with line numbers.
• Adds whole-file references, exact line ranges, changed hunks, revisions, or Git diffs without using the clipboard.
• Opens the current worktree file in Pi's configured external editor from the preview and reloads it after editing.
• Shows Git state, blame, bounded file history, provenance, and a deterministic token estimate before attachment.
• Reviews and removes exact queued snapshots before the next prompt.
• Preserves selection order, supports repeated browsing, skips common generated directories, and never follows symlinks during discovery.

📦 Install

Install persistently from npm:

pi install npm:@narumitw/pi-file-context

Try from npm without installing permanently:

pi -e npm:@narumitw/pi-file-context

Build and try the local working tree from this repository checkout:

npm --workspace @narumitw/pi-file-context run build
pi -e ./packages/pi-file-context

The package declares dist/index.ts, so an unbuilt local checkout must run the build before Pi loads the package directory.

🚀 Quick start

1. Press Ctrl+Shift+X or run /file-context browse.
2. Find a file, use the visible preview hints to edit or select exact lines or Git changes, and press Enter to attach the snapshot.
3. Review queued snapshots from /file-context, write the request, and submit normally.

🧭 Browser workflow

1. Run /file-context and choose Add context snippet. Press Ctrl+Shift+X or run /file-context browse to open the browser directly. Every route shows the same cancellable project scan before browsing.
2. Use Up/Down to select an immediate child folder or file, and press Enter to open it. Escape, Left, or Backspace returns to the parent folder when the search field is empty. Type to fuzzy-search file names across every discovered folder in relevance order. Press Tab on a file to insert a normal whole-file @path reference, or Enter to preview it for quoting.
3. Press Ctrl+F to switch between file-name and content search. Content search is literal and case-insensitive by default; Alt+C toggles case sensitivity and Alt+F toggles ordered fuzzy matching. The current states remain visible above the results.
4. In content results, use Up/Down to choose a highlighted path-and-line card. Press Tab for a whole-file reference or Enter to preview the file at that line. Escape from the preview restores the query, result selection, and scroll position.
5. In the preview, press Space to anchor the selection and extend the range with Up/Down. The adaptive footer shows line selection, capacity, navigation, Git actions, external editing, and the ? help action. Press Enter to add and close, or press a to add and return to the originating file or content results so you can keep browsing.
6. Use Pi's app.editor.external action, Ctrl+G by default, to open the current worktree file in the configured external editor. File Context pauses its TUI, waits for the editor to exit, reloads bounded text and Git state, and keeps a reload failure visible in the preview. A customized binding is matched and displayed directly, takes priority over File Context's additive letter shortcuts, and does not leave the old Ctrl+G active.
7. Press ? in the preview to review all actions. In a Git worktree, [/] selects changed hunks, b shows current-line blame, h opens file history, r opens a commit/branch/tag, and d reviews and adds explicit diff context. Historical revision previews are read-only and never overwrite the current worktree through the external-editor action.
8. Open /file-context and choose Review selected context to inspect each exact snapshot. Enter opens the snapshot first and then offers Remove from next prompt. Escape goes back without changing selected context, while Ctrl+C closes File Context. Write the question and submit normally; selected snippets are attached in order and cleared together.

Escape returns from a preview to its originating folder, file-search results, or content results. With an empty file-search field, Escape from a nested folder returns to its parent. When the browser was opened from the menu, Escape from the root folder returns to the menu. Direct browser routes cancel at the root instead. Ctrl+C closes menus and browsers. During project scanning, either cancel key stops the scan; menu-owned scans return to the menu and direct scans close without opening a stale explorer.

The agent receives an explicit block similar to:

<user_file_quote path="src/runtime.ts" lines="12-18" git_head="a1b2c3d4..." git_branch="main" git_status="modified (unstaged)" git_blob="e5f6..." content_sha256="9abc..." source="worktree" git_base="HEAD">
selected content
</user_file_quote>

Non-Git quotes retain the original path and lines attributes exactly. Git-backed quotes add ordered optional provenance: the repository HEAD at selection time, branch, file status, selected revision or baseline, tracked blob when available, source kind (worktree, revision, or git_diff), and SHA-256 of the exact attached text. HEAD alone does not identify uncommitted content; content_sha256 identifies the actual snapshot.

Token counts are deterministic byte-based estimates (ceil(UTF-8 bytes / 4)), not provider billing guarantees. Diff context is never attached automatically.

⚙️ Settings

File Context reads optional user settings from ~/.pi/agent/pi-file-context.json, or the equivalent file under Pi's configured agent directory.

The file is not created when defaults are used.

Open /file-context, choose Settings, then choose Open shortcut to change or disable it. The Settings action is unavailable while context snippets are selected because applying the shortcut reloads Pi and would otherwise discard those in-memory selections. A successful menu save reloads Pi automatically so the new shortcut becomes active.

{
  "openShortcut": "ctrl+shift+x"
}

Set openShortcut to any valid Pi key identifier, or set it to null to disable the direct browser shortcut and use /file-context browse. External editing uses Pi's own app.editor.external keybinding and externalEditor setting rather than a File Context setting. Customize those through Pi's keybindings.json and settings.json; File Context reads the effective values and does not register a competing external-editor shortcut. Use an editor wait option such as code --wait when the editor command would otherwise return before editing finishes. Run /reload after editing the JSON file manually.

Missing settings use Ctrl+Shift+X without creating the file. Ctrl+Shift+X requires a terminal that reports shifted control keys through the Kitty keyboard protocol or modifyOtherKeys; use F8 if the terminal cannot distinguish it from Ctrl+X. Invalid JSON or values leave the source file unchanged, use the safe default on load, show a warning, and make the Settings screen read-only until the file is fixed and Pi is reloaded. Failed saves preserve the previous effective shortcut. If an automatic reload fails after a successful save, run /reload to apply the saved value. Interactive saves preserve unknown fields, run in request order within the Pi process, and publish atomically with private file permissions.

Choose a shortcut that does not conflict with Pi or another extension; Ctrl+F is already File Context's internal search-mode toggle. Pi reserves Ctrl+X for app.message.copy by default, so remap that built-in action before assigning Ctrl+X to File Context. Explicit F8 and Ctrl+Alt+F values remain supported, but the default is now Ctrl+Shift+X.

💬 Commands

| Command | Mode | Description | | --- | --- | --- | | /file-context | TUI only | Open the Add, Review, Settings, Status, and Help menu. | | /file-context browse | TUI only | Scan and open the file explorer directly. | | /file-context remove | TUI only | Open selected-context review directly for compatibility. |

Unknown and trailing arguments are rejected. RPC receives an observable warning. JSON and print modes do not enter interactive UI.

🔒 Security and privacy

• Extensions run with the user's full permissions; install only trusted code.
• File paths and symlink targets are checked against the real project root before reading.
• External editing accepts only a canonical project-contained regular worktree file, rejects a final symlink, and serializes the full editing period with Pi's file mutation queue.
• The configured external editor runs with the user's full permissions and may modify other files or access external services according to that program's behavior.
• Preview files are limited to 1 MB and NUL-containing files are treated as binary.
• Discovery is limited to 5,000 files, skips symlinks, and prioritizes shallow files before deeper files.
• File-name and content-search queries are limited to 256 characters. Content search returns at most 100 cards and reports truncation and unreadable, oversized, or binary files as skipped.
• Content search uses the same 5,000-file, 1 MB-per-file, real-project-path, and no-symlink boundaries as preview loading. Superseded searches and file opens are cancelled.
• Terminal control characters are escaped before file names, Git refs, authors, summaries, search context, or file contents are rendered.
• Git is invoked read-only without a shell, pager, external diff, or text conversion; commands time out after 5 seconds and output is bounded to 1.1 MB.
• Revision names are resolved to a commit before file loading. Historical files remain subject to the 1 MB and binary guards.
• Blame shows the author name but not author email. Commit summaries and diffs can still contain sensitive project text; inspect selections before attachment.
• Each snippet stores the text visible at selection time. It does not silently reread changed content when the prompt is submitted.
• A snippet is limited to 500 lines and 50 KB. At most eight selected snippets and 100 KB of aggregate context text are accepted.

🚧 Limitations

• Keyboard line selection only; mouse drag selection is not implemented.
• External editing is available only from a current worktree File Preview, not from historical revisions, Git diffs, history lists, revision input, file lists, or search results.
• On Windows, File Context rejects editor target paths containing command-shell metacharacters instead of passing an unsafe path through Pi's shell-compatible editor launch.
• Up to eight selected snippets; exact review and repeated removal are supported, but there are not yet bulk clear, undo, or reorder actions.
• Selected context does not survive /reload, session replacement, or shutdown.
• The configurable shortcut is registered without replacing another extension's custom editor; /file-context remains available if the shortcut is disabled or conflicts.
• File discovery uses a small built-in ignore list rather than .gitignore semantics.
• Content search scans discovered files natively and sequentially; large projects or queries with no matches may take longer than indexed or external search tools.
• Fuzzy content search matches query characters in order on one line; it is not semantic search and does not cross line boundaries.
• Git integration degrades to the original filesystem-only workflow outside a repository or when Git metadata cannot be read.
• File history is limited to the 20 most recent commits. Untracked files have status and provenance but no HEAD diff hunk until Git tracks them.

🗂️ Package layout

dist/                         Generated TypeScript runtime loaded by Jiti
scripts/build-runtime.mjs      Deterministic runtime builder and boundary validator
src/index.ts                   Thin Pi entrypoint
src/file-context.ts            Lifecycle, routes, filesystem boundaries, selected state, prompt injection
src/file-context-menu.ts       Add, review, Settings, Status, Help, and removal flow
src/file-context-settings.ts   Shortcut validation, coordinated reads, and atomic persistence
src/external-editor.ts          Safe configured-editor process, path, queue, and TUI lifecycle
src/file-context-explorer.ts   Folder, file, content, Git, editing, and line-range controller
src/file-browser.ts            Safe hierarchy model for discovered project paths
src/file-browser-ui.ts         Width-safe folder and file list rendering with effective key hints
src/file-context-preview-ui.ts Width-safe preview, capacity, and progressive action help
src/content-search.ts          Bounded literal and fuzzy content matching
src/content-search-session.ts  Search input, toggles, navigation, and cancellation
src/content-search-ui.ts       Width-safe result cards and highlighted context
src/file-search.ts             Bounded native fuzzy file-name ranking
src/git-context.ts             Bounded read-only Git status, diff, blame, history, revisions

test/content-search.test.ts     Content matcher behavior and limits
test/content-search-ui.test.ts  Content interaction, rendering, and lifecycle tests
test/file-context-search.test.ts  File-name ranking, typo tolerance, and query-bound tests
test/file-context-folder-browser.test.ts  Folder hierarchy, navigation, keybinding, and terminal-safety tests
test/file-context.test.ts       Filesystem, prompt, lifecycle, shortcut, and explorer tests
test/file-context-selection.test.ts  Add-and-continue, capacity, and progressive-help tests
test/file-context-menu.test.ts  Menu, shortcut settings, exact review, removal, and rendering tests
test/file-context-command-menu.test.ts  Command routes, loading, and direct browser compatibility tests
test/pending-quotes.test.ts     Exact selected-context removal, cancellation, and stale-flow tests
test/file-context-settings.test.ts  Shortcut defaults, validation, ordering, and atomic-write tests
test/external-editor.test.ts    External process, path, queue, and cancellation tests
test/git-context.test.ts        Git repository behavior and parser tests

The generated runtime is built from the authoritative src/index.ts graph and does not import back into src.

🔎 Keywords

Pi extension, file explorer, source quote, line selection, coding agent, terminal UI.

📄 License

MIT