# Screen recording in Adom Bridge

![The desktop recorder HUD](recorder.png)

Adom Bridge can record your screen to a video file (`.webm`). Recording is
built so that it can never happen behind your back: whenever an AI records
your desktop, a small recorder window (the HUD) is visible on screen the
whole time.

## What you see when an AI records

The recorder HUD is a small always-on-top window in the bottom-right corner
of your screen. It shows:

- the current recording status and a Start/Stop control
- live Screen / Microphone source toggles
- a **reason line**, right at the top

The reason is required. The AI must state why it is recording ("Recording
the KiCad export demo you asked for", for example) before a recording can
start, and that reason is displayed in the HUD for as long as the session is
open. It is also saved in a small metadata file next to each clip, so you can
check later why any recording was made.

## Why the HUD exists

Two guarantees, by design:

1. **You can always tell recording is on.** The HUD is visible and always on
   top for the entire session. There is no silent or hidden desktop
   recording mode.
2. **You can always tell who asked and why.** The reason line comes from
   whoever started the recording. A recording request without a reason is
   rejected.

There is one more deliberate safeguard on the AI side: starting a desktop
recording requires the AI to explicitly confirm that it wants the whole
desktop and not just a browser tab. This prevents an AI from accidentally
capturing everything on your screen when it only meant to record one page.

## How to stop a recording

Click **Stop** in the HUD at any time. Your click is honored exactly like a
stop request from the AI: the clip is finalized and the AI is expected to
treat it as complete. Closing the recorder ends the whole session; the HUD
also dismisses itself after 5 minutes of inactivity.

One HUD session can contain several short clips. The HUD stays open between
clips so you keep seeing that a recording session is in progress.

## Where your clips are saved and how long they are kept

- Each clip is a single `.webm` video file on your machine. The AI can list
  them for you (with the reason each was recorded) or copy them wherever you
  ask.
- Adom Bridge cleans up its recordings folder automatically so it never
  fills your disk: clips are kept for about 2 days, capped at 40 files and
  3 GB total. Cleanup always removes the oldest files first, so a recording
  you just made (or one still in progress) is never touched.
- If you want to keep a clip long-term, copy it out (or ask the AI to) soon
  after recording.

## Desktop recording vs tab recording

Adom Bridge has two different recording features:

- **Desktop recording** (this page): records everything on your monitor,
  with the visible HUD and the reason line described above.
- **Tab recording**: records the contents of a single automated browser tab
  (a Puppeteer bridge feature, `pup_record_start`). It captures only
  that tab, needs no HUD (you already see the tab), and keeps recording even
  if the window is covered by other apps.

If an AI is recording a browser demo, it is usually using tab recording. If
the HUD is on your screen, the whole desktop is being recorded, and the HUD
tells you why.