Codex Desktop should avoid OneDrive-backed Documents as the default Windows project location

What version of Codex is running?

Codex Desktop on Windows. Exact Desktop build not included here because the issue is about the default workspace location behavior rather than a single runtime failure.

What platform is your computer?

Windows 11 with WSL2 enabled.

What issue are you seeing?

Codex Desktop can default or persist new/local project workspaces under the Windows Documents folder. On many Windows installs, Documents is redirected by OneDrive Known Folder Move, so the resulting workspace path becomes OneDrive-backed, for example:

C:\Users\<user>\OneDrive\Documents\<project>

This is a poor default for agent-driven coding work. Codex creates and modifies many files during normal operation, and Git repositories commonly keep frequently-open or lock-sensitive files under .git. OneDrive sync then becomes a source of persistent churn and fragility.

Why OneDrive-backed project folders are problematic

Observed/expected failure modes for Codex projects inside OneDrive-backed Documents:

OneDrive may never reach a fully synced state while Git metadata and generated/temp files are open or changing.
Git operations can become slow or flaky because the repository sits on a synced Windows filesystem.
WSL-backed Codex sessions pay the additional /mnt/c filesystem performance cost, then add OneDrive sync overhead on top.
If OneDrive is paused, stopped, unavailable, or mid-conflict, the project can appear broken even though the issue is the sync layer.
The default encourages users into a location that is actively hostile to local development workflows.

This is especially rough for Windows Desktop + WSL users. The better local default is usually a non-synced development folder, and for WSL-backed sessions it is often a native WSL path such as:

/home/<linux-user>/<project>

or, from the Windows UI side:

\\wsl.localhost\Ubuntu\home\<linux-user>\<project>

What steps can reproduce the issue?

Use Codex Desktop on Windows where the user's Documents known folder is managed or redirected by OneDrive.
Create/open a local Codex project using the default project location or recently persisted workspace root.
Observe the workspace being placed or remembered under a OneDrive-backed Documents path.
Use the workspace for a Git repository or agent-driven coding session.
Observe OneDrive sync churn, open-file sync stalls, and poor Git/development ergonomics.

Expected behavior

Codex Desktop should avoid OneDrive-backed folders for new/default local project workspaces.

Possible fixes:

Detect when the proposed default folder is under OneDrive and warn before creating or selecting it.
Prefer a non-synced development default on Windows, such as %USERPROFILE%\source, %USERPROFILE%\Code, or another local app-selected folder.
For WSL-enabled sessions, offer a WSL-native default such as /home/<linux-user>/<project> and display it through the Windows UNC path when needed.
If a user explicitly chooses OneDrive anyway, allow it, but make it an intentional opt-in rather than the path of least resistance.

Actual behavior

Codex Desktop can persist and reopen a OneDrive-backed project root as the active/default workspace. Local state uses workspace-root fields equivalent to:

{
  "electron-saved-workspace-roots": ["C:\\Users\\<user>\\OneDrive\\Documents\\<project>"],
  "active-workspace-roots": ["C:\\Users\\<user>\\OneDrive\\Documents\\<project>"]
}

Additional context

This is not asking Codex to block OneDrive entirely. Some users may intentionally use synced folders. The issue is that OneDrive-backed Documents is a hazardous default for coding agents and Git workspaces, particularly on Windows + WSL setups where native WSL storage is materially better for development.

Additional code-level finding from inspecting the installed Codex Desktop bundle:

The previous workaround of changing persisted workspace roots does not affect Projects -> Start from scratch. That flow has a separate main-process path.

In the packaged Desktop app (OpenAI.Codex_26.506.3741.0, app.asar), the relevant flow is:

pickOnboardingWorkspaceOrCreateDefault(...) {
  root = await this.pickLocalWorkspaceRoot();
  root ??= await this.createDefaultWorkspaceRoot(defaultProjectName);
  ...
}

async createDefaultWorkspaceRoot(projectName) {
  const name = this.sanitizeDefaultProjectName(projectName);
  const root = await this.findAvailableDefaultWorkspaceRoot(app.getPath("documents"), name, undefined);
  await mkdir(root, { recursive: true }, this.appServerClient);
  await this.initializeDefaultWorkspace(root); // git init
  ...
}

