Takt

Track time without losing your rhythm. A native macOS time tracker that lives in your menu bar, keeps every byte on your Mac, and books time straight into Azure DevOps.

Website · Design · Features · Architecture · Install · Getting started · Documentation · Contributing · License

[!NOTE] Takt is pre-release. Phases 1–4 are largely implemented, including the working time record under German labor law with flextime, overtime and vacation accounts. Still open are Entra ID sign-in, the Outlook calendar, signed and notarized builds with automatic updates and a desktop widget. Releases ship an unsigned Apple Silicon build; see Install.

Why Takt

Time tracking usually happens after the fact and from memory, because starting, switching and booking cost too many clicks. Takt makes it as casual as glancing at a clock:

• Zero friction. The goal: a timer running in under two seconds, without touching the mouse.
• Local-first and private. No cloud and no backend. Your entries stay in a SQLite file on your Mac.
• Honest time. Pauses, idle time and parallel work are recorded explicitly instead of being smoothed over.
• Native. Swift 6, SwiftUI and AppKit. It feels like an Apple app and stays light on resources.
• No double entry. Tracked time becomes analytics and Azure DevOps bookings without re-typing it.

Features

Menu bar first	Start, switch, pause and stop from a popover. Open it with a global shortcut (default ⌥⇧T), search, press Enter. Type @category, /project or #tag while starting, or #4821 to find a work item.
Main window	Day timeline and week grid: draw, drag and resize entries, move them to another day, delete by right-click, undo with ⌘Z. Plus an editable entry list, full-text search and a ⌘K command palette.
Parallel timers	Run several timers at once and count overlapping time as full or split by weight (e.g. 70/30), globally or per entry.
Pauses and idle detection	Per-timer and global pauses. When you come back from an idle period, keep, discard, count as pause or reassign the time, or decide later.
Stop panel	Stopping is instant, with an undo toast. Make project, category or work item required, and Takt asks for them before it stops; ⌥-click opens the panel any time.
Themes	Pick a color scheme in the settings: Takt, GitHub, SAP Fiori Horizon, Tokyo Night, Aura Dark, Panda, Dracula, One Dark, Nord or Catppuccin Mocha, light, dark or following the system. Every theme keeps readable contrast.
Rules	Assign category, project and tags automatically, for example "work item type Bug → category Support".
Azure DevOps	Search work items with a compact preview (state, iteration, effort), current sprint first, get suggestions from your checked-out Git branch, and book time back as differences that stay correct when you edit entries later. The day close lists what to book; uncheck what should wait.
Analytics	Stacked bars, distributions, top work items, heatmap, focus blocks and context switches, compared with the previous period and summed up in one sentence. Export CSV, Excel, JSON and a PDF report against your weekly target hours.
Working time record	Built for German labor law (ArbZG): start, end, breaks and net time per day with checks for maximum hours, breaks and rest periods, public holidays per state, a change log, flextime, overtime payouts, vacation account, export as PDF, CSV or Excel, and a monthly archive as PDF with a SHA-256 checksum.

Architecture

Eight modules in five layers. Dependencies only ever point downwards, and the domain layer knows nothing about Apple frameworks, so TaktCore and TaktStore are also tested on Linux in CI.

A few rules shape the codebase:

• Raw data, not derivations. Only time segments are stored (UTC milliseconds). Counting mode, rounding and booking amounts are computed at query time, so history stays correctable.
• Time only through TaktClock. Tests run on a manual clock, never on the wall clock.
• One command, one transaction. The timer engine writes exclusively through TimerStore.update(_:).
• Differential bookings. Azure DevOps updates are test /rev patches with a sync_record, never absolute values, so they are idempotent and reproducible.
• Secrets in the Keychain only. Titles, notes and tokens never appear in logs.

The full picture is in the technical concept.

Install

With Homebrew, from the nimble-123/tap tap:

brew tap nimble-123/tap
brew install --cask takt

Update with brew upgrade --cask takt. Every release updates the cask automatically, usually within minutes.

