worklog: Self-Hosted Work Timer

worklog: a self-hosted work timer

A work and break timer with reports, for people who bill or track their hours and want the data on their own server. An optional day planner on top shows work meetings, calendars and care duties on one timeline, and protects evenings and training time. I wrote it to replace the spreadsheet I used as a time log.

GitHub repository →

worklog Day page: one timeline with work meetings, personal and family calendars and protected blocks, next to the running timer, top tasks and milestones, on synthetic demo data — The Day page, on synthetic demo data.

Screenshots

All screenshots use synthetic demo data.

Timer page with a running work block, week and balance cards, today's blocks and calendar proposals — Timer: the running block, today, the week, the balance, and meetings that have no block yet.

Week view with work meetings, personal and family events, approved run blocks and hard stops — Week: the calendar view with approved blocks and hard stops.

Pomodoro countdown at round 2 of 4 — Pomodoro: a countdown that offers to pause or resume the timer.

Reports page with summaries and charts of extra hours — Reports: extra hours and balance per period.

The Qt Quick app's Timer, Pomodoro and Reports tabs — The Qt Quick app (desktop and Android): Timer, Pomodoro and Reports. A desktop render of the same QML.

Timer page at phone width — The web timer at phone width.

Who it is for

Freelancers and employees who track hours, and anyone who wants a small, hackable timer instead of a subscription service. The timer works on its own. The day planner needs more setup (calendar snapshots, household rules, a few host jobs) and suits people comfortable with scripts and cron. Everything personal is configuration, nothing is hardcoded to one household.

What it does

Timer

Start, pause and stop work blocks, switch type or project, and see the day's blocks with the gaps between them. Meeting proposals can come from a work-calendar database.

Pomodoro

A per-device countdown that offers to pause or resume the timer at each interval. It never does so on its own.

Reports

Summaries per week, month, quarter and year, charts, weekly stats, an invoice view, and XLSX/CSV import and export. Expected and sick hours per day, with holidays from a cache file.

Day planner (optional)

A Day and a Week page with one timeline of work meetings, personal and family calendars, care duties and protected blocks. A capacity gate (green, amber, red) looks at rolling weeks of hours, wellness and training, and helpers answer "where does this fit" and "move this".

Other clients use the same JSON API: a Qt Quick app for desktop and Android, and a Garmin Connect IQ widget.

How it works

A FastAPI app with SQLite storage serves the web pages and a JSON API.
The container never holds credentials. It reads a state directory and writes requests to a queue in its database.
Three host jobs fill the state directory: a daily capacity verdict, a sync every two minutes (snapshots, the write queue, a Google Calendar mirror, an optional hard-stop nudge) and a weekly proposal of next week's blocks. They run without any integration and report what is missing.
Optional HTTP Basic login via a PBKDF2 password hash; optional Sentry error reporting.

Stack: Python, FastAPI, SQLite, Docker, a Qt Quick client, a Garmin Connect IQ widget, tests on an example household.

Run it

git clone https://github.com/alexgoldhoorn/worklog && cd worklog
uv sync
mkdir -p data
export WORKLOG_DB=./data/worklog.db TZ=Europe/Amsterdam
uv run uvicorn worklog.web.app:factory --factory --port 8503

Then open http://127.0.0.1:8503/timer. To require a login, generate a hash with uv run python -m worklog.auth and set WORKLOG_AUTH_USER and WORKLOG_AUTH_PASSWORD_HASH. A Dockerfile and an example compose file are included, and all settings are documented in docs/configuration.md in the repository.

MIT licensed.

README and source on GitHub →