aiskillstore/terminal-title

<!-- ABOUTME: Terminal title skill that automatically updates terminal window title --> <!-- ABOUTME: Uses emoji from environment + Claude's project detection + current topic -->

Terminal Title Management

Overview

This skill updates the terminal window title to show current context:

• Work/fun emoji (from $TERMINAL_TITLE_EMOJI environment variable)
• Project name (intelligently detected by Claude)
• Current topic (what you're working on)

Format: 💼 ProjectName - Topic

CRITICAL: When to Invoke

MANDATORY invocations:

1. Session start: Automatically triggered by SessionStart hook. Claude must respond by setting title to "Claude Code" as default topic.
2. Topic changes: Claude MUST detect and invoke when user shifts to new topic.

Topic change patterns (Claude must detect these):

• ✅ "let's talk about X" / "can you tell me about Y" → invoke immediately
• ✅ User switches domains: debugging → documentation, frontend → backend, feature → tests
• ✅ User starts working on different module/component after sustained discussion
• ✅ User asks about completely unrelated topic after 3+ exchanges on current topic
• ❌ Follow-up questions on same topic ("add a comment to that function") → do NOT invoke
• ❌ Small refinements to current work ("make it blue") → do NOT invoke
• ❌ Clarifications about current task → do NOT invoke

Claude's responsibility: Actively monitor conversation flow and invoke this skill whenever topic materially shifts. Do not wait for explicit permission.

Example titles:

• 💼 Skills Repository - Terminal Title
• 🎉 dotfiles - zsh config
• 💼 OneOnOne - Firebase Config

Setup Requirements

Required Permission:

This skill runs scripts to update the terminal title. To prevent Claude from prompting for permission every time, add this to your ~/.claude/settings.json:

For Unix/Linux/macOS:

{
  "permissions": {
    "allow": [
      "Bash(bash *skills/scripts/set_title.sh:*)"
    ]
  }
}

For Windows:

{
  "permissions": {
    "allow": [
      "Bash(pwsh *skills/scripts/set_title.ps1:*)"
    ]
  }
}

Why this permission is needed: The skill executes a script that sends terminal escape sequences silently in the background to update your window title without interrupting your workflow.

Cross-platform support: The plugin includes both bash scripts (.sh) for Unix-like systems and PowerShell scripts (.ps1) for Windows. The SessionStart hook automatically detects your OS and uses the appropriate script.

Project Detection Strategy

Primary method: Claude's intelligence

Claude analyzes the current context to determine the project name:

• Current working directory and recent conversation
• Files read during the session
• Git repository information
• Package metadata (package.json, README.md, etc.)
• Overall understanding of what the project represents

Key principle: Use intelligent understanding, not just mechanical file parsing.

Detection examples:

• /Users/dylanr/work/2389/skills → "Skills Repository" (not just "skills")
• /Users/dylanr/work/2389/oneonone/hosting → "OneOnOne"
• /Users/dylanr/dotfiles → "dotfiles"
• /Users/dylanr/projects/my-app → "My App" (humanized from directory)

Supporting evidence Claude checks:

1. Git remote URL or repository directory name
2. package.json name field (Node.js projects)
3. First heading in README.md
4. Directory basename (last resort)

Fallback: If Claude cannot determine context, use current directory name.

Always include project name - Claude can always determine something meaningful.

Title Formatting

Standard format:

$emoji ProjectName - Topic

Component details:

1. Emoji (from environment):

• Read from $TERMINAL_TITLE_EMOJI environment variable
• Set by zsh theme based on directory context
• Common values: 💼 (work), 🎉 (fun/personal)
• Fallback: Use 🎉 if variable not set

2. Project Name (from Claude's detection):

• Human-friendly name, not slug format
• Proper capitalization (e.g., "OneOnOne" not "oneonone")
• Always present (use directory name as minimum)

3. Topic (from invocation context):

• Short description of current work (2-4 words)
• Provided when skill is invoked
• Examples: "Terminal Title", "Firebase Config", "CSS Refactor"

Script usage:

bash scripts/set_title.sh "ProjectName" "Topic"

Note: The script automatically reads emoji from environment and handles terminal escape sequences.

Edge cases:

• No $TERMINAL_TITLE_EMOJI: Use 🎉 as default
• Very long project/topic: Let terminal handle truncation naturally
• Empty topic: Use "Claude Code" as default

Workflow

When Claude detects a topic change (or session start), immediately invoke this workflow:

Follow these steps to update the terminal title:

Step 1: Determine project name

Use Claude's understanding of the current codebase and context to determine the project name. Check:

• What you know about this project from conversation and files
• Git repository name/remote URL
• package.json name field (if Node.js project)
• README.md first heading
• Directory basename (minimum fallback)

Generate a human-friendly name (e.g., "Skills Repository" not "skills").

Step 2: Get topic from context

The topic should come from:

• Invocation parameter (if provided explicitly)
• Current conversation context (what user is working on)
• Default to "Claude Code" for session start

Step 3: Detect operating system

Before executing the script, detect the operating system:

# Check if running on Windows (check for common Windows indicators)
if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OSTYPE" == "cygwin" ]]; then
    OS="windows"
else
    OS="unix"
fi

Step 4: Execute title update script (cross-platform)

Find the skill base directory (available in the skill loading message) and execute the appropriate script based on OS:

For Unix/Linux/macOS:

bash <skill-base-dir>/scripts/set_title.sh "Project Name" "Topic"

For Windows:

pwsh -NoProfile -ExecutionPolicy Bypass -File <skill-base-dir>/scripts/set_title.ps1 "Project Name" "Topic"

The scripts handle:

• Reading emoji from $TERMINAL_TITLE_EMOJI (Unix) or $env:TERMINAL_TITLE_EMOJI (Windows)
• Sanitizing inputs
• Formatting and sending terminal escape sequences

Execute this command silently using the Bash tool (pre-approved via permissions).

Step 5: Done

Title updated silently. Continue responding to user without mentioning the title update unless they ask about it.

Examples

Example 1: Session Start in Skills Repository

Context: User starts Claude Code in /Users/dylanr/work/2389/skills

Environment: TERMINAL_TITLE_EMOJI=💼

Execution:

1. Project: "Skills Repository" (Claude's knowledge)
2. Topic: "Claude Code" (session start default)
3. Command: bash /Users/dylanr/work/2389/claude-plugins/terminal-title/skills/scripts/set_title.sh "Skills Repository" "Claude Code"

Result: Terminal title shows 💼 Skills Repository - Claude Code (script reads emoji from environment)

---

Example 2: Topic Change Detection

Context: Conversation shifts from "terminal title implementation" to "rare VWs"

Claude's detection: User asked "can you tell me about rare vws?" - this is a clear topic shift

Environment: TERMINAL_TITLE_EMOJI=🎉

Claude's action:

1. Detect topic change (from terminal implementation to VWs)
2. Invoke terminal-title skill workflow
3. Project: "Home" (current directory basename)
4. Topic: "Rare VWs" (from new conversation direction)
5. Command: bash <skill-base-dir>/scripts/set_title.sh "Home" "Rare VWs"
6. Continue answering user's question about rare VWs

Result: Terminal title silently updates to 🎉 Home - Rare VWs (script reads emoji from environment)

---

Example 3: Personal Project Without Environment Variable

Context: User working in ~/projects/dotfiles directory

Environment: TERMINAL_TITLE_EMOJI not set

Execution:

1. Project: "dotfiles" (from directory)
2. Topic: "zsh config" (from conversation)
3. Command: bash <skill-base-dir>/scripts/set_title.sh "dotfiles" "zsh config"

Result: Terminal title shows 🎉 dotfiles - zsh config (script uses 🎉 as fallback when TERMINAL_TITLE_EMOJI not set)

---

Example 4: Different Project Context

Context: User working in /Users/dylanr/work/2389/oneonone/hosting

Environment: TERMINAL_TITLE_EMOJI=💼

Execution:

1. Project: "OneOnOne" (Claude knows this project name)
2. Topic: "Firebase Config" (from conversation)
3. Command: bash <skill-base-dir>/scripts/set_title.sh "OneOnOne" "Firebase Config"

Result: Terminal title shows 💼 OneOnOne - Firebase Config (script reads emoji from environment)

---

Example 5: Windows User Session Start

Context: Windows user starts Claude Code in C:\Users\Nat\projects\my-app

Environment: $env:TERMINAL_TITLE_EMOJI=💻 (Windows environment variable)

OS Detection: Claude detects Windows via $OSTYPE check

Execution:

1. Project: "My App" (from directory name, humanized)
2. Topic: "Claude Code" (session start default)
3. Command: pwsh -NoProfile -ExecutionPolicy Bypass -File <skill-base-dir>/scripts/set_title.ps1 "My App" "Claude Code"

Result: Terminal title shows 💻 My App - Claude Code (PowerShell script reads emoji from $env:TERMINAL_TITLE_EMOJI)

Note: The SessionStart hook automatically detected Windows and invoked the PowerShell version of the script instead of the bash version.