Feature request: configurable terminalTitleTemplate with cwd / project placeholders

Resolved 💬 3 comments Opened May 21, 2026 by mackenzieclark Closed May 21, 2026

Problem

Claude Code sets the terminal title to "Claude Code" (or the session/agent/haiku name if available) on every instance, via OSC 0 escape sequences. When running multiple Claude Code instances in different repositories — say ~/repos/foo, ~/repos/bar, ~/repos/baz — every terminal tab, window-list entry, and dock preview reads "Claude Code". The user has to focus each one and read the status line to figure out which repo it's running in.

claude --name <name> works as a per-invocation override, but requires the user to remember to type it (or wire up their shell aliases, terminal profiles, etc.). It also doesn't update if the working directory changes during a session.

Request

A terminalTitleTemplate setting in ~/.claude/settings.json (or settings.local.json / project-level) that lets users define a title pattern with placeholders. Example:

{
  "terminalTitleTemplate": "{basename} · Claude"
}

Suggested placeholders:

  • {cwd} — full working directory path
  • {basename} — last path component (most useful for repos: axan, claude-code, etc.)
  • {project} — name of the enclosing git repo (if any) or project root
  • {sessionName} — the name passed via --name or /rename, if set
  • {agentName} — the active subagent name, if any

A default template (or even just a built-in mode like "basename-and-claude") would make multi-instance workflows usable out of the box.

Why this is a Claude Code concern, not a terminal-emulator concern

Many users hit this exact pain in vanilla terminal emulators (GNOME Terminal, iTerm, etc.) — anywhere tabs/windows are distinguished by title. The terminal emulator is showing what Claude Code emits via OSC, so the fix has to be on the emitting side. Terminal-side sticky-title overrides exist but require per-emulator implementation.

Workarounds today

  • claude --name X — works but is per-invocation; doesn't survive cwd changes; user has to remember
  • SessionStart hook to emit a custom OSC 0 sequence — works but fires after Claude Code's initial title write, so the user sees a flicker; also brittle to internal Claude Code title-update timing

A first-class config setting would supersede both.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