Repository navigation
Description
What wmux does today
wmux already reads the OSC 0/2 window title of every terminal surface — there is an
onTitleChange subscription that trims it, caps it and stores it per surface. But the only
consumer is agent detection. It never reaches the tab.
The tab label resolves roughly as customTitle ?? <fallback> ?? cwd ?? "Agent". The OSC
title is not in that chain, so a pane whose program is actively announcing what it is doing
still shows a tab named after its directory.
Checked on 2.9.0.
The ask
Use the captured OSC title as a fallback for the surface's tab label, below an explicit
customTitle:
customTitle (rename-surface / UI) → OSC title → current fallback (cwd, "Agent")
An explicit rename should keep winning. This only fills the gap where the tab has no name
of its own but the program in it has been announcing one all along.
Why it matters
With six or seven panes open, every tab reads the same because every pane is in the same
directory. There is nothing to scan for.
Claude Code is the case that made me notice: it emits the conversation's own title as OSC 2
— the auto-generated topic, and whatever you set with /rename (its
terminalTitleFromRename setting, on by default). In Windows Terminal that lands in the tab
for free. In wmux it is captured and dropped.
It is not Claude-specific though. Shells with prompt integration, vim, ssh, long npm
scripts — anything that sets a window title would start labelling its own tab.
What it takes to work around it
A Claude Code plugin with hooks on SessionStart, UserPromptSubmit and Stop that shells
out to wmux rename-surface, deriving the name from ~/.claude/sessions/<pid>.json (for
/rename) or from the first user message in the session transcript.
It works, and it is worse than reading the OSC title in two specific ways:
- No hook fires on
/rename. The new name is only picked up on the next hook event, so
renaming and walking away leaves the tab stale. UserPromptSubmitraces./renamedoes fire it, but the hook reads the session file
before Claude Code has written the new name to it — so it sees the old one, decides
nothing changed, and exits. The name lands milliseconds later.
Both disappear if the tab just follows the title the program is already sending.
Related
Same install as #214.
Activity
feat(tabs): label a terminal tab with its program's window title (#221)
amirlehmam commentedon Sep 7, 2026
Shipped in 2.10.0. The tab now reads the title the program is already sending, and both of the workarounds you described stop being necessary — no hooks, no session file, no race.
The chain is:
Your ordering, with
agentLabelkept where it already was — an orchestrator that named a workerrevieweris identifying that pane within a wave, which stays more useful than whatever its TUI is announcing this second. An explicit rename still wins outright, which was the original reason the title was captured but never rendered: a tab's name is the user's to set.On by default, with a switch
Settings → Terminal → Tabs → Use the window title as the tab label, or
[terminal] osc-title-tabs = falsein~/.wmux/config.toml.The switch exists because OSC 0 fires the same callback as OSC 2, and Git for Windows' default profile sets it to
MINGW64:/c/Users/.... For a Git Bash pane that is strictly worse than the cwd basename it replaces. Turning it off restores the old labels everywhere. There is deliberately no heuristic that tries to tell an "interesting" title from a path — wmux stopped guessing about pane contents in 0.39.0 and a rule that silently drops a legitimatevim ~/notes.txttitle would be the same mistake in a smaller place.Two things worth recording, since neither is obvious
The title is not stored on the surface.
SurfaceRefis what goes intosession.json, and the split tree is persisted nearly verbatim — so a title parked there would come back after a restart on a fresh shell that has set no title at all, labelling a plainpwshpane with whatever the program that used to live in it was doing last week. It lives in its own store slice, which is live-only by construction rather than by remembering to strip a field in three separate save paths.A dedupe is not enough to make this cheap. The tab bar subscribes to that map now, and a program running a spinner in its own title (
⠋ building→⠙ building) emits distinct titles at ~10 Hz. One store write per change is a re-render of every subscriber at PTY speed. So: the setter no-ops on an unchanged title (several shells re-emit the same one on every prompt) and the producer throttles at 200 ms trailing.What the real xterm turned out to do
I sanity-checked the sanitizer against an actual xterm instance driven with real OSC bytes rather than reading its source, and it moved the code:
onTitleChangereceivedESC ] 2 ; build LF failed BEL"buildfailed"— xterm strips C0 itselfESC ] 2 ; a NEL b BELESC ] 2 ; safe U+202E evil BEL"safe\u202Eevil"— passed straight throughSo the control-character strip is defence in depth, and the bidi strip is the one line actually doing work: U+202E does not merely reverse its own tab, it reorders everything drawn after it, so without that a pane's program could rewrite the layout of chrome it was never given. Titles are also collapsed to one line and capped at 256 chars.
Thanks for the write-up — the detail about
UserPromptSubmitracing the session file is what made it obvious this belonged in the terminal layer rather than in a plugin.fix(tabs): a console's default exe-path title is not a tab label (#286)
feat(sidebar): name default-named workspaces from the terminal's OSC …
feat(sidebar): name default-named workspaces from the terminal's OSC …