---
title: GrotTrack
description: Automatic macOS time tracking with a native menu bar app, a Chrome native messaging host, and a local-first data model.
image: assets/social-card.png
---

# 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](https://github.com/rknightion/grotTrack)**.

## 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](architecture.md) for how the three pieces fit together and
[Native Messaging](native-messaging.md) 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](https://github.com/yonaskolb/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](https://github.com/googleapis/release-please)
for releases and [Conventional Commits](https://www.conventionalcommits.org/) for its history. See
[Releasing](releasing.md) for the release pipeline and [Changelog](changelog.md) for what has
shipped.

## Where to go next

- [Architecture](architecture.md) — how the app, native host and extension fit together, and where
  data is stored
- [Native Messaging](native-messaging.md) — the wire protocol between the extension and the host
- [Extension](extension.md) — what the Chrome extension observes and why it needs each permission
- [Building](building.md) — building the app and extension from source, and running the tests
- [Privacy](privacy.md) — the data-handling model
- [Contributing](contributing.md) — working on the codebase