Skip to main content

File Viewer

The file panel: read one file as source, rendered Markdown or HTML, inline media, or a diff, shown as a dialog, a grid panel, or a dock chip, and edit Markdown with the built-in Markdown editor plugin.

Updated
Reviewed

What the File Viewer is

The File Viewer is Daintree's file panel kind: a read-only view of one file. It renders source with syntax highlighting, Markdown and HTML as documents, images, video, audio and PDFs inline, and, when the file has local changes, its working-tree diff. It exists so you can confirm what an agent claims to have done without switching to an editor, so it is read-only by design. The one exception is Markdown, which the built-in Markdown editor plugin can make editable once you turn it on (see Editing Markdown).

To walk a whole directory rather than read one file, use the File Browser, which is a separate panel kind.

Opening a file

WhereWhat you get
Click a file path in terminal outputA file viewer dialog, scrolled to the line if the path carried one (src/index.ts:42:7)
Click a changed file in the Review Hub or the worktree sidebarThe file's diff (see Review Hub)
File Browser, Enter or double-click a rowThe file as its own grid panel
A worktree card's plan badge, or its menu → Linked work → View planThe worktree's plan file as a dialog, rendered (see Plan files)
The panel launcherAn empty file panel with a search box (see below). Matches on file, md, markdown, readme, docs, spec, document, viewer
An agent or pluginA dialog (ephemeral) or a grid panel (persistent), depending on which action it dispatches
Tip
Command Control Control +click a file path in a terminal opens it in your external editor instead of the viewer. Clicking a directory in terminal output opens the File Browser revealed at that folder.

A file panel opened with no file shows Open a file and a picker: type into Search files and it searches the project or worktree root, listing up to 50 matches. Pick one and the panel binds to it.

Dialog, grid, dock

The File Viewer supports three presentations, and the File Viewer is the kind that uses all three hardest.

  • Dialog: what a terminal file link gives you. A dialog is deliberately ephemeral: it never counts toward the panel limit and is never restored on restart. A new dialog replaces the one on screen; the exception is a diff opened from a Review Hub dialog, which layers over the hub and leaves it underneath.
  • Grid: a persistent panel alongside your terminals, saved with the layout. Any dialog can become one: the topmost dialog carries an Open as panel button in its header that promotes it into the grid.
  • Dock: the compact strip. File panels are dockable, and they keep both scroll position and view mode across the move, so docking a file mid-read and pulling it back does not reset it. A docked single file panel shows the inline Move to grid button in its header.

Closing a file panel, or moving it to the dock, returns focus to whatever you were last reading rather than to the first terminal in the grid: the viewer is a reading surface, and so is what you were doing before it.

Long files scroll inside the panel's own pane rather than growing the app layout, and the dialog scrolls in both Source and Rendered mode.

Open as panel moves this file into the grid

Source, Rendered, Diff, Edit

The toolbar's left segment is a toggle labeled Source, Rendered, Diff and Edit. It only appears when there is more than one mode to choose, and the optional modes are independent capabilities:

  • Rendered exists for Markdown and HTML only. Other text files use Source; supported media uses its own preview.
  • Diff appears only while the file has a local change in a worktree Daintree knows about. If the change is committed or reverted while you are looking, the segment disappears and the panel falls back to Source.
  • Edit appears for a Markdown file in a grid or docked panel once the Markdown editor plugin is on. See Editing Markdown.

Source mode carries a metadata bar above the content reading line count, byte size and encoding: 142 lines · 4.2 KB · UTF-8. Rendered mode omits it, because the document is the view.

Markdown

Markdown files get the full Source / Rendered pair. Rendered mode lays the document out with Daintree’s prose styling; Source mode shows the raw text with syntax highlighting. The Text size toolbar button, shown in Rendered mode, opens a stepper with Decrease text size, Increase text size and Reset, running from 11 to 30 px (14 px by default). This is one app-wide reading-size preference shared with Markdown in the File Browser; it does not change source-code font size or whole-window zoom.

  • Wrap long lines: a toolbar toggle, offered in Markdown source mode and in Edit mode. The choice is a preference, so it holds across files and panels.
  • Mermaid diagrams: a mermaid code block renders as a diagram, colored from the current theme. Until the diagram is ready, and for good if it doesn't parse, the block shows its source instead, so it is never blank. Mermaid loads only when a document actually contains a diagram, and only diagrams near the visible part of the document are drawn. A diagram whose source would make Mermaid fetch something (an image or icon URL, embedded HTML, or CSS that loads) stays as source, as does one over 50,000 characters. The same rendering applies in the File Browser and in the Diff Viewer's rendered Markdown diff.
  • Local images referenced by a rendered document are re-requested when they change on disk. A Markdown file whose embedded diagram was regenerated shows the new diagram without you reopening the panel: the file's own bytes never changed, which is exactly the case a naive freshness check misses.

Plan files

A worktree with a TODO.md, PLAN.md, plan.md or TASKS.md in its root carries a plan badge on its card, labeled with the file's own name. As of v0.34 that badge, and the card menu's Linked work → View plan, open the file through the ordinary File Viewer instead of a dialog built only for plans.

