openai
Adhere to XDG Base Desktop Specification on Linux platforms
The user's home directory is not the place to dump program data, and for future cross-platform compatibility handling this would be inappropriate. Currently Codex stores its data in ~/.codex (modulated by a custom CODEX_HOME environment variable), however Linux has a popular specification for where to place files of various types (link). In Codex's case, $XDG_CONFIG_HOME/codex/ would be suitable. (more info)
XDG_CONFIG_HOME on Mac (I know you're asking about Linux) is "$HOME/Library/Application Support", which is annoying, as it contains spaces and makes all sorts of commands hard to copy/paste.
The default of $HOME/.config on Linux is more sane, but then every documentation example is more complex.
We decided to go with ~/.codex instead, but we do honor CODEX_HOME, so you can set that to whatever you like.
A user needing to add a custom environment variable to their session for every application that (not unreasonably) prefers special behaviour to save development effort would lead to a very uncooperative ecosystem and tedium on part of users. Would a PR for the desired behaviour in this and #142 be considered?
@offsetcyan as noted:
The default of $HOME/.config on Linux is more sane, but then every documentation example is more complex.
Mainly for that reason, no, I would not consider a PR that would change the default to $XDG_CONFIG_HOME/codex on Linux.
It would also break existing users at this point.
This is a common mistake. Here you can track the progress of VS Code, Claude Code and Aider as they fix the same issue.
XDG_CONFIG_HOMEon Mac (I know you're asking about Linux) is"$HOME/Library/Application Support", which is annoying, as it contains spaces and makes all sorts of commands hard to copy/paste.
Thus, Linux users suffer again for Apple's sins.
It would also break existing users at this point.
This kind of change can be implemented in a backwards-compatible way by checking for the existence of CODEX_HOME and ~/.codex in that order, then following the XDG spec if neither were specified.
There seems to be a regression in latest version no longer respecting the $CODEX_HOME env var
@DanielZlotin do you have repro steps?
The only thing that could be remotely related in recent history is https://github.com/openai/codex/pull/2308.
Though note that many of our integration tests rely on CODEX_HOME being honored, so it feels unlikely that it could be completely broken.
@bolinfest the real issue is AGENTS.md and instructions.md stopped getting picked up from CODEX_HOME, so maybe the env does work in other contexts
@DanielZlotin are you sure it isn't being picked up? I believe it should:
https://github.com/openai/codex/blob/075e385969831e52ea07c9b8035b7fad8e5f7bb8/codex-rs/core/src/config.rs#L821-L836
Experience shows that it's almost impossible to convince anyone who isn't a CLI die-hard to learn about the XDG Base Directory Specification, especially those who live comfortably in macOS. Until one day, they suddenly notice their $HOME overflowing with all kinds of so-called "home directories" left behind by every piece of software they've ever installed. The clutter finally becomes unbearable.
That's when they stumble upon the XDG Base Directory Specification, and start looking for tools like xdg-ninja to free their $HOME. But soon, they discover that some software simply refuses to follow the spec. So they head to those projects' issue trackers, file proposals, and get rejected. Because, as it turns out, the maintainers are going through the very same awakening themselves.
Grumble aside, this is what I did for Codex:
export CODEX_HOME=~/.cache/codex
mkdir -p $CODEX_HOME ~/.config/codex
touch ~/.config/codex/config.toml
ln -s ~/.config/codex/config.toml $CODEX_HOME/
especially those who live comfortably in macOS
More discussion (including recent) about this on macOS here:
- https://github.com/openai/codex/issues/143
Notably recently:
In the referenced apple doc "app" refers to packaged macos Apps (living in /Applications). They distinguish in the docs between Apps and CLI tools, and here the universal way that also CLI tools that Apple packages by default uses is indeed also the ~/.config dir. So for CLI tools Application Support is not the correct location. For more info: https://becca.ooo/blog/macos-dotfiles/
Originally posted by @ponychicken in https://github.com/openai/codex/issues/143#issuecomment-3343504429
And:
There was a good discussion about that article (which I disagree with the conclusions of wholly and totally) on Lobste.rs: https://lobste.rs/s/iv17mx/macos_dotfiles_should_not_go_library
Originally posted by @offsetcyan in https://github.com/openai/codex/issues/143#issuecomment-3344411658
(With my far less detailed personal opinion that links to some other sources in this comment: https://github.com/openai/codex/issues/143#issuecomment-3193951902)