Finder & Editor

The Finder is a file manager sidebar that shows your project's directory tree with real-time git status, search, and a built-in preview pane for code, images, and Markdown.

The sidebar is made of cards

Finder is one card in a project's sidebar, alongside Git, GitHub Issues, Attach, Notes and any panel a plugin registers. Every card behaves the same way: opened from the sidebar's + menu, moved between the sidebar's two columns, resized by dragging its edge, and closed when it is in the way.

  • •Only what applies: a card is offered where it has something to show. Git needs a repository, Attach and Notes need a project, and none of them appear on the welcome tab.
  • •Remembered per project: which cards are open, in what order, how tall, in which column, and how wide the sidebar was. Reopen the project later and you find it as you left it.
  • •Restoring a session wins: a tab brought back from the previous run keeps its own arrangement. What is remembered is applied to a new tab opened on a project you have seen before.
  • •Stored in .nexion/sidebar.json, in a file of its own: how you like your sidebar is yours, while the project's name and colour in .nexion/config.json next door are meant to be shared. If you commit the .nexion folder, add .nexion/sidebar.json to your .gitignore and everyone on the project keeps their own arrangement.
  • •It settles when things change: a card for a plugin that has been removed is dropped, a Notes card comes down if Notes is switched off in Preferences, and a file written by a newer version is ignored rather than half-applied.

File Tree

The file tree displays your project's directory structure as a collapsible hierarchy. Folders are listed first, then files: both sorted alphabetically. Each entry shows the system file icon, name, and git status badge when applicable.

  • •Lazy loading: Subdirectories are loaded on demand when expanded, keeping large projects fast.
  • •Hidden files: Toggle hidden file visibility with Cmd+Shift+.
  • •Keyboard navigation: Use arrow keys to move through the tree and Return to toggle folders or select files.
  • •Gitignore-aware: Files and folders matched by .gitignore rules are visually dimmed in the tree.
  • •macOS metadata hidden: System files like .DS_Store and ._* resource forks are hidden automatically.
  • •Persistent folder state: Expanded and collapsed folder states are remembered across sessions.
  • •Focus shortcut: Press Cmd+Opt+F to jump focus to the Finder panel from anywhere.
  • •Single-click open: Configurable in Preferences: click a file once to preview it, or require a double-click.
  • •Auto-fold single-child directories: Compacted paths (e.g. src/utils) reduce visual clutter when a folder contains a single subfolder.
  • •Git status coloring: File and folder names are color-coded by git status: orange (modified), green (added), blue (untracked), red (deleted), purple (renamed). Folders inherit the dominant child status.
  • •Move to Trash: Right-click any file or folder and choose "Move to Trash" for safe deletion via macOS's native trash integration.

Quick Open Cmd+P

Press Cmd+P to open the Quick Open overlay: a fast, fuzzy file search inspired by Zed and VS Code. Start typing a file name to see instant results with match highlighting. Use arrow keys to navigate and Return to open.

  • •Fuzzy matching: Matches file names using a scoring algorithm with word boundary, camelCase, and path separator bonuses.
  • •.gitignore-aware: Powered by a bundled ripgrep backend. Automatically excludes files matched by .gitignore, .ignore, and .rgignore rules: no more node_modules or build directories cluttering results.
  • •Persistent cache: The file index is cached to disk and restored instantly on next launch, with a background refresh for accuracy.
  • •Recent files: Recently opened files appear at the top for quick re-access.
  • •Jump to next git change: Press Ctrl+] to quickly navigate to the next modified file.

Git Status Badges

Each file and folder displays a color-coded badge indicating its git status:

Badge Color Meaning
M Orange Modified
A Green Added
U Blue Untracked
D Red Deleted
R Purple Renamed

Both badges and file/folder name colors reflect git status. Folders aggregate the status of their children, a folder shows the dominant child status. Each file also shows line stats (lines added/removed) next to its status badge.

Search

The search bar at the top of the Finder filters the file tree in real time. It performs a case-insensitive substring match across all file names recursively. Results appear as a flat list. The search is debounced to avoid unnecessary work while typing.

Context Menu