Which means a plan gets everything on this page. It opens in Rendered mode, because a plan is a document; Source is one click away on the toolbar; and Open as panel promotes the dialog into the grid, so the plan can sit beside the agent working through it instead of being dismissed to get back to the terminal. Find, go-to-line, the path pill, reveal and Open in editor come with it.

The panel is bound to that card's worktree rather than to whichever worktree happens to be selected, and the bare filename is resolved against that worktree's own root. The binding decides both the pane's read root and, on promotion, which grid bucket the panel lands in. The badge itself acts on the active card; from an inactive one it reads as disabled, and the card menu is the route.

Editing Markdown

Daintree ships a built-in plugin, Markdown editor, that makes a Markdown file's source editable in place: for the plans, specs and notes your agents write and you want to adjust without leaving the panel. It is off until you turn it on, and it keeps the viewer itself read-only: every write goes through the plugin host's permission-checked, audited file access, confined to the project and its worktrees.

Turning it on

While the plugin is off, a strip above a Markdown file reads Enable Markdown editor to edit this file, with Enable and edit. That button turns the plugin on and opens the file in Edit mode. From then on, Edit is a segment of the mode toggle. Dismiss the strip with its close button if you don't want it. You can turn the plugin off again in Settings > Plugins; Edit disappears at once, and a panel left in Edit mode falls back to Source.

Edit is offered for .md, .markdown and .mkd files (never .mdx) inside an open project or one of its worktrees, read as text and under 2 MiB. It appears in the File Browser's viewer and in File Viewer panels in the grid or the dock. The File Viewer dialog stays read-only: use Open as panel first. The editor also refuses a file that isn't valid UTF-8, or that is a symlink, and says why.

Saving

Press Command-S Control-S Control-S with focus in the editor, or use the save button in the editor's status bar, which reads Saved, Unsaved changes or Saving…. The shortcut is consumed by the editor, so it never reaches a terminal. A save writes exactly what is in the editor, with the file's byte-order mark and dominant line ending kept: nothing is reformatted, and a save with no edits writes nothing. A file that mixes LF and CRLF line endings is the one exception; the status bar warns that saving will normalize every line to one of them.

Inside the editor, Enter continues a list, task list or quote, Command-F Control-F Control-F opens find, and Command-L Control-L Control-L goes to a line.

When the file changes underneath you

Agents write the same files you edit, so every save is checked against the version you loaded. If the file changes on disk while you have no unsaved edits, the editor simply reloads it. If you do have unsaved edits, a banner reads File changed on disk: your draft is kept and saving is held. It offers three ways out and no automatic merge:

  • Compare shows your draft against the disk version.
  • Load disk version replaces your edits, after a Discard changes confirmation.
  • Save draft as… writes your draft to a new Markdown file in the same project or worktree.

If the file is deleted or moved, or its worktree removed, the editor says File isn't available and keeps your draft until you save it elsewhere or discard it.

Unsaved drafts

