Track Your Time

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 for macOS, Windows and Linux. Self-host images are published through v0.3.0. The phone apps are in testing channels. Release readiness records the remaining distribution checks.

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 and OpenAPI document describe its public routes. docs/deploy.md explains the topology and why the domain moved.

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.

Where things live

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.
• 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 covers the setup, including a single-node replica set for the self-host compose file.
• A workspace switcher in the app shell. Each client keeps its own choice and names the workspace on every request.
• Invoices are limited to owners and admins who may see both time and money.

Data in and out

• Import from a delimited file. Headers are matched to roles by an alias table and the values decide the granularity, so it is column shapes rather than vendor-specific formats. Day/month order is decided per file and stated on screen when nothing in the data settles it.
• Preview then commit. The commit re-parses the same input rather than trusting the preview it handed back, so a tampered preview cannot write something you never approved.
• Every import is one undoable batch, deleted by an indexed id — and refused if any of its entries have since landed on an invoice.
• Workspace export: JSON (lossless — colours, archived rows, project rates, the business profile, catalog referenced by name so it restores into an empty or different workspace) and CSV (written in the exact column shape the importer reads back).
• Move to another server (Settings → Data): the same export and import, driven from one device, hosted → self-hosted and back.
• REST API and webhooks. /api/v1 covers entries, clients, projects, tasks, tags, reports and the current user, with scoped API tokens, an OpenAPI document and RFC 9457 errors. Signed webhooks report entry and invoice events. See docs/api.md and the MCP server.

Platform

• Realtime multi-device sync over WebSocket on the same Express process. The upgrade is authenticated, a socket joins only its own account's room, and a revoked session closes its socket within a minute.
• Offline queue in the web app, the phone apps, the browser extension and Raycast: entry mutations made offline are queued and replayed in order on reconnect, with optimistic temporary ids until the server answers. Each queued row records the account, workspace and server it was queued for, and replays only there.
• Sign-in for clients without a cookie jar. Every first-party client signs in normally and sends the resulting session token as Authorization: Bearer <token>; clients that cannot show a form (Raycast, a CLI) use the RFC 8628 device flow, approved in an already signed-in browser. Sessions are named by their client under Settings → Devices, where any of them can be revoked. API tokens are a separate credential, for the REST API only.
• Account security: TOTP two-factor with backup codes, change password, change email, and account deletion from Settings → Account. Email verification is required whenever the server has a mail transport.
• English and German in the web app, the phone apps, the browser extension, invoices, report PDFs and email, plus German public pages under /de/. Raycast stays English.
• Split settings: money and calendar conventions per workspace (default rate, currency, week start), rendering per user (12h/24h, h:m:s vs decimal, theme, language).
• Profile pictures: add, replace or remove a picture from Settings → Account or Profile. The server stores the image in MongoDB.
• Optional Google sign-in (web form, or browser approval for desktop and Raycast), optional Sentry/GlitchTip error reporting, optional Listmonk + SES newsletter double-opt-in.

Clients

Not there yet

• Most store listings are pending. The Chrome Web Store and Firefox Add-ons list the extension. The App Store, the Mac App Store, Google Play and the Raycast Store do not list the apps yet, and there is no Microsoft Store build. Desktop downloads come from GitHub Releases only; docs/release-readiness.md records what each listing still needs.
• Sign-up cannot be closed in the app. Anyone who reaches a server can register. The self-hosting guide shows how to block the sign-up endpoint at the proxy.
• No client portal or shared reports. A client cannot sign in or open a link to follow a project. Send them a report or an invoice as a PDF.
• Two-factor codes cannot be entered in the password form of the phone apps, the desktop app or the extension. The second step needs a cookie those clients cannot send. Each of them signs in through a browser instead: "Sign in with your browser" in the phone and desktop apps, "Sign in with the web app" in the extension, and Raycast's own sign-in. You approve the sign-in in a browser, which also covers Google accounts.
• Time off, PTO, holidays, absence. No model and no screen, so nothing computes capacity or utilization.
• Email notifications to you are one reminder per runaway timer, and only if you turn it on under Settings, Limits. No web push and no digests.

Self-hosting

