Adhere to XDG Base Desktop Specification on Linux platforms

[offsetcyan]

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)

[bolinfest]

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.

[offsetcyan]

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?

[bolinfest]

@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.

[99991]

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_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.

Thus, Linux users suffer again for Apple's sins.

[offsetcyan]

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.

[0xdevalias]

Duplicate of:

• Adhere to XDG Base Desktop Specification on Linux platforms #142

[DanielZlotin]

There seems to be a regression in latest version no longer respecting the $CODEX_HOME env var

[bolinfest]

@DanielZlotin do you have repro steps?

The only thing that could be remotely related in recent history is #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.

[DanielZlotin]

@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

[bolinfest]

@DanielZlotin are you sure it isn't being picked up? I believe it should:

codex/codex-rs/core/src/config.rs

Lines 821 to 836 in 075e385

	fn load_instructions(codex_dir: Option<&Path>) -> Option<String> {
	let mut p = match codex_dir {
	Some(p) => p.to_path_buf(),
	None => return None,
	};
	p.push("AGENTS.md");
	std::fs::read_to_string(&p).ok().and_then(|s| {
	let s = s.trim();
	if s.is_empty() {
	None
	} else {
	Some(s.to_string())
	}
	})
	}

[aofei]

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/