File Explorer & @-Mentions

Maestro’s File Explorer provides a keyboard-navigable file tree with git integration and a powerful @-mention system for referencing files in AI conversations.

Opening the File Explorer

The File Explorer lives in the Right Bar on the Files tab.

Keyboard
Mouse

Cmd+Shift+F        # Go to Files tab
Alt+Meta+ArrowRight # Toggle Right Bar

Shortcuts: src/renderer/constants/shortcuts.ts:27, 9-13

Component: src/renderer/components/FileExplorerPanel.tsx

File Tree Features

Git Status Indicators

Files display color-coded status badges:

Badge	Status	Color	Description
M	Modified	Orange	File has uncommitted changes
A	Added	Green	File is newly added (staged)
D	Deleted	Red	File is deleted (staged)
?	Untracked	Gray	File is not tracked by git
C	Conflicted	Red	File has merge conflicts

Context Provider: src/renderer/contexts/GitStatusContext.tsx

File Icons

Files show extension-specific icons with theme-aware colors:

// Extension color mapping
const extensionColors = {
  '.ts': 'blue',
  '.tsx': 'blue',
  '.js': 'blue',
  '.jsx': 'blue',
  '.md': 'green',
  '.json': 'amber',
  '.css': 'purple',
  '.py': 'teal',
  '.rs': 'rust',
  '.go': 'cyan',
  // ...
};

Badge Colors: Support light/dark themes and colorblind-safe palettes.

Folder Expansion

Click to Toggle

Click folder icons or names to expand/collapse.

Keyboard Navigation

Use arrow keys:

→ Expand folder
← Collapse folder
↑/↓ Navigate up/down
Enter Open selected file

Expand/Collapse All

Right-click in the file tree:

Expand All - Open all folders
Collapse All - Close all folders

Handlers: src/renderer/components/RightPanel.tsx:59-67

Hidden Files

Toggle hidden file visibility: Settings → Interface → Show Hidden Files When disabled, files matching these patterns are hidden:

.* (dotfiles)
node_modules/
dist/, build/, out/
__pycache__/
.git/

Setting: src/renderer/hooks/useSettings.ts → showHiddenFiles

Filtering Files

Quickly find files with fuzzy search:

Filter Files (Cmd+F)
Fuzzy File Search (Cmd+G)

When the Files tab is focused, press Cmd+F to filter the visible tree:

Cmd+F              # Filter files (in Files tab)

Features:

Case-insensitive search
Matches anywhere in path
Real-time filtering
Highlights matches

Shortcut: src/renderer/constants/shortcuts.ts:90

Global fuzzy file search across entire project:

Cmd+G              # Fuzzy file search

Opens a modal with:

Fuzzy matching algorithm
Keyboard navigation
Instant preview
Recently opened files at top

Shortcut: src/renderer/constants/shortcuts.ts:68

@-Mention System

Reference files directly in AI prompts using @-mentions:

How It Works

Type @ in AI Mode

In the input field (AI mode), type @ to trigger autocomplete.

Select File

Navigate suggestions with arrow keys:

↑/↓ Navigate up/down
Enter Select file
Esc Cancel autocomplete

Hook: src/renderer/hooks/useAtMentionCompletion.ts

File Path Inserted

The file path is inserted into your prompt:

@src/components/Header.tsx can you add a search bar?

AI Receives Context

The AI agent receives the file path and can read its contents for context-aware responses.

@-Mention Features

Fuzzy Matching

Type partial paths and get intelligent matches:

@hdr        → Header.tsx
@comp/hdr   → components/Header.tsx
@src/u/fmt  → src/utils/formatter.ts

File Type Icons

Autocomplete shows file extension badges:

TypeScript: Blue badge
Markdown: Green badge
JSON: Amber badge
CSS: Purple badge

Git Status

Modified files show their git status in autocomplete:

M for modified files (more likely to be relevant)
A for added files
? for untracked files

Folder @-Mentions

Reference entire directories:

@src/components/ review all files in this folder

The AI sees the folder structure and can analyze multiple files.

@-Mention Interface

// @-mention suggestion type
interface AtMentionSuggestion {
  value: string;           // Full path
  type: 'file' | 'folder'; // File or directory
  extension?: string;      // File extension (e.g., '.tsx')
  gitStatus?: string;      // Git status ('M', 'A', '?', etc.)
}

Source: src/renderer/components/MainPanel.tsx:96-100

File Preview

Double-click files to open them in File Preview tabs:

Preview Features

Syntax Highlighting
Edit Mode
Search in File
Copy Path

Code files render with full syntax highlighting:

100+ languages supported
Theme-aware colors
Line numbers
Copy code button

Library: Prism.js with custom themes

Toggle edit mode to modify files:

Cmd+E              # Toggle edit/preview mode

Features:

Live editing
Auto-save (with confirmation)
Unsaved changes indicator
Undo/redo

Component: src/renderer/components/FilePreview.tsx

Search within the open file:

Cmd+F              # Search in file

