All pages

Docs · Right-sidebar surfaces

Files

Availability: macOS · Linux · Windows (the GTK sidebar's Files pane) · cloud workspace.

The Files tab in the right sidebar is a directory tree rooted at the active project's folder. With no project bound, it falls back to the focused pane's current working directory. Use it to browse, preview, and edit files without leaving TRMNLY — and to pin files into the agent's context.

Each window keeps its own tree, bound to that window's project. Switching projects re-roots the tree and resets expansion and selection.

Browsing

  • Click a folder's chevron to expand it; folders sort first, then files (case-insensitive). Symlinks are badged with a link arrow.
  • The header shows the project name, or the root folder's name, or No folder when nothing is bound.
  • Directories are capped at 2000 entries per level; overflow shows a truncation notice.
  • Toggle Show/hide dotfiles (eye icon) to reveal .-prefixed files.
  • Refresh (⟳) reloads every expanded directory.
  • Jump to focused cwd (scope icon) re-roots the tree at the active pane's current directory instead of the project root.
  • Folders that fail to list — permission errors, or symlinks that resolve outside the project root — show an inline error row instead of expanding.

Expanded folders are watched live: when files appear, change, or vanish on disk — a build, a git checkout, the agent writing files — the tree updates on its own, no Refresh needed.

Preview

Selecting a file loads it in the preview pane:

Type Behavior
Text (≤ 256 KB) Syntax-highlighted by file extension. Larger files preview truncated with a …(truncated) marker.
Markdown (.md, .markdown, .mdown, .mkd) Rendered — headings, emphasis, code, lists, quotes — with a Source toggle to see it as typed.
Image (≤ 4 MB) Scrollable image preview. Larger images show as a binary file.
PDF Paged preview.
Binary File size plus a document icon.

Nothing in a file is ever treated as markup by the preview itself: a file containing <b> shows those three characters.

On Linux and Windows

The GTK sidebar's Files pane previews on activate — double-click, or Enter on the selected row — rather than on selection, and shows the same three things macOS does: text (bounded the same way, with a truncation line), markdown rendered with the same Source toggle, and binary named by size rather than dumped.

PDFs are not previewed there. macOS renders them with PDFKit, which is a system framework; the equivalent on Linux is poppler, a dependency the tarball and flatpak would then have to carry for one preview. The pane says so, with the file's size, instead of pretending the file is empty.

Editing

Click the pencil to edit inline. The editor shares the preview's typography and syntax coloring.

  • Unsaved changes flag with a • next to the filename.
  • ⌘S saves (atomic UTF-8 write); Esc or Cancel discards (with a confirmation if there are unsaved edits).
  • Truncated files can't be edited — saving would drop the tail.

Actions

From the action bar between the tree and the preview, and the right-click menu:

Action Effect
Pin to agent (pin icon) Add the file as a sticky reference in the agent's context (per project). See Agent.
Edit in TRMNLY (pencil) Enter inline edit mode.
Open With Launch in an external editor (VS Code, Cursor, Zed, Sublime, BBEdit, Nova, Xcode…). Only installed editors appear.
Reveal in Finder Show the file in Finder.
cd here Send cd <path> to the focused pane (directories).

A folder on another machine

The host button in the action row above the tree (an external-drive glyph, to the right of Jump to focused cwd) lists the SSH hosts saved in the Conn sidebar; it says No SSH hosts saved in Conn when there are none. Pick a host, type a path as that machine spells it, and the tree re-roots there — any readable folder, not only a worktree made with worktree_create { host } (Worktrees). A blue strip under the row reads <host> · refreshes when you ask, not live, and the menu gains Back to this machine.

Preview and inline editing work as they do locally, with three differences:

  • No live watcher. There are no file-system events from another machine, so the tree changes only when you press Refresh.
  • Saves are conflict-checked. A stamp is taken when the editor opens; if the file changed over there since, the write is refused and your buffer stays exactly as typed. A dropped connection is reported as one, with nothing half-written.
  • Reveal in Finder, Open With and cd here are off while remote — each would act on this machine.

Pinning vs. the agent's own file tools

Pinning a file from the Files tab injects its contents into the agent's system prompt as a "pinned files" block (up to 24 KB per file), so the agent always sees it without having to read it each turn. This is separate from the agent's read_file / edit_file tools — pin the handful of files you want the agent to keep in mind; let it read the rest on demand.

See Projects for how the tree binds to projects and worktrees, and Agent for how pinned files feed context.