So the root cause is more specific than remembered workspace state: Start from scratch uses Electron app.getPath("documents") as the hardcoded parent folder for new local projects. On Windows systems where Documents is redirected by OneDrive Known Folder Move, app.getPath("documents") resolves into a OneDrive-backed path, so Codex creates New project, New project 2, etc. inside OneDrive.

Related open issues:

Codex App: add default parent folder setting for Start from scratch projects #19913 requests a configurable default parent folder for Start from scratch projects.
App silently creates empty ~/Documents/Codex folder on every launch #20880 reports the same underlying Documents-folder behavior on macOS, where the app creates ~/Documents/Codex.

Suggested implementation direction:

Add a supported setting/config key for the Start from scratch parent directory, rather than only relying on persisted workspace roots.
On Windows, detect when app.getPath("documents") resolves under OneDrive and warn or choose a safer local default.
In Windows + WSL mode, allow a WSL-native default parent such as /home/<linux-user>/..., displayed via \\wsl.localhost\... where the Windows UI needs it.

This means users cannot currently fix this through .codex-global-state.json workspace roots alone; the Start from scratch code path needs its own configurable parent directory or OneDrive avoidance logic.

Additional runtime evidence from Codex Desktop 26.506.3741.0 on Windows + WSL:

The OneDrive default is not only a project-folder inconvenience. Codex stores and later consults project affinity in multiple user-state locations, including .codex-global-state.json, state_5.sqlite thread cwd, session JSONL metadata, ambient suggestions, config.toml project trust entries, and cap_sid cwd capability mappings.
When the project root is C:\Users\<user>\OneDrive\Documents\New project, Desktop continues to launch WSL git probes against that root, for example git ls-files / git add -A with temp index state. In this environment that left OneDrive stuck in an incomplete upload state and created open handles under .git/objects.
This also affects recovery: if OneDrive is stopped or broken, Codex may not load the expected project/chat history because the active project and transcript metadata still point at the OneDrive-backed project root.
A manual migration required changing routing state to a WSL-native project root and patching old metadata carefully while avoiding live-open transcript files.

This makes the upstream fix more than a UX default: Desktop should avoid OneDrive-backed known folders for new projects, expose a configurable default project root, and ideally provide a supported project-state migration path from OneDrive to a local/WSL-native location.

related: Feature Request: [App] Make the "Chats" project directory configurable #19909

Additional impact after migrating active work away from OneDrive/Documents.

The default-to-Documents behavior is especially harmful in Windows + WSL mode because it compounds two slow/fragile layers:

Documents is often redirected to OneDrive, causing sync churn on Codex-generated temp/cache/session files.
When the agent runs in WSL, any Windows-backed project/default root becomes /mnt/c/..., triggering the WSL cross-filesystem performance warning and slower IO.

In this setup the practical stable pattern is:

active repos/projects under native WSL paths such as /home/<wsl-user>/<project>
Windows/Codex home under C:\Users\<user>\.codex only for Desktop app state/config
OneDrive paths treated as archive only, never active project/runtime state

A better new-project flow would let Windows Desktop users choose a persistent default root and, when WSL mode is enabled, strongly prefer a WSL-native default such as /home/<wsl-user> over Windows Documents/OneDrive.

Ironically, I came here to file the exact opposite issue. I genuinely DO want my Codex projects in OneDrive, and on my machine they have been hardcoded to go into userprofile\Documents which is not where I want them. So I don't know if this is a simple default change or a deeper bug.

You're gonna be in a world of hurt if you move them into OneDrive unless you disable git, it's perpetual constant churn, I would batch copy backups to a OD folder but NOT keep it as a live project folder. Also Onedrive should be you default documents root, I'm surprised it's not mapped there? Either way I'd look at simply automating copying the actual project artifacts you want to backup to a OD destination instead of using it as a live folder. OD client is not made to handle the churn, you're talking about tens of thousands of git objects if not more for a typical project. Beyond that, your entire chat history will live there, which means if you turn off one drive or pause sync, your chat sessions will literally disappear if you launch it with OD paused or disabled. There's really no gain.

Oh wow, I didn't realize that start from scratch actually puts your git repo inside that folder. That is absolutely terrible just as you described. I keep my git repos in a separate tree and just want the workspace metadata to be persisted in OneDrive really. (so I can switch to a different computer and keep working) But yes, for this specific issue, git repos absolutely should not be placed inside OneDrive.

