# 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

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

### Angular Frontend

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

## Tool Development Guidelines

- This is a personal tool, not professionally developed
- reuse as it is as much as possible unless refactor is required explicitly, suggest improvements
- Only modify existing code if it absolutely doesn't make sense to add a new flow