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
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:
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:
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.
- Send stop, and wait for the app’s real reply.
- Watch the Screen Studio Projects folder for a new
.screenstudiobundle. - Wait until the bundle stops growing.
- Return the real path and the captured duration. If nothing saved, exit non-zero.
It’s slower, but it can’t lie, and it survives the app renaming its internals.
Before / after
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
--waitreturns 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
quitcloses the app and verifies the port is shutShell args
Before
$(...)in a filename would executeAfter
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.