tabtint-iterm2

Tabtint

Tabtint is a small coding-agent plugin for tinting terminal tabs based on local coding-agent state.

The first package, tabtint-iterm2, provides lifecycle hooks for Codex and Claude Code that set the current iTerm2 tab color:

• Running: blue, 5fd7ff
• Permission prompt: red, ff5f87
• Idle or done: green, 5fff87

The hook writes iTerm2 OSC 1337 tab-color sequences directly to the controlling terminal, or to AGENT_ITERM_TAB_TTY when set. It does not print escape codes to stdout, so hook output remains clean.

Install for Codex

Add the marketplace from GitHub:

codex plugin marketplace add stevwonder/tabtint --ref main

Restart Codex, open the plugin browser, and install tabtint-iterm2 from the tabtint marketplace:

/plugins

Codex plugin installation caches and enables the package, but it does not write lifecycle hooks into your active config. Enable actual tab tinting by invoking the plugin's installer skill:

$tabtint-iterm2:install-tabtint-hooks

That skill runs the plugin's bundled installer from its plugin cache and may ask for permission before updating ~/.codex/config.toml and ~/.codex/hooks.json.

For local development before publishing:

codex plugin marketplace add /path/to/tabtint

Install for Claude Code

Add the marketplace from GitHub:

claude plugin marketplace add stevwonder/tabtint
claude plugin install tabtint-iterm2@tabtint

Or use the interactive commands inside Claude Code:

/plugin marketplace add stevwonder/tabtint
/plugin install tabtint-iterm2@tabtint

The plugin also exposes the install-tabtint-hooks skill for explicit hook installation or repair inside Claude Code.

/install-tabtint-hooks

For local development before publishing:

claude plugin marketplace add /path/to/tabtint
claude plugin install tabtint-iterm2@tabtint

Standalone Install

The plugin installers are useful in sandboxes or environments where plugin installation is unavailable.

Install into Codex:

bash plugins/tabtint-iterm2/scripts/install-codex-standalone.sh

Install into Claude Code:

bash plugins/tabtint-iterm2/scripts/install-claude-standalone.sh

Target a non-default config location:

CODEX_HOME=/path/to/codex-home bash plugins/tabtint-iterm2/scripts/install-codex-standalone.sh
CLAUDE_SETTINGS=/path/to/settings.json bash plugins/tabtint-iterm2/scripts/install-claude-standalone.sh

Both installers create .bak backups before changing config.

Compatibility

tabtint-iterm2 is intentionally iTerm2-specific. It uses OSC 1337;SetColors=tab=..., which is documented by iTerm2 and is not a general terminal standard.

Ghostty does not support iTerm2 tab tinting. A future Tabtint plugin could target Ghostty with its supported OSC 9;4 progress indicator instead.

Repository Layout

This repository is both a Codex marketplace and a Claude Code marketplace:

tabtint/
  .agents/plugins/marketplace.json
  .claude-plugin/marketplace.json
  plugins/
    tabtint-iterm2/
      .codex-plugin/plugin.json
      .claude-plugin/plugin.json
      hooks/hooks.json
      skills/install-tabtint-hooks/
        SKILL.md
        agents/openai.yaml
      scripts/tabtint-iterm2
      scripts/install-codex-standalone.sh
      scripts/install-claude-standalone.sh
  tests/test-package.sh

The two agents use separate marketplace and plugin metadata, but they call the same bundled script. Codex does not currently install hook definitions directly from plugin manifests, so the Codex plugin includes an installer skill that writes supported entries into ~/.codex/hooks.json.

Configuration

Disable Tabtint:

export AGENT_ITERM_TAB_STATE=0

Override the terminal target:

export AGENT_ITERM_TAB_TTY=/dev/ttys001

Override colors:

export AGENT_ITERM_TAB_RUNNING=5fd7ff
export AGENT_ITERM_TAB_APPROVAL=ff5f87
export AGENT_ITERM_TAB_IDLE=5fff87
export AGENT_ITERM_TAB_ERROR=ff5f87

Agent-specific variables are also supported: CODEX_ITERM_TAB_* and CLAUDE_ITERM_TAB_*.

Test

Run the package test:

bash tests/test-package.sh

Validate the Claude marketplace and plugin metadata:

claude plugin validate .
claude plugin validate plugins/tabtint-iterm2

Validate JSON and shell syntax: