iterm-vars

claude-iterm-vars

A Claude Code plugin that exposes session info as iTerm2 user variables. The variables work anywhere iTerm2 accepts an interpolated string: tab subtitle, window title, badge, and status bar. Vertical tabs benefit the most, since the subtitle line is usually wasted space.

The screenshot above shows three tabs, each with a custom subtitle built from \(user.claude_subtitle), and the same information reused in the status bar.

Requirements

• macOS with iTerm2
• Claude Code running directly in iTerm2 (not inside tmux, unless you enable OSC passthrough)
• jq, base64, git, ps (all default on macOS)

Install

/plugin marketplace add sherifabdlnaby/claude-iterm-vars
/plugin install iterm-vars@sherifabdlnaby
/reload-plugins

iTerm2 setup

In iTerm2, open Preferences, Profiles, General. The Title row has three fields (Title, Subtitle, Icon) that accept interpolated strings. You can also reference the same variables from the status bar (Preferences, Profiles, Session, Configure Status Bar) or from the badge (Preferences, Profiles, General, Badge).

Easiest starting point, paste into Subtitle:

\(user.claude_subtitle)

That gives you ✳ mode | state | repo, with segments dropping cleanly when empty.

For more control, use the raw variables listed below and compose your own format.

Variables

Name	Meaning	Updated
claude_session	Last 6 chars of the session UUID	Every event
claude_repo	Git repo name, or cwd basename	Every event
claude_mode	Permission mode (auto, plan, default)	Every event
claude_state	idle, thinking, tool(<name>), waiting	Every event
claude_title	First user message or Claude's own session title	First prompt, or resume
claude_last_usr_msg	Last user message, truncated	UserPromptSubmit
claude_last_agent_msg	Last assistant reply, truncated	Stop
claude_subtitle	Composed ✳ mode | state | repo with empty segments dropped	Every event

claude_title prefers Claude Code's custom-title from the transcript when present, and otherwise captures the first user message.

Title format examples

iTerm2's title-field expression grammar doesn't support string literals, comparisons, ternary, or + concat. That means you can't do conditionals inline. Use claude_subtitle for the common case, or keep in mind that empty raw variables leave their separators behind.

Basic:

\(user.claude_subtitle)

Raw composition (watch for orphan separators when values are empty):

\(user.claude_repo): \(user.claude_last_usr_msg)

How it works

Each hook event runs hooks/dispatch.sh. The script reads the event payload on stdin, walks parent PIDs to find the controlling tty, and writes iTerm2 OSC 1337 SetUserVar escapes to it. iTerm2 stores the variables and expands them wherever you reference them.

No LLM calls. Runs in well under 50ms per event.

Troubleshooting

• Nothing appears: confirm your profile actually references \(user.claude_*) somewhere, and that /reload-plugins shows iterm-vars in the summary.
• Stale title: delete the sidecar and the next message recaptures.

  rm ~/.claude/plugins/data/iterm-vars-sherifabdlnaby/titles/*
  

• tmux: add set -g allow-passthrough on to your tmux config. Untested beyond that.

License

MIT.