Managed worktrees should use readable, task-derived names instead of opaque IDs (883f, 576d11db-…)
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 125k
- Forks
- 19.5k
- PR merge metrics
- PR metrics pending
Description
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the App and CLI managed-worktree creation entry points that produce directories under ~/.codex/worktrees; compare the generated 4-character and UUID names with the hand-named examples and existing git worktree behavior. Done means task-derived names are sanitized, length-capped, collision-safe, and fall back to an ID when empty; verify the proposed default across both App and CLI.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, rust
- Domain
- cli, developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100