Scripts & Tooling

Scripts

6 scripts in scripts/, split between status bar renderers and utilities.

Status Bar Scripts

These run on a 5-second interval via status.conf. They must NEVER use set -e — a crash breaks the status bar for every window.

Script Purpose Design Notes

status-git.sh

Git branch, ahead/behind count, dirty/clean state, stash count

Caches via single git status --porcelain --branch call. Known limitation: parses English ahead/behind strings — breaks on non-English locales.

status-project.sh

Project context — detects atelier directory structure, shows project name with category icon

3-second cache in /tmp. Parses ~/atelier/_projects/<category>/<name> path structure. Truncates long names to 12-15 chars.

status-system.sh

CPU usage, memory usage, load average — rotates metrics on each call

Linux-only (reads /proc/stat, /proc/meminfo, /proc/loadavg). 3-second cache. No macOS/BSD fallback.

Utility Scripts

Script Purpose Design Notes

check-conflicts.sh

Table-aware keybinding conflict detection. Parses bind statements, tracks {table}:{key} tuples, flags same-table duplicates.

Uses set -euo pipefail. Scans lib/.conf and plugins/.conf. Exit 0 = clean, exit 1 = conflicts found.

help.sh

Keybinding reference displayed via C-a / popup. Box-drawing layout with Unicode borders.

Must stay in sync with actual bindings in lib/*.conf. No error handling needed (static output).

theme-switcher.sh

Interactive theme switching — fzf preview, cycling, direct selection. Modifies tmux.conf with backup/restore.

Uses set -euo pipefail. Validates theme existence, creates backup before sed, auto-reloads if inside tmux.

Claude Code Project Tooling

Project-scoped configurations in .claude/ within the repo. Tracked in git except settings.local.json.

Configurations

Config Purpose

rules/tmux-conf.md

Auto-loads when editing .conf files. Enforces theme variables over hardcoded hex, binding table awareness (prefix vs root vs copy-mode-vi), version guards for 3.2+ features, and documentation sync across help.sh, keybindings.adoc, and README.adoc.

agents/tmux-validator.md

Deep 6-point validation: keybinding conflicts, theme variable consistency across all themes, documentation sync vs actual bindings, script health (shebangs, set -e policy, predecessor paths), sourcing order verification, and session template validation.

skills/tmux-qa/SKILL.md

/tmux-qa — quick pass/fail checks (conflicts, theme vars, doc sync spot-check, predecessor path scan). --full spawns the validator agent for comprehensive analysis.

skills/session/SKILL.md

/session <prefix>-<name> "description" — scaffolds tmuxinator YAML with naming convention enforcement (proj-, cfg-, train-, lab-, sec-, etc.) and standard 3-window template.

Recommended settings.local.json

Not tracked in git (globally gitignored by design — machine-local overrides). Create after cloning:

{
  "permissions": {
    "allow": [
      "Bash(tmux source-file:*)",
      "Bash(tmux list-keys:*)",
      "Bash(tmux show-options:*)",
      "Bash(tmux display-message:*)",
      "Bash(bash scripts/*)",
      "Bash(bash:*)"
    ]
  }
}

Save to .claude/settings.local.json to enable tmux introspection and project script execution without prompts.