> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File explorer and code editor

> Browse, edit and ship changes to any project's files from the dashboard, with edit workspaces, search, trash and pull requests.

# File explorer

The file explorer shows a project's files in a panel beside your conversations. You can read any file, edit it in a full code editor, and turn your edits into a pull request without leaving the dashboard. The main checkout of a project is never changed by the explorer: edits made there go to a separate edit workspace.

## Opening Files

The explorer lives in the work dock, a panel on the right of the Command Deck's tab area. The dock has four tabs: **Files**, **Changes**, **Search** and **Live**. It keeps your conversation on screen, and a file you open from it opens beside the chat.

Open the dock in any of these ways:

* the Stage **+** menu: **Files**, **Changes in** your project, or **Go to file…**;
* the **Files** button on a project home or on an issue overview;
* `Ctrl+Shift+E` (`⌘⇧E` on macOS) to show or hide Files, `Ctrl+Shift+G` (`⌘⇧G`) to show or hide Changes, and `Ctrl+Shift+F` (`⌘⇧F`) to open Search.

The dock follows the tab you are on. A conversation tab shows that conversation's folder, an issue tab shows the issue's workspace, a code tab shows its file's root and selects the file, and every other tab shows the project's main checkout. The line under the tabs names what the dock shows. Click the root name in the Files header to pin the dock to the main checkout or to one of the project's edit workspaces; **Follow the active tab** (or **Follow tab** on that line) undoes the pin. Drag the dock's left edge to resize it; the dock remembers its width and whether it was open.

A conversation that runs on another machine, or in a folder outside every project, has no files here. The dock says so and offers **Open project files**.

To open a file or folder here from a terminal or from your file manager's right-click menu, use `pan open <path>`. See [Open in Overdeck](https://panopticon-cli.com/features/open-in-overdeck.md).

## The tree

Folders load when you expand them, so a large repository opens quickly. Each file shows its type, folders show a chevron, and indent guides mark the depth. Git-ignored files are hidden until you turn them on.

The **⋯ View options** menu holds the view choices: **Show all files**, **Only changed files**, **Only what this conversation changed** (on a conversation tab), **Show git-ignored files** and **Show dotfiles**, then **New folder**, **Expand all folders** and **Refresh**. A filtered tree shows a line such as "Showing changed files" with **Show all**.

The `.git` folder never shows in the tree, even with **Show dotfiles** on, and **Expand all folders** skips it.

Files carry git colors and a status letter after the name: `U` untracked, `A` added, `M` modified, `D` deleted, `R` renamed and `C` copied. A folder takes the color of its most important changed child, so you can find a change without expanding every folder. A small dot marks the files the current conversation changed, and the folders that hold them.

## Search

Press `Ctrl+P` (`⌘P` on macOS) anywhere in the Command Deck to open **Go to file**. An exact file name ranks first, then a name that starts with what you typed, a name that contains it, a path that contains it, and last a fuzzy match. Within each of those, files changed here rank first and carry a **changed here** tag. `Enter` opens the file beside the chat and `Shift+Enter` reveals it in Files. The `Ctrl+K` command palette also lists these files under **Files**.

