Teumnirm

A macOS app that monitors your computer usage time and reminds you to take breaks

Note: This project was entirely built using AI tools (Claude, Cursor).

The name "Teumnirm" combines the Korean word "teum" (틈, meaning break/gap) and the Middle Korean word "nirm" (니름, meaning notification/announcement), signifying "notifying you of break time."

Teumnirm detects keyboard/mouse activity and blurs the screen after 55 minutes of continuous use, while turning Philips Hue lights red to remind you to take a break.

한국어 README

Features

• Activity Monitoring: Tracks computer usage time by detecting keyboard/mouse input
• Inactivity Detection: Pauses the timer after 3 minutes of inactivity, and completely resets the timer if inactive for half of the break interval (default: 27.5 minutes)
• Meeting-safe Break Deferral: Optionally delays break alerts while your microphone is in use and shows the alert immediately after mic use ends
• Usage History Window: Shows computer usage history in a separate window, one day at a time, with previous/next day navigation
• Screen Blur: Blurs the entire screen after a configured period of time
• Philips Hue Integration: Changes lights to red for visual notification
• Auto Recovery: Automatically restores to normal state after 5 minutes
• Menu Bar App: Easy control from the system menu bar

Screenshots

When it's time for a break:

1. The screen becomes blurred
2. A "Break Complete" button appears
3. Philips Hue lights turn red

Installation

You can download the latest version from the GitHub Releases page.

"damaged and can't be opened" Warning

When you first launch the downloaded app, you may see a warning saying "Teumnirm is damaged and can't be opened". This happens because the app is not notarized by Apple.

Run the following command in Terminal to fix this:

xattr -cr ~/Downloads/Teumnirm.app

If you downloaded to a different location, adjust the path accordingly (e.g., /Applications/Teumnirm.app)

Usage

Basic Usage

1. When you launch the app, a timer icon appears in the menu bar

   

2. The app automatically monitors keyboard/mouse activity

3. After 55 minutes (default) of continuous use, the screen becomes blurred

4. Click the "Break Complete" button after your break, or it will auto-dismiss after 5 minutes

Usage History

1. Click the menu bar icon > Usage History...
2. Review one day's usage at a time with the left/right buttons
3. The header shows the selected day and total usage time for that day
4. The current in-progress usage session is shown live in the history window
5. Sessions separated by 3 minutes or less are merged automatically, but sessions across midnight remain separate

During Meetings/Calls

1. Open menu bar icon > Settings... > General
2. Enable Delay break alert while microphone is in use
3. If break time is reached while your mic is active, the break alert is deferred and shown immediately after the mic is released

Permissions

Input Monitoring

Input monitoring permission is required to detect keyboard/mouse activity.

1. System Settings > Privacy & Security > Input Monitoring
2. Enable Teumnirm

Local Network (When using Philips Hue)

Local network access permission is required to communicate with the Hue bridge.

Philips Hue Setup

1. Click the menu bar icon > Settings...
2. Select the Philips Hue tab
3. Enable Use Philips Hue Integration
4. Use Auto Discovery to find the bridge (or enter the IP manually)
5. Press the button on your Hue bridge, then click Connect to Bridge
6. Select the lights to control

Settings Options

• Break Reminder Interval: 20 to 120 minutes (default: 55 minutes)
• Auto Dismiss Time: 3 to 15 minutes (default: 5 minutes)
• Usage History Range: 1 to 30 days (default: 7 days). Older history outside this range is automatically deleted
• Delay Break Alert While Microphone Is In Use: Useful for meetings; this is based on mic usage (not Zoom-only integration)
• Compatibility Mode: Enable if the blur is not displaying properly

Privacy

• All data is processed locally
• Keyboard/mouse input content is not recorded; only activity presence is detected
• Usage history is stored locally on the device
• Network communication is only used for local communication with the Philips Hue bridge

License

MIT License

Acknowledgments

• posturr - Reference for screen blur implementation
• rainygirl's blog post - Inspiration for Philips Hue integration

---

For Developers

Build From Source

Requirements

• macOS 13.0 (Ventura) or later
• Xcode Command Line Tools (xcode-select --install)
• (Optional) Philips Hue Bridge

Build

git clone https://github.com/yourusername/teumnirm.git
cd teumnirm
./build.sh

The built app will be created at build/Teumnirm.app.

Run

open build/Teumnirm.app

Or copy Teumnirm.app to your /Applications folder.

Project Structure

teumnirm/
├── Sources/
│   ├── main.swift              # App entry point
│   ├── AppDelegate.swift       # Main coordinator
│   ├── Models.swift            # Data models
│   ├── ActivityMonitor.swift   # Activity detection
│   ├── BlurOverlay.swift       # Screen blur
│   ├── HueController.swift     # Philips Hue control
│   ├── ConfirmWindow.swift     # Confirmation window
│   ├── SettingsWindow.swift    # Settings window (SwiftUI)
│   ├── UsageHistoryStore.swift # Usage history persistence and queries
│   └── UsageHistoryWindow.swift # Usage history window (SwiftUI)
├── Package.swift
├── Tests/
│   └── TeumnirmTests/          # Usage history tests
├── build.sh
└── README.md

Tech Stack

• Swift 5.9+
• SwiftUI (Settings window)
• AppKit (Menu bar, overlay)
• IOKit/CoreGraphics (Input event detection)
• Philips Hue REST API (Light control)