TokenAtlas

📊 Map your local AI coding usage — tokens, cost, sessions, and Git activity — in one native macOS menu-bar app.

💡 TokenAtlas reads the traces your AI CLIs already write to disk — no API keys, no account, no telemetry. It maps tokens, estimated cost, cache activity, sessions, and Git history for Claude Code, Codex, and more into one quiet, native macOS menu-bar app. Your data never leaves your Mac.

Demo

_{▶ Watch the full 60-second tour (1080p — adds the multi-provider, privacy & CTA scenes): tokenatlas-promo.mp4}

Table of Contents

• Features
• Highlights
• Quick Start
• Privacy
• Development
• Release and Auto-update
• Requirements
• Project Layout
• Design Notes
• Open Source
• Contributors
• Star History
• Contributing
• License

Features

• Menu-bar usage map — tokens, estimated cost, cache activity, recent sessions, and provider status, always one click away.
• Multi-provider by design — Claude Code and Codex today, with provider-specific quirks kept behind a clean adapter protocol so new CLIs slot in without touching shared code.
• Sessions and projects — inspect conversations, projects, messages, model mix, and personal records, entirely on-device.
• Repository activity — correlate AI coding usage with local Git history and bundled language statistics.
• Optional Notch Island — Atoll-backed glanceable panels for activity, stats, media, timers, clipboard, and more.
• Packaged auto-updates — Sparkle appcast delivery for manual checks and silent background updates.

Highlights

A quiet utility, not a marketing dashboard: restrained color, stable tables, readable numbers, and fast paths to the records that explain a workday.

Dashboard — your coding activity, day by day

Sessions, messages, total tokens, streaks, and peak hours at a glance, with a token trend you can read in a second.

Usage — tokens, cost, cache, and model mix

Cost and cache hit rate per period, broken down by model, for whichever provider you're looking at.

Sessions — every conversation, inspectable

Discovered conversations and projects with messages, model mix, and cache hit rate — drill into any single session.

Git activity — usage mapped to your commits

Correlate AI coding usage with local Git history and per-language statistics across your repositories.

More views — Activity, Switcher, Configs, Skills

Activity Focus timeline of when the work actually happened	Switcher Jump between providers and compare them side by side
Configs Browse the AI config files each CLI reads	Skills Your skill library, organized and searchable

Animated GIF demos of the menu-bar HUD live in docs/assets/screens.

Quick Start

Install a packaged build

1. Open the latest GitHub Release.
2. Download TokenAtlas-<version>.dmg.
3. Open the disk image and drag TokenAtlas.app to Applications.
4. Launch TokenAtlas — it lives in the menu bar.

Unsigned preview builds may need a right-click ▸ Open on first launch. See Installation and Releases for the zip fallback, the update feed, and the maintainer release flow.

Build from source

git clone --recursive https://github.com/can4hou6joeng4/TokenAtlas.git
cd TokenAtlas
brew install xcodegen
bash scripts/run-debug.sh

Already cloned without submodules? Pull them in:

git submodule update --init --recursive

Run the checks

bash scripts/run-tests.sh

Privacy

TokenAtlas is local-first. Core usage stats are read from local tool data such as ~/.claude/projects/ and ~/.codex/sessions/; optional activity and desktop-limit features may request macOS permissions such as Full Disk Access, Accessibility, or Screen Recording.

Network-facing features are opt-in or feature-specific: Sparkle checks for updates, provider status views may query public status pages, and browser-backed integrations may authenticate through the browser. Nothing is sent to a hosted TokenAtlas service — there isn't one.

Development

TokenAtlas.xcodeproj is generated from project.yml with XcodeGen. Use the helper scripts instead of opening stale build products:

bash scripts/run-debug.sh    # generate, build Debug, and launch
bash scripts/run-tests.sh    # Python + XCTest suites

The debug launcher builds into /tmp/TokenAtlas-build and launches by full path. This avoids Launch Services conflicts for the menu-bar (LSUIElement) app. For local daily use, install a separate bundle:

bash scripts/install-app.sh

Release and Auto-update

Maintainers cut releases by pushing a semver tag:

git tag v1.2.0
git push origin v1.2.0

The release workflow builds the app, packages a drag-install DMG, creates release notes from source commits, publishes archives to GitHub Releases, and updates the public Sparkle appcast when SPARKLE_PRIVATE_ED_KEY is configured. Signing and notarization inputs are documented in .github/workflows/release.yml.

Requirements

• Apple Silicon Mac with macOS 14+
• Xcode 26.4+ with Swift 6 language mode
• XcodeGen for project generation

Project Layout

TokenAtlas/       app entry point, providers, services, view models, and SwiftUI views
AtollEmbed/       app-side wrapper for the Atoll / DynamicIsland integration
ThirdParty/       git submodules for embedded upstream projects
TokenAtlasTests/  parser, scanner, settings, integration, and feature tests
docs/assets/      README images, icons, screenshots, and GIFs
scripts/          project generation, local run/test, release, and appcast tooling

Design Notes

Quiet by default, dense when needed. TokenAtlas should feel like a native macOS utility rather than a marketing dashboard: restrained color, stable tables, readable numbers, and fast paths to the records that explain a workday.

Provider-specific behavior lives under TokenAtlas/Providers/<Provider>/; shared rendering, formatting, and charts stay in common app layers. Adding a provider should be a provider folder, a Provider conformance, and one registry entry — nothing more.

Open Source

TokenAtlas is released under the GNU Affero General Public License v3.0. The app also embeds and adapts several major open-source projects:

Project	License	How TokenAtlas uses it
Atoll / DynamicIsland	GPL-3.0	Integrated through AtollEmbed for the optional Notch Island surface and modules. Its NOTICE and COPYRIGHT_ASSETS files remain part of the attribution trail.
OpenComputerUseKit	MIT	Vendored under ThirdParty/OpenComputerUseKit for internal app automation runtime support. See UPSTREAM.md and the preserved LICENSE.

Additional Swift Package Manager dependencies include Sparkle, Defaults, KeyboardShortcuts, SwiftUIIntrospect, Lottie, MacroVisionKit, SkyLightWindow, AtollExtensionKit, Swift Collections, and SwiftSoup. Those packages keep their upstream licenses and notices.

Contributors

Thanks to everyone who helps build TokenAtlas. ❤️

Star History

If TokenAtlas helps you understand your AI coding work, a ⭐ keeps the project visible and motivates continued development.

Contributing

Issues, ideas, and pull requests are welcome — start a thread in Discussions or open an issue. See CONTRIBUTING.md and the Code of Conduct first.

Before opening a PR, run the checks:

bash scripts/run-tests.sh

For app behavior changes, also smoke-test the build:

bash scripts/run-debug.sh

License

TokenAtlas is open source under AGPL-3.0. A version you modify and run as a network service must stay open under the same license. If you fork TokenAtlas into your own product, please give it a different name and credit TokenAtlas as the source. With gratitude to the maintainers of every embedded project and Swift package catalogued under Open Source, and to everyone who reports issues or sends a pull request.