Or download Takt-<version>-arm64.dmg from the latest release and drag Takt into Applications. It runs on Apple Silicon with macOS 26 or later.

Command line

The Homebrew cask links the takt command automatically. With the DMG, open Settings → Command line → Install … to link it to /usr/local/bin. Then try takt --help:

takt status                                   # running and paused timers
takt start "Code review @Review /Portal #qa"   # start, with category, project and tag
takt start 4821 --parallel                    # a work item, next to the running timer
takt stop                                     # stop everything; takt stop review stops one
takt log --week                               # this week's entries
takt report --month --by category --json      # totals for scripts

Exit codes: 0 success, 1 invalid input, 3 nothing running or paused, 4 not found, 5 ambiguous. For zsh completion, run takt --generate-completion-script zsh > ~/.zfunc/_takt and add ~/.zfunc to your fpath.

Import an Excel timesheet

To bring hours recorded in the German Excel template „Zeiterfassungstabelle … Vollzeit V2“ into Takt once, convert it to JSON and import it. The import only adds: days that already have time in Takt are skipped and listed, and nothing is booked to Azure DevOps.

uv run --with openpyxl scripts/timesheet-to-json.py Zeiterfassung.xlsx ~/timesheet.json
takt import ~/timesheet.json --dry-run    # counts, skipped days, flex time per month: Excel vs. Takt
takt import ~/timesheet.json --settings   # import; also takes over weekly hours, state, flex balance and vacation days
takt import --remove                      # undo the import, e.g. to run it again with --distribute

The database is backed up first. Options: --until 2026-09-30, --category Development, --distribute Meeting=30,Development=70. Details are in the technical concept.

[!IMPORTANT] These builds are not signed or notarized yet, so macOS blocks the first launch. Open System Settings → Privacy & Security and click Open Anyway, or run xattr -dr com.apple.quarantine /Applications/Takt.app. After each update macOS asks again for access to the Keychain.

To check that a download was built by this repository's release workflow, verify its build provenance with the GitHub CLI:

gh attestation verify Takt-<version>-arm64.dmg --repo nimble-123/takt

Getting started

Build from source. Requirements: macOS 26, Xcode 26 and XcodeGen.

brew install xcodegen
xcodegen generate            # creates Takt.xcodeproj (not checked in)
open Takt.xcodeproj

Run the package tests without opening Xcode:

swift test --package-path Packages/TaktKit

Try it with sample data

scripts/run-local.sh                          # build and start with your real data
scripts/run-local.sh --test --seed            # separate data folder ~/takt-test with two weeks of sample entries
scripts/run-local.sh --test --seed --clean    # recreate the sample data
scripts/run-local.sh --no-build --logs        # start without building and follow the log

In test mode your entries stay separate. Settings, Azure DevOps connections and the Keychain are shared with the real app. scripts/run-local.sh --help lists all options.

Documentation

The project documentation is written in German.

Document	Contents
PRD	Goals, requirements with IDs, release plan, decisions
Technical concept	Modules, database schema, timer engine, Azure DevOps booking flow, tests
Design	Screens, colors, typography, interaction rules
UI designs	Read-only gallery of all screens; edited on the design canvas
Releasing	Versioning, release PRs, signing and notarization
MDM	Managed settings and rollout with Intune or Jamf
CLAUDE.md	Working rules for Claude Code and everyone else

Contributing

Contributions are welcome. Work is tracked in issues and four milestones: Phase 1 · Erfassen, Phase 2 · Azure DevOps, Phase 3 · Ausbau and Phase 4 · Nachweis.

1. Pick or open an issue and branch from main as feat/<issue>-<name> or fix/<issue>-<name>.
2. Keep PRs small, one topic each, and reference requirement IDs from the PRD (e.g. TM-05).
3. Run swift test --package-path Packages/TaktKit and scripts/format.sh (SwiftFormat and SwiftLint, Airbnb style) before you push.
4. PR titles follow Conventional Commits and are squash-merged. release-please creates versions, tags and the changelog automatically.

License

MIT © 2026 Nils Lutz