---
url: https://clusto.app/docs/file-previews.md
description: >-
  Preview absolute image, audio, video, PDF, and text paths directly from
  terminals and chats.
---

# File Path Previews

Absolute file paths (POSIX `/a/b.png` or Windows `C:\a\b.png`) that show up in a session terminal or in a chat transcript are
previewable in place: hover a path (or tap it on a phone) and Clusto reads the file
from the node that owns it and shows it in a small card - image, audio, video, or
a PDF, or the head of a text file.

This closes the loop on pasted attachments. Pasting an image into a terminal
uploads it to the daemon and types its path at the prompt
(`/var/lib/clusto/attachments/<session>/paste-1786690246488.png`), and agents print
paths constantly. Before, that path was dead text and checking what it pointed at
meant opening the Files explorer.

## Where it works

| Surface | Trigger |
| --- | --- |
| Session terminal | Paths are underlined on hover; hover previews, click pins the card |
| Agent chat transcript (session chats, first-class Chats, team messages) | Hover a path, or tap it on touch |
| Chat history and the streaming turn alike | Same handles - history is rendered through the same Markdown pipeline |

Markdown links and images that point at a local path are rendered as preview
handles too, so `![Image](/var/lib/clusto/attachments/<id>/paste-1.png)` becomes a
preview handle instead of a broken `<img>` (a daemon-side path is not a URL the
WebView can fetch). Remote `http(s)` images and links keep their normal
behaviour.

## What is previewable

Detection is by extension, matching the Files explorer:

* **Images** - png, jpg/jpeg, gif, webp, avif, bmp, ico, svg
* **Audio** - mp3, wav, ogg/oga, flac, m4a, aac, opus
* **Video** - mp4, m4v, webm, mov, mkv, ogv
* **PDF** - pdf
* **Text and code** - md, txt, log, json, yaml/yml, toml, rs, ts/tsx, js/jsx, vue,
  py, go, sh, sql, and the rest of the usual set (first 60 lines are shown)

Anything else - an unknown extension, an extensionless path (other than
`Makefile` and `Dockerfile`), a binary, a socket - is left as plain text, so ordinary prose does not fill up with false handles. Paths inside code
spans and fenced blocks are never turned into handles, and the path component of
a URL is ignored.

Quoted paths containing spaces (`"/home/dan/my notes/todo.md"`, the form the
terminal paste flow types) are matched whole.

## Where the bytes come from

The card reads through the same `FsReadText` / `FsReadBinary` wire messages the
Files explorer uses, addressed to the node that owns the session. A chat that ran
on another node previews its files over cluster forwarding exactly like a local
one, and the store's cache means hovering the same path twice costs nothing.

Reads are subject to the daemon's own size cap; a file over the cap reports the
daemon's error in the card rather than silently showing nothing.

## Interaction details

* Hover opens after a short delay, so scanning a transcript full of paths does
  not flash cards
* The card stays open while the pointer is over it, closes shortly after leaving
* Click (desktop) or tap (touch) pins the card. Pinned cards have a visible close
  button on desktop; on touch the card opens as a centred sheet with a backdrop
* When a terminal path wraps across rows, every visible row segment opens the
  same complete path, so the preview remains usable on narrow mobile screens
* Click or tap outside the card to close either a pinned card or an unpinned
  hover preview. `Escape` closes a pinned card; scrolling closes an unpinned one
* The card measures its rendered content and opens below or above the path when
  it fits. On shorter viewports it stays within the screen bounds and scales
  image or video content so the preview remains visible; long text scrolls
  inside the card
* The card has an **Open in tab** button (Terminals and Chats views) that opens the
  file as an editor tab beside the focused terminal or chat. PDFs have no such
  button because the card renders them itself
* Path handles are keyboard reachable - `Tab` to one, `Enter` or `Space` opens it

## Related

* [File Explorer](/file-explorer) - clipboard and drag-and-drop attachments for
  terminal prompts, and where pasted files land
* [Files Explorer](/files-view) - full-filesystem browsing and the `Fs*` wire
  protocol the preview reuses
* [Chats](/chats#send-files-with-a-message) - files sent with a message show in
  the message bubble and open in a preview dialog with a Download button
* [Chats](/chats) - chat attachments, which are linked context rather than
  printed paths
