Skip to content
Daniel Acosta

Case study · Open-source CLI · AI agent tooling

screenstudio-agent

Trust the file, not the app.

Creator / Software Engineer

A command-line tool that lets an AI agent record my screen through Screen Studio, with no one at the keyboard. It’s rebuilt so the agent can tell whether a recording actually happened instead of being told it did.

Built on Shawn Pana’s screenstudio-cli. The way in was his; the verification is mine.

  • TypeScript
  • Node
  • Chrome DevTools Protocol
  • AI agents
  • CLI
View on GitHub ↗

The problem

I make a lot of screen recordings: product walkthroughs, teaching material, demo footage. The recording itself is the boring part, so it’s work an agent should do.

Screen Studio has no automation surface: no AppleScript, no URL scheme, no CLI.

The way in

Shawn Pana’s screenstudio-cli drives the app over the Chrome DevTools Protocol. It worked, but it was built for a person watching the screen, and an agent isn’t watching.

The lie

Every command threw away the app’s reply and printed success:

Exhibit A · How every command ended
bridge.client.mutation("capture.finish").then(function() {}).catch(function() {});
output({ success: true, message: "Recording stopped and saved" });

An empty .catch() swallowed every error. A failed stop still said “saved”.

A person would notice. An unattended agent would report a video that doesn’t exist.

The fix

Verify by outcome, not by asking

The app has no “am I recording?” query. I tried every plausible name:

Exhibit B · Asking the app
capture.state · capture.status · capture.getState · capture.isRecording
capture.info  · capture.current · capture.get     · recording.state
→ "No query-procedure on path"

So record stop doesn’t ask. It watches for the thing the app is supposed to make.

  1. Send stop, and wait for the app’s real reply.
  2. Watch the Screen Studio Projects folder for a new .screenstudio bundle.
  3. Wait until the bundle stops growing.
  4. Return the real path and the captured duration. If nothing saved, exit non-zero.
Exhibit C · What the agent gets back

It’s slower, but it can’t lie, and it survives the app renaming its internals.

Before / after

Exhibit D · What changed
  • record stop

    Before

    Always printed success

    After

    Waits for the file on disk, returns path + duration, fails loudly if nothing saved

  • record start

    Before

    Returned ~4.2s early (asked 10s, got ~6s)

    After

    --wait returns once capture is rolling (asked 10s, got 9.97s)

  • pause / resume / cancel

    Before

    Always printed success

    After

    Show real failures

  • Debug port

    Before

    Nothing closed it

    After

    quit closes the app and verifies the port is shut

  • Shell args

    Before

    $(...) in a filename would execute

    After

    Safely single-quoted

Security, honestly

The debug port binds to 127.0.0.1 only and Node integration is off, but any local process can drive the app while the port is open.

So quit exits non-zero if the port is still open: open it for the job, not for the day.

One runtime dependency, nothing phones home, and it’s deliberately not published to npm. You should read the code that can record your screen before you run it.

What I learned

  • Tools built for agents need a different contract than tools built for people.
  • Silent success is worse than loud failure.
  • When you can’t trust an API to report state, check the artifact it’s supposed to make.

Credits

Built on Shawn Pana’s screenstudio-cli. The Chrome DevTools Protocol approach, the command surface and the editing model are his work. MIT licensed, and the fork stays MIT.