trackyourtime

# Track Your Time

Free, open-source time tracking for freelancers and small teams who bill by the hour.

Start a timer in the web app, the desktop app, the Chrome extension, Raycast on your Mac, or the iPhone and Android apps. Each one keeps counting without a connection and sends your changes when the connection comes back. Stop the timer on your phone, and your laptop shows it stopped.

At the end of the month, the hours become a report, a PDF invoice, or a ZUGFeRD or XRechnung e-invoice. Invite colleagues, and each person sees only their own time until you let them see more. Import a CSV from another tracker, take everything out as JSON or CSV, or connect other tools through the REST API.

There's no paid plan, now or later. Use the hosted version at <https://trackyourtime.dev>, or run the same app on your own server from one compose file. The desktop app, the extensions and the phone apps work with either, because each one asks for a server address.

The Chrome extension is in the Chrome Web Store, and Firefox 0.3.0 is public on Firefox Add-ons. Desktop version 0.2.2 downloads from [GitHub Releases](https://github.com/trebeljahr/trackyourtime/releases/latest) for macOS, Windows and Linux. Self-host images are published through v0.3.0. The phone apps are in testing channels. [Release readiness](docs/release-readiness.md) records the remaining distribution checks.

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)
[![build-and-deploy](https://github.com/trebeljahr/trackyourtime/actions/workflows/build-and-deploy.yml/badge.svg?branch=main)](https://github.com/trebeljahr/trackyourtime/actions/workflows/build-and-deploy.yml?query=branch%3Amain)

The product was called tracktime until September 2026. The repository, images, bundle ids and every other identifier were renamed to `trackyourtime` before the first release.

The hosted web app is at <https://trackyourtime.dev>, with the API on its own host at <https://api.trackyourtime.dev>. The [API reference](https://trackyourtime.dev/docs/api/reference/) and [OpenAPI document](https://api.trackyourtime.dev/api/v1/openapi.json) describe its public routes. [`docs/deploy.md`](docs/deploy.md) explains the topology and why the domain moved.

![The Track Your Time web app tracking time against a project](packages/client/public/marketing/web-track.png)

## What it is

A pnpm monorepo: one Express + tRPC API, one Next.js web client exported as static files, and shared packages (`shared`, `core`) that the extension, Raycast, the phone apps and the MCP server reuse. Two Docker images and a MongoDB are the whole production footprint; Redis is optional. There is no feature gate between the hosted version and a self-hosted one, and no telemetry you have not configured yourself.

Everything is scoped to a workspace. A person can belong to several, and a workspace can have many members — see [Teams](#teams).

## Where things live

| If you want to | Go to |
| --- | --- |
| Understand how the system fits together | [`ARCHITECTURE.md`](ARCHITECTURE.md) |
| Run it locally and open a pull request | [`CONTRIBUTING.md`](CONTRIBUTING.md), or [Development](#development) below for the short version |
| Run your own instance | [`docs/self-hosting.md`](docs/self-hosting.md) — one VPS, one domain, one `docker compose up` |
| Deploy it | [`docs/deploy.md`](docs/deploy.md) — the two-app, two-host Coolify topology and the four places that must agree on the API origin |

[Project](#project) below indexes the rest — roadmap, governance, support, security, and what `CLAUDE.md` and `docs-site/` are.

## Features

### Tracking

- **Timer with start / stop / continue / discard**, plus manual entry creation and editing. Entries carry a description, project, task, tags, a billable flag, a snapshotted hourly rate and currency, a source (web/desktop/mobile/extension/api/import) and the time zone they were recorded in.
- **Favorites and quick-start recents.** Favorites are reorderable one-tap job templates; quick-start collapses your recent entries into distinct combinations. Quick starts deliberately open untagged, so the same job tagged differently one day does not fragment the list.
- **Description autocomplete** from earlier entries, searched server-side. Tab takes the name; Cmd/Ctrl+Enter also takes the project, task, tags and billable flag.
- **Command palette** (Cmd/Ctrl+K) for timer actions, every page, and clients, projects, tasks and tags. Typing also searches entry descriptions, and choosing an entry opens it — for editing if it is yours, read-only if it is a colleague's. On a phone the palette opens from the More drawer.
- **Idle detection** with ask, pause-and-resume, keep-running or stop, and a per-project override.
- **Runaway-timer guard.** A maximum entry duration that asks, caps or stops a forgotten timer. A scheduler job (`services/scheduler/`) checks running timers every 5 minutes and sends one reminder email per timer; the lazy check on every read of the running timer stays as the fallback. `SCHEDULER_ENABLED=false` turns the job off.

### Catalog

- **Clients → Projects**, one two-level hierarchy. **Tasks** are workspace-wide and sit beside it, so an entry carries a project and a task as two independent references. **Tags** are a third dimension, many per entry.
- Full CRUD. Clients, projects and tasks have an archive toggle and a delete that always deletes — never the tracked time, though: entries and favorites are detached and survive as project-less rows. Tags follow a different rule: a tag that still labels tracked time is archived instead of deleted, and only an unreferenced tag is removed outright.
- Projects carry colour, client, billable default, hourly rate, estimated hours, a budget amount and currency, and an idle-behaviour override. A billing change can also reprice the project's un-invoiced entries.

### Views

- **Track** — the timer plus the day's entries.
- **Weekly timesheet grid** — rows of project + task, columns of weekday, editable cells. The edit rules are explicit and unit-tested: the running entry's cell is never writable, an empty cell creates exactly one entry, a single same-day entry has its end moved (typing 0 deletes it), and a midnight-crossing or multi-entry cell is refused read-only with a breakdown and a link through rather than guessing.
- **Calendar** — day, week, month and year views positioned by clock time, with drag editing, zoom, clustering for dense bursts of short entries, and an undo stack.

### Reports and money

- **One Reports screen with two views** over the same URL-backed filters: Totals (grouped by client, project, task, tag, member, day, week or month, with a zero-filled timeline and budgets; each group drills down into its entries) and Entries (paginated, sortable, bulk-editable, with totals that span the whole range). The old `/app/reports/summary`, `/detailed` and `/weekly` addresses redirect to it; the REST API still serves summary, detailed and weekly reports.
- **CSV and PDF export** for both views, paginating the full range so an export is never a page of what you were looking at.
- **Invoices** built from un-invoiced billable time. Preview rolls up line items without writing; creating an invoice re-gathers server-side rather than trusting the client's line items, assigns a per-year sequential number, and stamps the invoice onto every entry it billed. Draft/sent/paid status, PDF export, and a guard that refuses edits to entries already on an invoice.
- **Payments, credits and reminders.** Record payments against an invoice or credit it in full. Payment reminder emails to the client are opt-in per invoice and go out 1, 7 and 14 days after the due date.
- **Business profile and client billing details.** The issuer and recipient are copied onto the invoice when it is created, so a later address change does not rewrite a document a customer holds.
- **E-invoices.** An invoice also downloads as a ZUGFeRD PDF (PDF/A-3b with the EN 16931 XML embedded) or an XRechnung 3.0 XML file. CI runs every sample through the Mustang and KoSIT validators. See [`docs-site/docs/e-invoices.md`](docs-site/docs/e-invoices.md).
- **Project budgets and estimates** — a lifetime roll-up of hours and earnings against estimated hours and budget, computed from each entry's own snapshotted rate.

> Reporting grouped by tag gives each of an entry's tags that entry's **full** duration, so tag rows sum to more than the range total on purpose. The alternative — splitting a duration across tags — would invent time nobody spent. The screen says so where it happens; the report's own totals stay single-counted.

### Teams

- **Workspaces, members and invitations** through the `workspaces`, `members` and `invitations` tRPC routers. Invite by email, or copy the invitation link when the server has no mail transport. The public `/invite/?id=` page accepts it, before or after sign-in.
- **Roles** `owner`, `admin` and `member`, with ownership transfer. A workspace always keeps an owner.
- **Two visibility flags per member**: colleagues' time, and colleagues' money. Every surface answers both server-side — reports, entry lists, exports, the REST API and the sync socket, which sends each member only what they may see.
- **Member rates.** An owner or admin who may see money can give each member an hourly rate. A new billable entry takes its project's rate first, then its author's member rate, then the workspace default, and keeps that rate as a snapshot.
- **Timesheet approval**, off by default. A member submits a week, and an owner or admin who may see colleagues' time approves or rejects it. A submitted or approved week is locked against edits, and an invoice can be limited to approved time. Approval needs MongoDB with transactions (a replica set); [`docs/timesheet-approvals.md`](docs/timesheet-approvals.md) covers the setup, including a single-node replica set for the self-host compose file.
- **A workspace switcher** in the app shel