A native macOS menu bar app for your Codex profiles.
Open separate ChatGPT windows, check Codex quota and get back to your projects.
Build the macOS app » · App guide · CLI
Actual AppKit view with sample quota values. Light and dark appearance follow macOS.
Table of contents
Keep personal, work and client profiles within reach. Codex Profiles.app lets you open ChatGPT windows side by side or launch Codex in Terminal, with a profile's quota and project shortcuts in the same menu.
| In the menu | What you can do |
|---|---|
| Profiles | Create a profile and open it in ChatGPT or Terminal, with no project folder required. |
| Codex quota | See remaining CLI limits, low-quota warnings and reset times for each profile. |
| Projects | Bind folders to profiles, pin favourites and find them with search or keyboard shortcuts. |
The app bundles the codex-profile CLI engine. Both use the same profiles
and project bindings. This is a community project, unaffiliated with OpenAI.
Swift and AppKit for the native macOS interface, Bash and standard system tools for profile operations. The app follows macOS appearance, accent colours and accessibility preferences.
The app is built on your Mac, in one command. There is no signed download
yet. codex-profile menu install builds the app from its release source and
installs it, with no clone needed. macOS does not quarantine an app built on
the same Mac, so Gatekeeper lets it open.
Prefer the terminal? Install the CLI with
brew install Ducksss/tap/codex-profile or npm install -g codex-profile
and follow its quick start on macOS or Linux.
- macOS 13+, on Apple silicon or Intel.
- Xcode Command Line Tools with Swift. Install with
xcode-select --install. Xcode itself is not needed. - The official ChatGPT desktop app for ChatGPT windows. Terminal launches and quota readings need the official Codex CLI, installed separately or available inside ChatGPT.
brew install Ducksss/tap/codex-profile
codex-profile menu installWithout Homebrew, run npx -y codex-profile@latest menu install, or install
the CLI another way first.
The build takes a few minutes. It installs Codex Profiles.app in
Applications, or in ~/Applications if you cannot write to
Applications, and replaces an earlier copy where it is. Open it from Spotlight
or Applications. The app bundles the same codex-profile version, so it needs
no separate CLI. After upgrading the CLI, run codex-profile menu install
again to rebuild the app at the new version.
Build from a source checkout instead
git clone https://github.com/Ducksss/codex-profiles.git
cd codex-profiles
make menu-app
open build/macosDrag Codex Profiles.app to Applications, then open it.
Local builds are unsigned and meant only for the Mac that built them. For a DMG, signing and notarisation, see the macOS build guide.
- Click the menu bar icon. Existing profiles appear automatically.
- Choose New profile… in the gear menu, or Create profile… if the list
is empty. Give it a name such as
personalorwork. - Click the profile to open it in ChatGPT and sign in inside that window when prompted. ⌘-click it, or press ⌘Return, to start Codex CLI in Terminal instead.
Different names can stay open side by side. Reopening a name keeps its local
data, and default opens your normal ChatGPT session. Enable Open at Login
in the gear menu to keep the app available after you log in.
Each profile shows the remaining CLI quota of its tightest window beside a ring. Low readings turn orange or red and show their reset time, and the profile's ⋯ menu lists every window. Hover for details or press ⌘R to refresh.
The menu bar icon gains a badge when a profile runs low. Turn on Quota in menu bar in the gear menu to see the lowest remaining percentage beside the icon, or Low-quota alerts for a notification when a profile crosses into low or critical. Both are off by default, and the app never switches profiles for you.
Give each profile its own colour and symbol with Appearance… in its ⋯
menu, or codex-profile appearance work --color teal, so work and personal
are easy to tell apart. The shell prompt, Raycast and new launchers use the
same colour. To delete a profile you no longer need, use Remove profile…
in its ⋯ menu, or codex-profile remove <profile>.
For an unavailable reading, use Sign in to Codex CLI… in that profile's actions menu, then refresh. Quota follows the profile's CLI sign-in. ChatGPT can use a different account, and the app does not compare accounts. A missing reading never prevents you from opening a profile. See the quota guide for supported accounts and troubleshooting.
Choose +, select a folder and assign a profile. The project appears under its profile; pin the ones you use often, then search and click one, or press Return, to open it. The row's ⋯ menu, or a right-click, lets you change the profile, repair a moved folder or remove the shortcut. Bindings are local metadata and do not change project files.
Keyboard shortcuts and macOS controls
| Shortcut | Action |
|---|---|
| ↑ / ↓, then Return | Select and open a profile or project |
| ⌘Return or ⌘-click | Open in the other destination: Terminal, unless the gear menu's Return opens in chooses it for Return |
| ⌘1–9 | Open the corresponding visible row |
| ⌘K | Focus search |
| ⌘R | Refresh profiles, projects and quota |
| Escape | Clear search, then close the menu |
| ⌃⌥⌘P | Open the menu from any app, once Keyboard shortcut is on in the gear menu |
Opening the app again from Finder or Spotlight shows the menu. Terminal actions may request macOS Automation permission on first use. The app guide covers all controls and accessibility details.
The Raycast extension opens profiles and bound
projects in ChatGPT or Terminal and shows each profile's remaining Codex quota.
Like the menu bar app, it runs every action through codex-profile, using a
standalone install or the copy inside the menu bar app. It isn't in the
Raycast Store yet, so build it from a source checkout with Node.js. See the
extension guide.
cd raycast && npm install && npm run dev| Profile | Codex home | ChatGPT window |
|---|---|---|
default |
~/.codex |
Your normal Desktop session |
work |
~/.codex-work |
Separate local state, including electron-user-data/ in that home |
| Any other name | ~/.codex-<name> |
Its own local state, kept when reopened |
A named window's state covers Chat, Work and Codex. CLI commands such as
cli, login, env and use select Codex state only and do not switch an
open ChatGPT window. Profiles do not inherit from default.
The tool opens the original signed ChatGPT app and does not read or copy
authentication file contents or ChatGPT cookies. Desktop launch refuses a
non-empty CODEX_ACCESS_TOKEN override. Local-state separation is not an
account, OS or server-side security boundary. Use separate OS users for a
stronger boundary. Read the security model and
configuration-sharing guide.
The same profiles work from the terminal on macOS and Linux. You need
Bash and the official Codex CLI, on PATH or discoverable inside ChatGPT.
npm install -g codex-profile
codex-profile setup work
codex-profile cli worksetup guides you through profile creation and offers sign-in, project
binding, a macOS launcher and shell integration. Sign-in defaults to yes and
the others to no; shell startup changes are shown for approval first. For scripts, use init,
login and cli separately.
Install codex-profile (singular). It provides both codex-profile and
codex-profiles commands. The plural npm package is another project.
Homebrew, source, standalone and Nix
brew install Ducksss/tap/codex-profileFrom a source checkout, run make install.
The standalone and Nix commands below are pinned to the v1.4.0 release.
curl -fsSL https://raw.githubusercontent.com/Ducksss/codex-profiles/v1.4.0/install.sh \
| CODEX_PROFILE_VERSION=v1.4.0 shnix run github:Ducksss/codex-profiles/v1.4.0
nix profile install github:Ducksss/codex-profiles/v1.4.0Check your installation with codex-profile doctor.
Launch profiles and projects from the terminal
codex-profile cli work exec "review this repo"
codex-profile app work
codex-profile workspace bind . work
codex-profile run
codex-profile run --appRun codex-profile cli without a name for the profile picker. app work
opens a named ChatGPT window on macOS. run uses the nearest project binding.
Run codex-profile help for all commands or codex-profile help app for
one command. codex-profile status reports Codex-local status only, and
codex-profile usage shows each profile's remaining Codex quota.
Full manual and FAQ · Shell integration · Completions · Environment overrides
For agent-led setup, use agent.md or the machine-readable guide.
CLI commands work on macOS and Linux. app, launcher create and
menu install require macOS. Shell integration supports Bash, Zsh and Fish. NO_COLOR=1 disables
terminal colours, and piped help is plain text.
- Native menu bar app with profile, quota and project controls.
- Universal app and DMG builds with signing and notarisation support.
- One-command local build and install with
codex-profile menu install. - Published signed and notarised macOS app download.
See the changelog and open issues.
Start with the contributor guide
and coding-agent instructions.
Before opening a pull request, run make check for syntax, behaviour,
packaging, native macOS tests and ShellCheck. Native builds are skipped
on hosts without macOS and Swift.
MIT.
Report a bug · Request a feature · Discuss a workflow · Project site
For security reports, follow SECURITY.md.
Best-README-Template for the structure, and contributors for improving the app and CLI.