CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Deskmeter is a productivity tool that measures time spent across desktop workspaces. It consists of three main components:

dmcore: Core tracking daemon (dmapp/dmcore/main.py) that monitors active workspace and task changes
dmweb: Flask web application (dmapp/dmweb/) for viewing productivity data
dmfnt: Angular frontend (dmapp/dmfnt/) for enhanced UI (in development)

Architecture

Core Components

Task Management System:

Task definitions stored in files, tracked via dmapp/dmcore/task.py
File modification time monitoring for automatic task switching
Hierarchical task organization under workspace paths (e.g., work/default, work/dlt)

Workspace Tracking:

Uses wmctrl to detect active X11 workspace (requires XORG, not Wayland)
Maps workspace indices to labels in dmapp/dmcore/main.py:desktops
Special handling for "work" desktops with automatic task enforcement

Data Storage:

MongoDB backend storing workspace switches with timestamps and durations
State persistence in dmapp/dmcore/state.py for current workspace/task tracking

Web Interface Structure

Flask Routes (dmapp/dmweb/dm.py):

/ - Today's productivity summary
/day/<month>/<day> - Single day view
/calendar - Monthly calendar view via dmapp/dmweb/dmcal.py
/totals - All-time statistics

Development Commands

Python Backend

# Install dependencies
pip install -r requirements.txt

# Start MongoDB service
sudo systemctl start mongod.service

# Run core tracking daemon
cd dmapp/dmcore
python3 main.py

# Run Flask web server
cd dmapp/dmweb  
python3 run.py

# Run tests
cd dmapp/tests
python3 test_dmapp.py

Angular Frontend

cd dmapp/dmfnt

# Install dependencies
npm install

# Development server
npm run start

# Build for production
npm run build

# Run tests
npm run test

System Setup

The application requires:

MongoDB running locally
wmctrl installed (apt install wmctrl)
X11 desktop environment (not Wayland)
Python virtual environment recommended

Key Configuration

Workspace Labels: Edit desktops tuple in dmapp/dmcore/main.py:12 Work Desktop Mapping: Configure work_desktops dict in dmapp/dmcore/main.py:13 Timezone: Set in dmapp/dmcore/main.py:19 using zoneinfo

Development Notes

The system enforces task constraints within work desktops - switching to a non-work task automatically reverts to the designated work task
Task files are monitored for changes to enable automatic context switching
Web interface runs on port 10000 by default
Core daemon sleeps for 2 seconds between workspace checks

2.7 KiB Raw Blame History