This is a submission for the Presage SmartSpectra SDK Challenge
What I Built
The coding agents I work with all come with a harness: tools, state, feedback, and rules for when to stop. Someone thought hard about every one of those.
On the same diagrams, the human in the loop is a box with one arrow going in and one coming out. No timeout, no retry policy, no stop condition. Its health check is somebody typing "fine".
So I built a harness for the box. A climbing harness, ideally: you do the climbing, and it holds when you stop.
FlowBreak is a desktop break companion for developers, written with Electron, Node.js and plain HTML, CSS and JavaScript. It uses the Presage SmartSpectra SDK to read pulse, breathing rate, the chest breathing waveform and HRV from the laptop's webcam. The interface speaks French and English.
A session has a start and an end. I choose a reminder interval (25, 45, 60 or 90 minutes), allow the camera for this session only, and see which measurements are usable right now, and why the others aren't. When the reminder shows up, it asks "A little breathing room?" and offers two buttons: Take a break and Later. Later buys 5, 10 or 15 minutes, whatever I set in Preferences. (The button exists because I know the user.)
Below the timer, a card asks "How are you feeling?" with three answers: Focused, Scattered, Need a break. SmartSpectra attaches a confidence score to every pulse estimate. My "Focused" comes with none, and FlowBreak takes it as given anyway. How I feel is mine to report.
There are two kinds of break. A free break turns the camera off, and the screen says "The camera is taking a break too". A breathing break keeps measuring and uses the chest breathing trace to drive an animation. When the trace drops out, the animation waits instead of inventing a rhythm.
I started out wanting FlowBreak to notice when I was losing focus. The camera gives pulse, breathing and HRV. It doesn't give focus, and nothing in this project validates a concentration or fatigue score. So the app keeps time, shows what it can measure, and asks. It doesn't guess.
Demo
The video lasts 1 minute 43 seconds, cut from two recordings made on November 13 with version 0.2.4. It shows consent and startup, 42 continuous seconds of live SmartSpectra signals, the report from that earlier session, the data preferences, a free break with the camera off, resuming, and ending the session. Title cards mark the switch between recordings, and everything plays at normal speed. The interface is in French; English captions explain each step, and there's no audio. I cropped out the camera preview and anyone in the background.
That frame comes from the live part. Pulse passes at confidence 100 and HRV at 87. Breathing rate arrived at 67.9, the app asks for 70, so it shows a dash and says why. FlowBreak is mostly a machine for explaining dashes.
The breathing break is implemented but isn't in the video. Evaluating it in a real session is still on my list.
Code
sintineddi
/
flowbreak
A break companion for developers: Presage SmartSpectra reads pulse, breathing and HRV from the webcam, and every decision stays with you.
I've verified the build on macOS Apple Silicon, with Node.js 22.12 or later. On a fresh checkout:
npm ci
cp .env.example .env.local
# Put your own PRESAGE_API_KEY in .env.local, then:
npm start
Skip the cp if you already have an .env.local: it would replace your key. Demo mode needs neither a key nor a camera, and it labels every value as simulated. Live mode needs your own key from Presage's getting started guide, a webcam, an Internet connection and macOS camera permission. The key stays in Electron's main process. The window only learns whether one is configured.
npm test # 37 unit tests
npm run test:ui # 7 Electron runs, simulated signals only
Both suites passed on November 17. The Mac package is unsigned, and I haven't tried Windows or Linux.
How It Responds to Human Signals
SmartSpectra runs in Electron's main process. FlowBreak requests four metrics (pulse rate, HRV, chest breathing and breathing rate) with SDK telemetry turned off. Each metrics event is decoded and passes through a small signal buffer before the interface sees it. The window receives either a usable value or the reason it doesn't have one.
That reason ended up being most of the product. A missing number can mean the signal is still warming up, nothing has arrived, the last sample is more than five seconds old, the value is out of range, the SDK flags it as unstable, the confidence is too low, or framing validation failed. Each case has its own message, and the camera preview shows the full frame with advice on where to sit.
A pulse, breathing rate or HRV value reaches the screen only when all of these hold:
- its warm up is over: 12 seconds for pulse, 30 for breathing rate, 60 for HRV
- the SDK marks it stable
- its confidence is at least 70
- framing validation is OK
- the value is finite and in range
- the sample is less than five seconds old
I picked the 70. It isn't a Presage requirement, and passing it doesn't make a value accurate. The breathing waveform has no confidence field in this SDK, so it only gets the stability, framing and freshness checks. A repeated timestamp can't make an old sample look new again.
None of this touches the clock. Reminders run on time, so they keep working when every measurement on screen is a dash.
One optional setting goes further, and it's off by default. After 20 minutes of work, if pulse stays at least 20% away from a baseline for 30 seconds, FlowBreak invites me to check in. The baseline is the median of 30 valid readings taken at least a second apart. I haven't validated it, it isn't fatigue detection, and all it does is ask.
The simulated me was a model user
In demo mode, every value showed up on time. With the real camera, the screen stayed empty, and the interface blamed framing.
Framing wasn't the problem. SmartSpectra's protobuf messages carry their int64 timestamps as Long objects, and my filter called Number.isFinite() on them. Every sample failed. In a five minute test during a meeting on November 9, FlowBreak threw away 103 pulse samples, 57 breathing rates, 75 HRV readings and 7,233 points of breathing waveform as malformed. Presage had been sending data the whole time.
The demo generated plain numbers for timestamps, and so did my tests: the simulated me never sent a Long. A regression test now encodes and decodes messages with the protobuf classes that ship with the SDK.
Three real sessions
Here are the three longer live sessions I ran after the fix. This is the share of time, after each signal's warm up, during which FlowBreak had a usable value:
| Session | Length | Pulse | Breathing rate | Breathing waveform | HRV |
|---|---|---|---|---|---|
| November 10, v0.2.2 | about 10 min | 11.8% | 1.1% | 9.5% | 0% |
| November 12, v0.2.3 | 10 min 6 s | 50.8% | 29.3% | 55.6% | 0% |
| November 13, v0.2.4 | 5 min 46 s | 68.4% | 42.0% | 61.3% | 27.4% |
These numbers measure availability. They say nothing about accuracy. I didn't control the conditions between sessions: on November 12 I was working or talking, and the November 13 session was shorter, with no activity markers and no break. Framing, light and what I was doing all changed along with the code, so I can't credit the code for the whole improvement. None of the three sessions recorded a malformed sample.
HRV deserves its own line. On November 12, 409 HRV samples arrived and none got through. The best confidence of the session was 63.9. The bouncer wanted 70. On November 13, 83 of 298 got in.
Tracking during real work stays intermittent. That's why the harness leans on time, explicit choices and what I report, and treats the camera as extra information when it has some.
The loophole a human would find
Stopping has to work as well as measuring. Before version 0.2.4, suspending the camera after 24 minutes of work and then resuming restarted the reminder interval. At 25 minutes worked, no reminder. The harness had a hole exactly where a tired developer would lean on it. Suspending now keeps the time already worked, and only a real break resets the interval.
The other stop rules: reloading the window or locking the Mac cancels a pending camera start and suspends an active session. Readings and charts clear as soon as stopping begins, and reports stay readable while the native SDK shuts down. If that shutdown fails, the app says so and asks for a restart before the next capture.
The automated tests cover simulated sessions, protobuf decoding, persistence, camera permission refusal, cancelling a pending start and a slow sensor shutdown. They test the software. The three sessions above are the only evidence I have about the signals.
Not tested yet
The next experiment is a marked quiet reference, then ordinary work, with the same camera setup. I also need to try the breathing break live, and find out whether the reminders help during a normal development day rather than a test.
Prize Categories
I'm entering both Best Thoughtful Real-World Use and Most Creative or Delightful Use.
Best Thoughtful Real-World Use. The need is small and comes back every day: when to stop during a development session, decided by the developer. FlowBreak is for one person at their own desk. The camera stays off until that person starts a session, every reminder can be pushed back, a free break turns the camera off, and each missing value comes with an explanation instead of a guess. It gives no productivity score and isn't built to watch anyone else.
Most Creative or Delightful Use. The idea is an agent harness turned around: the developer gets the session boundary, the feedback, the stop condition and the way back in. The delightful part is small on purpose. During a breathing break, the animation moves with my own chest breathing as SmartSpectra measures it, and it waits when the signal goes. During a free break, the camera takes a break too.
Consent and Data Handling
FlowBreak is a personal tool. It makes no diagnosis or medical claim, gives no productivity score, and isn't built for monitoring someone else.
The camera is off at launch. Every session starts with a consent dialog, and live capture also needs macOS camera permission. A free break, suspending, ending the session, quitting, sleeping or locking the Mac, reloading the window and the menu bar's "Stop camera" item all stop capture. A breathing break keeps it running, and the screen says so.
FlowBreak doesn't record video or save camera images. Preview frames and the short chart buffers live in memory and clear when capture stops. The app doesn't read code, keystrokes or editor content.
Test reports are on by default in this test build. FlowBreak says so before each session, and they can be turned off in Preferences for later sessions. A report holds physiological statistics (mean, min, max and counts), confidence and quality statistics, timing, optional activity markers, SDK error codes and sampled CPU and memory use. It holds no video, raw sample stream, API key or screen content. The journal is separate and off by default. When it's on, it keeps session durations, breaks and the answers given on the "How are you feeling?" card.
All files stay on the computer, unencrypted, readable only by the user's account. Retention is 30 days and at most 100 entries. Pruning runs when the app loads or saves its data, so nothing is deleted while FlowBreak is closed. Reports can be deleted one at a time or all together, and the journal has its own Clear button. JSON and CSV exports only happen on request. Deleting a report also deletes its exports from the app's export folder; a copy moved somewhere else is out of FlowBreak's hands.
FlowBreak creates SmartSpectra with enableTelemetry: false. Presage's Telemetry and Privacy documentation describes telemetry as on by default and explains how to turn it off. Live measurement still needs authenticated access to Presage's service, so this isn't an offline sensor. Presage's side falls under its SDK Privacy Policy; the 30 day retention above only covers FlowBreak's own files. I haven't run a network audit. FlowBreak has no backend, and it doesn't call LLM Insights or any other AI service.
Agent Session
I used Codex to help implement, review and test FlowBreak, and Claude Code to help edit this post and rerun the checks. The interface polish follows Unslop by Damir Sokolovsky (CC BY 4.0), and the icons come from Lucide.
Codex worked inside its harness the whole time. Now I have one too, and mine has a Later button.


Top comments (1)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.