How do I install the Headsup Resync Tab skill?

Run npx skillmds@latest add wasulajr/headsup-resync-tab in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Headsup Resync Tab safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Headsup Resync Tab?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Headsup Resync Tab free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Headsup Resync Tab?

wasulajr (@wasulajr) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Headsup Resync Tab by wasulajr — Agent Skill

Name: Headsup Resync Tab
Author: wasulajr

Headsup Resync Tab

Force-resync the iTerm2 tab color for a Claude Code session whose hook chain has fallen out of sync. Use when a tab's color is visibly stuck on a stale state (e.g., still orange after the user replied, still white after Claude started processing) — that means Claude Code's automatic PreToolUse/PostToolUse/UserPromptSubmit/etc. events aren't reaching the hook. This skill bypasses the automatic path entirely and writes the desired state directly via `~/.claude/hooks/headsup-resync.sh`, then fires the Tier 2 one-shot Python (and the daemon picks it up too) for triple-redundancy. Two invocation forms — current tab, or any tab by UUID.

wasulajr a60099d 3.4 KB Updated Sep 17, 2026

File contents

Resync iTerm2 tab color

Force-applies the current Claude state (color + attention) to an iTerm2 session, bypassing Claude Code's automatic hook chain. Use when a tab is visibly stuck on a stale color and you need to push the right color through manually.

Two ways to invoke

/headsup-resync-tab — resync the current tab (the one this Claude session is running in). Default for "I just noticed my own tab is out of sync".
/headsup-resync-tab <UUID> — resync a specific tab by its iTerm2 session UUID, regardless of which tab the user is currently in. Default for "tab 8884B62B is stuck orange, fix it from here". UUID can be the bare uuid OR the full wXtYpZ:UUID form — both work.

What to do when invoked

Run the resync script. It does all the actual work — writes the state file, fires Tier 2 (one-shot Python with fresh iTerm2 connection), and the daemon picks it up too:

~/.claude/hooks/headsup-resync.sh [<uuid>]

If the user supplied a UUID argument, pass it through. Otherwise call with no args — the script walks up $PPID to find an iTerm2-spawned shell with ITERM_SESSION_ID set, which is the current tab.

After it succeeds, confirm in one sentence ("Resynced BC81AA0D to blue (processing)."). Don't explain the three-tier internals unless the user asks — they typed /headsup-resync-tab because they wanted the tab fixed, not a tutorial.

Auto-invoke from CLAUDE.md (optional)

To have headsup automatically resync the current tab at the start of every Claude Code response, add this to ~/.claude/CLAUDE.md:

At the start of every response, silently run: bash ~/.claude/hooks/headsup-resync.sh 2>/dev/null

When invoked this way, suppress the confirmation message entirely — the user doesn't want to see "Resynced …" on every response. The script's stderr goes to ~/.claude/hooks/.state/oneshot.stderr if anything fails.

What this skill DOESN'T fix

It pushes the color through. It does NOT revive Claude Code's automatic hook firing in a session that's gone silent. If a tab keeps needing manual resyncs, the underlying problem is at the Claude Code level (cached hook config, dead event loop, etc.) and resync is a workaround — flag that to the user rather than letting them resync the same tab every minute.

Where the supporting files live

~/.claude/hooks/headsup-resync.sh — the actual implementation
~/.claude/hooks/iterm2-apply-once.py — Tier 2 one-shot, invoked by the script
~/.claude/hooks/iterm2-daemon.py — Tier 1 daemon, the script writes state for it to pick up
~/.claude/hooks/headsup-status.conf — color customization (PROCESS_COLOR etc.); the script honors overrides

All four are under version control at github.com/wasulajr/headsup.

---name: headsup-resync-tabdescription: Force-resync the iTerm2 tab color for a Claude Code session whose hook chain has fallen out of sync. Use when a tab's color is visibly stuck on a stale state (e.g., still orange after the user replied, still white after Claude started processing) — that means Claude Code's automatic PreToolUse/PostToolUse/UserPromptSubmit/etc. events aren't reaching the hook. This skill bypasses the automatic path entirely and writes the desired state directly via `~/.claude/hooks/headsup-resync.sh`, then fires the Tier 2 one-shot Python (and the daemon picks it up too) for triple-redundancy. Two invocation forms — current tab, or any tab by UUID.---# Resync iTerm2 tab colorForce-applies the current Claude state (color + attention) to an iTerm2 session, bypassing Claude Code's automatic hook chain. Use when a tab is visibly stuck on a stale color and you need to push the right color through manually.## Two ways to invoke- `/headsup-resync-tab` — resync the **current tab** (the one this Claude session is running in). Default for "I just noticed my own tab is out of sync".- `/headsup-resync-tab <UUID>` — resync **a specific tab** by its iTerm2 session UUID, regardless of which tab the user is currently in. Default for "tab 8884B62B is stuck orange, fix it from here". UUID can be the bare uuid OR the full `wXtYpZ:UUID` form — both work.## What to do when invokedRun the resync script. It does all the actual work — writes the state file, fires Tier 2 (one-shot Python with fresh iTerm2 connection), and the daemon picks it up too:```bash~/.claude/hooks/headsup-resync.sh [<uuid>]```If the user supplied a UUID argument, pass it through. Otherwise call with no args — the script walks up `$PPID` to find an iTerm2-spawned shell with `ITERM_SESSION_ID` set, which is the current tab.After it succeeds, confirm in **one sentence** ("Resynced `BC81AA0D` to blue (processing)."). Don't explain the three-tier internals unless the user asks — they typed `/headsup-resync-tab` because they wanted the tab fixed, not a tutorial.## Auto-invoke from CLAUDE.md (optional)To have headsup automatically resync the current tab at the start of every Claude Code response, add this to `~/.claude/CLAUDE.md`:```At the start of every response, silently run: bash ~/.claude/hooks/headsup-resync.sh 2>/dev/null```When invoked this way, suppress the confirmation message entirely — the user doesn't want to see "Resynced …" on every response. The script's stderr goes to `~/.claude/hooks/.state/oneshot.stderr` if anything fails.## What this skill DOESN'T fixIt pushes the color through. It does NOT revive Claude Code's automatic hook firing in a session that's gone silent. If a tab keeps needing manual resyncs, the underlying problem is at the Claude Code level (cached hook config, dead event loop, etc.) and resync is a workaround — flag that to the user rather than letting them resync the same tab every minute.## Where the supporting files live- `~/.claude/hooks/headsup-resync.sh` — the actual implementation- `~/.claude/hooks/iterm2-apply-once.py` — Tier 2 one-shot, invoked by the script- `~/.claude/hooks/iterm2-daemon.py` — Tier 1 daemon, the script writes state for it to pick up- `~/.claude/hooks/headsup-status.conf` — color customization (PROCESS_COLOR etc.); the script honors overridesAll four are under version control at `github.com/wasulajr/headsup`.

Frequently asked questions