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.
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
| Where | What you get |
|---|---|
| Click a file path in terminal output | A 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 sidebar | The file's diff (see Review Hub) |
| File Browser, Enter or double-click a row | The file as its own grid panel |
| A worktree card's plan badge, or its menu → Linked work → View plan | The worktree's plan file as a dialog, rendered (see Plan files) |
| The panel launcher | An empty file panel with a search box (see below). Matches on file, md, markdown, readme, docs, spec, document, viewer |
| An agent or plugin | A dialog (ephemeral) or a grid panel (persistent), depending on which action it dispatches |
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.
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
mermaidcode 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.
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.
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.
| Kind | Plays or renders | Recognized, but refused with a reason |
|---|---|---|
| Images | png, apng, jpg, jpeg, gif, webp, avif, bmp, ico | None |
| SVG | Read as text, sanitized, then inlined | Content the sanitizer rejects |
| Video | mp4, m4v, webm, ogv, played inline | mov, mkv, avi, wmv |
| Audio | mp3, wav, flac, ogg, oga, opus, m4a, aac, played inline | wma, aiff, aif, mid, midi, amr |
| Framed into Chromium's built-in viewer, with its own page and zoom controls | None |
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
| Control | What it does |
|---|---|
| Copy file contents | Copies 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 / Diff | View mode. Shown only when more than one mode applies. |
| Path pill | Shows 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 size | Rendered Markdown only. See Markdown. |
| Wrap long lines | Markdown source mode, Edit mode, and Diff mode. Diff wrapping defaults on for prose and off for code until you choose an override. |
| Refresh | Re-reads the file, or re-fetches the diff, depending on which is on screen. |
| Show in file browser | Opens 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 folder | The 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 browser | Your 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.
Keyboard
| Shortcut | Action |
|---|---|
| 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. |
| Escape | Closes 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:
| State | The panel says | Offers |
|---|---|---|
| Binary | Binary file: it can't be shown as text. | Reveal |
| Too large | Too large to preview: open it outside Daintree instead. | Open in editor, Retry |
| Git LFS pointer | Git LFS pointer: run git lfs pull, then refresh. | Retry |
| Missing | This file was deleted | Retry |
| Permissions | No permission to read this file | Reveal, Retry |
| Outside the root | Outside this worktree | Reveal, Retry |
| A folder | This is a folder | Reveal |
| Invalid path | Couldn't read this file: its path isn't valid. | Reveal, Retry |
| Unsupported media | Can't play this format, naming the formats that do work | Open in the default app or Reveal |
| SVG the sanitizer rejects | Can't preview this SVG, with the reason | Open in editor, Retry |
| Media, image or PDF that fails to load | What failed, such as This PDF couldn't be displayed | Open 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.