openai / openai/codex

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

Open
#38,326 1 comment 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

app enhancement
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:

  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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.