The **Search** tab searches file contents, with toggles for case sensitivity and regular expressions; a result opens the file at the matching line. Right-click a folder and choose **Find in folder** to search only inside it. See [Keyboard shortcuts](https://panopticon-cli.com/features/keyboard-shortcuts.md).

`Ctrl+Shift+F` (`⌘⇧F`) moves the cursor to the Search box even in a conversation tab. `Ctrl+F` (`⌘F`) still opens the conversation's own find bar.

## Changes

The **Changes** tab lists what changed in the dock's scope.

* On a conversation tab, chips pick **This conversation**, **Last turn**, **Not committed** or **All of main today**. A **Not committed yet** group comes first, then one group per commit with its short hash, subject, whether it is pushed, and the time. In **All of main today** each commit names who made it.
* On an issue or edit workspace, the groups are **Not committed yet** and **Committed on** the branch.
* On a project, the tab lists today's commits on the default branch, plus the main checkout's uncommitted files.

Each file row offers **Open diff**, **Open beside** and **Reveal in files**. An uncommitted file that other sessions also changed carries a note, for example "Shared file. 612 other uncommitted lines come from … Only this conversation's lines are counted."

The diff view shows one file with previous and next buttons; `J` and `K` move through the list when you are not typing. Back returns to the list.

A Markdown file in the diff view has a **Diff** and **Preview** switch next to its commit tag. Preview shows the document as rendered text, as it is after the change. A file not committed yet shows its current text. A file committed on an issue branch shows the committed version. For a file in a commit, a file the commit added shows as committed; any other file shows its current text, with the note "Showing the current file". A deleted file has no Preview. Moving to another file shows its diff again. See [Markdown preview](#markdown-preview) for the rest of how previewing works.

## Live

The **Live** tab shows the conversations you popped into the dock, with needs-you items first. It replaces the floating conversation dock, and it appears only when there is something to watch.

## Editing files

A file opens in a Monaco code pane. Your edits save automatically one second after you stop typing and when the editor loses focus, and `Ctrl/Cmd+S` saves at once. A single click on a file opens a preview tab, shown in italics, that the next single click replaces; a double click pins the tab.

The header shows where the file lives as a breadcrumb: the project or workspace name, then each folder, then the file name. **File / Changes** switches between the file and the **Changes** view, which compares your file with the last commit. **Reveal in files** (the target icon) opens the dock's Files tab with the file selected. `Alt+Z` toggles word wrap, and a Markdown file has a **Preview** tab; see [Markdown preview](#markdown-preview).

When a conversation is open beside the file, a blue bar in the margin marks each line that conversation changed, whether it committed the change or not. Lines another session wrote in the same file get no bar. The marks follow the conversation's changes as it works.

## Markdown preview

A `.md`, `.mdx` or `.markdown` file can be previewed as rendered text instead of source. The switch appears in two places: the diff view and the dock's deck view show a **Diff** / **Preview** switch next to an **Open file** button when a deck is open; the code pane shows an **Edit** / **Preview** switch instead. The choice resets to its default whenever you pick another file.

A preview is not always available. It shows "This file is outside the conversation's folder." or "This file is too large to preview." when either is true, and "Open this conversation's folder on this machine to preview this file." when the conversation's folder is not open locally.

In Preview, a relative link opens the linked file in a preview tab, the same as a single click in the tree; a link to a folder shows it in Files; a `#heading` link scrolls the Preview to that heading; a link to a missing file is shown dashed with the tooltip "Link target not found: ...", and opens nothing; and web links open in a new browser tab. Relative links only resolve this way when the preview knows the file's folder. They stay plain or inert in a newly added file shown from its patch, in the standalone diff window, in the Docs pane, and in the issue cockpit's PRD tab.

A file that starts with YAML front matter shows it as a short list of keys and values above the content, with `title` and `description` first. Front matter is recognized only when the first line is `---`, a later `---` closes it, and at least one `key: value` line sits between them; a `---` anywhere else is still a horizontal rule. MDX `import` lines and components still show as text.

## When a file changes on disk

If an agent or another program changes a file you have open and you have no unsaved edits, the pane reloads the new content. If you do have unsaved edits, a banner offers **Compare**, **Reload from disk**, **Keep my edits** and **Overwrite**, so nothing is overwritten without your choice. A file that is deleted or renamed on disk is marked as such in its pane.

## Viewers

Files that are not plain text open in a viewer: images, PDF, audio, fonts, large text and CSV files, zip archives, SQLite databases, Office documents, Jupyter notebooks and Mermaid diagrams. Any other binary file offers **Download**.

## File actions

Right-click in the tree, or use the header buttons, to create files and folders, rename, duplicate and delete. Drag rows to move them. A deleted entry goes to the Overdeck trash in `~/.overdeck/trash/` and stays there for 7 days. With the tree focused, `F2` renames the selected row, `Delete` (or `⌘⌫` on macOS) deletes the selection, `Ctrl/Cmd+Z` undoes the last file action and `Ctrl/Cmd+Shift+Z` redoes it.

Drop files from your computer onto a folder to upload them. Each file can be up to 100 MB, and an upload never replaces a file of the same name. You can download a file, or a folder as a `.tar.gz` archive, and drag rows into a conversation composer to reference those files.

## Edit workspaces

The explorer never changes a project's main checkout. When you first save a file or run a file action there, Overdeck creates an **edit workspace**: a git worktree on the branch `scratch/edit-<MMDD-HHMM>`, stored under the project's `workspaces/scratch-edit-*` directory and cut from the remote default branch. Your edit is saved there, and the dock and every code pane on the project switch to the edit workspace.

While a project has an edit workspace that is not merged or closed, later edits reuse it. **New edit workspace**, in the menu you open from the root name at the top of the Files tab, starts a second one and points the dock at it. On an edit workspace, the Files tab shows the same editor bar as a code tab, so **Create PR** and **Discard…** are there even when no file is open. A file that exists only in your main checkout, such as an untracked file or a commit you have not pushed, does not exist in the edit workspace, so the pane reports that the file no longer exists and keeps your text in memory.

## Editing and PRs

Every code tab on a project or an edit workspace has an **editor bar** under its header. On the main checkout it reads "This is the **main checkout**. Start typing and Overdeck moves your edits to a new edit workspace, so main never changes until a PR merges." **Start editing** creates the edit workspace now, and so does your first save. The tab moves to the edit workspace and your cursor, scroll position and focus stay where they were.

On an edit workspace the bar names it and its branch, counts the files you changed with the added and removed lines, and says **Saving…** or **All edits saved**. It offers **Discard…** and **Create PR**.

**Create PR** opens a dialog. It names the edit workspace, its branch and the branch it lands in, and asks for a **Title** and an optional **Description**. The default title is a conventional-commit subject, such as `chore: edit README.md`, because the repository's commit hooks run on this commit and may reject a plain sentence. If a hook refuses the commit, the dialog shows its output so you can fix the title. **What will land** lists every file with its added and removed lines. **How should it land?** has two choices, and both need a project with a GitHub repository:

* **Open a pull request**: you review and merge it yourself. When GitHub reports no conflicts, **Merge** appears in the editor bar; it asks for confirmation while the PR's checks have not all passed. **Open as a draft** opens it as a draft.
* **Send through the pipeline**: creates a GitHub issue and its PR, and Overdeck's review and test agents check it before it merges like any other issue. It needs a project whose tracker is GitHub Issues and that has an issue prefix.

A choice the project cannot use is disabled, with the reason under it. The button is labelled by your choice: **Open pull request** or **Send through the pipeline**.

While the PR is open, the bar follows it. It reads "PR #N is open" with GitHub's reason when the PR cannot merge yet, such as "Required checks or reviews are not met" or "Conflicts with the base branch", and **Merge** stays disabled with that reason. While GitHub is still deciding, the bar checks the PR again every 15 seconds; **Refresh** checks it now. **View on GitHub** opens the PR. If you edit after opening the PR, **Push changes** opens **Commit and push**, which lists the uncommitted files and adds them to the same PR. When GitHub reports no conflicts the bar reads "no conflicts" and **Merge** squash-merges the PR into the default branch. On a repository with required checks, **Merge** stays disabled until those checks pass, so it can take as long as the repository's CI run.

When GitHub allows the merge but the PR's checks have not all passed, for example while CI is still running on a repository without required checks, the bar turns amber and reads "PR #N · no conflicts, but its checks have not all passed." **Merge** is still enabled, but it asks "Merge PR #N before its checks pass?" first, and only **Merge anyway** merges. The bar checks the PR again every 15 seconds and shows the usual "no conflicts" line once the checks pass.

A PR merged or closed on GitHub has its own line in the bar.

After **Merge**, the tab returns to the main checkout and the bar says the PR was merged and the edit workspace and its branch were removed. After **Send through the pipeline** it names the new issue and PR and offers **Open PR**. After **Discard…** it says the edit workspace was discarded. Each note has **Dismiss** and **Close tab**.

**Discard…** lists the changes that will be lost and removes the edit workspace. While its PR is open, **Also close PR** (checked by default) closes the PR too.

A tab whose edit workspace was merged or discarded elsewhere, such as in another tab or from the CLI, says "This edit workspace was merged or discarded." instead of an error. **Open on main** shows the same file on the main checkout, and **Close tab** closes it. A tab on an issue workspace that no longer exists says so the same way.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.