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.
cstelmach