Regex support
Case-sensitive toggle
Match count
Jump to next/prev

Copy file path to clipboard:

Cmd+P              # Copy file path (in preview)

Shortcut: src/renderer/constants/shortcuts.ts:30

File Preview Tabs

File previews open as tabs alongside AI tabs:

interface FilePreviewTab {
  id: string;              // Unique tab ID
  path: string;            // Full file path
  name: string;            // Filename (without extension)
  extension: string;       // File extension (e.g., '.tsx')
  content: string;         // File content
  scrollTop: number;       // Preserved scroll position
  searchQuery: string;     // Preserved search query
  editMode: boolean;       // Edit/preview toggle state
  editContent?: string;    // Unsaved changes
}

Tab System: src/renderer/utils/tabHelpers.ts

File Operations

Right-click any file for operations:

Open in Preview - Open in tab
@-Mention - Insert reference in prompt
Copy Path - Copy full path
Copy Relative Path - Copy workspace-relative path
Reveal in Finder - Show in file manager
Open in External Editor - Open in default app

Menu: src/renderer/components/FileExplorerPanel.tsx

Drag and Drop (Planned)

Future: Drag files from explorer into input field to create @-mentions.

File Tree Refresh

Refresh file tree to see new files:

Auto-Refresh
Manual Refresh

Enable auto-refresh in File Explorer settings:Right Bar → Files → ⚙️ → Auto-refresh intervalOptions: 5s, 10s, 30s, 60s, or disabled.

Click the refresh icon in the Files tab header.Handler: onAutoRunRefresh from useAutoRunHandlers

Refresh Handler: src/renderer/hooks/useFileTreeManagement.ts:refreshFileTree()

SSH Remote Files

When an agent uses SSH remote execution, file operations work transparently:

// SSH config in session
sshRemoteConfig?: {
  enabled: boolean;
  host: string;
  port: number;
  username: string;
  // ...
}

Features:

File tree shows remote files
@-mentions work with remote paths
File preview loads remote content
Edit mode saves to remote host

SSH Wrapper: src/main/utils/ssh-spawn-wrapper.ts

When implementing file features, always support SSH remote execution using wrapSpawnWithSsh().

File Tree State Persistence

Your file tree state persists across sessions:

Saved State

Expanded folders - Which folders are open
Scroll position - Where you scrolled to
Filter query - Last search term
Hidden files toggle - Show/hide setting

Storage: Saved per agent in maestro-sessions.json

// Session interface
interface Session {
  expandedFolders: Set<string>;  // Expanded folder paths
  // ...
}

Keyboard Shortcuts

# Files Tab
Cmd+Shift+F        # Go to Files tab
Cmd+F              # Filter files (when Files tab focused)
Cmd+G              # Fuzzy file search

# In File Tree
↑/↓                # Navigate files
→                  # Expand folder
←                  # Collapse folder
Enter              # Open selected file

# File Preview
Cmd+E              # Toggle edit/preview mode
Cmd+P              # Copy file path
Cmd+F              # Search in file
Cmd+W              # Close file tab

Next Steps

Git Integration

Git status indicators and diff viewer

Output Filtering

Search and filter AI responses

Dual-Mode Sessions

Switch between AI and terminal

Keyboard Shortcuts

Complete keyboard reference

Get Started

Core Features

Power Features

Analytics

File Explorer & @-Mentions

Opening the File Explorer

File Tree Features

Git Status Indicators

File Icons

Folder Expansion

Hidden Files

Filtering Files

@-Mention System

How It Works

@-Mention Features

@-Mention Interface

File Preview

Preview Features

File Preview Tabs

File Operations

Context Menu

Drag and Drop (Planned)

File Tree Refresh

SSH Remote Files

File Tree State Persistence

Saved State

Keyboard Shortcuts

Next Steps

Git Integration

Output Filtering

Dual-Mode Sessions

Keyboard Shortcuts

Build docs developers (and LLMs) love

Get Started

Core Features

Power Features

Analytics

​Opening the File Explorer

​File Tree Features

​Git Status Indicators

​File Icons

​Folder Expansion

​Hidden Files

​Filtering Files

​@-Mention System

​How It Works

​@-Mention Features

​@-Mention Interface

​File Preview

​Preview Features

​File Preview Tabs

​File Operations

​Context Menu

​Drag and Drop (Planned)

​File Tree Refresh

​SSH Remote Files

​File Tree State Persistence

​Saved State

​Keyboard Shortcuts

​Next Steps

Git Integration

Output Filtering

Dual-Mode Sessions

Keyboard Shortcuts

Build docs developers (and LLMs) love

Opening the File Explorer

File Tree Features

Git Status Indicators

File Icons

Folder Expansion

Hidden Files

Filtering Files

@-Mention System

How It Works

@-Mention Features

@-Mention Interface

File Preview

Preview Features

File Preview Tabs

File Operations

Context Menu

Drag and Drop (Planned)

File Tree Refresh

SSH Remote Files

File Tree State Persistence

Saved State

Keyboard Shortcuts

Next Steps