UsageOS is a private, on-device time tracker. It runs quietly in the background, keeps track of which app and window you're using, and shows you where your time actually went — by the hour, and by the kind of work it was. Everything stays on your machine — macOS is the first platform it runs on.

What it shows

• A day dial. Your whole day on a 24-hour clock, with each stretch coloured by the kind of work it was.
• A daily recap. A few plain sentences about your day, written on your machine.
• A week and a timeline. Seven days side by side, and a scrollable list when you want the detail.
• Two ways to read it. By category — work, browsing, messaging, entertainment, personal — and by project, recognised from the repo you're working in, so the same work doesn't fragment across your editor, terminal, and browser.

Privacy

• Nothing leaves your machine. No cloud, no account, no telemetry, and no network calls in the data path. It's open source, so you can read the code and check for yourself.
• Your data is one file — a local SQLite database on your machine. Export it or delete it whenever you want.
• It never uses screen recording. It reads window titles and, if you allow it, the address of the page open in your browser. That's all it reads.
• You stay in control. For incognito and private windows, no title or URL is ever stored. You can leave any app or site out completely, or mark one private so it still counts the time but hides the title — your password manager or bank included.

Permissions

UsageOS asks for two macOS permissions. Both are optional — it still works without them, just with less detail.

• Accessibility — to read the title of your active window, so it can tell what you were working on, not just which app was open.
• Automation — to read the address of the current browser tab, so browsing shows the actual site instead of just “browsing.” Private windows are never read.

It never asks for Screen Recording.

Install

Homebrew:

brew install --cask f-gozie/tap/usageos

Or download directly: grab the latest signed, notarized Universal DMG from the Releases page, open it, and drag UsageOS into Applications. Universal · macOS 13+ · ~15 MB.

Either way, UsageOS can keep itself up to date — automatic checks are opt-in (off by default; enable them in onboarding or Settings), and every update is signed. Or build it from source below — it's a normal Tauri app.

Build from source

Requirements

• macOS
• Rust (stable)
• Node.js 22 or newer
• Xcode Command Line Tools — xcode-select --install

Run it

npm install
npm run tauri dev

Build a release

./sidecar/build.sh      # builds the recap helper → src-tauri/binaries/usageos-ai
npm run tauri build

The daily recap can use Apple's on-device model (Foundation Models, macOS 26). When that isn't available, UsageOS writes a plain recap instead — nothing else changes.

Develop

cargo test --manifest-path src-tauri/Cargo.toml   # Rust tests
npm test                                           # TypeScript tests

Before a pull request, these checks must pass: cargo clippy -D warnings, cargo fmt --check, cargo test, tsc, and the generated IPC bindings must be up to date.

How it works

A Rust backend watches macOS for window and app changes through the native Accessibility and Automation APIs, works out the category and project, and stores everything in SQLite. A React and TypeScript frontend draws the dial and the rest of the interface. The recap is written by a small Swift helper using Apple's on-device model, with a plain-text fallback when it isn't available. The interface between Rust and the frontend is generated from the Rust side, so the two can't drift apart.

More detail is in context/architecture.md.

How this was built

UsageOS was built with Claude Code as a hands-on collaborator — I set the direction and reviewed the changes; a lot of the implementation is Claude's. The commit history, the decision log, and the plans and handoffs are kept as the real, unedited trail of how it actually came together — some commits are Claude-authored, all under review. The way it was made is part of what this repo is for.

Project docs

• What it is and why → context/vision.md
• Decisions → context/decisions.md
• Architecture → context/architecture.md
• Design system → context/design-system.md
• Engineering standards → context/standards/
• Feasibility & risk audit → context/feasibility/
• Plans → context/plans/
• Contributor & agent guide → CLAUDE.md

Contributing

Contributions are welcome — see CONTRIBUTING.md.

License

MIT — see LICENSE.