Auto Rename

Auto-rename cmux tabs & workspaces

Summarize what a cmux tab (surface) or workspace is actually doing, generate a concise helpful name, and apply it with cmux rename-tab / cmux rename-workspace.

REQUIRED BACKGROUND: the companion using-cmux-cli skill covers handle formats, identify, tree, read-screen, and its gotchas (especially the Claude Code ghost-autosuggest trap). This skill assumes that vocabulary.

Current context (resolved at skill load)

```! cmux identify --json --id-format both 2>/dev/null || echo '{"error":"cmux identify failed — outside cmux or socket unreachable"}'

`--id-format both` gives each entry its stable UUID (`*_id`) alongside its positional `*_ref`. Target by the UUID.

- `caller.*` — where this agent runs. Default target for "rename **this** tab/workspace".
- `focused.*` — where the user is looking. Target this when they say "the tab I'm looking at".

## Step 1 — Resolve the target(s)

| User says | Target |
|-----------|--------|
| "rename this tab" / "auto-name my tab" | `caller.tab_id` (UUID) |
| "rename this workspace" | `caller.workspace_id` (UUID) |
| "rename both" / bare "auto-rename" | caller tab **and** caller workspace |
| "the tab/workspace I'm looking at" | `focused.*` |
| "the tab running the build" / a named workspace | find it: `cmux tree --all --json` + `jq`, or the using-cmux-cli `find-surface.sh` helper |
| "rename everything here" / "all tabs in this workspace" / "fix all the tab names" / bare "all" | scoped batch — every tab under `caller.workspace_id`, **plus** the workspace itself (see Batch mode) |

**Scope is always the current workspace, never all of them.** There is deliberately no "rename every workspace" mode — a mass rename across many workspaces is disruptive and unwanted. "all" means "everything in *this* workspace."

**Gotcha (verified):** `cmux tree --workspace  --json` ignores the workspace filter and returns the whole tree — grabbing the first surface from it targets the wrong workspace and `rename-tab` fails with `not_found: Tab not found`. Either use the plain-text `cmux tree --workspace ` (which *is* scoped) or filter the JSON yourself by UUID: `cmux tree --all --json --id-format both | jq --arg w "" '.. | objects | select(.id==$w)'`.

## Step 2 — Gather evidence for the name

**If the target is this agent's own tab/workspace, name it from what you're actually working on — skip read-screen.** Your live conversation is the best evidence there is.

**For any other surface, read it and distill the name yourself, on the main model — do not delegate to a subagent.** Naming well is a judgment task (recognize what a surface *is*, ignore transient noise, dedupe similar ones); a small distiller model reliably gets this wrong — it pattern-matches the most prominent text on screen instead of understanding purpose (e.g. it named a lazygit TUI showing a fetch error `git fetch temp` instead of `lazygit`). Reading a few hundred lines to produce a label is cheap enough to do inline, and the quality and speed are both better than fanning out subagents.

Read shallow first, go deeper only if inconclusive:

```bash
cmux read-screen --workspace  --surface  --scrollback --lines 60

Supplement for workspaces (cwd, git branch, ports, status pills tell you the project even when screens are quiet):

cmux sidebar-state --workspace 
cmux tree --workspace    # existing tab titles are evidence too

Name the surface's purpose, not the most prominent text on screen. A TUI showing a transient error is still what it is (a git TUI showing a failed fetch is lazygit, not git fetch temp). A command that just scrolled past isn't the surface's job if a long-running process owns it. Understand the surface, then label it.

Agent sessions (claude / codex / opencode / etc.)

If the scrollback shows an agent REPL, name it after the task the session is doing, not the tool. Read the most recent user prompt and assistant activity in the scrollback and distill the task.

• ❌ "claude session", "codex" — says nothing
• ✅ "fix lindris 500s", "gws gmail-read skill"

Ghost-autosuggest warning: agent REPLs render a grayed next-prompt suggestion inside the input box that looks like real user input in read-screen output. Text sitting alone in the prompt with no output below it is a suggestion, not the task. Base the name on prompts that have responses under them.

