Screen Time & App Usage Tracker

A simple, offline terminal application to track your application usage time. Built with Python standard library only - no external dependencies required.

Features

• Cross-Platform: Works on Linux, macOS, and Windows
• No Dependencies: Uses only Python standard library
• Offline: All data stored locally in JSON files
• Privacy-Focused: No data leaves your computer
• Idle Detection: Automatically pauses tracking when inactive
• Detailed Statistics: View daily, weekly, and all-time usage stats
• Simple Interface: Easy-to-use terminal menu

Installation

Option 1: Run directly (no installation)

# Clone or download the project
cd screen_time_tracker

# Run the application
python -m screen_time_tracker

Option 2: Install as package

# Install in development mode
pip install -e .

# Run using command
screen-time-tracker
# or
stt

System Requirements

Linux

Install xdotool for window detection:

sudo apt install xdotool

Or alternatively:

sudo apt install x11-utils  # for xprop

macOS

No additional requirements - uses built-in AppleScript.

Windows

No additional requirements - uses built-in PowerShell.

Usage

Starting the Application

python -m screen_time_tracker

Menu Options

1. Start tracking - Begin monitoring your application usage
2. Stop tracking - Stop monitoring and save current session
3. View today's usage - See detailed breakdown of today's app usage
4. View weekly summary - See usage statistics for the past 7 days
5. View all-time statistics - See complete usage history
6. Clear old data - Remove entries older than specified days
7. Check system compatibility - Verify window detection is working
8. Exit - Stop tracking and exit the application

Example Output

============================================================
       SCREEN TIME & APP USAGE TRACKER
       File-Based Offline Tracker
============================================================

========================================
  TRACKER STATUS
========================================
  Status: TRACKING
  Current App: Visual Studio Code
  Session Duration: 5m 23s
  Sessions Recorded: 12
  Total Tracked: 2h 15m 30s
========================================

----------------------------------------
  MAIN MENU
----------------------------------------
  [1] Start tracking
  [2] Stop tracking
  [3] View today's usage
  [4] View weekly summary
  [5] View all-time statistics
  [6] Clear old data
  [7] Check system compatibility
  [0] Exit
----------------------------------------

Data Storage

Activity data is stored in JSON format at:

screen_time_tracker/data/activity_log.json

Data Format

[
  {
    "app_name": "Visual Studio Code",
    "start_time": "2024-01-15T10:30:00",
    "end_time": "2024-01-15T11:45:30",
    "duration_seconds": 4530,
    "date": "2024-01-15"
  }
]

Configuration

You can modify tracking behavior by editing constants in tracker.py:

POLL_INTERVAL = 2      # Seconds between window checks
IDLE_THRESHOLD = 300   # Seconds of inactivity before idle state
MIN_SESSION_DURATION = 3  # Minimum seconds to record a session

Project Structure

screen_time_tracker/
├── __init__.py          # Package initialization
├── __main__.py          # Entry point
├── menu.py              # Terminal menu interface
├── tracker.py           # Core tracking logic
├── storage.py           # JSON file storage
├── window_detector.py   # Cross-platform window detection
├── data/
│   └── activity_log.json  # Activity data (created on first run)
├── requirements.txt     # Dependencies (none required)
├── setup.py            # Package setup
├── README.md           # This file
├── LICENSE             # MIT License
└── .gitignore          # Git ignore rules

How It Works

1. Window Detection: The tracker polls the system every 2 seconds to detect the currently active window
2. Session Management: When you switch applications, the previous session is saved and a new one begins
3. Idle Detection: If no window change is detected for 5 minutes, the tracker enters idle state
4. Data Storage: Sessions are saved to a JSON file with atomic writes to prevent corruption

Troubleshooting

"Window detection is NOT AVAILABLE"

Linux: Install xdotool

sudo apt install xdotool

macOS: Grant accessibility permissions to Terminal/iTerm in System Preferences > Security & Privacy > Privacy > Accessibility

Windows: Run as administrator if detection fails

No data being recorded

1. Check system compatibility using menu option 7
2. Ensure the application has necessary permissions
3. Verify the data/ directory is writable

Data file corrupted

The application automatically creates backups. If the main file is corrupted, it will attempt to restore from activity_log.json.backup.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - see LICENSE file for details.

Privacy

This application:

• Stores all data locally on your computer
• Does not send any data over the network
• Does not require an internet connection
• Only tracks application names, not window contents or keystrokes