One VPS, one domain, one command. docker-compose.selfhost.yml brings up Caddy, the API, the static web app, Mongo and Redis, with Caddy terminating TLS and routing /api/*, including /api/ws, to the server and everything else to the client.

cp .env.selfhost.example .env

Set APP_DOMAIN and APP_URL to your domain, generate BETTER_AUTH_SECRET, then:

docker compose -f docker-compose.selfhost.yml up -d

docs/self-hosting.md is the full manual: prerequisites, first run, SMTP, backup and restore, upgrades, and troubleshooting.

Which compose file is which

The service names server and client are load-bearing under Coolify — it keys routing by them. Do not rename them.

Under the self-host layout the client image is built with an empty NEXT_PUBLIC_API_URL, so every call the browser makes is same-origin and the image works on anybody's domain. That is why it is published separately as ghcr.io/trebeljahr/trackyourtime-client-selfhost — the hosted client image bakes in the maintainer's own API host.

TRUSTED_ORIGINS

A single-domain self-host does not need this at all: the browser's origin is FRONTEND_URL. It matters when something other than that domain signs in.

better-auth validates the Origin header on sign-in whenever the request carries Sec-Fetch-* headers, which every real browser fetch does. A browser origin that is not FRONTEND_URL gets 403 INVALID_ORIGIN before the password is checked. Add, comma-separated, whichever apply:

• chrome-extension://<id> — a browser extension you built yourself (pnpm run extension:id prod prints it)
• capacitor://localhost,https://localhost — the iOS and Android apps
• app://- — the desktop app, which serves its bundle from that privileged scheme (file:// would send Origin: null, which cannot be trusted with credentials)

Or set TRUST_STORE_APPS=true, which trusts the iOS and Android apps, the desktop app and the Chrome Web Store extension (its id is pinned in packages/shared/src/store-clients.ts) in one switch. docker-compose.selfhost.yml defaults it to true, so the store builds can sign in to a self-hosted server with nothing to configure. The extension's site access covers only the hosted API, so every request it sends to your server is a cross-origin request: without this trust it cannot sign in, sync or send an entry.

Raycast and CLI clients need nothing here — their requests carry neither Origin nor Sec-Fetch-*. What guards them is the device flow plus the client-id allowlist in packages/server/src/auth/client-label.ts.

MCP server

packages/mcp is a Model Context Protocol server over the public REST API (/api/v1). An assistant can read the running timer, start and stop it, log past time, list and search entries, list and create clients, projects, tasks and tags, and run the summary report. There are no invoice tools, because v1 has no invoice routes.

It authenticates with a personal API token from Settings → Integrations → API tokens, and offers only the tools that token's scopes allow. It works against the hosted API or any self-hosted origin.

npx -y trackyourtime-mcp --version

claude mcp add trackyourtime --env TRACKYOURTIME_API_TOKEN=tt_your_token -- npx -y trackyourtime-mcp

TRACKYOURTIME_API_URL defaults to https://api.trackyourtime.dev; set it to your own origin for a self-hosted instance. Claude Desktop and other clients, the tool list and the error table are in docs-site/docs/mcp.md.

To build from a local checkout, run pnpm install && pnpm build:mcp. Use node with the absolute path to packages/mcp/dist/index.js in your client configuration.

Development

Requires Node 24 (.nvmrc), pnpm 11 via corepack, and Docker for the local infra.

corepack enable
nvm install && nvm use

git clone https://github.com/trebeljahr/trackyourtime.git && cd trackyourtime
pnpm install

# REQUIRED — .env.development is not tracked, so create it from the example
cp packages/server/.env.example packages/server/.env.development
# then set BETTER_AUTH_SECRET in it to any 32+ character string

pnpm run dev:infra     # Mongo 27017, Redis 6379, SeaweedFS S3 9000 (docker)
pnpm run dev           # client 3392, API 5159

Open http://localhost:3392.

pnpm run dev pins those ports on purpose: the browser extension, Raycast and any native build bake their API URL in and cannot follow a port that moves. Variants:

pnpm run dev:auto            # every port auto-picked — use this for a second instance
pnpm run dev:fixed           # the pinned ports, or exit
pnpm run dev:docs            # also runs the docs site on 4000
node scripts/dev.mjs --dry-run   # print the resolved ports, start nothing

Inside a git worktree, pnpm run dev behaves like dev:auto so parallel checkouts do not fight over the pinned ports — which also means the extension and Raycast will not find the server there unless you run dev:fixed or point them at the printed ports.

Other clients:

pnpm run dev:extension       # browser extension, dev target (localhost:5159)
pnpm run build:extension     # dist/       -> http://localhost:5159
pnpm run build:extension:prod # dist-prod/ -> https://api.trackyourtime.dev
pnpm run build:extension:firefox # Firefox MV3 build
pnpm run extension:id [dev|prod]  # the chrome-extension:// origin to trust

pnpm run dev:raycast         # ray develop
pnpm run dev:desktop         # Next dev + an Electron window (UI only; see the note below)
NEXT_PUBLIC_API_URL=http://localhost:5159 pnpm run electron:preview  # packaged app over app://-

Testing

pnpm run test:unit      # core, server (node:test), MCP and extension suites — no services needed
pnpm run test:client    # Vitest suites in the client — jsdom, no services needed
pnpm run test:e2e       # Playwright specs — REQUIRES DOCKER
pnpm run test:mcp:integration  # MCP server over a real API — starts its own mongod
pnpm run test:e2e:desktop      # the Electron app over app://- — starts its own mongod and API
pnpm test               # all three in sequence

pnpm run typecheck      # builds shared + core, then tsc --noEmit everywhere else
pnpm run build          # shared -> core -> server -> client

The E2E suite starts its own Mongo, Redis and S3 containers on separate ports and runs against the static export, not the dev server, so the first run includes a full client build. It needs Docker and a one-off npx playwright install chromium. CONTRIBUTING.md has the details, including the port and database variables you must set if another checkout is running the suite at the same time.

Project

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup and the pull request process, and ROADMAP.md if you are looking for something to pick up.

Commits must be signed off under the Developer Certificate of Origin 1.1 — git commit -s adds the Signed-off-by trailer. There is no CLA.

License

Licensed under the GNU Affero General Public License, version 3 or later (AGPL-3.0-or-later). See LICENSE.

The Raycast extension, including the core/shared code copied into its package, is available under the MIT license.

Track Your Time is an application you run, not a library you link. Running an unmodified copy internally does not require publishing your own software. If you modify it and let others use that version over a network, offer those users its corresponding source under the AGPL. See GOVERNANCE.md for the contribution policy and TRADEMARK.md for the name and logo rules.

The code is AGPL; the Track Your Time name, logo and domain are not — see TRADEMARK.md.