deskmeter/CLAUDE.md

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 with dark mode UI
• dmfnt: Angular frontend (dmapp/dmfnt/) for enhanced UI (planned, not yet implemented)
• gnome-extension: GNOME Shell extension for displaying current task in the top panel

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 (large display with auto-refresh)
• /calendar/<scope>/<year>/<month>/<day>?grid=<1|3|6> - Google Calendar-style view with aggregated task blocks
  • Scopes: daily, weekly, monthly
  • Grid: Hour aggregation (1h, 3h, or 6h blocks)
  • Shows only active workspaces (Plan/Think/Work) with gaps for idle time
  • Cascading overlapping blocks for multiple tasks per time period
• /switches/<scope>/<year>/<month>/<day> - Raw switches view with proportional cell heights
  • Shows all workspace switches with time-based height visualization
• /work - Work projects breakdown for today
• /totals - All-time statistics
• /day/<month>/<day> - Single day view
• /period/<start>/<end> - Custom date range
• /api/current_task - JSON endpoint for current task info (used by GNOME extension)
• /api/today - HTML fragment for AJAX updates

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

Running the Web Interface

Use the dmweb.sh script for flexible deployment:

cd /home/mariano/wdir/run

# Syntax: ./dmweb.sh <worktree> <port> <debug>
./dmweb.sh dm-fend-updates 10002 1

# Parameters:
# - worktree: directory name in /home/mariano/wdir/ (default: dm)
# - port: Flask server port (default: 10000)
# - debug: 1 for debug mode with auto-reload, 0 for production (default: 0)

Angular Frontend (Not Yet Implemented)

The Angular frontend (dmapp/dmfnt/) mentioned in the architecture is planned but not currently implemented. All current functionality is in the Flask templates.

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 (configurable via dmweb.sh script)
• Core daemon sleeps for 2 seconds between workspace checks

UI/UX Design

Dark Mode Theme (applied across all views):

• Background: #1a1a1a
• Text: #e0e0e0
• Accent/links: #6b9bd1
• Borders: #444
• Component backgrounds: #2a2a2a

Calendar View Features:

• Hour-based aggregation (configurable: 1h, 3h, 6h grids)
• Overlapping task blocks cascade right and down (8% horizontal, 4px vertical per task)
• Only active workspaces shown (Plan/Think/Work) - idle time appears as gaps
• Task colors generated via hash-based HSL for consistency
• Height proportional to time spent in each grid period

Switches View Features:

• Cell heights proportional to switch duration (30px min, 200px max)
• Color-coded by task with hash-based HSL
• Dark backgrounds with reduced opacity for idle workspaces

Navigation:

• Consistent nav bar across all views: Today | Calendar | Switches | Work | All Time
• All views interconnected for easy movement between different data perspectives

GNOME Extension

A GNOME Shell extension displays the current task in the top panel:

• Location: gnome-extension/deskmeter-indicator@local/
• Polls /api/current_task endpoint
• Updates on workspace switch with 2.2s debounce
• Automatically truncates long task paths
• Installation: ./gnome-extension/install.sh or ./gnome-extension/update.sh

Key Implementation Details

Calendar Aggregation (dmapp/dmweb/get_period_times.py:get_task_blocks_calendar()):

• Aggregates switches by configurable time grid (1h, 3h, or 6h)
• Only includes active workspaces: Plan, Think, Work
• Returns blocks with task_id, task_path, start time, duration, and hour
• Filters out blocks shorter than min_block_seconds

Task Path Resolution:

• Primary: tasks collection (current tasks)
• Fallback: task_history collection (cached historical tasks)
• Last resort: On-demand file search in task directory
• Caching prevents repeated file I/O

Switch Height Calculation (switches view):

• Finds max delta in current view
• Heights scale linearly: base_height + (ratio * (max_height - base_height))
• Base: 30px, Max: 200px

Tool Development Guidelines

• This is a personal tool, not professionally developed
• Reuse existing code as much as possible unless refactor is required explicitly
• Only modify existing code if it absolutely doesn't make sense to add a new flow
• When adding features, maintain the dark mode theme consistency
• All new views should include the standard navigation bar