wezterm-notify

Signals agent working-session status to WezTerm via OSC 1337 SetUserVar sequences. WezTerm Lua config reads pi_status from pane:get_user_vars() to show a spinner while the agent works and change the tab color when it finishes.

Only active when WEZTERM_PANE is set — silent no-op outside WezTerm.

How it works

The extension tracks an agent-level working session (start → finish), then emits coalesced pi_status transitions:

Lifecycle edge	pi_status value	Effect
before_agent_start / agent_start	working	Enter working once (duplicate starts are coalesced)
agent_end	done	Inactive tab turns blue
input while working	(unchanged)	Avoids mid-run flicker
input while idle, session_start, session_shutdown	(cleared)	Reset to neutral

Entering working emits an immediate pi_heartbeat, then pulses continue every 500ms while working to force WezTerm redraws. Spinner frames advance deterministically from those redraws, and only while work is active.

WezTerm Lua setup

This extension emits the signals. A Lua module shipped alongside it consumes them in WezTerm.

Copy or symlink tallow.lua into your WezTerm config directory:

# Find the file inside tallow's install
TALLOW_DIR="$(dirname "$(which tallow)")"

# Symlink into WezTerm config
ln -s "$TALLOW_DIR/../lib/node_modules/tallow/extensions/wezterm-notify/wezterm/tallow.lua" \
  ~/.config/wezterm/tallow.lua

Then add one line to your wezterm.lua:

require("tallow").setup()

setup() owns both format-tab-title and update-right-status. If you already have either handler, compose manually with tallow.tick(), tallow.get_tab_status(tab), and tallow.spinner_char() instead.

With custom colors:

require("tallow").setup({
  spinner_color = "#d8a274",
  done_color = "#61afef",
  active_color = "#ccb266",
  inactive_color = "#737373",
})

For the full integration picture, see the WezTerm Integration guide.

Relationships with other extensions

wezterm-pane-control

wezterm-notify enhances the pane control extension. Together they provide full WezTerm integration: pane/tab management plus visual working-session indicators.