Codex Profiles 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 About the project Getting started Usage How separation works Command-line usage Roadmap Contributing License…
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.
Built with
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.
Getting started
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.
Prerequisites
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.
Installation
brew install Ducksss/tap/codex-profile
codex-profile menu install
Without 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/macos
Drag 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.
Usage
Open your first profile
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 personal or work.
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.
Check quota before opening a profile
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.
Open a project with its profile
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.
Raycast
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
How separation works
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.
Command-line usage
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.
Quick start
npm install -g codex-profile
codex-profile setup work
codex-profile cli work
setup 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.
Install
Homebrew, source, standalone and Nix
brew install Ducksss/tap/codex-profile
From a source checkout, run make install.
The standalone and Nix commands below are pinned to the v1.5.0 release.
curl -fsSL https://raw.githubusercontent.com/Ducksss/codex-profiles/v1.5.0/install.sh \
| CODEX_PROFILE_VERSION=v1.5.0 sh
nix run github:Ducksss/codex-profiles/v1.5.0
nix profile install github:Ducksss/codex-profiles/v1.5.0
Check your installation with codex-profile doctor.
Everyday workflows
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 --app
Run 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.
Command reference
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.
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.
Roadmap
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.
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.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
![imgbot[bot]](https://avatars.githubusercontent.com/in/4706?v=4)
评论