Usage Tracker

Usage Tracker is a lightweight desktop time-tracking tool that records which application and window you spend time on, stores the data in a local SQLite database, and lets you review it from the command line or in a Streamlit dashboard.

It is designed for tracking active window usage over time so you can answer questions like:

• Which applications did I spend the most time in today?
• How much time did I spend in a specific window or project?
• What was my usage pattern over the last week?

Features

• Tracks the currently active window on KDE/Plasma-based Linux desktops
• Records start/end timestamps and duration in a local SQLite database
• Groups activity by window class and window name
• Generates terminal-based usage reports for selected date ranges
• Provides an interactive Streamlit dashboard for browsing usage trends

Current requirements

This project currently targets KDE/Plasma environments and relies on kdotool being installed and available in your PATH.

Before running the tracker, install the Python dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

You will also need the required system utility for active window detection:

# Example for Debian/Ubuntu-based distributions
sudo apt install kdotool

If you are using a different Linux distribution, install the equivalent package for kdotool on that system.

Installation

1. Clone the repository:

git clone <repository-url>
cd usage-tracker

2. Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

3. Install Python dependencies:

pip install -r requirements.txt

4. Make sure your active window tool is available:

kdotool --help

Starting tracking

Run the tracker in the background or in a terminal window:

python main.py track --interval 60

• --interval sets how often the tracker checks the active window, in seconds.
• The default interval is 60 seconds.
• Data is stored in a SQLite file named window_usage.db in the project directory.

To stop tracking, press Ctrl+C in the terminal where it is running.

Viewing reports from the command line

Once tracking has collected some data, generate a report:

python main.py report

This prints a summary grouped by application and window, along with total tracked time.

You can also filter by date range:

python main.py report --date-start 01-01-2025 --date-end 15-01-2025

Useful options:

python main.py report --active-only
python main.py report --window-class-only
python main.py report --date-start 01-01-2025 --date-end 31-01-2025 --active-only

• --active-only omits known idle or blank entries
• --window-class-only changes the reporting style to focus on application classes
• Dates should be supplied in the format dd-mm-YYYY

Viewing reports in Streamlit

The project includes a Streamlit dashboard that visualizes the same database records.

Start the dashboard with:

streamlit run streamlit_app.py

Then open the local URL shown in the terminal, usually:

http://localhost:8501

From the dashboard you can:

• pick the database path
• choose a date range
• inspect top applications and windows
• review daily totals and activity summaries
• browse tracked usage visually in charts and tables

Example workflow

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py track --interval 30

In another terminal:

python main.py report --date-start 20-08-2026 --date-end 20-08-2026
streamlit run streamlit_app.py

Data stored

The tracker creates and uses a local SQLite database:

window_usage.db

This file is saved in the project directory by default and contains the recorded window activity used for reports and dashboards.

Future features

The project is planned to grow with additional capabilities, including:

• Windows tracking support and other Linux Desktop Environments.
• A notification tray icon while tracking