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

Browse project files in Pi, select exact lines or Git changes, and review each snapshot before attaching it to the next prompt.

✨ Features

• Opens from /file-context or a configurable shortcut that defaults to Ctrl+Shift+X.
• Browses project folders, 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 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

Run once from npm:

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

Build and run the local working tree:

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

The package declares dist/index.ts, so build a local checkout before loading its package directory.

Pi extensions run with your user permissions. Review third-party extension source before installing it.

🚀 Quick start

1. Press Ctrl+Shift+X or run /file-context browse.
2. Find a file, select exact lines or Git changes, and press Enter to queue the snapshot.
3. Run /file-context to review the queue, then write and submit the request 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 use the deterministic estimate ceil(UTF-8 bytes / 4) and do not predict provider billing. 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. Using the defaults does not create the file.

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 a valid Pi key identifier. Set it to null to disable the 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	Purpose
/file-context	Select and review file context for the next prompt, or change settings.
/file-context browse	Scan and open the file explorer directly.
/file-context remove	Review selected context through the compatibility route; it does not delete files.

All routes require TUI mode and reject unknown or trailing arguments. RPC reports the TUI requirement; print and JSON modes reject the command before opening UI. See Security and privacy before sending selected file content.

🔒 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

packages/pi-file-context/
├── src/                               # Authoritative implementation and helpers
│   ├── index.ts                       # Thin Pi entrypoint
│   └── file-context.ts                # Context selection and prompt attachment
├── dist/                              # Generated Jiti runtime
├── scripts/build-runtime.mjs          # Runtime builder
└── test/                              # Behavior and lifecycle coverage

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

🔎 Keywords

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

📄 License

MIT