Studio Overview

The Studio is fcheap's terminal user interface (TUI) for browsing and managing stashes interactively.

Launching

fcheap studio

The Studio requires an interactive terminal. It checks term.IsTerminal() on both stdin and stdout before launching. If run in a non-interactive context (piped input/output), it exits with an error message suggesting CLI commands instead.

Views

List

The default view: a themed table of stashes (ID, tool, file count, size, relative age) with colored chips — zst/gz for compressed stashes and a ⚠ secrets chip when a stash contains likely credentials. Newest first. j/k to move, Enter to open detail.

Detail

A grouped, color-coded provenance pane with IDENTITY (id, name), PROVENANCE (source, tool, created with relative + absolute time, bundle), CONTENT (files, size, hash, tags, secrets warning), and STORAGE (compression with the space-saved ratio, and indexed status). A scrollable file tree sits beside a live preview of the selected file's content (Tab cycles focus). Compressed stashes show a "restore to view" placeholder.

Search

Press / to focus a working query input, type, and Enter to run a per-file search across all indexed stashes. Results show stash › file with a relevance-colored score (green → cyan → dim), and the preview pane shows the hit. Tab cycles query ↔ results ↔ preview. Press m (from the results/preview pane) to cycle the search mode — auto → keyword → semantic → hybrid — and re-run; the query panel shows the requested mode and the results panel shows the mode actually used (semantic/hybrid require a configured embedder).

Timeline (vidtrace bundles)

Press t on a vidtrace bundle to see its evidence timeline — each entry's timestamp, frame, OCR text, and transcript — in a scrollable, colored panel.

Run view (Cairntrace and Glyphrun bundles)

On a stash whose bundle type is cairntrace-run or glyphrun-run, press v for a run summary in a scrollable panel: status, spec name, run ID, environment and backend, start time and duration, exit code, step count, outcome totals (passed / failed / other), whether report.html exists, and up to 50 outcomes with their status. Reads are bounded to run.json and report.json (report.json fills fields run.json lacks) and never touch evidence files.

Press V to restore the stash into a fresh temp directory (works for compressed stashes), verify it, and print the exact path of report.html in the footer and the panel; open that file in a browser. Studio does not launch a browser itself. A compressed stash needs V; v reads in place and asks you to restore first.

Diff

Press x to diff a stash against a directory. The prompt is pre-filled with the stash's source path (just press Enter), or type any path. Results are colored: green + (only in stash), red - (only in target), yellow ~ (changed), plus an unchanged count — comparison is by content hash.

Status & Help

s shows index health at a glance: stash directory, count, total size, how many stashes are indexed/compressed, whether the SQLite metadata index and veclite search index exist, and vecgrep availability. ? shows the keybinding reference.

Keybindings

Key	Action
j / k (↓/↑)	Move cursor / scroll
Enter / l	Open detail
Esc / h	Back
Tab	Cycle pane focus
/	Search
r	Restore to a temp dir (with hash verification)
c	Compress (zstd)
a	Analyze / index for search
x	Diff against a directory
t	vidtrace timeline (bundles only)
v / V	Run summary / restore and print the report.html path (cairntrace-run, glyphrun-run bundles only)
d	Drop (with y/n confirm) — from the list or the files pane
f	Filter the list live by name / tool / tag (enter keeps it, esc clears)
o / O	Cycle the list sort (age / name / tool / files / size) / reverse direction (list view)
s	Status
g	Refresh list (list view)
?	Help
q	Quit · Ctrl+C force quit

Enter/l (open) and g (refresh) apply in the list view. In a focused preview pane, j/k scroll a line, and d/u, PgDn/PgUp, and Ctrl+D/Ctrl+U half-page — there, d pages down rather than dropping (drop a stash from the list or the files pane).

Async operations (loading, search, restore, drop, compress) show an animated spinner while in flight. Indexing (a) streams per-file progress into an animated progress bar (indexing 42/805). Destructive d requires a y/n confirm in the footer.

Tech Stack

• Bubbletea v2 -- TUI framework (charm.land/bubbletea/v2)
• Lipgloss v2 -- styling (charm.land/lipgloss/v2)
• Bubbles v2 -- textinput, viewport, spinner, progress (charm.land/bubbles/v2)

Layout is responsive: side-by-side panels at ≥96 columns, stacked below. Panels expand to fill the full terminal height, with the footer pinned to the bottom.