This also has historically affected macOS with OneDrive. Unsure of whether it still does, but I'd never suggest doing git repos in OneDrive for that reason. The macOS setup uses ~/Documents as a OneDrive hooked up location too, so this should be avoided / configurable.

Adding a concrete Windows datapoint that supports avoiding OneDrive-backed project roots for active coding work.

In my environment, a New project workspace under a OneDrive-backed Documents path became effectively I/O-bound during normal JS project setup:

pnpm install produced a partially built node_modules of about 90,910 files / 2.8 GB;
the same workspace also had .worktrees around 250,160 files / 6.23 GB;
.git was around 2.44 GB;
the apparent symptom to the user was "Codex/project is stuck" and every click/step felt delayed.

After stopping the stuck install and cloning/moving the active repo to a non-synced local path under F:\openclaw\repos\newproject-fast, the same class of work became normal:

dependency install completed in about 17s;
Vite was ready in about 2s at http://127.0.0.1:5173/.

This was a separate issue from a degraded old Codex thread on the same machine, which is important: moving the repo out of OneDrive fixed the project I/O problem, but it did not make an already bloated long-context Desktop thread safe to continue.

Requested product behavior:

warn when a new/active project root is under OneDrive or another cloud-sync known folder;
make the warning stronger when .git, .worktrees, node_modules, or large file counts are detected;
offer a supported migration path to a non-synced development directory;
avoid presenting OneDrive-backed Documents as the path of least resistance for agent-driven JS/Git projects.

Related narrower diagnostic-boundary issue: #28345.

I prepared a small patch for this, but GitHub is not letting my account open the upstream PR directly.

Compare: main...ooiuuii:fix/windows-onedrive-workspace-warning
Commit: bdb39c2d18010437da18d5125cfbd8ec77c6ea1c

TL;DR

Warn before opening Codex Desktop on Windows with a OneDrive-backed workspace.

codex app <path> currently opens Desktop without any signal when <path> is inside OneDrive or OneDrive - .... That is an easy trap for active coding work, since Git metadata, worktrees, and package-manager directories can create a lot of small-file churn in synced folders.

What changed

detect OneDrive and OneDrive - ... path components on the Windows codex app path
print a warning that synced folders can make Git, worktrees, and node_modules slow or fragile
add unit coverage for consumer OneDrive, organization OneDrive, unrelated path names, and verbatim-prefix display

Why

This keeps behavior unchanged and does not try to change Desktop's Start from scratch default location. It only makes the risk visible at the CLI boundary where the workspace path is already known.

Related: #28345.

Test plan

git diff --check
cargo fmt -p codex-cli
cargo test -p codex-cli desktop_app::windows

I could not run the Rust checks locally because this Windows machine does not currently have cargo/rustup installed.

I tried to open this as a PR, but GitHub returned CreatePullRequest permission errors for my account against openai/codex. If maintainers are open to the change, I can open the PR once invited/enabled, or the commit can be cherry-picked.

I had this problem as described in #28729

Keeping human readable documents in a Onedrive scoped folder is proper behavior and is where users will expect to find docx, xlsx, pptx files.

Code files should rely on github etc coding specific backup systems. This is especially true for generated ephemera rather than files a human is likely to want to edit or otherwise manage by hand.

I prepared a small patch for this, but GitHub is not letting my account open the upstream PR directly.

Compare: main...ooiuuii:fix/windows-onedrive-workspace-warning

Commit: bdb39c2d18010437da18d5125cfbd8ec77c6ea1c

TL;DR

Warn before opening Codex Desktop on Windows with a OneDrive-backed workspace.

codex app <path> currently opens Desktop without any signal when <path> is inside OneDrive or OneDrive - .... That is an easy trap for active coding work, since Git metadata, worktrees, and package-manager directories can create a lot of small-file churn in synced folders.

What changed

detect OneDrive and OneDrive - ... path components on the Windows codex app path

print a warning that synced folders can make Git, worktrees, and node_modules slow or fragile

add unit coverage for consumer OneDrive, organization OneDrive, unrelated path names, and verbatim-prefix display

Why

