Your hand is halfway to your mouth. Habit Guard noticed first.

Habit Guard watches your webcam for a hand going to your mouth, mustache, brows or hair, and interrupts the habit within about a second: a sound, a dimmed screen, a spoken phrase or a notification, your choice. It runs on your computer, costs a fraction of a percent of your CPU and never saves a picture.

Get Habit Guard Star on GitHub

Version 0.1.0 · Free and open source, MIT licence · Windows, macOS, Linux · Offline

Alpha. Built and tested, but new to real desks and webcams. Reports of false alarms and misses help most.

Zones Watching

Watching. Pick a habit to see what it looks like, or wait: the demo plays by itself.

Measured, not promised

Windows 11 on a Ryzen 7 3700X, replaying a 640×480 clip with habit-guard bench.

CPU, face in view
0.34%5.5% of one core
CPU, hand near the face
~1.3%20% of one core
One analysis
20 to 26 msface and hand
Network connections
0no telemetry, no update check
Pictures saved
0analysed in memory only
Tested in CI on
3 systemsWindows, macOS, Linux

Ten seconds, start to finish

A hand drifts toward the mouth, the camera notices, the dwell time fills up, the alarm steps in, and it stops the moment the hand is down.

An illustration made with an AI video tool, not a recording of the app.
  1. NoticedThe webcam finds your face and hand. Everything stays on your computer.
  2. In the zoneA fingertip enters the zone of a habit, measured in eye distances.
  3. Dwell timeThe ring fills while the hand stays. A quick scratch never completes it.
  4. Alarm, then calmA sound, a dimmed screen, a voice or a notification. It stops when the hand is down.

Set it up once. Then forget it.

A hand has to stay in a zone for a moment before anything happens, so drinking, wiping your lips or a quick scratch are ignored.

  1. Place the camera

    Where your face and both raised hands are in the picture, with light on your face. The camera preview shows exactly what Habit Guard sees.

  2. Choose your habits

    Tick the ones to watch. Each has its own zone on your face, its own dwell time and size. Zones follow you when you lean in or tilt your head.

  3. Carry on

    It waits in the tray. When a fingertip stays in a zone for the dwell time the alarm goes off, and steps up while the hand stays.

See what you get

These are the real windows. The camera picture in the preview is an illustration, not a photograph: no real face appears anywhere in this project.

The camera preview: a drawn person with a hand at the mouth, the zones on the face and the hand's 21 points
Camera previewZones on your face, the hand's 21 points with the fingertips in red. A zone fills in when a fingertip is inside it.
The statistics window: alarms today and in total, the clean time, a 7-day bar chart and totals per habit
StatisticsAlarms per day and habit, a 7-day chart and your clean streak. Kept as plain numbers on your computer.
Settings, Habits tab: a switch, a dwell time and a zone size for each of four habits
HabitsA switch, a dwell time and a zone size for each habit.
Settings, Alarms tab: sound, notification, screen curtain, voice and escalation
AlarmsSound, notification, screen, voice and escalation, each on its own switch.
Settings, General tab: language, camera, camera interface and performance profile
GeneralLanguage, camera, how the camera is opened and the performance profile.
A document with the screen dimmed and the message Hands down!
The screen dimsUntil your hand is down, on every monitor. Clicks pass straight through, so it can never lock you out.
A document with a pulsing red frame around the screen and the message Hands down!
Or a red frameA pulsing frame instead of the dimming, if you want to keep reading.
The tray menu: status, today's alarms, pause, pause for a set time, camera preview, statistics, settings, test the alarm, quit
Lives in the trayPause, preview, statistics and settings, one click away.

Pause when you need to

Eating, a video call, a phone call with your chin on your hand: pause tracking from the tray for 15 minutes, an hour or three hours, and it resumes by itself. Pausing releases the camera, so the webcam light goes out.

Try the alarm any time with Test the alarm: it plays exactly what your settings describe.

Four habits, four zones

Each zone is a few ellipses on your face, measured in eye distances, so they follow you as you lean in, lean back or tilt your head. The picture is drawn from the same numbers the app uses.

A face with the zones of the four habits drawn over it
  • Nail and finger biting

    The lips and the area around them.

    1.0 s dwell
  • Mustache, beard and lip picking

    Between the nose and the mouth. Optionally the chin and the beard line.

    1.5 s dwell
  • Brow, lash and hair pulling

    Brows, eyelids, forehead and hairline. Optionally the scalp.

    1.5 s · off
  • Face touching and skin picking

    The rest of the face, whatever the other habits do not own.

    4 s · off

Nail biting and mustache are on by default; the other two are one tick away. Sizes, dwell times and the wider areas are all settings. See zones and tuning.

What happens when it catches you

