Tavs setup

TAVS Setup & Configuration Assistant

Conversational configuration for Terminal Agent Visual Signals. Handles initial setup, ongoing config changes, and named profile management — all with backup, preview, and verification.

When to Use

• Setup: First-time configuration, re-setup, "tavs wizard", "tavs setup"
• Config: Modify a setting, change theme, adjust colors, "tavs config"
• Profiles: Save/load/apply named config sets, "tavs profile"
• Agent settings: Per-agent color, face, or title format overrides

Prerequisites

Verify the TAVS CLI is available:

./tavs version 2>/dev/null || echo "TAVS CLI not found"

If unavailable, the tavs CLI is part of TAVS v3.0.0+.

Intent Detection

Determine which workflow to use based on the user's request:

Keywords	Workflow
"set up", "configure from scratch", "wizard", "first time", "install"	A: Setup Wizard
"change", "modify", "set", "switch", "update", "enable", "disable"	B: Config Change
"profile", "save config", "load config", "apply profile", "list profiles"	C: Profile Management

When unclear, ask the user:

• Run the setup wizard — Full guided configuration
• Change a specific setting — Quick, targeted modification
• Manage profiles — Save or load a named configuration

---

Workflow A: Setup Wizard

Guided multi-step configuration. Best for first-time users or full reconfiguration.

Phase 1: Environment Detection (Automatic)

Run silently to detect the user's environment:

./tavs status 2>/dev/null
echo "TERM_PROGRAM=${TERM_PROGRAM:-unset}"
echo "GHOSTTY_RESOURCES_DIR=${GHOSTTY_RESOURCES_DIR:-unset}"
echo "ITERM_SESSION_ID=${ITERM_SESSION_ID:-unset}"
echo "KITTY_PID=${KITTY_PID:-unset}"
echo "COLORTERM=${COLORTERM:-unset}"
echo "TERM=${TERM:-unset}"
echo "TAVS_AGENT=${TAVS_AGENT:-claude}"
defaults read -g AppleInterfaceStyle 2>/dev/null || echo "light"

Present: "I detected [Terminal] in [dark/light] mode running [Agent]." Mention terminal-specific notes from references/terminal-guide.md.

Phase 2: Essential Questions (2-3 via AskUserQuestion)

Q1: Theme Preference

• Nord — Arctic blue, calm (Recommended for dark)
• Catppuccin Mocha — Warm pastel dark
• Dracula — Vibrant, high contrast
• Tokyo Night — Modern city-lights
• Other (catppuccin-frappe/latte/macchiato, solarized-dark/light)
• No theme — Default static colors

Plan: tavs set theme <name>

Q2: Face Mode (show visual examples in descriptions)

• Standard (Recommended) — Ǝ[• •]E 🟠 ~/project
• Compact — Ǝ[🟧 🟠]E ~/project (emoji eyes, denser)
• Off — No faces, just colors and icons

Plan: tavs set faces true/false + tavs set face-mode standard/compact

Q3: Title Mode (adapt to detected terminal)

• Skip Processing (Recommended) — TAVS handles non-processing titles
• Prefix Only — TAVS adds prefix, preserves tab names
• Full — TAVS owns all titles with animated spinners
• Off — No title changes, only background colors

Plan: tavs set title-mode <mode>

Phase 3: "Want More?" Gate

"Those are the essentials! Want to dive into advanced options?"

• Yes, show me more — Continue to Phase 4
• No, apply these settings — Skip to Phase 5

Phase 4: Advanced Options (Conditional)

Ask only questions relevant to earlier choices. Use AskUserQuestion for each group.

If title-mode = full:

• Spinner style: braille, circle, block, eye-animate, random (Recommended)
• Eye sync mode: sync, opposite, mirror, random (Recommended)

If face-mode = compact:

• Compact theme: semantic (Recommended), circles, squares, mixed
• See references/agent-visual-identity.md for examples

Session icons (always): Keep or disable? Plan: tavs set session-icons <bool>

Background images (only iTerm2/Kitty): Plan: tavs set backgrounds true Note iTerm2 prerequisite: Preferences > Profiles > Window > Background Image.

