tavs

TAVS - Terminal Agent Visual Signals

Visual terminal feedback for AI coding sessions — background colors, tab titles, and faces that show you what's happening at a glance.

Why?

When running multiple AI sessions (12+ terminals side by side), you need to instantly see which ones need attention. TAVS provides visual feedback through background colors, emoji indicators, animated faces, and optional audible bells.

State	Color	Icon	Meaning
Processing	Orange	🟠	Agent is working
Permission	Red	🔴	Needs your approval
Complete	Green	🟢	Response finished
Idle	Purple	🟣	Waiting for input (fades over time)
Compacting	Teal	🔄	Context being compressed
Subagent	Golden	🔀	Spawned a subagent
Tool Error	Orange-Red	❌	Tool execution failed

Works with Claude Code, Gemini CLI, OpenCode, and Codex CLI.

At scale, TAVS turns terminal chaos into a glanceable dashboard. Each tab's background color and title icon tells you its state without switching — reducing the cognitive load of tracking what every session is doing. Here's 20+ concurrent Claude Code sessions during a real multi-project work session:

Single notebook screen. 18+ sessions, working in parallel. Zero tab-switching needed to know what's happening.
(Recorded in a distant past)

---

Install

Plugin (Recommended — Claude Code)

# Add marketplace (one-time)
claude plugin marketplace add cstelmach/terminal-agent-visual-signals

# Install
claude plugin install tavs@terminal-agent-visual-signals

Then enable via /plugin in Claude Code and restart.

Other Agents

# Gemini CLI (full support, 8 events)
./tavs install gemini

# Codex CLI (limited, 1 event)
./tavs install codex

# OpenCode (npm package — see docs/)
cd src/agents/opencode && npm install && npm run build

Manual Install (Claude Code)

# Clone
git clone https://github.com/cstelmach/terminal-agent-visual-signals.git \
    ~/.claude/hooks/terminal-agent-visual-signals

# Make executable
chmod +x ~/.claude/hooks/terminal-agent-visual-signals/src/core/trigger.sh

Copy hooks from hooks/hooks.json into ~/.claude/settings.json, replacing ${CLAUDE_PLUGIN_ROOT} with the full clone path. Restart Claude Code.

---

Configuration — Four Ways

TAVS works in four tiers. Pick the one that fits you.

1. Just Use the Defaults

Do nothing. After installing, TAVS works immediately with sensible defaults:

• Catppuccin Frappe dark theme (muted, professional colors)
• ASCII faces in tab titles: Ǝ[• •]E 🟠 ~/project
• Background color changes per state
• Session icons (unique animal emoji per tab)
• Mode-aware processing (subtle color shift in plan mode)

This is enough for most users. The colors are designed to be noticeable but not distracting — subtle tints that blend with your terminal background.

Check what you're running:

./tavs status

2. AI-Assisted Configuration (Claude Code Skill)

The tavs-setup skill lets your AI agent handle configuration for you — with backup, preview, and verification at every step.

Setup wizard — guided first-time configuration:

"tavs setup" or "set up visual signals"

Config changes — modify individual settings safely:

"change my tavs theme to nord" or "tavs config"

Profile management — save and switch named configurations:

"save my tavs config as a profile" or "tavs profile"

The skill automatically backs up ~/.tavs/user.conf before changes, shows a diff preview, applies via tavs set (for the 28 CLI aliases) or direct file editing (for 50+ advanced raw variables like per-agent colors and faces), and verifies with tavs status.

Profiles are stored in ~/.tavs/profiles/<name>.conf and can be applied additively — switching between "presentation", "coding", and "minimal" setups with a single command.

The skill ships with the TAVS plugin and activates automatically in Claude Code.

3. Change a Setting

One command to tweak anything. No files to edit.