GrotTrack¶
GrotTrack is a local-first, automatic time-tracking app for macOS. It runs in the menu bar, polls the frontmost application every few seconds, captures periodic screenshots, and — with an optional Chrome extension — records the active browser tab. Everything is written to a SwiftData store on disk; nothing is sent to a remote server.
The project is built for Grafana Labs employees, but the source is public and the architecture is generic macOS time tracking with no dependency on any Grafana product.
The source, issues and releases live on GitHub.
Three components¶
GrotTrack ships as three things that work together:
| Component | What it is | Where it runs |
|---|---|---|
| GrotTrack.app | The menu bar app: SwiftUI, SwiftData, all tracking and reporting logic | On the user's Mac, as a background (LSUIElement) app |
| GrotTrackNativeHost | A small CLI tool embedded at GrotTrack.app/Contents/MacOS/GrotTrackNativeHost | Launched as a subprocess by Chrome via the native messaging protocol |
| GrotTrack Tab Tracker (Chrome extension) | A WXT/TypeScript MV3 extension that reports the active tab | Inside Chrome, communicating only with the native host on the same machine |
The app and the native host are both built from one Xcode project (GrotTrack.xcodeproj, generated by XcodeGen from project.yml); the extension is a separate TypeScript project. See Architecture for how the three pieces fit together and Native Messaging for the protocol between the extension and the host.
Platform requirements¶
- macOS 26.0 (Tahoe) or later — the deployment target set in
project.yml - Xcode 26 and XcodeGen to build the app
- Node.js 20+ to build the Chrome extension
- Google Chrome, only if the browser-tab tracking feature is used
Project status¶
GrotTrack is an active, versioned project using release-please for releases and Conventional Commits for its history. See Releasing for the release pipeline and Changelog for what has shipped.
Where to go next¶
- Architecture — how the app, native host and extension fit together, and where data is stored
- Native Messaging — the wire protocol between the extension and the host
- Extension — what the Chrome extension observes and why it needs each permission
- Building — building the app and extension from source, and running the tests
- Privacy — the data-handling model
- Contributing — working on the codebase