Palette theming: Explain TrueColor limitation. Options: false, auto, true. Plan: tavs set palette <value>

Mode-aware colors: Currently enabled by default. Keep or disable? Plan: tavs set mode-aware <bool>

Bell notifications: Options: permission only (default), permission + complete, off. Plan: tavs set bell-permission/bell-complete <bool>

Phase 5: Apply Settings

1. Summary — Show all planned tavs set commands
2. Confirm via AskUserQuestion: Apply all / Edit first / Cancel
3. Execute each command sequentially
4. Verify with ./tavs status --colors
5. Demo (optional): ./tavs test --quick
6. Post-setup notes (terminal-specific):
   • Ghostty: shell-integration-features = no-title
   • iTerm2: Enable background images in preferences
   • Full title: Add CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 to settings
   • Palette: TrueColor limitation and COLORTERM= workaround

---

Workflow B: Configuration Changes

Quick, targeted setting modifications. For detailed procedure, read references/config-workflow.md.

Steps

1. Understand what the user wants to change
2. Back up current config: ~/.tavs/backups/user.conf.TIMESTAMP
3. Resolve setting type:
   • CLI alias (28 known)? -> ./tavs set <alias> <value> — see references/config-options.md
   • Raw variable? -> Edit ~/.tavs/user.conf — see references/raw-variables.md
   • Unknown? -> Suggest closest match
4. Preview planned changes: Setting: current -> new
5. Confirm via AskUserQuestion: Apply / Edit / Cancel
6. Apply — CLI for aliases, Edit for raw variables
7. Verify with ./tavs status and optionally ./tavs test --quick

Rollback

If something went wrong, restore from backup:

ls -1t ~/.tavs/backups/   # List backups
cp ~/.tavs/backups/user.conf.TIMESTAMP ~/.tavs/user.conf

Setting Types

CLI aliases (validated, use ./tavs set): theme, mode, faces, face-mode, title-mode, spinner, identity-mode, and 21 more. Full list in config-options.md.

Raw variables (direct edit): per-agent colors (CLAUDE_DARK_PROCESSING), per-agent faces (CLAUDE_FACES_PROCESSING), per-state title formats (TAVS_TITLE_FORMAT_PERMISSION), feature toggles, timers, and more. Full catalog in raw-variables.md.

---

Workflow C: Profile Management

Save, list, apply, and delete named configuration sets. For detailed procedure, read references/profiles.md.

Operations

Save: Extract settings from current user.conf into ~/.tavs/profiles/<name>.conf. Ask which settings to include (specific or all active).

List: Show all profiles in ~/.tavs/profiles/ with setting count and summary.

Apply: Back up first, preview each setting's current vs. profile value, confirm, apply (CLI for aliases, Edit for raw), verify with ./tavs status.

Delete: Confirm, then remove the profile file.

Profiles are additive — they only overwrite settings they contain, not a full config replacement.

---

Reference Files

File	Purpose
references/config-options.md	All 28 CLI setting aliases with valid values
references/config-workflow.md	Config change procedure (backup, resolve, apply, verify)
references/raw-variables.md	All 50+ raw variables beyond CLI aliases
references/profiles.md	Profile save/list/apply/delete procedure
references/terminal-guide.md	Terminal detection and recommendations
references/agent-visual-identity.md	Per-agent faces, colors, spinners
references/preset-themes.md	All 9 theme presets with descriptions
troubleshooting/lessons-learned.md	Known issues and fixes (setup + config)

Important Notes

• All settings stored in ~/.tavs/user.conf (takes effect on next hook trigger)
• Use tavs set for validated changes; Edit tool for raw variables
• The theme alias is compound — sets both THEME_PRESET and THEME_MODE
• Run ./tavs status to see current configuration
• Run ./tavs test to demo all visual states
• Backups: ~/.tavs/backups/user.conf.TIMESTAMP
• Profiles: ~/.tavs/profiles/<name>.conf
• Plugin cache sync: ./tavs sync (only needed after source code changes, not config)