This keeps behavior unchanged and does not try to change Desktop's Start from scratch default location. It only makes the risk visible at the CLI boundary where the workspace path is already known.

Related: #28345.

Test plan

git diff --check[ ] cargo fmt -p codex-cli[ ] cargo test -p codex-cli desktop_app::windows

I could not run the Rust checks locally because this Windows machine does not currently have cargo/rustup installed.

I tried to open this as a PR, but GitHub returned CreatePullRequest permission errors for my account against openai/codex. If maintainers are open to the change, I can open the PR once invited/enabled, or the commit can be cherry-picked.

This is a situation where a warning is insufficient and likely to be ineffective. Codex should have a strong bias to keep generated, constantly changing files out of Onedrive et al while relatively stable files should be perfectly fine to live within it, especially given Windows love of making "Documents" a Onedrive folder.

Better harness defaults can prevent issues that make sense after you've experienced and diagnosed them but are incomprehensible and unexpected ahead of time.

I fixed the overall issue by creating a global codex rule that kept human readable artifacts in a OneDrive scoped folder while git internals and throwaway files went into C:\tmp.

This way I can easily find files in my Documents folder without breaking OneDrive sync. Output - xlsx, png, md, html, css - lives in an expected project related hierarchy.

FWIW same on Mac

Corroborating enterprise Windows data point: this can progress beyond ordinary Git slowness or transient sync churn into a OneDrive client failure that prevents new files from reaching SharePoint.

Environment: Windows 11, enterprise Microsoft 365/OneDrive Known Folder Move, Codex Desktop package OpenAI.Codex 26.715.2305.0.

We reproduced the following sequence:

Codex workspaces operated inside OneDrive/SharePoint-synced roots and generated sustained rapid file creation, modification, rename, and deletion activity.
The OneDrive client's local change-processing pipeline fell behind and stalled.
Fresh canary files created after the stall remained local. They did not enter the OneDrive upload queue/tracking state and never reached SharePoint while the client was stalled.
Restarting or resetting OneDrive did not produce durable recovery while the high-churn sources remained in the synced roots.
Moving agent/runtime workspaces outside the synced roots and rebuilding synchronization restored successful cloud writes.

The intervention and reversal make the agent-generated filesystem churn a demonstrated cause in this environment, rather than merely a correlated risk. SharePoint service throttling may compound incidents, but it was not required for this failure: the post-stall files had not reached SharePoint at all.

One affected machine was remediated preventively by moving its active Windows Documents location out of OneDrive, so newly created Codex workspaces now land in a local Documents\Codex tree. That works as an administrative workaround, but Codex should not require users to alter Known Folder configuration to obtain a safe agent workspace.

The product characteristics that make this easy to trigger are:

de novo/generated workspaces can land under a OneDrive-managed Documents folder;
the folder picker accepts and persists OneDrive/SharePoint sync roots without a warning;
agent workloads create substantially more filesystem churn than normal document editing;
there is no obvious configurable safe default or enterprise guardrail.

Requested mitigations:

Default generated workspaces to a non-synced location such as %LOCALAPPDATA%\OpenAI\Workspaces, with a configurable override.
Detect Windows Cloud Files/OneDrive/SharePoint roots during workspace selection and show a specific warning.
Provide an enterprise policy to block synced workspace roots or require explicit override.
Keep high-churn runtime, cache, temporary, and intermediate state outside the selected synced project tree when possible.
Add a visible synced-provider indicator/preflight check and remediation guidance.

No raw logs or session data are attached because they may contain private enterprise content.

Follow-up after completing a controlled end-to-end recovery on an affected enterprise Windows endpoint:

The recovery succeeded. We rebuilt more than a dozen OneDrive/SharePoint relationships, restored dozens of endpoint-only files after exact remote checks, performed zero remote overwrites, and ended with stable relationships and no postponed file, folder, or migration records. Developer/runtime workspace material was retained locally and was deliberately not returned to synced folders.

A few findings may be useful for the product design:

