Allow use of worktrees created outside codex app

The app wasn't designed to support this, so we wouldn't consider this a bug. I'm changing this from a bug report to an enhancement request.

It appears to be a bug after all - I created a worktree using codex - yet can't switch my working branch to it with similar error.

I agree it seems to be a bug. I'll have a bunch of of threads going, one of them will be associated with a specific corktree, some how it gets disassociated in the app with that worktree and I can't get codex to move the thread back to it.

Work around is to use the git CLI to "git worktree remove .." and then go back to codex and pick the thread, then pick the branch (now a branch not worktree so codex doesn't puke any more) and tell it to run on a new worktree, converting the branch back to a worktree...

In my project, I have a script to set up the Git worktree, which copies files and creates symlinks. It used to work in Codex by using the command codex app /path/to/the/worktree, which would add a new project to the Codex app. However, this no longer functions in the latest Codex version 26.602.30954, and no project is added.

UPDATE: My workaround is to avoid creating the Git worktree and let Codex handle that. I also moved the setup and cleanup scripts to the environment configuration.

Until Codex supports opening existing worktrees natively, I made a small macOS-only skill as a temporary workaround.

It discovers any worktree registered with Git and opens the selected directory as a separate Codex/ChatGPT workspace without switching branches or modifying Git state.

npx skills add https://github.com/sepantajoshani/agents-skills --skill codex-open-worktree

Skill page: codex-open-worktree

I’d appreciate feedback from anyone trying it with worktrees created outside Codex.

I traced a related gap for CLI-created sessions running in externally managed worktrees.

Today these sessions can be discovered by app-server clients (for example, through Recent), but app-server has no persisted association between a thread and a saved project's primary folder. Exact cwd matching cannot represent this safely: the real worktree cwd and branch must remain unchanged, and rewriting cwd would also affect execution, workspace, sandbox, and permission semantics. There is also no supported way to attach or reattach an existing thread after creation.

A narrow open-protocol option would be an experimental, advisory projectRootHint:

• thread/start can set it;
• thread/read and thread/list return it;
• thread/list can filter by one or more normalized exact hints;
• thread/metadata/update can set or clear it for existing sessions;
• forks inherit it;
• CLI start/resume/fork accept --project-root-hint;
• rollout and SQLite persistence preserve it without changing cwd, sandbox, permissions, or trust.

The hint would be an absolute path in the app-server host's path namespace, not a Desktop App project ID. That keeps the contract useful to other app-server clients and avoids coupling the open protocol to a private project registry.

This would not make the Desktop App open arbitrary external worktrees by itself. It would provide the missing session-association layer that an App consumer could map to its saved Local Projects.

I have a locally validated prototype of this shape, including new/existing-session coverage, persistence and reconciliation tests, schema updates, and documentation. I have not opened a PR because the repository accepts external code contributions by invitation only.

Would this API direction align with the intended solution for external worktrees? If so, would a maintainer be open to inviting a focused PR?