💡 Atlas 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

Table of Contents

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

Why Atlas

An atlas is a book of sea charts — maps that turn open water into something you can navigate. Atlas does the same for your AI coding: it charts the tokens, cost, sessions, and Git activity you produce every day into a map you can actually read.

Part of a nautical family: Harbor is where knowledge docks, Beacon lights up expiring certificates before they bite, and Atlas charts the voyage.

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 Atlas-<version>.dmg.
3. Open the disk image and drag Atlas.app to Applications.
4. Launch Atlas — 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/Atlas.git
cd Atlas
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

Atlas 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 Atlas service — there isn't one.

Development

Atlas.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/Atlas-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

Atlas/       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
AtlasTests/  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. Atlas 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 Atlas/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

Atlas 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 Atlas 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 Atlas. ❤️

Star History

If Atlas 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

Atlas 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 Atlas into your own product, please give it a different name and credit Atlas 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.