What variant of Codex are you using?
Desktop App
What feature would you like to see?
Problem
When starting a conversation that is not tied to any project, referred to internally as a "projectless thread", the Codex Desktop App uses ~/Documents/Codex as the default working directory.
On macOS, ~/Documents may be automatically synced to iCloud Drive when "Desktop & Documents Folders" sync is enabled. This means projectless conversation workspace files, generated files, and outputs can be uploaded to iCloud.
This causes several issues:
-
Unnecessary bandwidth and storage consumption
Codex can generate many temporary and intermediate files, such as images, build artifacts, exported documents, and other generated outputs. These files usually do not need cloud sync.
-
Potential sync conflicts and slowdowns
iCloud may lock, delay, or re-upload files while Codex is actively writing to them. This can slow down file operations and may cause confusing filesystem behavior.
-
Privacy concerns
Users may not want generated content, local working files, or projectless conversation outputs to be synced to a cloud provider by default.
Reproduction
-
Move the default projectless workspace directory outside ~/Documents and create a symlink at the original path:
mv ~/Documents/Codex ~/codex-project
ln -s ~/codex-project ~/Documents/Codex
-
Restart the Codex Desktop App.
-
Create a new non-project conversation.
-
The app fails with:
Projectless thread directory must be a real directory
The app appears to reject symlinks for the projectless thread directory. Since the default projectless workspace path is not configurable, users currently have no reliable way to store this workspace outside the iCloud-synced ~/Documents directory.
Proposal
Add a configurable option in config.toml to override the default working directory for projectless conversations:
[desktop]
projectless-thread-directory = "/Users/username/codex-project"
When this option is not set, Codex should continue to fall back to the current default:
This keeps full backward compatibility while allowing users to opt into a different local workspace location.
Expected behavior
If projectless-thread-directory is configured:
- New non-project conversations should create their working directories under the configured path.
- The configured path should be validated as a writable directory.
- Existing behavior should remain unchanged when the option is not configured.
- Existing project-based conversations should not be affected.
####Alternatives considered
-
Allow symlinks
Resolve symlinks before validation instead of rejecting them. This would let users manage their own directory layout without adding a new config option.
-
Use ~/Codex instead of ~/Documents/Codex
This would avoid the iCloud-synced Documents directory by default, but it would be a behavior change for existing users.
-
Expose the setting in the Desktop App UI
A UI setting would be helpful, but a config.toml option would already solve the core issue and is consistent with existing Codex configuration patterns.
Environment
- OS: macOS 26.3
- Codex: Desktop App 26.519.81530
- iCloud Drive: Enabled with Desktop & Documents Folders sync
Additional information
No response
What variant of Codex are you using?
Desktop App
What feature would you like to see?
Problem
When starting a conversation that is not tied to any project, referred to internally as a "projectless thread", the Codex Desktop App uses
~/Documents/Codexas the default working directory.On macOS,
~/Documentsmay be automatically synced to iCloud Drive when "Desktop & Documents Folders" sync is enabled. This means projectless conversation workspace files, generated files, and outputs can be uploaded to iCloud.This causes several issues:
Unnecessary bandwidth and storage consumption
Codex can generate many temporary and intermediate files, such as images, build artifacts, exported documents, and other generated outputs. These files usually do not need cloud sync.
Potential sync conflicts and slowdowns
iCloud may lock, delay, or re-upload files while Codex is actively writing to them. This can slow down file operations and may cause confusing filesystem behavior.
Privacy concerns
Users may not want generated content, local working files, or projectless conversation outputs to be synced to a cloud provider by default.
Reproduction
Move the default projectless workspace directory outside
~/Documentsand create a symlink at the original path:Restart the Codex Desktop App.
Create a new non-project conversation.
The app fails with:
The app appears to reject symlinks for the projectless thread directory. Since the default projectless workspace path is not configurable, users currently have no reliable way to store this workspace outside the iCloud-synced
~/Documentsdirectory.Proposal
Add a configurable option in
config.tomlto override the default working directory for projectless conversations:When this option is not set, Codex should continue to fall back to the current default:
This keeps full backward compatibility while allowing users to opt into a different local workspace location.
Expected behavior
If
projectless-thread-directoryis configured:####Alternatives considered
Allow symlinks
Resolve symlinks before validation instead of rejecting them. This would let users manage their own directory layout without adding a new config option.
Use
~/Codexinstead of~/Documents/CodexThis would avoid the iCloud-synced Documents directory by default, but it would be a behavior change for existing users.
Expose the setting in the Desktop App UI
A UI setting would be helpful, but a
config.tomloption would already solve the core issue and is consistent with existing Codex configuration patterns.Environment
Additional information
No response