What we want
An agent session names files constantly: "I wrote the parser to internal/wire/binary.go". Reading that file today means leaving the terminal, and on a phone over the relay there is no window to leave to. The feature: a real path in terminal output underlines on hover, and clicking it opens the file in a viewer over the session, on loopback and over the relay alike.
The full design is in docs/superpowers/specs/2026-08-11-file-peek-design.md, and the protocol contract is in spec/protocol.md. The design deliberately splits into three shippable phases, riskiest first.
Where it stands
Phase 1 shipped in #55: the wire and the daemon. stat/stats, read/file/eof, cancel, binary frame 0x02 for file chunks, path resolution against the session's live cwd, content sniffing, the 32 KiB chunk pump, the caps, and the conformance cases in testdata/wire/control.json. All of it is live daemon-side and typed in web/src/client/protocol.ts.
Nothing consumes it. FlueClient implements none of the file verbs, there is no link provider, no viewer, no web/src/files/. #74 (the agent sessions browser) notes the same: the daemon plumbing is complete and has no consumer.
What remains
Two phases, one sub-issue each:
- Phase 2, clicking and reading. Client methods for
stat/read/cancel, the emulator-agnostic detectLinks seam, the xterm link provider with wrapped-line handling, hover verification, and a plain windowed text viewer. The feature works end to end here at zero bundle cost. This phase is the honest test of whether clicking a path is the right interaction, and it lands before a byte of highlighter ships.
- Phase 3, polish. Shiki highlighting on the JavaScript regex engine (the CSP stays untouched), image rendering via
data: URLs, and an in-memory LRU so reopening a file costs nothing.
Boundaries
It reads. It does not write, rename, delete, diff, search inside a file, or download one. Everything it does is something the session's own shell could already do with cat, so it grants no authority that does not already exist.
What we want
An agent session names files constantly: "I wrote the parser to
internal/wire/binary.go". Reading that file today means leaving the terminal, and on a phone over the relay there is no window to leave to. The feature: a real path in terminal output underlines on hover, and clicking it opens the file in a viewer over the session, on loopback and over the relay alike.The full design is in
docs/superpowers/specs/2026-08-11-file-peek-design.md, and the protocol contract is inspec/protocol.md. The design deliberately splits into three shippable phases, riskiest first.Where it stands
Phase 1 shipped in #55: the wire and the daemon.
stat/stats,read/file/eof,cancel, binary frame0x02for file chunks, path resolution against the session's live cwd, content sniffing, the 32 KiB chunk pump, the caps, and the conformance cases intestdata/wire/control.json. All of it is live daemon-side and typed inweb/src/client/protocol.ts.Nothing consumes it.
FlueClientimplements none of the file verbs, there is no link provider, no viewer, noweb/src/files/. #74 (the agent sessions browser) notes the same: the daemon plumbing is complete and has no consumer.What remains
Two phases, one sub-issue each:
stat/read/cancel, the emulator-agnosticdetectLinksseam, the xterm link provider with wrapped-line handling, hover verification, and a plain windowed text viewer. The feature works end to end here at zero bundle cost. This phase is the honest test of whether clicking a path is the right interaction, and it lands before a byte of highlighter ships.data:URLs, and an in-memory LRU so reopening a file costs nothing.Boundaries
It reads. It does not write, rename, delete, diff, search inside a file, or download one. Everything it does is something the session's own shell could already do with
cat, so it grants no authority that does not already exist.