Help us improve
Share bugs, ideas, or general feedback.
From iterm
Standard 9-section organizational structure for all iTerm plugin shell scripts
npx claudepluginhub manifoldlogic/claude-code-plugins --plugin itermHow this skill is triggered — by the user, by Claude, or both
Slash command
/iterm:iterm-nine-section-structureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
All shell scripts in the iTerm plugin follow a consistent 9-section organizational structure. This pattern ensures scripts are immediately recognizable, maintainable, and follow established conventions. The structure was established in `iterm-open-tab.sh` and is enforced for all new iTerm scripts.
Enforces modern best practices for shell scripts: portable shebangs, strict mode, quoted variables, error traps, exit codes, and secure coding. Use when writing Bash or POSIX sh scripts.
Provides defensive Bash scripting standards for production automation, CI scripts, and skill glue code. Covers strict mode, quoting, argument parsing, traps, safe tempfiles, and the stream-separation/exit-code contract.
Shell script conventions, defensive patterns, and correctness rules: strict mode, quoting, portability, error handling, and common pitfalls. Invoke whenever task involves any interaction with shell scripts — writing, reviewing, debugging, or understanding .sh, .bash, .zsh files.
Share bugs, ideas, or general feedback.
All shell scripts in the iTerm plugin follow a consistent 9-section organizational structure. This pattern ensures scripts are immediately recognizable, maintainable, and follow established conventions. The structure was established in iterm-open-tab.sh and is enforced for all new iTerm scripts.
This is an architectural standard, not a suggestion. New scripts that deviate from this structure will be rejected during code review.
Apply this structure when:
plugins/iterm/skills/*/scripts/*.sh)Every iTerm script must contain these sections in this order, with comment headers:
#!/usr/bin/env bash
#
# script-name.sh - Brief description
#
# [Header documentation block with DESCRIPTION, USAGE, EXIT CODES, etc.]
#
set -euo pipefail
##############################################################################
# 1. Script Location and Sourcing
##############################################################################
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# ... sourcing utilities ...
##############################################################################
# 2. Trap Handler Setup
##############################################################################
trap _cleanup_temp_script EXIT INT TERM
##############################################################################
# 3. Default Values
##############################################################################
DEFAULT_PROFILE="Devcontainer"
# ... other defaults ...
##############################################################################
# 4. Usage Information
##############################################################################
show_help() {
cat << 'EOF'
# ... help text ...
EOF
}
##############################################################################
# 5. Argument Parsing
##############################################################################
parse_arguments() {
# ... argument parsing logic ...
}
##############################################################################
# 6. AppleScript Escaping
##############################################################################
escape_applescript_string() {
# ... escaping logic ...
}
##############################################################################
# 7. AppleScript Generation
##############################################################################
build_applescript() {
# ... AppleScript generation logic ...
}
##############################################################################
# 8. Main Execution
##############################################################################
main() {
# ... main logic orchestration ...
}
##############################################################################
# Script Entry Point
##############################################################################
main "$@"
Purpose: Establish script location and source dependencies
Contents:
SCRIPT_DIR calculation using BASH_SOURCE[0]iterm-utils.sh with error handlingExample:
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
UTILS_DIR="$(cd "$SCRIPT_DIR/../../tab-management/scripts" && pwd)"
if ! source "$UTILS_DIR/iterm-utils.sh" 2>/dev/null; then
echo "[ERROR] Failed to source iterm-utils.sh from $UTILS_DIR" >&2
exit 3
fi
Purpose: Register cleanup handlers before any operations
Contents:
trap statement calling _cleanup_temp_script from iterm-utils.shExample:
trap _cleanup_temp_script EXIT INT TERM
Purpose: Define constants and default values
Contents:
Example:
DEFAULT_DIRECTION="vertical"
DEFAULT_PROFILE="Devcontainer"
DEFAULT_DIRECTORY="/workspace"
Purpose: Provide help text via show_help() function
Contents:
show_help()Example:
show_help() {
cat << 'EOF'
script-name.sh - Brief description
USAGE:
script-name.sh [OPTIONS]
OPTIONS:
-h, --help Show help
EXIT CODES:
0 - Success
# ... etc
EOF
}
Purpose: Parse and validate command-line arguments
Contents:
parse_arguments()Example:
parse_arguments() {
while [[ $# -gt 0 ]]; do
case "$1" in
-h|--help)
show_help
exit 0
;;
# ... other cases ...
esac
shift
done
}
Purpose: Escape strings for safe AppleScript embedding
Contents:
escape_applescript_string()Note: This function is currently duplicated across scripts. Future cleanup may move it to iterm-utils.sh.
Example:
escape_applescript_string() {
local input="$1"
# Escape backslashes first, then double quotes
local escaped="${input//\\/\\\\}"
escaped="${escaped//\"/\\\"}"
printf '%s' "$escaped"
}
Purpose: Build the AppleScript to be executed
Contents:
build_applescript() or similarcat << 'EOF' for AppleScript templateExample:
build_applescript() {
local direction="$1"
local profile="$2"
cat << 'EOF'
tell application "iTerm2"
activate
# ... AppleScript ...
end tell
EOF
}
Purpose: Orchestrate the script's workflow
Contents:
main()run_applescript()Example:
main() {
parse_arguments "$@"
local applescript
applescript=$(build_applescript ...)
if [[ "${ARG_DRY_RUN:-false}" == "true" ]]; then
echo "$applescript"
exit 0
fi
validate_iterm
run_applescript "$applescript"
iterm_ok "Operation completed successfully"
}
Contents:
main "$@" at end of fileExample:
##############################################################################
# Script Entry Point
##############################################################################
main "$@"
Complete implementation of the 9-section structure:
plugins/iterm/skills/pane-management/scripts/iterm-split-pane.sh
- 316 lines total
- 9 sections clearly marked with comment headers
- Each section contains expected components
- Model implementation for new scripts
Original template that established this pattern:
plugins/iterm/skills/tab-management/scripts/iterm-open-tab.sh
- 377 lines total
- Same 9 sections as iterm-split-pane.sh
- Proven in production with 87 passing tests
- Reference implementation
When reviewing a new iTerm script, verify:
# Check for all section headers
grep "Script Location and Sourcing" script.sh
grep "Trap Handler Setup" script.sh
grep "Default Values" script.sh
grep "Usage Information" script.sh
grep "Argument Parsing" script.sh
grep "AppleScript Escaping" script.sh
grep "AppleScript Generation" script.sh
grep "Main Execution" script.sh
# Verify strict mode
head -n 50 script.sh | grep "set -euo pipefail"
# Verify entry point
tail -n 5 script.sh | grep 'main "$@"'
plugins/iterm/skills/pane-management/scripts/iterm-split-pane.sh (316 lines, full implementation)plugins/iterm/skills/tab-management/scripts/iterm-open-tab.sh (377 lines, original template)plugins/iterm/skills/tab-management/scripts/iterm-close-tab.sh (follows same pattern)archive/tickets/PANE-001_core-split-script/planning/architecture.md (Decision 1: Mirror iterm-open-tab.sh Structure Exactly)