Projects and VS Code · Troubleshooting
Remove a folder's Codex settings to stop it from automatically selecting an identity. Use this guide when Remove Codex context from this folder… fails in Finder, or when you prefer Terminal. Your source files, accounts, and credentials stay in place.
| Your situation | Start here |
|---|---|
| The menu does not work, but the generated files are unchanged | Try removal from Terminal |
| Removal is refused, files were customized, or a file is already missing | Remove the settings manually |
| You need to undo a manual edit | Restore your backup |
For VS Code - NAME menu entries, use Open With cleanup. To remove the Finder app and Quick Action, uninstall the Finder integration. Those actions leave a folder's Codex settings in place.
Save your work and quit the affected identity's VS Code instance and Codex chats. From the codex-contexts repository directory, run this command, replacing the example path with the folder you want to disconnect:
./bin/codex-home project-reset "/path/to/project"The command removes only an unchanged, untracked pair of generated files:
.envrc and the Codex .code-workspace file. It revokes that folder's direnv
approval and removes its exact local Git exclude patterns.
- It reports
Removed generated Codex project context: go to Check the result. - It refuses the files or the helper is unavailable: use manual removal. A refusal protects edited, shared, or incomplete configuration; there is no force-removal step.
For example, adding Python setup to .envrc makes automatic removal refuse
the file. The manual route lets you keep that setup and remove the Codex block.
Keep these intact: source files and data; .git, .codex, .direnv, and
the project's .env; unrelated files in .vscode; ~/.codex, ~/.codex-homes
(or your custom identity root), and each identity's vscode-user-data.
Follow the four steps below. Missing files can be skipped. Optional Git housekeeping comes after the result check.
Save your work and quit the affected identity's VS Code instance and Codex chats. In Finder, open the project folder and press Command-Shift-. to show hidden files. Read the following files in a text editor:
| File | What it controls |
|---|---|
.envrc |
The selected identity and environment setup. It may also contain commands your project needs. |
.vscode/<folder-name>.code-workspace |
The Codex window title and colors, plus any workspace customizations you added. |
Older setups may use .vscode/codex-context.code-workspace; renamed folders
may retain a workspace with the previous folder name. Also inspect
.vscode/settings.json or another workspace if you merged Codex settings
there yourself.
Copy each file you will change to a new, private backup folder outside the
project, noting its original path. A Generated by codex-home comment does
not establish that the file is still unchanged.
If the project uses Git, run these read-only checks from any Terminal directory:
git -C "/path/to/project" status --short
git -C "/path/to/project" ls-files -- .envrc .vscodeThe second command lists tracked files. Keep any existing uncommitted edits in your backup and coordinate changes to shared files with the project team. Skip these commands for a folder outside Git.
If a file or .vscode is a symbolic link: inspect its target first. Keep
shared targets intact; use an independent local copy if this folder needs
different settings. Do not edit through a link into another project's files.
If this folder still has its own .envrc, revoke its approval from a separate
Terminal window:
direnv deny "/path/to/project/.envrc"If .envrc is missing, skip this step; do not revoke a parent folder's approval.
For a permissions error, resolve access to the named file before editing.
If direnv is unavailable, keep the affected sessions closed while editing and
review the final file before using direnv again. See the
direnv approval commands.
Choose separately for each file you inspected:
| What you found | What to do |
|---|---|
| Entirely generated, untracked, and no longer needed | Move that exact .envrc or .code-workspace into a removed-files subfolder of your backup. Keep your earlier copies and the rest of .vscode. |
| Customized or shared | Keep the file and make only the edits described below. |
| Already missing | Leave it missing; no replacement is needed for cleanup. |
If you moved both generated files out of the project, go straight to Check the result.
If you keep .envrc: remove the identity exports (CODEX_IDENTITY and
CODEX_HOME) and the associated directory check,
dotenv_if_exists "$CODEX_HOME/.env", identity watch_file calls, and
log_status "Codex identity: ..." line. Remove the helper's PATH_add only if
other commands do not need it. Remove associated
if/fi blocks together. Compare with the
Codex environment block; generated files
also add the helper path and status message.
Keep Python/R/Node setup, other environment variables, project-specific paths,
and unrelated .env loading. If you cannot identify a line's purpose, leave
it in place until you have checked it.
If you keep a workspace or .vscode/settings.json: restore the previous
window.title, or remove the helper's [CODEX: ...] label. In
workbench.colorCustomizations, restore or remove only values introduced by
the helper: statusBar.background, statusBar.foreground,
statusBar.noFolderBackground, and statusBar.debuggingBackground.
Preserve other settings, folders, tasks, and launch configuration. Changing
the label alone does not change the identity.
If a custom .envrc remains, check its syntax:
bash -n "/path/to/project/.envrc"Fix any syntax errors, read the complete file, and then approve it only if the remaining commands are intended:
direnv allow "/path/to/project/.envrc"If .envrc was removed, skip both commands.
Open a fresh standalone Terminal with the direnv hook enabled. Enter the project folder, wait for the prompt, then run:
direnv status
printf 'CODEX_IDENTITY=%s\nCODEX_HOME=%s\n' "${CODEX_IDENTITY-}" "${CODEX_HOME-}"You are done when this folder no longer selects the removed identity and
your normal project tools still work. Open the folder normally in VS Code to
check its title, colors, and other settings. Review any tracked-file edits with
git diff. Keep the backup until you have checked the result.
If the old identity or title remains, follow The old identity still appears.
- Only an old window or terminal shows it: quit that identity's editor and start a fresh session. Running processes keep their existing environment.
- A fresh terminal still shows it: inspect the
.envrcpath indirenv statusand your shell startup files. direnv also searches parent folders; keep shared configuration intact while tracing the source. A parent or shell-wide identity is separate from this folder's removed setup. - Only the title or colors remain: check the workspace you actually opened
and
.vscode/settings.jsonfor settings you previously merged there. Return to step 3 to edit those properties.
Skip this section if the folder is not in Git or you want to leave exclusions alone. Stale ignore rules do not keep a Codex context active.
From inside the project, locate its actual local exclude file:
(
cd "/path/to/project" || exit
git rev-parse --git-path info/exclude
)Open the reported path, resolving a relative path from the project folder, and
back it up. Remove only helper-added, exact patterns for files you moved out of
the project. In nested projects, those patterns include the path from the
repository root. Keep rules for retained local files, broad .vscode rules,
other projects, shared .gitignore files, and global ignores.
Compare the backup with the current files. Restore only the files or settings
you changed, preserving newer work. If you restore .envrc, read it before
running direnv allow "/path/to/project/.envrc", then start a fresh editor
session. This brings back the identity selection recorded in that file.
Return to Projects and VS Code for normal project setup, or Troubleshooting for a different problem.