The failure can be invisible to aggregate queue metrics. A locally existing file can be absent from the current OneDrive client file index, absent from postponed/failure/upload records, and absent remotely. Therefore, “zero files waiting to upload” or a healthy-looking process is not sufficient evidence that all local files reached OneDrive.
The causal mechanism was reproducible. Sustained high-churn agent activity inside synced roots—Git metadata, runtime databases and sidecars, caches, logs, temporary files, generated trees, and rapid create/edit/delete sequences—caused the client’s outbound processing to stop making durable progress. Removing the high-churn source restored normal writes in the reproduced case. On the affected production endpoint, moving those workloads out and rebuilding the sync relationships produced durable recovery.
A low-impact first remediation is possible. Confidently de novo files that never entered OneDrive tracking can be moved to a non-synced quarantine and preserved. If synchronization resumes, stable human-facing files can be returned gradually after checking their exact remote paths. Developer/runtime files should remain local. A full client rebuild is needed only if this narrower intervention does not restore progress.
Healthy endpoints can be distinguished without mutation. A read-only item-level join between the local filesystem and the current OneDrive client index, combined with empty outbound/failure surfaces and stable process state, can exit early without backup, reset, or browser investigation.

The product mitigations I would prioritize are:

Provide one supported configurable parent for every app-managed workspace path, including Start from scratch, saved projects, and projectless/scratch chats.
Default those paths to a physical non-synced location.
Detect actual Windows Cloud Files/OneDrive/SharePoint roots using provider and Known Folder information, rather than folder-name matching.
Warn strongly—or allow enterprise policy to block—when an active workspace is placed under a sync provider.
Provide a supported migration path for existing saved projects whose roots are already synced.
Keep high-churn runtime, cache, database, temporary, and intermediate state outside the selected synced tree even when stable human-facing deliverables are intentionally copied to OneDrive or SharePoint.

A warning at workspace selection would help, but safe defaults matter more: users generally cannot predict that an apparently normal Documents folder can eventually produce silent local-only files that never reach the cloud.

No enterprise files, raw logs, tenant identifiers, or recovery artifacts are included here.

Adding a concrete Windows migration experience: I had ChatGPT Work project folders under OneDrive-backed Documents without really thinking of them as “cloud-synced development workspaces.” Over time Work generated very large trees of small files (for example artifact-build/temp dependency trees with many thousands of files). That makes OneDrive a particularly poor fit even when the user never intended to use OneDrive as a project storage strategy.

I eventually moved my Work projects to a local root outside OneDrive (for example %USERPROFILE%\ChatGPT\...). That felt like the right layout, but the migration exposed another problem: old chats and linked local files remained tied to the original absolute OneDrive paths.

So for Windows users I’d suggest two product changes together:

Detect when a new/local Work project root is under OneDrive-backed Documents and warn or recommend a non-synced local root.
Provide a first-class relocation flow so users who already started under OneDrive can move later without breaking historical chat/file associations.

The current path-of-least-resistance on Windows makes it very easy to choose a location that works initially but becomes awkward once the project matures.

Navigation Menu

Repository navigation

Codex Desktop should avoid OneDrive-backed Documents as the default Windows project location #22532

What version of Codex is running?

What platform is your computer?

What issue are you seeing?

Why OneDrive-backed project folders are problematic

What steps can reproduce the issue?

Expected behavior

Actual behavior

Additional context

TL;DR

What changed

Why

Test plan

TL;DR

What changed

Why

Test plan

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Codex Desktop should avoid OneDrive-backed Documents as the default Windows project location #22532

Description

What version of Codex is running?

What platform is your computer?

What issue are you seeing?

Why OneDrive-backed project folders are problematic

What steps can reproduce the issue?

Expected behavior

Actual behavior

Additional context

Activity

MisterRound commented on May 13, 2026

MisterRound commented on May 14, 2026

miraclebakelaser commented on May 14, 2026

MisterRound commented on May 15, 2026

demonbane commented on May 20, 2026

MisterRound commented on May 20, 2026

demonbane commented on May 20, 2026

joshka commented on Jun 14, 2026

ooiuuii commented on Jun 15, 2026

ooiuuii commented on Jun 15, 2026

TL;DR

What changed

Why

Test plan

graemeh commented on Jun 17, 2026

graemeh commented on Jun 17, 2026

TL;DR

What changed

Why

Test plan

graemeh commented on Jun 17, 2026

AxicomBrian commented on Jul 16, 2026

mark-defcap commented on Jul 17, 2026

mark-defcap commented on Jul 19, 2026

keen-romoya commented on Sep 11, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions