managarten/services/matrix-clock-bot/CLAUDE.md

Matrix Clock Bot - Claude Code Guidelines

Overview

Matrix Clock Bot provides time tracking functionality via Matrix chat. Users can create timers, set alarms, and manage world clocks through text commands or voice notes.

Tech Stack

• Framework: NestJS 10
• Matrix: matrix-bot-sdk
• Backend: Clock API (port 3017)
• STT: mana-stt service (port 3020)

Commands

# Development
pnpm install
pnpm start:dev        # Start with hot reload

# Build
pnpm build            # Production build

# Type check
pnpm type-check       # Check TypeScript types

Project Structure

services/matrix-clock-bot/
├── src/
│   ├── main.ts               # Application entry point (port 3317)
│   ├── app.module.ts         # Root module
│   ├── config/
│   │   └── configuration.ts  # Configuration & help messages
│   ├── bot/
│   │   ├── bot.module.ts
│   │   └── matrix.service.ts # Matrix client & command handlers
│   ├── clock/
│   │   ├── clock.module.ts
│   │   └── clock.service.ts  # Clock API client
│   └── widget/
│       ├── widget.module.ts
│       └── widget.controller.ts  # Timer widget for Element sidebar
├── Dockerfile
└── package.json

Bot Commands

Timer Commands

Command	Description
!timer 25m	Create & start 25-minute timer
!timer 1h30m	Create 1.5 hour timer
!timer 25m Pomodoro	Timer with label
!stop	Pause running timer
!resume	Resume paused timer
!reset	Reset timer to start
!status	Show current timer status
!timers	List all timers
!widget	Add timer widget to room sidebar

Alarm Commands

Command	Description
!alarm 07:30	Set alarm for 7:30
!alarm 7 Uhr 30	German time format
!alarm 06:00 Aufstehen!	Alarm with label
!alarms	List all alarms

World Clock Commands

Command	Description
!zeit / !time	Current time + world clocks
!weltuhr Berlin	Add world clock
!weltuhren	List world clocks

Natural Language & Voice

The bot understands natural language:

• "Timer 25 Minuten"
• "Wecker um 7 Uhr"
• "Stop"
• "Status"

Voice notes are transcribed and parsed as commands.

Environment Variables

# Server
PORT=3317

# Matrix
MATRIX_HOMESERVER_URL=http://localhost:8008
MATRIX_ACCESS_TOKEN=syt_xxx
MATRIX_ALLOWED_ROOMS=#clock:matrix.mana.how
MATRIX_STORAGE_PATH=./data/bot-storage.json

# Clock Backend API
CLOCK_API_URL=http://localhost:3017/api/v1
CLOCK_API_TOKEN=

# Speech-to-Text
STT_URL=http://localhost:3020

# Widget (public URL for embedding in Matrix clients)
WIDGET_PUBLIC_URL=http://localhost:3317/widget

Clock API Endpoints Used

Endpoint	Method	Description
/timers	GET	List all timers
/timers	POST	Create timer
/timers/:id/start	POST	Start timer
/timers/:id/pause	POST	Pause timer
/timers/:id/reset	POST	Reset timer
/alarms	GET	List alarms
/alarms	POST	Create alarm
/alarms/:id/toggle	PATCH	Toggle alarm
/world-clocks	GET	List world clocks
/world-clocks	POST	Add world clock
/timezones/search	GET	Search timezones (public)

Widget

The bot provides a timer widget that can be embedded in Matrix/Element rooms.

Widget Endpoints

Endpoint	Description
GET /widget	HTML page with timer display
GET /widget/api/status?userId=X	Timer status JSON
GET /widget/api/control?userId=X&action=Y	Control timer (start/pause/reset)

Adding Widget

1. Use !widget command - bot adds widget automatically
2. Or manually: /addwidget <WIDGET_PUBLIC_URL>

Widget Features

• Live timer progress bar with countdown
• Start/Pause/Reset controls
• Auto-refresh every 10 seconds with local countdown
• Dark theme matching Element

Docker

# Build
docker build -f services/matrix-clock-bot/Dockerfile -t matrix-clock-bot services/matrix-clock-bot

# Run
docker run -p 3318:3318 \
  -e MATRIX_HOMESERVER_URL=http://synapse:8008 \
  -e MATRIX_ACCESS_TOKEN=syt_xxx \
  -e CLOCK_API_URL=http://clock-backend:3017/api/v1 \
  -e STT_URL=http://mana-stt:3020 \
  -v matrix-clock-bot-data:/app/data \
  matrix-clock-bot

Health Check

curl http://localhost:3318/health

Authentication

Currently uses a demo token (CLOCK_API_TOKEN) for development. Production should implement proper user authentication flow:

1. User sends !login command
2. Bot initiates OAuth/auth flow with mana-core-auth
3. User token stored per Matrix user ID
4. Token used for all Clock API calls