Skip to content

Use the captured OSC window title as the surface's tab label #221

Closed

Description

@javierguevara-habi

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:

  1. 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.
  2. UserPromptSubmit races. /rename does 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

  1. amirlehmam commented on Sep 7, 2026

    @amirlehmam
    Owner

    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:

    customTitle (rename-surface / UI)
      → agent spawn label (`wmux agent spawn --label`)
        → OSC 0/2 window title
          → cwd → shell
    

    Your ordering, with agentLabel kept where it already was — an orchestrator that named a worker reviewer is 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 = false in ~/.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 legitimate vim ~/notes.txt title 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. SurfaceRef is what goes into session.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 plain pwsh pane 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:

    sent onTitleChange received
    ESC ] 2 ; build LF failed BEL "buildfailed" — xterm strips C0 itself
    ESC ] 2 ; a NEL b BEL never fires — a C1 aborts the sequence
    ESC ] 2 ; safe U+202E evil BEL "safe\u202Eevil" — passed straight through

    So 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 UserPromptSubmit racing the session file is what made it obvious this belonged in the terminal layer rather than in a plugin.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions