The Files card

The Files card is a file browser and editor for the workspace, running against the host’s filesystem.

It exists for the small interventions: fix a typo the agent introduced, read a config it keeps getting wrong, check what a generated file actually contains, without switching to a terminal card and without being at the machine.

What it does

Browse the workspace tree, with hidden files on or off.
Open files in tabs. A path an agent mentions in its terminal (docs/PLAN.md, Foo.swift:42) is one click away and opens at that line.
Edit in a syntax-highlighted editor. Unsaved work is a draft, marked with a dot on the tab.
Star files you keep coming back to, and filter the tree down to starred files or to files with drafts.
Search for a file by name.
Create files and folders, delete entries, and Open in Finder on macOS hosts when you happen to be at the machine.

Tabs, drafts and stars live on the host, not in the app. Open three files on the Mac, pick up your phone, and the same three tabs are there — with your unsaved edits.

It keeps up with the agent

The card watches the folders it is showing. When the agent, a terminal, or anything else on that machine creates, renames or deletes a file in one of them, it appears in the tree within a second or two. No refresh button, no wondering whether what you see is current.

The file you have open is checked the same way, but cheaply: the card asks “has this changed since version X?”, and an unchanged file answers in a few hundred bytes instead of resending itself.

When you and the agent edit the same file

The draft remembers which version of the file it started from. If the file changed on disk before you save, the card stops and shows you a diff of the host’s version against yours, with two explicit choices:

Keep my draft (overwrite host)
Take host version (discard my draft)

Nothing is decided for you, and nothing is merged behind your back.

Speed

The card was rebuilt around the fact that its host may be a VPS on the other side of a relay:

Opening a file is one round trip instead of four.
Directory listings and file contents are fetched conditionally: unchanged means “not modified” instead of a resend.
Expanded folders load in parallel, and only the folders that actually changed reload.
File search skips the places nobody means (.git, node_modules, DerivedData, .build, Pods, __pycache__), and stops after about a second rather than walking a monorepo to the end.
Images over ~1 MB are scaled down on the host and arrive as a preview, with the original one button away, so a 12 MB screenshot no longer blocks the rest of your board.
Typing in the editor no longer makes every other device reload its tree.

Where it fits

Use it for the quick, surgical edit — the typo, the config value, the file you want to read before you answer the agent. Structural work belongs in the card next to it: describing the refactor to an agent that has the whole repository in its head beats doing it by hand on a phone.

Details

All paths are resolved inside the workspace root, so the card always shows the project you are in.
Saving writes through a temporary file and an atomic replace, so a failed save cannot leave a half-written file.
Drafts live in the host’s state database with the file version they started from, which is what makes both cross-device editing and the conflict check possible.
The host watches at most 48 directories per connection, polling their modification times about once a second, and pushes only the paths that changed. Content changes inside the file you have open are caught by the versioned refresh instead.
Image previews cap at 2048 px on the long edge; GIFs are always sent as-is so they keep animating.
Files are classified from their first few kilobytes: text is editable, images preview, anything else is listed but not opened.
File contents travel over the same connection as everything else; there is no separate file service and no port to open.
Live updates and conditional fetches need host and app on protocol 28 or newer, which is anything current.