https://github.com/can4hou6joeng4/tokenatlas
📊 Map your local AI coding usage — tokens, cost, sessions, and Git activity — in a native macOS menu-bar app. Reads Claude Code & Codex traces on-device.
https://github.com/can4hou6joeng4/tokenatlas
ai-coding apple-silicon claude-code codex cost-tracking developer-tools llm local-first macos menu-bar productivity sparkle swift swiftui token-usage usage-analytics
Last synced: 6 days ago
JSON representation
📊 Map your local AI coding usage — tokens, cost, sessions, and Git activity — in a native macOS menu-bar app. Reads Claude Code & Codex traces on-device.
- Host: GitHub
- URL: https://github.com/can4hou6joeng4/tokenatlas
- Owner: can4hou6joeng4
- License: agpl-3.0
- Created: 2026-06-18T02:00:04.000Z (7 days ago)
- Default Branch: main
- Last Pushed: 2026-06-18T03:35:07.000Z (7 days ago)
- Last Synced: 2026-06-18T05:10:51.505Z (7 days ago)
- Topics: ai-coding, apple-silicon, claude-code, codex, cost-tracking, developer-tools, llm, local-first, macos, menu-bar, productivity, sparkle, swift, swiftui, token-usage, usage-analytics
- Language: Swift
- Homepage: https://can4hou6joeng4.github.io/TokenAtlas/
- Size: 23.9 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
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](#features)
- [Highlights](#highlights)
- [Quick Start](#quick-start)
- [Privacy](#privacy)
- [Development](#development)
- [Release and Auto-update](#release-and-auto-update)
- [Requirements](#requirements)
- [Project Layout](#project-layout)
- [Design Notes](#design-notes)
- [Open Source](#open-source)
- [Contributors](#contributors)
- [Star History](#star-history)
- [Contributing](#contributing)
- [License](#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`](docs/assets/screens).
## Quick Start
**Install a packaged build**
1. Open the [latest GitHub Release](https://github.com/can4hou6joeng4/TokenAtlas/releases).
2. Download `TokenAtlas-.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](docs/installation.md) for the zip fallback, the update feed, and the maintainer release flow.
**Build from source**
```bash
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:
```bash
git submodule update --init --recursive
```
**Run the checks**
```bash
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`](project.yml) with [XcodeGen](https://github.com/yonaskolb/XcodeGen). Use the helper scripts instead of opening stale build products:
```bash
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
bash scripts/install-app.sh
```
## Release and Auto-update
Maintainers cut releases by pushing a semver tag:
```bash
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](https://can4hou6joeng4.github.io/TokenAtlas/appcast.xml) when `SPARKLE_PRIVATE_ED_KEY` is configured. Signing and notarization inputs are documented in [`.github/workflows/release.yml`](.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
```text
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//`; 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](LICENSE). The app also embeds and adapts several major open-source projects:
| Project | License | How TokenAtlas uses it |
| --- | --- | --- |
| [Atoll / DynamicIsland](https://github.com/can4hou6joeng4/Atoll) | GPL-3.0 | Integrated through `AtollEmbed` for the optional Notch Island surface and modules. Its [`NOTICE`](ThirdParty/Atoll/NOTICE) and [`COPYRIGHT_ASSETS`](ThirdParty/Atoll/COPYRIGHT_ASSETS) files remain part of the attribution trail. |
| [OpenComputerUseKit](https://github.com/iFurySt/open-codex-computer-use) | MIT | Vendored under `ThirdParty/OpenComputerUseKit` for internal app automation runtime support. See [`UPSTREAM.md`](ThirdParty/OpenComputerUseKit/UPSTREAM.md) and the preserved [`LICENSE`](ThirdParty/OpenComputerUseKit/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](https://github.com/can4hou6joeng4/TokenAtlas/discussions) or open an [issue](https://github.com/can4hou6joeng4/TokenAtlas/issues). See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md) first.
Before opening a PR, run the checks:
```bash
bash scripts/run-tests.sh
```
For app behavior changes, also smoke-test the build:
```bash
bash scripts/run-debug.sh
```
## License
TokenAtlas is open source under [AGPL-3.0](LICENSE). 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](#open-source), and to everyone who reports issues or sends a pull request.