Managed worktrees should use readable, task-derived names instead of opaque IDs (883f, 576d11db-…)

Open 💬 1 comment Opened Aug 13, 2026 by vltansky

What variant of Codex are you using?

App + CLI (managed worktrees under ~/.codex/worktrees), codex-cli 0.146.0, macOS

What feature would you like to see?

Managed worktrees are created with opaque, meaningless directory names — a 4-character hex ID (and sometimes a full UUID):

~/.codex/worktrees/883f/project-name
~/.codex/worktrees/0018/todo
~/.codex/worktrees/1d27/...
~/.codex/worktrees/62ab/...
~/.codex/worktrees/576d11db-32f2-4f20-a5a8-2b3625cc6db5/...

Here is my actual ~/.codex/worktrees listing today (22 entries):

0018  1d27  62ab  6dbb  760f  81ec  8d9c  9a72  a629  c49c  c566  e64d  f261
576d11db-32f2-4f20-a5a8-2b3625cc6db5
a05b0fce-c1d9-470e-8fa0-196b67efc959
e34beafd-d3d9-491d-9f18-863cdd3abf29
ef2d4ab1-f188-4c60-a16a-9a1651882953
dependency-smoke  docx-e2e  fix-451  runtime-smoke  worktree-improvements

The hand-named ones at the end are instantly identifiable. The generated ones tell me nothing.

Please derive the worktree name from the task instead — the way Claude Code does it, e.g. test-suite-audit-113627: a slug of the task/prompt plus a short disambiguating suffix.

Why the current naming hurts:

  1. Outside the app, worktrees are unidentifiable. git worktree list, cd, shell history, editor window titles, ls ~/.codex/worktrees, tab titles in a terminal multiplexer, docker ps mounts — all show 883f, and there is no way to tell which of a dozen concurrent tasks it belongs to without opening the app and cross-referencing.
  2. Cleanup is guesswork. When stale worktrees accumulate (see #35383), deciding which of 0018, 62ab, c49c is safe to delete requires inspecting each one's branch and diff.
  3. Branch names are not a fallback. Several of my generated worktrees are sitting on master, so the branch carries no task information either.
  4. Inconsistent formats. Some are 4-hex, some are full UUIDs — the latter are long enough to cause UI truncation (#23183) while still being unreadable.

Proposed behavior:

  • Default the worktree directory name to a slug derived from the first user message / task title, e.g. test-suite-audit, with a short numeric or hex suffix only when needed for uniqueness (test-suite-audit-113627, or test-suite-audit-2).
  • Cap the slug length (e.g. 32–40 chars) so dropdowns and status lines stay readable.
  • Sanitize to a filesystem- and Git-safe charset; fall back to the current ID scheme if the slug ends up empty.
  • Optionally expose the pattern as a config setting (e.g. worktree_name_template) for people with their own conventions.
  • Nice to have: allow renaming an existing worktree from the UI, and reuse the same slug for the auto-created branch so directory and branch names line up.

Additional information

Related existing issues (none of them cover auto-generated name readability):

  • #22751 — asks for manually specifying a worktree name when creating a permanent worktree; this request is about the default generated name so the common path doesn't require manual naming.
  • #23183 — long worktree names clip the "Handoff to Worktree" dropdown; a length-capped slug helps here, and the current UUID-format names are the worst case.
  • #14498 — renaming a Codex folder/worktree causes the folder name to be overlapped by the worktree name.
  • #35383 — stale worktree/temp-clone accumulation, which opaque names make much harder to triage manually.

View original on GitHub ↗

1 Comment

darchambault · 5 days ago

I would suggest also reversing the path ordering for the project name and the worktree slug. So instead of having:

~/.codex/worktrees/883f/project-name

You would have:

~/.codex/worktrees/project-name/test-suite-audit-113627

This makes for a cleaner directory structure under ~/.codex/worktrees/, and also allows proper identifications for external tools, editors and IDEs that use the base directory name as the project identifier.