desk-ai.app

desk.ai

desk.ai is a lightweight desktop app that uses your webcam to help you build healthier screen habits.

The app runs locally on your machine. It detects blinks, posture, prolonged times without movement and screen distance in real time, then nudges you in the moment to build healthier habits. No account required and your data stays on your device.

Features

• Blink reminders - dims the screen when you have not blinked for a while; clears when you blink again
• Posture detection - alerts you when you are hunching
• Screen distance - warns when you sit too close to the display
• Motion breaks - prompts you to move after long still periods
• Pomodoro timer - built-in focus/break cycles
• 20-20-20 rule - optional passive eye-rest reminders
• Multi-monitor support - works across several screens
• No GPU required - runs on CPU
• Customizable - adjust sensitivity, timers, and reminders in the GUI

Quick start (run from source)

Prerequisites

• Python 3.10
• A working webcam
• Windows, Mac, and Linux supported. For Linux, X11 is recommended (Wayland is not fully supported; the app forces X11 via xcb when needed)

1. Clone the repository

git clone https://github.com/psykidlearn/desk-ai.git
cd desk-ai

2. Create a virtual environment

Using conda or micromamba (recommended — includes PySide6 and MediaPipe):

conda env create -f dist/env/deskai.yml
conda activate deskai

Or with micromamba:

micromamba env create -f dist/env/deskai.yml
micromamba activate deskai

3. Install remaining dependencies

From the repo root (after activating deskai):

pip install -r requirements.txt

4. Run the app

From the project root:

python src/run.py

On first launch, complete the in-app onboarding, then grant camera access when prompted.

Build an executable (optional)

Build on the target OS (Windows, macOS, or Linux). From the repo root:

pip install -r requirements-build.txt
python build_application.py

Outputs:

OS	Output
Windows	dist/dist.dist/desk_ai.exe (+ DLLs in same folder)
Linux	dist/dist.dist/desk_ai (+ libs in same folder)
macOS	dist/desk_ai.app

Optional distributables (after Nuitka build):

python dist/create_app_windows.py   # Windows installer (needs Inno Setup)
python dist/create_app_linux.py     # Linux AppImage
python dist/create_app_macos.py     # macOS DMG

See dist/README.md for third-party license generation.

Troubleshooting

• Camera errors - check that a webcam is connected, not running in another app and that the app has camera permission.
• desk.ai is already running - only one instance per user is allowed; close the existing window first.
• Linux Wayland - screen dimming may not work; use an X11 session if possible.

Project layout

desk-ai/
├── assets/          # Icons, themes, MediaPipe models, default configs
├── configs/         # Hydra configuration (detectors, widgets, views)
├── dist/            # Build scripts, conda envs, installer tooling
├── src/
│   ├── run.py       # Local development entry point
│   ├── dist.py      # Packaged/production entry point
│   └── utils/       # GUI, detection pipeline, camera, auth
└── build_application.py

Contributing

See CONTRIBUTING.md. Security reports: SECURITY.md.

License

This project is licensed under the desk.ai Community License v1.0.

You may use, modify, and share the source code for free. The software must remain free for all users. Derivative works must be distributed under the same terms.

Disclaimer

desk.ai is not a medical product and makes no health claims. It is a personal wellness tool, not a substitute for professional medical advice. Use at your own discretion and consult an eye care professional if you have concerns about your eye health.