Right-click on any file or folder to access the context menu:

  • •Copy Path: Copy the full file path to the clipboard.
  • •Copy Filename: Copy just the file name.
  • •Open in [Editor]: Opens the file in your configured external editor.
  • •Show in Finder: Reveals the file in macOS Finder.
  • •Move to Trash: Safely moves the file or folder to the macOS Trash with a confirmation dialog.
  • •Open with Default App: Opens the file with the system default application.
  • •Use as Prompt Reference: Attaches the file as context for AI prompts, with optional line selection (#L123 format).
  • •Explain with AI: Sends the file content to your configured AI provider for an AI-generated explanation.*

File Attachments

The Attach panel in the Finder sidebar lets you manage file attachments for AI prompts. Drag and drop files into the drop zone, or place files directly in the .nexion/attachments directory: they are picked up automatically.

  • •Auto-scan: Files added manually to .nexion/attachments/ are detected automatically via the file system watcher and appear in the panel.
  • •Preview: Click on any attached file to open it in a Quick Look preview window.
  • •Prompt reference: Click the @ button to send the file path as a prompt reference (prefixed with @) to the terminal.
  • •Move to Trash: Remove an attachment via macOS Trash with a confirmation dialog.
  • •CLI management: Use nexion attach list|add|remove|clear|open to manage attachments from the command line.
  • •Security: Files must be under 50 MB, symlinks and hidden files are ignored, and path traversal is blocked.

Note: The Attach panel is not available on SSH tabs.

Drag & Drop

Drag files from the Finder panel into the terminal to attach them as @path references in your AI prompts.

Preview Pane

The preview header shows the file name, type, size, last modified date, and the per-mode action buttons (Preview, Edit, Diff).

Code Preview & Edit

Source files are rendered with syntax highlighting powered by Monaco Editor, supporting 40+ languages. The language is auto-detected from the file extension.

The inspector supports three modes, accessible via tabs: Preview, Edit, and Diff. The Edit and Diff tabs appear automatically when the file is editable or has uncommitted changes.

Preview Mode

Toolbar toggles for code preview:

  • •Minimap: A code minimap on the right side for quick navigation through long files.
  • •Line numbers: Toggleable in Preferences.
  • •Word wrap: Toggleable in Preferences.

Edit Mode

The built-in Edit mode turns the preview into a full Monaco Editor. It works with both local and SSH remote files.

  • •Cmd+S: Save the file (local or SSH).
  • •Cmd+Z / Cmd+Shift+Z: Undo / Redo.
  • •Cmd+X / Cmd+C / Cmd+V: Cut, Copy, Paste.
  • •Cmd+A: Select all.
  • •Esc: Return keyboard focus to the Finder tree.

A Modified / Saved indicator appears in the header. The default mode (Preview or Edit) can be configured in Preferences.

Auto-save on file switch: When enabled in Preferences > Editor, the editor automatically saves changes when you switch to another file, replacing the "unsaved changes" confirmation dialog. Enabled by default for local files.

Markdown Preview

Markdown files (.md, .markdown) show a toggle button in the preview toolbar to switch between source code and rendered view. The rendered view supports headings, bold/italic, code blocks with syntax highlighting, tables, blockquotes, lists, and links. The toggle state is remembered across sessions.

Image Preview

Supported formats: PNG, JPG, GIF, BMP, TIFF, WebP, HEIC, ICO, ICNS, SVG, and PDF. All previews support scrollable zoom.

Diff Mode

For files with uncommitted changes, the Diff tab compares the current file content against HEAD, displaying the differences in either side-by-side or inline mode (configurable in Preferences). Newly added or untracked files show the full content as additions. Diffs can also be opened in a separate window.

External Editor

If you have an external editor configured in Preferences, an edit button appears in the toolbar to open the current file directly in that editor. The button is available in all inspector modes.

External Editors

Nexion detects installed editors automatically and lets you pick your preferred one in Preferences. You can also add custom editors by specifying their name and bundle identifier. Detected editors include:

  • •Visual Studio Code, Cursor, Windsurf, Zed
  • •Sublime Text, BBEdit, Nova
  • •Xcode, IntelliJ IDEA, TextEdit
  • •Vim, Neovim, Emacs (via terminal)

SSH Tabs

When connected to an SSH host, the Finder browses the remote file system. Some local-only features are automatically disabled:

  • •Quick Open: Disabled (Cmd+P does nothing on SSH tabs).
  • •Search bar: Hidden from the Finder toolbar.
  • •File Attachments: The Attach panel is hidden.
  • •External Editor / Show in Finder: Disabled since files are remote.

Git integration, code preview, edit mode, and the file tree all work normally over SSH via the ControlMaster connection.

Performance

The Finder uses a Zed-inspired architecture optimized for large projects. Path-based stable identity eliminates UUID regeneration on reload. A cached flat snapshot avoids per-render recursive tree walks. The FS watcher uses 300ms debounce with smart event deduplication. File previews are cached (up to 50 entries), file icons use a system-level cache, and the first 6 visible files are prefetched in the background.

* AI features require a configured provider: works with Anthropic, OpenAI, Codex / ChatGPT, Gemini, or GitHub Models.