106 lines
3.0 KiB
Markdown
106 lines
3.0 KiB
Markdown
# 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 |