Codex

Basics

Typing /status in the desktop app will show you your quota usage directly in the window.
OpenAI occasionally grants “reset tokens” (formally “usage limit resets”). The only official communication I could find on them is this tweet. In the desktop app, you can see when they expire by expanding your usage:
- - To get the exact expiration times, run this privately: curl 'https://chatgpt.com/backend-api/wham/rate-limit-reset-credits' -H "Authorization: Bearer $(jq -r '.tokens.access_token' "$HOME/.codex/auth.json")" -H "ChatGPT-Account-ID: $(jq -r '.tokens.account_id' "$HOME/.codex/auth.json")" -H "originator: Codex Desktop"
- Using one only resets your quota, not the reset date. For example, if you have 5 days remaining in the week and use a reset, you’ll still have 5 days remaining.

Acting on notifications

I haven’t actually done anything here yet, but HiDeoo told me about this:

HiDeoo: @AdamLearnsLive In case you didn’t know, in the codex config, there is a notify option where you can specify a path to a script that will trigger for the same event you have notifications, and you can use AppleScript to spawn an alert or w/e in it. ( HeyGuys btw)

Granting permission to write temporary files

When working with Godot and C#, Codex would often ask me whether it has permission to modify /private/tmp to create and edit .gd files to validate Godot behavior. I wanted it to have this permission permanently, but AGENTS.md is not the place to do it. Instead, here’s what I did:

Make a .codex directory under my Godot project folder.
Make AGENTS.md and config.toml under it:

AGENTS.md:

- Use `/private/tmp/codex-my-game-gd` for temporary `.gd` scratch files

config.toml:

approval_policy = "on-request"
default_permissions = "my-game-temp-gd"

[permissions.my-game-temp-gd]
description = "Workspace write plus disposable Godot temp scratch."
extends = ":workspace"

[permissions.my-game-temp-gd.filesystem]
"/private/tmp/codex-my-game-gd" = "write"

Using worktrees

Testing changes from a worktree:
- Option 1: commit and cherry-pick
  - Click “Commit”. Codex will make a new branch.
  - Merge in the changes from that branch: git merge --squash codex/NAME-OF-BRANCH
    - This will leave the files in an uncommitted state for you to review them and test them out.
    - Note: you could cherry-pick (git cherry-pick -n codex/NAME-OF-BRANCH), but it will only pull in the tip, so if you have Codex make future commits to that branch, you could end up with merge conflicts.
- Option 2: hand off to a new branch
  - Click this to pull the changes Codex made into your local checkout without actually committing anything:
    - Then, click “Hand off” in the resulting dialog.
    - You’ll then be on the branch that Codex made though. You have a few options:
      - Option 1: git stash push -u -m "Codex hand-off" && git switch YOUR_ORIGINAL_BRANCH && git stash pop
      - Option 2: commit on the new branch, then git switch YOUR_ORIGINAL_BRANCH && git merge --ff-only CODEX_BRANCH

Stupid manual steps

These notes are probably worthless for most people; see the parent header for “good” notes.

Testing changes from a worktree
- First, look at where the worktree is on your filesystem through Codex. You should be able to click “Worktree created”, then you’ll see a path like this: /Users/adam/.codex/worktrees/fbf2/StuckInABrokenTutorial
- Switch into that directory
- Run any repo-initialization tasks → build → run. E.g. for me:
  - git submodule update --init --recursive --remote
  - cd game
  - $GODOT4 --import ./
  - $GODOT4 --path ./
  - NOTE: you can achieve this automatically by using Codex’s environments (Settings → Local environments → create one → choose it when making a new workspace)
If Codex has uncommitted changes in a worktree and you want to see them in your current branch (e.g. to diff them), I think it’s best to just commit the files directly from Codex (click “Commit or push”), then do the following:
- Get the path of the worktree: git worktree list | grep NAME-CODEX-GAVE-IT
- Get the commit hash: git log -1
- Cherry-pick it into your repo: git cherry-pick -n COMMIT_HASH
  - The -n means that it won’t commit in your local repo; it’ll just make the changes to the underlying files.

Troubleshooting

Can’t use workspaces

E.g. I would get an error like this:

Error starting task

failed to load configuration: default_permissions requires a "[permissions]" table

It turns out this is because I had a custom config.toml ignored by Git. In my particular case, I didn’t want to commit these files, so I used Codex’s .worktreeinclude file (reference) in the root of the repo.