Non-agent terminals

Evidence, in order of usefulness: the running foreground command (dev server, tail, ssh host, tests), recent commands + output in scrollback, then cwd/branch from sidebar-state. A browser surface names itself after the page/site. A dedicated TUI (lazygit, htop, k9s, …) is named for what it is — the tool name here is the activity.

Step 3 — Generate the name

Rules:

• 2–5 words, scannable in a tab bar; no trailing punctuation.
• Name the activity or subject, never the shell/tool: not "zsh", "terminal", "claude", "node".
• Tab names say what that surface does: dev server :3000, ssh prod-web1, tail nginx logs, tests (watch).
• Workspace names say the project/mission, usually anchored on repo or task: lindris frontend, gws gmail-read skill.
• When tab and workspace are both renamed, don't duplicate — workspace carries the project, tab carries the activity.
• Idle/empty shell with nothing to go on → name by cwd/branch (e.g. claude-plugins), or leave it and say so rather than inventing something.

Step 4 — Apply

cmux rename-tab --workspace  --tab  "name here"
cmux rename-workspace --workspace  "name here"

**Pass explicit handles you resolved this run from cmux identify --json --id-format both — even when renaming your own tab. Use caller.workspace_id + caller.tab_id (UUIDs). A freshly-resolved UUID is verified to work here (rename-tab --workspace --tab applies correctly). The failure mode to avoid is the stale env-var default**: a bare cmux rename-tab "name" (no explicit handle) run from inside the tab being renamed has returned Error: not_found: Tab not found in practice — because $CMUX_TAB_ID/$CMUX_SURFACE_ID were captured at spawn and can go stale, not because UUIDs don't work. Resolve fresh, pass the UUID.

To clear a tab name back to automatic: cmux tab-action --action clear-name --tab .

Step 5 — Verify

cmux tree --workspace 

Confirm the new title actually appears. Then tell the user what each thing was named and (briefly) why.

Batch mode — this workspace (all tabs + the workspace)

Triggered by "all", "rename everything here", "fix all the tab names". Scope is the current workspace only (caller.workspace_id) — its tabs and itself. Never fan out across other workspaces.

1. Enumerate this workspace's tabs. cmux tree --all --json --id-format both, filter to caller.workspace_id, and collect the .id (UUID) of every surface under its panes — each surface is one tab. Skip tabs already well-named unless asked to redo everything.
2. Read and name each yourself, on the main model (Step 2) — no subagents. Read each surface shallow first (--lines 60), distill by purpose. Your own tab (caller.surface_id) is named from live context. This is fast (no spawn overhead) and gives better names than a distiller model, which is the whole reason batch naming is done inline.
3. Name the workspace itself from the collective picture — its cwd/branch (cmux sidebar-state --workspace ) plus the tab purposes you just gathered tell you the project/mission.
4. Apply every rename by UUID (rename-tab per tab, rename-workspace once), then one cmux tree --workspace to confirm. Per Step 3's no-duplicate rule: the workspace name carries the project, the tab names carry each activity.

For a workspace with an unusually large number of tabs, read shallow and name in a single pass rather than exhaustively — a good-enough name beats a slow perfect one.

Common mistakes

| Mistake | Fix | |---------|-----| | Naming after the tool ("claude", "zsh") | Name the task/subject the tool is working on | | Trusting the ghost autosuggest as the session's task | Only use prompts that have output beneath them | | Omitting --workspace/--tab and hitting not_found: Tab not found | The stale env-var default is the culprit, not the UUID format; resolve a fresh caller.workspace_id/caller.tab_id from identify --id-format both and pass those | | Long sentence names | 2–5 words; tab bars truncate | | Inventing a name for an idle shell | Fall back to cwd/branch, or say there's nothing to name it from |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jtsternberg
• Source: jtsternberg/claude-plugins
• License: MIT

Install and usage instructions live in the source repository linked above.