Monitor currently has no browser or graphical interface. Its user experience is a terminal command that prints status while it records screenshots and summaries. This document defines that terminal UX now and the standards for any future rendered interface.
Monitor should feel quiet, utilitarian, and transparent. The user should immediately understand whether monitoring is running, how often screenshots are being captured, where artifacts are being saved, and what the current summary says.
The interface should never feel stealthy, decorative, or ambiguous about sensitive screenshot capture. If a future UI is added, it should be work-focused and dense enough for reviewing timelines without becoming visually noisy.
The CLI should render a concise live dashboard while a run is active. When stdout is an interactive terminal, it may use ANSI color, bold labels, and screen refreshes. When stdout is redirected, when TERM=dumb, or when NO_COLOR is set, output should degrade to readable plain text blocks.
The dashboard should include:
- screenshot count
- bounded progress such as
1/10 - unbounded progress such as
1/∞ - percentage complete, using
∞%for unbounded runs - a stable progress bar
- capture interval
- time to the next screenshot
- estimated time to completion, using
∞for unbounded runs - analyzer name, initially
codex - output directory
- latest screenshot path
- latest per-screenshot analysis path
- latest per-screenshot analysis excerpt
- current run-level summary excerpt
- any analyzer or capture error for the latest cycle
The dashboard should avoid dumping every full analysis into the terminal. Show short excerpts for the latest analysis and current summary, and keep the full Markdown artifacts in the run directory.
After a bounded invocation finishes, the CLI should print the complete final detailed current-summary.md once. That final print is separate from the live dashboard, so the running view stays compact while the completed run still leaves a readable narrative in terminal scrollback.
Run artifacts should be easy to inspect with ordinary terminal tools.
Per-screenshot summaries should be timestamped and detailed enough to reconstruct the visible desktop state without reopening the screenshot. current-summary.md should read like the best current narrative of the run so far and preserve concrete visible details across screenshots. The aggregate activity-summary.md should remain a deterministic rollup and timeline, but it should include fuller latest-summary and current-summary detail than the live dashboard. It should not become a raw log dump.
index.tsv should be machine-readable enough for later scripts while still understandable in a text editor.
The default run is foreground and can be stopped with Ctrl-C.
The first test command should be safe and bounded: bash src/monitor.sh --once.
The CLI should make sensitive output paths obvious. It should not hide where screenshots are stored.
Error states should be explicit. If screenshot capture fails, the terminal and run artifacts should show that no usable screenshot was produced. If Codex analysis fails, the terminal should say that the screenshot was saved and an error summary was recorded.
If Monitor later adds a browser or Electron UI, prefer a restrained dashboard-like interface:
- neutral page background
- high-contrast readable text
- clear timestamp hierarchy
- compact timeline rows
- visible controls for retention, deletion, and analyzer choice
- no ornamental gradients, bokeh, or marketing-style hero sections
Cards should be used only for repeated run or timeline items, not as nested page sections. Responsive layouts must keep timestamps, summaries, and controls readable on desktop and mobile.
Any future ExecPlan that creates, changes, or can indirectly affect a browser UI, Electron UI, rendered documentation surface, empty/loading/error state, layout, copy, navigation, or frontend data presentation must include a final UI/UX review pass before the work is called complete.
The review must inspect screenshots or recordings captured after implementation and compare them to before evidence when an existing surface changed. Cover desktop and mobile viewports, plus tablet or narrow-desktop widths when layout behavior changes at intermediate sizes.
Look for unclear primary actions, cramped spacing, text overflow, clipped controls, inaccessible contrast, missing focus states, undersized touch targets, confusing empty/loading/error states, inconsistent styling, layout breakage, and unnecessary workflow friction. Make in-scope corrections immediately or document deferred issues in the ExecPlan.
For Monitor's current CLI-only bootstrap, browser visual evidence is not applicable. Validation is structural and terminal-focused.
Useful phrases for future UI work:
- "quiet local activity timeline"
- "plain, privacy-aware monitoring controls"
- "dense but readable terminal-derived run summaries"
Avoid:
- stealth-monitoring language
- decorative dashboard visuals that distract from sensitive data review
- implying screenshots are redacted or private from OpenAI services unless a real redaction or local-only analyzer exists