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

```bash
# 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:

```bash
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