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:
- 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 psmounts — all show883f, and there is no way to tell which of a dozen concurrent tasks it belongs to without opening the app and cross-referencing. - Cleanup is guesswork. When stale worktrees accumulate (see #35383), deciding which of
0018,62ab,c49cis safe to delete requires inspecting each one's branch and diff. - Branch names are not a fallback. Several of my generated worktrees are sitting on
master, so the branch carries no task information either. - 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, ortest-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.
1 Comment
I would suggest also reversing the path ordering for the project name and the worktree slug. So instead of having:
~/.codex/worktrees/883f/project-nameYou would have:
~/.codex/worktrees/project-name/test-suite-audit-113627This 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.