UsageAtlasBeta
Sign inGitHubOpen source
Codex

Codex usage on Mac

Track Codex usage on macOS from the menu bar. Where sessions live, how to point a tracker at CODEX_HOME, and what to check on Apple silicon.

By UsageAtlas on

Quick answer

On macOS, Codex writes sessions to `~/.codex/sessions` unless `CODEX_HOME` is set. UsageAtlas runs as a signed, notarized menu bar app and reads that folder locally. The two things that break tracking are a custom `CODEX_HOME` and running Codex inside a container or a different user account.

Where macOS keeps the data

ItemPath
Sessions`~/.codex/sessions`
Config`~/.codex/config.toml`
Custom home`$CODEX_HOME/sessions`
Installed app`/Applications/UsageAtlas.app`
ls -la ~/.codex/sessions | tail
echo $CODEX_HOME

Set up the menu bar view

  1. Download the .dmg from UsageAtlas and drag the app to Applications.
  2. Launch it and allow access to your home folder when prompted.
  3. Confirm Codex appears in the detected tools list.
  4. If it does not, add the custom path from CODEX_HOME.
  5. Keep the app running so alerts can fire.

macOS may ask for Full Disk Access if the sessions folder sits in a protected location. Grant it only if detection fails after a correct path is set.

If usage is missing

  • Codex installed through a version manager may run as a different user.
  • A container writes sessions inside the container, not to the host home folder.
  • iCloud Drive syncing of the home folder can delay file writes.
  • A stale date filter hides recent sessions.

The Codex usage not showing guide walks through the same causes with checks for each.

Where Codex keeps data on macOS

Codex writes sessions to a hidden folder in your home directory, which Finder hides by default. You do not need to browse it by hand: the CLI and a tracker both read it, but knowing the location helps when you back up a machine or move to a new Mac.

  1. Open Terminal and list your home directory including hidden entries.
  2. Confirm the Codex data folder exists and contains session files.
  3. Back it up with your dotfiles before a clean install.
  4. Point UsageAtlas at the folder if detection fails.
ls -la ~ | grep -i codex
ls ~/.codex/sessions | head

The Windows guide and Linux guide cover the equivalent paths.

Questions, answered

Does UsageAtlas work on Apple silicon?

Yes. The macOS build is signed and notarized and runs natively on Apple silicon and Intel.

Where does Codex store sessions on Mac?

In ~/.codex/sessions by default, or under $CODEX_HOME/sessions if that variable is set.

Can I track Codex usage from the menu bar only?

Yes. The menu bar shows the current windows and reset times; open the main window for history and model breakdowns.

Browse by topic