{"id":50974273,"url":"https://github.com/can4hou6joeng4/tokenatlas","last_synced_at":"2026-06-19T06:01:23.717Z","repository":{"id":365602866,"uuid":"1272856081","full_name":"can4hou6joeng4/TokenAtlas","owner":"can4hou6joeng4","description":"📊 Map your local AI coding usage — tokens, cost, sessions, and Git activity — in a native macOS menu-bar app. Reads Claude Code \u0026 Codex traces on-device.","archived":false,"fork":false,"pushed_at":"2026-06-18T03:35:07.000Z","size":25071,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T05:10:51.505Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://can4hou6joeng4.github.io/TokenAtlas/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/can4hou6joeng4.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-18T02:00:04.000Z","updated_at":"2026-06-18T03:13:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/can4hou6joeng4/TokenAtlas","commit_stats":null,"previous_names":["can4hou6joeng4/tokenatlas"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/can4hou6joeng4/TokenAtlas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/can4hou6joeng4%2FTokenAtlas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/can4hou6joeng4%2FTokenAtlas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/can4hou6joeng4%2FTokenAtlas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/can4hou6joeng4%2FTokenAtlas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/can4hou6joeng4","download_url":"https://codeload.github.com/can4hou6joeng4/TokenAtlas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/can4hou6joeng4%2FTokenAtlas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34519051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-06-19T06:01:22.541Z","updated_at":"2026-06-19T06:01:23.711Z","avatar_url":"https://github.com/can4hou6joeng4.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/token-atlas-icon.png\" alt=\"TokenAtlas app icon\" width=\"120\" height=\"120\"\u003e\n  \u003ch1\u003eTokenAtlas\u003c/h1\u003e\n  \u003cp\u003e\u003cem\u003e📊 Map your local AI coding usage — tokens, cost, sessions, and Git activity — in one native macOS menu-bar app.\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/can4hou6joeng4/TokenAtlas/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/can4hou6joeng4/TokenAtlas?style=flat-square\" alt=\"Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/can4hou6joeng4/TokenAtlas/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/can4hou6joeng4/TokenAtlas?include_prereleases\u0026label=version\u0026style=flat-square\" alt=\"Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/can4hou6joeng4/TokenAtlas/actions/workflows/release.yml?query=branch%3Amain\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/can4hou6joeng4/TokenAtlas/release.yml?branch=main\u0026style=flat-square\" alt=\"Build\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-AGPL_v3-blue.svg?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/can4hou6joeng4/TokenAtlas/commits/main\"\u003e\u003cimg src=\"https://img.shields.io/github/commit-activity/m/can4hou6joeng4/TokenAtlas?style=flat-square\" alt=\"Commits\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://can4hou6joeng4.github.io/TokenAtlas/\"\u003e\u003cimg src=\"https://img.shields.io/badge/homepage-tokenatlas-f06b1f?style=flat-square\u0026logo=safari\u0026logoColor=white\" alt=\"Homepage\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/macOS-14%2B-black?style=flat-square\u0026logo=apple\" alt=\"macOS 14+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Swift-6-orange?style=flat-square\u0026logo=swift\u0026logoColor=white\" alt=\"Swift 6\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/social-preview.png\" alt=\"TokenAtlas - local AI coding usage map\" width=\"1000\"\u003e\n\u003c/p\u003e\n\n\u003e 💡 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.\n\n## Demo\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/assets/tokenatlas-promo.gif\" alt=\"TokenAtlas demo — dashboard, usage, and providers at a glance\" width=\"860\"\u003e\n\n\u003cp\u003e\u003csub\u003e\u003cb\u003e▶ Watch the full 60-second tour\u003c/b\u003e (1080p — adds the multi-provider, privacy \u0026amp; CTA scenes): \u003ca href=\"https://github.com/can4hou6joeng4/TokenAtlas/raw/main/docs/assets/tokenatlas-promo.mp4\"\u003e\u003ccode\u003etokenatlas-promo.mp4\u003c/code\u003e\u003c/a\u003e\u003c/sub\u003e\u003c/p\u003e\n\n\u003c/div\u003e\n\n## Table of Contents\n\n- [Features](#features)\n- [Highlights](#highlights)\n- [Quick Start](#quick-start)\n- [Privacy](#privacy)\n- [Development](#development)\n- [Release and Auto-update](#release-and-auto-update)\n- [Requirements](#requirements)\n- [Project Layout](#project-layout)\n- [Design Notes](#design-notes)\n- [Open Source](#open-source)\n- [Contributors](#contributors)\n- [Star History](#star-history)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- **Menu-bar usage map** — tokens, estimated cost, cache activity, recent sessions, and provider status, **always one click away**.\n- **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.\n- **Sessions and projects** — inspect conversations, projects, messages, model mix, and personal records, **entirely on-device**.\n- **Repository activity** — correlate AI coding usage with **local Git history** and bundled language statistics.\n- **Optional Notch Island** — Atoll-backed glanceable panels for activity, stats, media, timers, clipboard, and more.\n- **Packaged auto-updates** — Sparkle appcast delivery for **manual checks and silent background updates**.\n\n## Highlights\n\nA quiet utility, not a marketing dashboard: restrained color, stable tables, readable numbers, and fast paths to the records that explain a workday.\n\n### Dashboard — your coding activity, day by day\n\nSessions, messages, total tokens, streaks, and peak hours at a glance, with a token trend you can read in a second.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/screens/dashboard-overview.png\" alt=\"TokenAtlas dashboard with sessions, tokens, streaks, and a token trend chart\" width=\"900\"\u003e\n\u003c/p\u003e\n\n### Usage — tokens, cost, cache, and model mix\n\nCost and cache hit rate per period, broken down by model, for whichever provider you're looking at.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/screens/usage-token-limits.png\" alt=\"Token usage with cost, cache hit rate, and per-model breakdown\" width=\"900\"\u003e\n\u003c/p\u003e\n\n### Sessions — every conversation, inspectable\n\nDiscovered conversations and projects with messages, model mix, and cache hit rate — drill into any single session.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/screens/sessions-overview.png\" alt=\"Session statistics overview\" width=\"900\"\u003e\n\u003c/p\u003e\n\n### Git activity — usage mapped to your commits\n\nCorrelate AI coding usage with local Git history and per-language statistics across your repositories.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/screens/git-repository-workspace.png\" alt=\"Git repository workspace with commit activity and language stats\" width=\"900\"\u003e\n\u003c/p\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMore views — Activity, Switcher, Configs, Skills\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\n  \u003ctd align=\"center\" width=\"50%\"\u003e\n    \u003cimg src=\"docs/assets/screens/activity-focus-timeline.png\" alt=\"Activity focus timeline\"\u003e\u003cbr\u003e\n    \u003cb\u003eActivity\u003c/b\u003e\u003cbr\u003e\u003csub\u003eFocus timeline of when the work actually happened\u003c/sub\u003e\n  \u003c/td\u003e\n  \u003ctd align=\"center\" width=\"50%\"\u003e\n    \u003cimg src=\"docs/assets/screens/provider-switcher.png\" alt=\"Provider switcher\"\u003e\u003cbr\u003e\n    \u003cb\u003eSwitcher\u003c/b\u003e\u003cbr\u003e\u003csub\u003eJump between providers and compare them side by side\u003c/sub\u003e\n  \u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd align=\"center\" width=\"50%\"\u003e\n    \u003cimg src=\"docs/assets/screens/configs-plans-browser.png\" alt=\"Configs and plans browser\"\u003e\u003cbr\u003e\n    \u003cb\u003eConfigs\u003c/b\u003e\u003cbr\u003e\u003csub\u003eBrowse the AI config files each CLI reads\u003c/sub\u003e\n  \u003c/td\u003e\n  \u003ctd align=\"center\" width=\"50%\"\u003e\n    \u003cimg src=\"docs/assets/screens/skills-library.png\" alt=\"Skills library\"\u003e\u003cbr\u003e\n    \u003cb\u003eSkills\u003c/b\u003e\u003cbr\u003e\u003csub\u003eYour skill library, organized and searchable\u003c/sub\u003e\n  \u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nAnimated GIF demos of the menu-bar HUD live in [`docs/assets/screens`](docs/assets/screens).\n\n\u003c/details\u003e\n\n## Quick Start\n\n**Install a packaged build**\n\n1. Open the [latest GitHub Release](https://github.com/can4hou6joeng4/TokenAtlas/releases).\n2. Download `TokenAtlas-\u003cversion\u003e.dmg`.\n3. Open the disk image and drag `TokenAtlas.app` to `Applications`.\n4. Launch TokenAtlas — it lives in the menu bar.\n\n\u003e 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.\n\n**Build from source**\n\n```bash\ngit clone --recursive https://github.com/can4hou6joeng4/TokenAtlas.git\ncd TokenAtlas\nbrew install xcodegen\nbash scripts/run-debug.sh\n```\n\nAlready cloned without submodules? Pull them in:\n\n```bash\ngit submodule update --init --recursive\n```\n\n**Run the checks**\n\n```bash\nbash scripts/run-tests.sh\n```\n\n## Privacy\n\nTokenAtlas 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.\n\nNetwork-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.\n\n## Development\n\n`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:\n\n```bash\nbash scripts/run-debug.sh    # generate, build Debug, and launch\nbash scripts/run-tests.sh    # Python + XCTest suites\n```\n\nThe 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:\n\n```bash\nbash scripts/install-app.sh\n```\n\n## Release and Auto-update\n\nMaintainers cut releases by pushing a semver tag:\n\n```bash\ngit tag v1.2.0\ngit push origin v1.2.0\n```\n\nThe 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).\n\n## Requirements\n\n- Apple Silicon Mac with macOS 14+\n- Xcode 26.4+ with Swift 6 language mode\n- XcodeGen for project generation\n\n## Project Layout\n\n```text\nTokenAtlas/       app entry point, providers, services, view models, and SwiftUI views\nAtollEmbed/       app-side wrapper for the Atoll / DynamicIsland integration\nThirdParty/       git submodules for embedded upstream projects\nTokenAtlasTests/  parser, scanner, settings, integration, and feature tests\ndocs/assets/      README images, icons, screenshots, and GIFs\nscripts/          project generation, local run/test, release, and appcast tooling\n```\n\n## Design Notes\n\nQuiet 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.\n\nProvider-specific behavior lives under `TokenAtlas/Providers/\u003cProvider\u003e/`; 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.\n\n## Open Source\n\nTokenAtlas is released under the [GNU Affero General Public License v3.0](LICENSE). The app also embeds and adapts several major open-source projects:\n\n| Project | License | How TokenAtlas uses it |\n| --- | --- | --- |\n| [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. |\n| [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). |\n\nAdditional 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.\n\n## Contributors\n\nThanks to everyone who helps build TokenAtlas. ❤️\n\n\u003ca href=\"https://github.com/can4hou6joeng4/TokenAtlas/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=can4hou6joeng4/TokenAtlas\" alt=\"TokenAtlas contributors\" /\u003e\n\u003c/a\u003e\n\n## Star History\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://star-history.com/#can4hou6joeng4/TokenAtlas\u0026Date\"\u003e\n    \u003cimg src=\"https://api.star-history.com/svg?repos=can4hou6joeng4/TokenAtlas\u0026type=Date\" alt=\"TokenAtlas star history\" width=\"640\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\nIf TokenAtlas helps you understand your AI coding work, a ⭐ keeps the project visible and motivates continued development.\n\n## Contributing\n\nIssues, 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.\n\nBefore opening a PR, run the checks:\n\n```bash\nbash scripts/run-tests.sh\n```\n\nFor app behavior changes, also smoke-test the build:\n\n```bash\nbash scripts/run-debug.sh\n```\n\n## License\n\nTokenAtlas 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcan4hou6joeng4%2Ftokenatlas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcan4hou6joeng4%2Ftokenatlas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcan4hou6joeng4%2Ftokenatlas/lists"}