Idle Detection

Idle detection automatically tracks when you've been away from your computer, helping you log breaks accurately without manual effort.

How It Works

The z8 Timer monitors your keyboard and mouse activity:

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Working        Idle (5+ min)        Resume Activity       │
│   ─────────────►───────────────────►─────────────────────   │
│   ⌨️🖱️ Active     No input detected    Activity detected    │
│                                              │              │
│                                              ▼              │
│                                    ┌─────────────────┐      │
│                                    │  Idle Dialog    │      │
│                                    │                 │      │
│                                    │ "You were away" │      │
│                                    │                 │      │
│                                    │ [Break] [Work]  │      │
│                                    └─────────────────┘      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Continuous monitoring - Tracks keyboard and mouse activity in the background
5-minute threshold - Triggers after 5 minutes of no input
Resume detection - When you start using your computer again
Dialog prompt - Asks what you were doing

Privacy

The app only tracks that input occurred, not what you typed. No keystrokes or mouse positions are logged.

The Idle Dialog

When idle is detected and you resume activity:

┌───────────────────────────────────────┐
│                                       │
│         You were away                 │
│                                       │
│   You were idle for 15 minutes.       │
│   What were you doing?                │
│                                       │
│   ┌─────────────┐  ┌─────────────┐    │
│   │ I was on    │  │ I was still │    │
│   │ break       │  │ working     │    │
│   └─────────────┘  └─────────────┘    │
│                                       │
└───────────────────────────────────────┘

Options

Option	What it does
I was on break	Records the idle period as a break
I was still working	Dismisses the dialog, continues timer

Recording a Break

When you select "I was on break":

Clock out calculated

You're clocked out at the moment you went idle (e.g., 15 minutes ago)

Break recorded

The idle period is recorded as break time in your timesheet

Clock back in

You're immediately clocked back in at the current time

Continue working

Your work session continues with accurate break tracking

Example Timeline

09:00  Clock in
        │
11:30  Last keyboard/mouse activity
        │  ← You went for coffee
11:45  Resume activity (idle detected: 15 min)
        │
        Dialog appears: "You were away for 15 minutes"
        │
        Select "I was on break"
        │
        Result:
        - Time entry: 09:00 - 11:30 (2h 30m work)
        - Break: 11:30 - 11:45 (15m break)
        - New time entry: 11:45 - ongoing

Continuing Without Break

When you select "I was still working":

Dialog is dismissed
Timer continues uninterrupted
No break is recorded
Idle period counts as work time

Use this when:

You were reading/thinking (no input but still working)
You were on a call (phone/video without computer input)
False positive (brief bathroom break you don't want to log)

Idle Detection Settings

Idle detection is always active when you're clocked in. The threshold is fixed at 5 minutes.

When it triggers

Condition	Triggers?
No keyboard input for 5+ min	Yes
No mouse movement for 5+ min	Yes
Computer locked	No (monitors input, not lock state)
App minimized	Yes (continues monitoring)
App closed	No (need app running)

When it doesn't trigger

When you're not clocked in
When the app is not running
During the first 5 minutes after clocking in

Technical Details

Input Monitoring

The app uses the rdev library for cross-platform input monitoring:

Windows: Raw input API
macOS: IOKit (requires Accessibility permission)
Linux: libevdev

Detection Algorithm

Every 10 seconds:
  If clocked_in AND last_input > 5 minutes ago:
    Wait for next input event
    Show idle dialog with calculated idle duration

Resource Usage

Idle detection runs in a separate thread:

Metric	Impact
CPU	< 0.1% (event-based, not polling)
Memory	~1 MB
Battery	Negligible

Platform-Specific Notes

macOS

You must grant Accessibility permission:

Go to System Preferences → Security & Privacy → Privacy
Select Accessibility
Enable z8 Timer

Without this permission, idle detection won't work.

Linux

Ensure your user has access to input devices:

# Add yourself to the input group
sudo usermod -aG input $USER

# Log out and back in for changes to take effect

Windows

No special permissions required. Works out of the box.

Troubleshooting

Idle detection not triggering

Check if clocked in - Only works while clocked in
Wait 5 minutes - Threshold must be exceeded
Verify app is running - Check tray icon
macOS: Check Accessibility permission

False positives

If idle detection triggers while you're working:

Select "I was still working"
This is expected during reading, calls, or thinking

Dialog not appearing

Ensure the app has focus capability
Check if "Do Not Disturb" mode is blocking it
Restart the app

Idle Detection

On this page