A draft belongs to the document, not the mode: switching to Source, Rendered or Diff keeps it, Rendered previews it, and the panel shows an unsaved-changes dot in every mode. Closing a panel with unsaved edits, or moving to another file in the File Browser, asks Save changes to 'file'? with Save, Discard changes and Cancel. A panel that is only hidden for a moment (a neighbor maximized, another dock tab chosen, a background project's view released) has not been closed, and never asks.

Drafts are also stored for recovery, outside the repository, about a second after you stop typing, and straight away when the window is hidden or the panel closes. Markdown: Recover drafts… in the command palette lists drafts whose panel is gone and reopens one in Edit mode in its own project and worktree. A recovered draft is never saved automatically; it is checked against the file on disk first, and opens in the conflict state if the file has changed since.

Keep an unsaved draft while another process changes the file

HTML

HTML files also get a Rendered mode, served into a sandboxed iframe over a nonce'd internal preview URL that the main process mints only when a read explicitly asks for it. A generated report, a coverage summary, a built page: an agent can produce one and you can look at it without giving the file the run of the app.

In Rendered mode the toolbar's last button changes from Open in editor to Open in browser, which hands the file to your real browser when the sandbox is too tight for what the page needs.

Note
The preview frame is served with a matching cross-origin embedder policy header. Without it the frame loaded but painted nothing: a blank Rendered mode, fixed in v0.27.1. If you are on an older build and HTML previews render empty, that is the bug.

Images, video, audio and PDFs

Media does not go through the text read path at all. Images, video, audio and PDFs are served to the renderer over Daintree's own internal file protocols, which is why they are not subject to the 512 KiB text limit: an image larger than that displays rather than failing.

KindPlays or rendersRecognized, but refused with a reason
Imagespng, apng, jpg, jpeg, gif, webp, avif, bmp, icoNone
SVGRead as text, sanitized, then inlinedContent the sanitizer rejects
Videomp4, m4v, webm, ogv, played inlinemov, mkv, avi, wmv
Audiomp3, wav, flac, ogg, oga, opus, m4a, aac, played inlinewma, aiff, aif, mid, midi, amr
PDFFramed into Chromium's built-in viewer, with its own page and zoom controlsNone

The refused formats are listed by name on purpose. Chromium cannot demux them even when the codec inside is one it knows, so the viewer says "Can't play this video format" rather than dropping through to the text path and claiming the file is binary or oversized.

Refresh re-requests the media surface, so a video an agent just re-encoded plays the new file. Background refreshes deliberately do not: a change tick from an unrelated write must not restart playback or throw away a PDF reader's page and zoom.

Diffs

When the file has a local change, the Diff segment opens its working-tree diff without leaving the panel: you do not have to go back to the Review Hub to see what moved. If the file changes underneath a loaded diff, an inline banner reads "File changed since this diff loaded" with a Refresh action.

The multi-file review surface (the changed-file sidebar, per-file viewed markers, full-file toggle, image compare) is a separate panel kind. See Diff Workspace.

The toolbar

ControlWhat it does
Copy file contentsCopies the loaded raw text, including while Markdown/HTML is rendered or a diff is displayed. Absent for media, unsupported files and failed reads.
Source / Rendered / DiffView mode. Shown only when more than one mode applies.
Path pillShows the path relative to the project or worktree root, middle-truncated to fit while keeping the file name. Click it to copy the absolute path.
Text sizeRendered Markdown only. See Markdown.
Wrap long linesMarkdown source mode, Edit mode, and Diff mode. Diff wrapping defaults on for prose and off for code until you choose an override.
RefreshRe-reads the file, or re-fetches the diff, depending on which is on screen.
Show in file browserOpens the File Browser revealed at this file. Offered only when a live worktree contains it: the browser is scoped to a folder, so there is nothing to open for a file outside every worktree.
Reveal in Finder / Show in Explorer / Show in folderThe system file manager, named for your platform. Always offered, including for a file the viewer cannot render. That is exactly when it matters most.
Open in editor or Open in browserYour external editor, or your real browser when you are looking at rendered HTML.

In a narrow panel the secondary actions fold into a More actions menu so the path pill keeps the file's name; Refresh stays out, since its spinner is the panel's only progress indicator.

When one of the external actions fails, an inline banner names the target that failed ("Couldn't open in editor", "Couldn't reveal in Finder") with a Retry that re-runs only that one.

Files stay open as grid panels beside the browser and agent

Keyboard

ShortcutAction
Command-F Control-F Control-F Find in the focused panel. In a file panel showing source, this opens the viewer's own find bar.
Command-L Control-L Control-L Go to line, in source mode.
EscapeCloses the dialog presentation. A grid or docked panel has nothing for Escape to close. Use the panel's own close control.

Command-F Control-F Control-F is one global binding routed to whichever panel has focus, so the same key finds in a terminal's scrollback, in a file, or in a web page depending on where you are.

Staying current with what agents write

Agents rewrite files while you are watching them, and the panel stays focused the whole time, so "refresh on focus" would never fire. The viewer instead re-reads on a live change signal, and where that signal comes from depends on where the file lives:

  • Inside a worktree: the worktree's own filesystem watcher and its git-status poll, whichever moved most recently. Two signals rather than one, because git status never moves for a write into a gitignored folder.
  • Outside every worktree: scratch folders, projects with no repository, unregistered repos. These previously showed whatever was on disk when the panel opened. They now get their own live signal, polled from the main process and only while the view is visible, so a file the panel is showing stays current wherever it sits.
  • Returning to a project: a project view that was cached while you worked elsewhere re-reads its file panels on reveal, because everything that happened while it sat cached is precisely what the panel could not otherwise see.

Background re-reads are silent: no loading skeleton flashes, and a transient failure (catching a file mid-save) keeps the last good content rather than blanking the panel. A file that is genuinely gone (deleted, or permissions revoked) surfaces the error rather than showing stale text forever.

With focus in the read-only viewer body, Command-A Control-A Control-A selects that viewer’s content rather than the surrounding application. Copy file contents copies the loaded raw text without rendered formatting or diff markers.

Limits and error states

Text reads are capped at 524,288 bytes (512 KiB). The cap is not configurable, and it applies only to the text path: media served over the internal protocols is unaffected.

When a file can't be shown, the panel keeps the file's name in the toolbar and says what happened and what to do instead, with one way forward:

StateThe panel saysOffers
BinaryBinary file: it can't be shown as text.Reveal
Too largeToo large to preview: open it outside Daintree instead.Open in editor, Retry
Git LFS pointerGit LFS pointer: run git lfs pull, then refresh.Retry
MissingThis file was deletedRetry
PermissionsNo permission to read this fileReveal, Retry
Outside the rootOutside this worktreeReveal, Retry
A folderThis is a folderReveal
Invalid pathCouldn't read this file: its path isn't valid.Reveal, Retry
Unsupported mediaCan't play this format, naming the formats that do workOpen in the default app or Reveal
SVG the sanitizer rejectsCan't preview this SVG, with the reasonOpen in editor, Retry
Media, image or PDF that fails to loadWhat failed, such as This PDF couldn't be displayedOpen in the default app or Reveal, Retry

Retry is left off where it could never succeed (a binary file, a folder, an unsupported format). The toolbar's reveal and open actions stay available in every state.