Codex Desktop should guide Git initialization before worktree creation

Open 💬 1 comment Opened Apr 11, 2026 by warment

Codex Desktop worktree creation has poor behavior for newly opened folders that are not initialized Git repositories or have no commits.

Expected behavior:
When a user opens a normal project folder and clicks the UI button to create a worktree/branch, Codex should either:

  1. detect that the folder is not a Git repo and offer to initialize it, create or suggest a sensible .gitignore, and make the first baseline commit; or
  2. show a clear guided message explaining that the project needs Git initialization and a first commit before worktrees can be created.

Actual behavior:
The UI can hide the worktree button or fail with low-level Git errors such as:

fatal: invalid reference: HEAD

Local reproduction/context:

  • A new project folder at /Users/sergey/ai/bene_rus_v2 was not a Git repository at all, so the user could not create a worktree through the expected UI flow.
  • An accidental empty parent repository at /Users/sergey/.git also caused child folders to be misdetected as part of that empty repo, so Codex tried to create a worktree from a non-existent HEAD.
  • The user expected to open a project folder and use the UI button, not manually diagnose Git state.

Why this matters:
A normal user should not need to understand Git internals, run git init manually, create a .gitignore, make a first commit, or diagnose HEAD/reference errors just to use Codex's worktree feature.

Suggested fix:
Add a preflight check before worktree creation:

  • detect whether the selected folder is inside a Git repository;
  • detect whether HEAD resolves to a valid commit;
  • detect whether the resolved Git root is unexpectedly a parent directory such as the user's home folder;
  • if no repo exists, offer an "Initialize Git project" flow;
  • if a repo exists but has no commits, offer a "Create initial commit" flow;
  • if the repo root is a suspicious parent directory, warn the user and ask whether to use the selected folder as a separate project;
  • only run git worktree add after HEAD is valid.

The UI should surface this as a guided setup flow, not as raw Git errors or a missing worktree button.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