# TimeTagger

Tag-based personal time tracker with a documented web API that mirrors the hosted timetagger.app.

TimeTagger is a lightweight time tracker for individuals and freelancers: an interactive timeline, tags instead of projects, targets, Pomodoro and PDF/CSV reports. The Python server runs from pip or Docker and is configured with TIMETAGGER_* environment variables. The Builder documents a records/settings/updates web API with API tokens, identical on self-hosted servers and the EUR 3 per month hosted edition.

Alternative to: Toggl Track, Harvest

- Capabilities: adaptable, operable
- Vertical: scheduling-staffing
- Shape: business-app
- Form factor: web-app
- Execution model: deterministic
- Provenance: human-written (recorded, never ranked)
- Repo: https://github.com/almarklein/timetagger (GPL-3.0), 1779 stars, last commit 2026-05-17
- Last activity: 2026-05-17
- Page: apps/almarklein--timetagger.html
- JSON: apps/almarklein--timetagger.json

## Use it when

- I'm a freelancer who wants a fast timeline-style tracker on my own box, with tags instead of a project hierarchy
- I want my agent to log what I worked on and pull the week's records over a small token-authenticated API

## Gotchas

- GPL-3.0 plus a CLA granting the author rights to use contributions in the hosted service
- Built for individuals: no teams, clients or invoicing; multi-user means separate credential entries, not shared data
- Last push 2026-05-17, inside the window but the slowest cadence on this shortlist
- API tokens never expire; reports and exports are not reachable through API

## Editions

- Self-hosted: Free, open source
  - source: https://github.com/almarklein/timetagger
  - installable: pip install -U timetagger && python -m timetagger
  - container: https://github.com/almarklein/timetagger/pkgs/container/timetagger
- timetagger.app: €3 per month, closed source
  - hosted: https://timetagger.app

## Adaptable: make it yours

Effort: config-only (11 things to edit)

Everything is an environment variable or CLI flag: TIMETAGGER_BIND, TIMETAGGER_DATADIR, TIMETAGGER_CREDENTIALS (bcrypt user:hash pairs) for multi-user, TIMETAGGER_PROXY_AUTH_ENABLED, TIMETAGGER_PROXY_AUTH_TRUSTED and TIMETAGGER_PROXY_AUTH_HEADER to sit behind Authelia or similar, TIMETAGGER_PATH_PREFIX and TIMETAGGER_APP_REDIRECT. deploy/docker-compose.yml is the Docker path. For custom auth (JWT, OAuth) the libapi docs show a short Python run script overriding authenticate() and api_handler_triage().

- Env vars: TIMETAGGER_BIND, TIMETAGGER_DATADIR, TIMETAGGER_LOG_LEVEL, TIMETAGGER_CREDENTIALS, TIMETAGGER_PROXY_AUTH_ENABLED, TIMETAGGER_PROXY_AUTH_TRUSTED, TIMETAGGER_PROXY_AUTH_HEADER, TIMETAGGER_PATH_PREFIX, TIMETAGGER_APP_REDIRECT
- Config files: deploy/docker-compose.yml, deploy/docker-compose.nonroot.yml
- Prompt files: none
- Accounts you'll need: timetagger.app (hosted edition only)

## Operable: what an agent can drive

Operability: official. Interface: api at https://timetagger.readthedocs.io/en/latest/webapi/ (published by the builder, both).

### Reach (partial coverage)

- Read time records for a date range: reachable. webapi: GET records with range and tag filters
- Create and edit records: reachable. webapi: PUT records accepts new or edited record objects
- Start and stop a running timer: reachable. webapi: records can be filtered by running state; a running record is written with PUT
- Delete a record: reachable. webapi: prefix the description with HIDDEN, the convention clients honour
- Read and change settings: reachable. webapi: GET and PUT settings
- Sync incrementally: reachable. webapi: GET updates since a timestamp
- Generate PDF or CSV reports: not reachable. webapi documents no report endpoint; reports are produced client-side from records
- Set daily, weekly or monthly targets: undetermined. targets live in the client; not stated whether they are in the settings object
- Pomodoro timer: not reachable. client-side feature

## Code stack

- Languages: Python
- Frameworks: asgineer, uvicorn, itemdb, PScript
- Package manager: pip
- Database: SQLite
- Hosting target: docker, pypi

## Evidence and confidence

- formFactor: README: web-based time tracker served by a Python server, runs locally or on a server (confidence 0.95)
- executionModel: no model SDK or AI feature (confidence 0.95)
- operability: timetagger.readthedocs.io/en/latest/webapi/ published by the Builder; same endpoints on timetagger.app (confidence 0.9)
- effort: timetagger.readthedocs.io/en/latest/libapi/ lists TIMETAGGER_* variables; README shows credential and proxy-auth examples (confidence 0.9)
- editions: README: pip and Docker self-host under GPL-3.0; timetagger.app account EUR 3 per month (confidence 0.9)
- active: shortlist pushedAt 2026-05-17
- reach:  (confidence 0.8)

## Open questions

- Are targets stored in the settings object and therefore reachable through PUT settings?
- Does the hosted edition expose API tokens on every plan?

## Sources

- https://github.com/almarklein/timetagger (sourcing:scheduling-staffing:curated)
- https://timetagger.readthedocs.io/en/latest/libapi/ (sourcing:scheduling-staffing:curated)
- https://timetagger.readthedocs.io/en/latest/webapi/ (analysis:scheduling-staffing)