Every response is a setting. Use one, or all of them together.

  • Sound

    A soft chime, then three beeps, then a warbling alarm as you keep going. Or your own sound file (WAV, MP3, ...).

    On
  • Screen curtain

    Dim the screen or pulse a red frame on every monitor, until the hand is down.

    Dim the screen
  • Voice

    Says a phrase of your choice with your system's offline voice.

    Off
  • Notification

    A desktop notification on the first alarm of each episode.

    On
  • Escalation

    Quieter first, louder and darker the longer the hand stays.

    Every 4 s
  • Pause from the tray

    For 15 minutes, an hour or three hours. It resumes by itself.

    15 m1 h3 h
  • Statistics

    Alarms per day and habit, a 7-day chart and a clean streak, stored locally as plain numbers.

    On
  • Performance profile

    An adaptive analysis rate and a motion gate keep the CPU near a third of a percent.

    Balanced

All of these, with their ranges, are in the configuration reference.

A camera app you can actually trust

Habit Guard watches your face and hands, so privacy is designed in, and anyone can check it.

We removed MediaPipe's runtime because it phones home

The hand models come from Google's MediaPipe (Apache-2.0), but its runtime contains a usage logger that connects to Google's servers. Habit Guard runs the same weights through OpenCV instead, and the runtime is not shipped.

Every change is scanned for networking code and picture writing
  • Network access

    No telemetry, no accounts, no update check, no crash reports. CI fails when any file imports a networking library.

    None
  • Camera pictures

    Analysed in memory for a few milliseconds and never written to disk. CI fails on OpenCV's image and video writers.

    Never stored
  • What is stored

    Your settings and the daily counters, in plain JSON you can read. No images.

    Numbers only
  • Pause

    The camera device is released, so the webcam light goes out.

    Camera off
  • Screen, keyboard, mouse

    The curtain draws over the screen; it never reads it. Keys and clicks are never read.

    Never read

Honest about the limits

Habit Guard is alpha software. Here is what has been tried and what has not.

Detection and alarmsScreen curtainVoice
Windows 10 and 11Developed and used here, with a real cameraYesYes
macOSBuilt for it; CI builds the package and runs its selftest, not yet tried with a cameraBuilt for itYes (say)
Linux (X11, Wayland)Built for it, tested in CI, not yet with a cameraX11; some Wayland compositors may block clicksWith spd-say or espeak

Installers for all three systems are below, and the tray app also runs from source. Most webcams can be used by one program at a time; if another app holds the camera, Habit Guard waits and retries. The troubleshooting guide covers it.

Get Habit Guard 0.1.0

Free and open source. Released October 2, 2026. Your system is selected.

Your system

Windows

Windows 10 or 11, 64-bit

Installer (.exe)52 MB Portable (.zip)75 MB

Per-user install, no administrator rights. Builds are not code-signed yet: if SmartScreen warns, choose More info → Run anyway.

Your system

macOS

macOS 14 or later, Apple silicon

Disk image (.dmg)88 MB

Not notarised yet: the first time, right-click the app and choose Open, then allow the camera. Intel Macs can run from source.

Your system

Linux

x86_64, glibc 2.35+ (Ubuntu 22.04 or newer)

AppImage141 MB Tarball (.tar.gz)153 MB

Needs a desktop with a system tray (GNOME needs an extension). The AppImage needs FUSE, or run it with --appimage-extract-and-run.

SHA256SUMS.txt Release notes All releases Troubleshooting

Prefer to run from source?

You need Git and uv, which fetches the right Python itself. Intel Macs use this route too.

  1. A hand icon appears in the tray (the menu bar on macOS). The settings window opens the first time.
  2. Pick the habits to watch, then open Camera preview from the tray menu to check that it sees you well.
  3. Optional: uv run habit-guard autostart enable starts it at login.
git clone https://github.com/bugraskl/habit-guard.git
cd habit-guard
uv sync
uv run habit-guard

Questions people ask

Does it record me?

No. A camera picture exists only in memory for a few milliseconds while it is analysed. Nothing is written to disk or sent anywhere, and a scan in CI fails the build if code that could do either is added.

It goes off when I drink, or talk on the phone. What can I do?

Give that habit a longer dwell time, make its zone smaller, or pause tracking from the tray for a while. The camera preview shows exactly which zone your hand is in.

Does it work with glasses?

Yes. Strong reflections on the lenses can hide the eyes, which are used to place the zones; tilt the lamp or the camera slightly if that happens.

Can I use it during a video call?

Most webcams can be opened by one program at a time. If a call app holds the camera, Habit Guard waits and starts again when the camera is free; you can also pause it from the tray for a set time.

Which webcam do I need?

Any webcam, built-in or external. Place it so that your face and both raised hands are in the picture, with light on your face.

Is it a medical device?

No. It is a self-help tool. If a habit hurts you or causes distress, talking to a doctor or therapist is worth it; many people find reminders like this a helpful addition, not a replacement.

My habit is not on the list.

Zones are just shapes on the face, so new habits are mostly a matter of drawing one. Open a feature request and describe where your hand goes.

Notice the hand before the habit does

Free, open source and private by design. Setup takes about a minute.

Get Habit Guard Star on GitHub