---
title: File Explorer (browse a project's files)
---

# File Explorer (browse a project's files)

## What it is

The **File Explorer** is a collapsible sidebar pane on a project's workspace that lets you browse the project's folder on disk without leaving Omniscio. It has two tabs:

- **Files** — a live, expandable file tree of the project directory (the subject of this page).
- **Changes** — the git diff-review surface (its own page: [diff-viewer.md](diff-viewer.md)).

This page covers the **Files** tab. The header shows the project name and a collapse button; below it the tab bar switches between Files and Changes.

> **Desktop only — no CLI control surface.** The whole File Explorer pane is gated `hidden md:flex` ([FileExplorerSidebar.tsx](/src/renderer/src/features/file-explorer/FileExplorerSidebar.tsx)), so it never renders on mobile / phone-width layouts. It is also **not** exposed through Omniscio's local control server — there is no `/files*` route, so an external script or an AI driving Omniscio over the CLI control API cannot browse, open, reveal, or delete files. Browsing a project's files is an in-app, desktop-only action.

## Where to find it

### How to use it

1. **Open the File Explorer** for the active project and make sure the **Files** tab is selected.
2. **Expand folders** by clicking a directory row — its chevron rotates and the children load and indent beneath it. Click again to collapse.
3. **Click a file** to open it in the in-app preview (the [Peek Viewer](peek-viewer.md)) — code renders with syntax highlighting, and renderable formats can toggle to a rendered preview. **PDF files** open in the built-in PDF viewer (paginated, with zoom, selectable/copyable text, in-page search via Ctrl+F, a convert-to-Markdown/text action, and a Print button that prints every page at its true physical size) rather than the Peek Viewer or your OS default app, unless you have turned off "Open PDFs in the built-in viewer" in Settings.
4. **Right-click a file or folder** for a context menu:
   - **Open** — hand the file to your OS default app (`shell.openPath`).
   - **Show in folder** — reveal the file in the OS file manager (Explorer / Finder).
   - **Copy path**, **Copy relative path**, **Copy name** — copy the file's location or name to the clipboard.
   - **Delete** — remove the file or folder. This opens a confirmation dialog first (deleting a folder removes its contents), and the delete goes through the `FILES_DELETE` IPC.

## How it behaves

### States

- **Loading** — a spinner shows while the root directory's entries are still being read.
- **Empty directory** — an "Empty directory" message when the project folder has no entries.
- **Error** — a read error (e.g. the folder is gone or unreadable) shows in red in the pane.

## For agents

### Where things live (for agents with repo access)

- Sidebar shell, tab bar, Files/Changes switch, desktop-only gating (`hidden md:flex`): [/src/renderer/src/features/file-explorer/FileExplorerSidebar.tsx](/src/renderer/src/features/file-explorer/FileExplorerSidebar.tsx).
- File-tree row (expand/collapse, click-to-open, right-click menu, delete-with-confirm): [/src/renderer/src/features/file-explorer/FileTreeItem.tsx](/src/renderer/src/features/file-explorer/FileTreeItem.tsx) + [FileTreeContextMenu.tsx](/src/renderer/src/features/file-explorer/FileTreeContextMenu.tsx).
- Directory listing + open/reveal/delete state: [/src/renderer/src/stores/file-explorer-store.ts](/src/renderer/src/stores/file-explorer-store.ts).

## Related

- [diff-viewer.md](diff-viewer.md) — the File Explorer's other tab: review (accept/reject) a project's git changes.
- [peek-viewer.md](peek-viewer.md) — the in-app preview that opens when you click a file here.
- [media-link-open.md](media-link-open.md) — how binary media files (mp3 / mp4 / pdf) open in your OS default app.