terminal-guru

Use this agent when the user has ambiguous terminal or shell problems that span multiple domains, needs diagnostic triage to identify root causes, or has cross-domain issues involving terminal display, shell configuration, system logging, process signals, or environment composition. This agent routes to the correct skill (terminal-emulation, zsh-dev, signals-monitoring, or environment-composition) after initial triage. Examples: <example> Context: User reports garbled characters in terminal user: "My terminal is showing weird characters instead of box drawing" assistant: "I'll use the terminal-guru agent to diagnose whether this is a terminfo, Unicode, or font issue." <commentary> Garbled characters could be terminfo (wrong TERM), Unicode (locale), or font issues. Agent triages the symptom to identify the correct domain before routing. </commentary> </example> <example> Context: User wants to generate a zsh function user: "Create a zsh function that manages SSH connections with keychain" assistant: "I'll use the terminal-guru agent to generate the function using established patterns." <commentary> Function generation request that may involve both zsh patterns and terminal/SSH considerations. Agent routes to zsh-dev skill with cross-domain awareness. </commentary> </example> <example> Context: User has SSH connection with display issues and shell problems user: "Colors are wrong and my functions aren't loading when I SSH into my server" assistant: "I'll use the terminal-guru agent to diagnose both the display and shell configuration issues." <commentary> Cross-domain problem: terminal display (colors/TERM) AND shell config (functions/fpath). Agent handles both domains in sequence. </commentary> </example> <example> Context: User reports slow shell startup user: "My zsh takes 5 seconds to start and I'm not sure what's causing it" assistant: "I'll use the terminal-guru agent to profile and identify the bottleneck." <commentary> Performance issue that requires diagnostic triage. Could be plugin loading, compinit, or other factors. Agent runs diagnostics before routing to zsh-dev. </commentary> </example> <example> Context: User wants to set up a project workspace user: "Help me configure sesh.toml to create a dev environment with claude and direnv for my project" assistant: "I'll use the terminal-guru agent to compose an environment using sesh, claude CLI, and direnv." <commentary> Environment composition request involving sesh.toml configuration and multi-tool integration. Agent routes to environment-composition skill. </commentary> </example> <example> Context: User's script isn't cleaning up on exit user: "My background process keeps running after I close the terminal" assistant: "I'll use the terminal-guru agent to diagnose signal handling and cleanup behavior." <commentary> Signal/trap issue — process not receiving or handling SIGHUP/SIGTERM. Agent routes to signals-monitoring skill. </commentary> </example>

This skill should be used when the user asks to "configure sesh.toml", "create a dev environment", "build a session template", "set up sesh config", "add a sesh wildcard", "configure startup command", "create workspace with sesh", "clean up worktrees", "resume my session", "debug environment decay", or needs help composing development environments from sesh, claude CLI, direnv, and git worktrees. Also trigger on mentions of sesh.toml, environment composition, session templates, sesh wildcards, or teardown patterns. Do NOT use for general tmux session management, display issues, or keybindings (use terminal-emulation instead). Do NOT use for worktree lifecycle management (use chronicle instead). Do NOT use for signal handling or system logging (use signals-monitoring instead).

This skill should be used when working with Unix process signals, shell trap handlers, macOS unified logging, file watching, process monitoring, and terminal notifications. Use when users ask to "check system logs", "debug my app", "fix script cleanup on Ctrl+C", "add signal handling to a script", "configure log streaming", "build a file watcher", "send a notification from the terminal", or "open a log stream in tmux".

This skill should be used when diagnosing, fixing, or understanding Unix terminal display issues including terminfo database problems, Unicode/UTF-8 character rendering, locale configuration, TUI application display, SSH terminal setup, and terminal emulator configuration. Also use for tmux session management, session creation with sesh, pane logging, and environment setup with direnv. Use for garbled characters, wrong colors, broken box drawing, emoji rendering, character encoding problems, "create a tmux session", "set up pane logging", "configure sesh", or "session naming convention".

This skill should be used when the user asks to "create a zsh function", "configure fpath", "add a keychain secret", "set up keychainctl", "check shell startup", or needs help with autoload functions, completions, zsh testing, Plugin Standard compliance, storing tokens, retrieving secrets, or macOS keychain management via keychainctl. Do NOT use for terminal display issues or signal handling (use terminal-emulation or signals-monitoring skills instead).