Reorganize: Move all skills to skills/ folder

- Created skills/ directory - Moved 272 skills to skills/ subfolder - Kept agents/ at root level - Kept installation scripts and docs at root level Repository structure: - skills/ - All 272 skills from skills.sh - agents/ - Agent definitions - *.sh, *.ps1 - Installation scripts - README.md, etc. - Documentation Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-23 18:05:17 +00:00
parent 2b4e974878
commit b723e2bd7d
4083 changed files with 1056 additions and 1098063 deletions
--- a/skills/plugins/claude-hud/commands/configure.md
+++ b/skills/plugins/claude-hud/commands/configure.md
@@ -0,0 +1,256 @@
+---
+description: Configure HUD display options (layout, presets, display elements)
+allowed-tools: Read, Write, AskUserQuestion
+---
+
+# Configure Claude HUD
+
+**FIRST**: Use the Read tool to load `~/.claude/plugins/claude-hud/config.json` if it exists.
+
+Store current values and note whether config exists (determines which flow to use).
+
+## Always On (Core Features)
+
+These are always enabled and NOT configurable:
+- Model name `[Opus]`
+- Context bar `████░░░░░░ 45%`
+
+---
+
+## Two Flows Based on Config State
+
+### Flow A: New User (no config)
+Questions: **Layout → Preset → Turn Off → Turn On**
+
+### Flow B: Update Config (config exists)
+Questions: **Turn Off → Turn On → Git Style → Layout/Reset**
+
+---
+
+## Flow A: New User (4 Questions)
+
+### Q1: Layout
+- header: "Layout"
+- question: "Choose your HUD layout:"
+- multiSelect: false
+- options:
+  - "Expanded (Recommended)" - Split into semantic lines (identity, project, environment, usage)
+  - "Compact" - Everything on one line
+  - "Compact + Separators" - One line with separator before activity
+
+### Q2: Preset
+- header: "Preset"
+- question: "Choose a starting configuration:"
+- multiSelect: false
+- options:
+  - "Full" - Everything enabled (Recommended)
+  - "Essential" - Activity + git, minimal info
+  - "Minimal" - Core only (model, context bar)
+
+### Q3: Turn Off (based on chosen preset)
+- header: "Turn Off"
+- question: "Disable any of these? (enabled by your preset)"
+- multiSelect: true
+- options: **ONLY items that are ON in the chosen preset** (max 4)
+  - "Tools activity" - ◐ Edit: file.ts | ✓ Read ×3
+  - "Agents status" - ◐ explore [haiku]: Finding code
+  - "Todo progress" - ▸ Fix bug (2/5 tasks)
+  - "Git status" - git:(main*) branch indicator
+  - "Config counts" - 2 CLAUDE.md | 4 rules
+  - "Token breakdown" - (in: 45k, cache: 12k)
+  - "Usage limits" - 5h: 25% | 7d: 10%
+  - "Session duration" - ⏱️ 5m
+
+### Q4: Turn On (based on chosen preset)
+- header: "Turn On"
+- question: "Enable any of these? (disabled by your preset)"
+- multiSelect: true
+- options: **ONLY items that are OFF in the chosen preset** (max 4)
+  - (same list as above, filtered to OFF items)
+
+**Note:** If preset has all items ON (Full), Q4 shows "Nothing to enable - Full preset has everything!"
+If preset has all items OFF (Minimal), Q3 shows "Nothing to disable - Minimal preset is already minimal!"
+
+---
+
+## Flow B: Update Config (4 Questions)
+
+### Q1: Turn Off
+- header: "Turn Off"
+- question: "What do you want to DISABLE? (currently enabled)"
+- multiSelect: true
+- options: **ONLY items currently ON** (max 4, prioritize Activity first)
+  - "Tools activity" - ◐ Edit: file.ts | ✓ Read ×3
+  - "Agents status" - ◐ explore [haiku]: Finding code
+  - "Todo progress" - ▸ Fix bug (2/5 tasks)
+  - "Git status" - git:(main*) branch indicator
+
+If more than 4 items ON, show Activity items (Tools, Agents, Todos, Git) first.
+Info items (Counts, Tokens, Usage, Duration) can be turned off via "Reset to Minimal" in Q4.
+
+### Q2: Turn On
+- header: "Turn On"
+- question: "What do you want to ENABLE? (currently disabled)"
+- multiSelect: true
+- options: **ONLY items currently OFF** (max 4)
+  - "Config counts" - 2 CLAUDE.md | 4 rules
+  - "Token breakdown" - (in: 45k, cache: 12k)
+  - "Usage limits" - 5h: 25% | 7d: 10%
+  - "Session duration" - ⏱️ 5m
+
+### Q3: Git Style (only if Git is currently enabled)
+- header: "Git Style"
+- question: "How much git info to show?"
+- multiSelect: false
+- options:
+  - "Branch only" - git:(main)
+  - "Branch + dirty" - git:(main*) shows uncommitted changes
+  - "Full details" - git:(main* ↑2 ↓1) includes ahead/behind
+  - "File stats" - git:(main* !2 +1 ?3) Starship-compatible format
+
+**Skip Q3 if Git is OFF** - show only 3 questions total, or replace with placeholder.
+
+### Q4: Layout/Reset
+- header: "Layout/Reset"
+- question: "Change layout or reset to preset?"
+- multiSelect: false
+- options:
+  - "Keep current" - No layout/preset changes (current: Expanded/Compact/Compact + Separators)
+  - "Switch to Expanded" - Split into semantic lines (if not current)
+  - "Switch to Compact" - Everything on one line (if not current)
+  - "Reset to Full" - Enable everything
+  - "Reset to Essential" - Activity + git only
+
+---
+
+## Preset Definitions
+
+**Full** (everything ON):
+- Activity: Tools ON, Agents ON, Todos ON
+- Info: Counts ON, Tokens ON, Usage ON, Duration ON
+- Git: ON (with dirty indicator, no ahead/behind)
+
+**Essential** (activity + git):
+- Activity: Tools ON, Agents ON, Todos ON
+- Info: Counts OFF, Tokens OFF, Usage OFF, Duration ON
+- Git: ON (with dirty indicator)
+
+**Minimal** (core only):
+- Activity: Tools OFF, Agents OFF, Todos OFF
+- Info: Counts OFF, Tokens OFF, Usage OFF, Duration OFF
+- Git: OFF
+
+---
+
+## Layout Mapping
+
+| Option | Config |
+|--------|--------|
+| Expanded | `lineLayout: "expanded", showSeparators: false` |
+| Compact | `lineLayout: "compact", showSeparators: false` |
+| Compact + Separators | `lineLayout: "compact", showSeparators: true` |
+
+---
+
+## Git Style Mapping
+
+| Option | Config |
+|--------|--------|
+| Branch only | `gitStatus: { enabled: true, showDirty: false, showAheadBehind: false, showFileStats: false }` |
+| Branch + dirty | `gitStatus: { enabled: true, showDirty: true, showAheadBehind: false, showFileStats: false }` |
+| Full details | `gitStatus: { enabled: true, showDirty: true, showAheadBehind: true, showFileStats: false }` |
+| File stats | `gitStatus: { enabled: true, showDirty: true, showAheadBehind: false, showFileStats: true }` |
+
+---
+
+## Element Mapping
+
+| Element | Config Key |
+|---------|------------|
+| Tools activity | `display.showTools` |
+| Agents status | `display.showAgents` |
+| Todo progress | `display.showTodos` |
+| Git status | `gitStatus.enabled` |
+| Config counts | `display.showConfigCounts` |
+| Token breakdown | `display.showTokenBreakdown` |
+| Usage limits | `display.showUsage` |
+| Session duration | `display.showDuration` |
+
+**Always true (not configurable):**
+- `display.showModel: true`
+- `display.showContextBar: true`
+
+---
+
+## Processing Logic
+
+### For New Users (Flow A):
+1. Apply chosen preset as base
+2. Apply Turn Off selections (set those items to OFF)
+3. Apply Turn On selections (set those items to ON)
+4. Apply chosen layout
+
+### For Returning Users (Flow B):
+1. Start from current config
+2. Apply Turn Off selections (set to OFF)
+3. Apply Turn On selections (set to ON)
+4. Apply Git Style selection (if shown)
+5. If "Reset to [preset]" selected, override with preset values
+6. If layout change selected, apply it
+
+---
+
+## Before Writing - Validate & Preview
+
+**GUARDS - Do NOT write config if:**
+- User cancels (Esc) → say "Configuration cancelled."
+- No changes from current config → say "No changes needed - config unchanged."
+
+**Show preview before saving:**
+
+1. **Summary of changes:**
+```
+Layout: Compact → Expanded
+Git style: Branch + dirty
+Changes:
+  - Usage limits: OFF → ON
+  - Config counts: ON → OFF
+```
+
+2. **Preview of HUD (Expanded layout):**
+```
+[Opus | Pro] ████░░░░░ 45% | ⏱️ 5m
+my-project git:(main*)
+2 CLAUDE.md | 4 rules | 3 MCPs
+5h: 25% (1h 30m)
+◐ Edit: file.ts | ✓ Read ×3
+▸ Fix auth bug (2/5)
+```
+
+**Preview of HUD (Compact layout):**
+```
+[Opus | Pro] ████░░░░░ 45% | my-project git:(main*) | 2 CLAUDE.md | 5h: 25% | ⏱️ 5m
+◐ Edit: file.ts | ✓ Read ×3
+▸ Fix auth bug (2/5)
+```
+
+3. **Confirm**: "Save these changes?"
+
+---
+
+## Write Configuration
+
+Write to `~/.claude/plugins/claude-hud/config.json`.
+
+Merge with existing config, preserving:
+- `pathLevels` (not in configure flow)
+- `display.usageThreshold` (advanced config)
+- `display.environmentThreshold` (advanced config)
+
+**Migration note**: Old configs with `layout: "default"` or `layout: "separators"` are automatically migrated to the new `lineLayout` + `showSeparators` format on load.
+
+---
+
+## After Writing
+
+Say: "Configuration saved! The HUD will reflect your changes immediately."
--- a/skills/plugins/claude-hud/commands/setup.md
+++ b/skills/plugins/claude-hud/commands/setup.md
@@ -0,0 +1,226 @@
+---
+description: Configure claude-hud as your statusline
+allowed-tools: Bash, Read, Edit, AskUserQuestion
+---
+
+**Note**: Placeholders like `{RUNTIME_PATH}`, `{SOURCE}`, and `{GENERATED_COMMAND}` should be substituted with actual detected values.
+
+## Step 0: Detect Ghost Installation (Run First)
+
+Check for inconsistent plugin state that can occur after failed installations:
+
+**macOS/Linux**:
+```bash
+# Check 1: Cache exists?
+CACHE_EXISTS=$(ls -d ~/.claude/plugins/cache/claude-hud 2>/dev/null && echo "YES" || echo "NO")
+
+# Check 2: Registry entry exists?
+REGISTRY_EXISTS=$(grep -q "claude-hud" ~/.claude/plugins/installed_plugins.json 2>/dev/null && echo "YES" || echo "NO")
+
+# Check 3: Temp files left behind?
+TEMP_FILES=$(ls -d ~/.claude/plugins/cache/temp_local_* 2>/dev/null | head -1)
+
+echo "Cache: $CACHE_EXISTS | Registry: $REGISTRY_EXISTS | Temp: ${TEMP_FILES:-none}"
+```
+
+**Windows (PowerShell)**:
+```powershell
+$cache = Test-Path "$env:USERPROFILE\.claude\plugins\cache\claude-hud"
+$registry = (Get-Content "$env:USERPROFILE\.claude\plugins\installed_plugins.json" -ErrorAction SilentlyContinue) -match "claude-hud"
+$temp = Get-ChildItem "$env:USERPROFILE\.claude\plugins\cache\temp_local_*" -ErrorAction SilentlyContinue
+Write-Host "Cache: $cache | Registry: $registry | Temp: $($temp.Count) files"
+```
+
+### Interpreting Results
+
+| Cache | Registry | Meaning | Action |
+|-------|----------|---------|--------|
+| YES | YES | Normal install (may still be broken) | Continue to Step 1 |
+| YES | NO | Ghost install - cache orphaned | Clean up cache |
+| NO | YES | Ghost install - registry stale | Clean up registry |
+| NO | NO | Not installed | Continue to Step 1 |
+
+If **temp files exist**, a previous install was interrupted. Clean them up.
+
+### Cleanup Commands
+
+If ghost installation detected, ask user if they want to reset. If yes:
+
+**macOS/Linux**:
+```bash
+# Remove orphaned cache
+rm -rf ~/.claude/plugins/cache/claude-hud
+
+# Remove temp files from failed installs
+rm -rf ~/.claude/plugins/cache/temp_local_*
+
+# Reset registry (removes ALL plugins - warn user first!)
+# Only run if user confirms they have no other plugins they want to keep:
+echo '{"version": 2, "plugins": {}}' > ~/.claude/plugins/installed_plugins.json
+```
+
+**Windows (PowerShell)**:
+```powershell
+# Remove orphaned cache
+Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\cache\claude-hud" -ErrorAction SilentlyContinue
+
+# Remove temp files
+Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\cache\temp_local_*" -ErrorAction SilentlyContinue
+
+# Reset registry (removes ALL plugins - warn user first!)
+'{"version": 2, "plugins": {}}' | Set-Content "$env:USERPROFILE\.claude\plugins\installed_plugins.json"
+```
+
+After cleanup, tell user to **restart Claude Code** and run `/plugin install claude-hud` again.
+
+### Linux: Cross-Device Filesystem Check
+
+**On Linux only**, if install keeps failing, check for EXDEV issue:
+```bash
+[ "$(df --output=source ~ /tmp 2>/dev/null | tail -2 | uniq | wc -l)" = "2" ] && echo "CROSS_DEVICE"
+```
+
+If this outputs `CROSS_DEVICE`, `/tmp` and home are on different filesystems. This causes `EXDEV: cross-device link not permitted` during installation. Workaround:
+```bash
+mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude /plugin install claude-hud
+```
+
+This is a [Claude Code platform limitation](https://github.com/anthropics/claude-code/issues/14799).
+
+---
+
+## Step 1: Detect Platform & Runtime
+
+**macOS/Linux** (if `uname -s` returns "Darwin", "Linux", or a MINGW*/MSYS*/CYGWIN* variant):
+
+> **Git Bash/MSYS2/Cygwin users on Windows**: Follow these macOS/Linux instructions, not the Windows section below. Your environment provides bash and Unix-like tools.
+
+1. Get plugin path:
+   ```bash
+   ls -td ~/.claude/plugins/cache/claude-hud/claude-hud/*/ 2>/dev/null | head -1
+   ```
+   If empty, the plugin is not installed. Go back to Step 0 to check for ghost installation or EXDEV issues. If Step 0 was clean, tell user to install via `/plugin install claude-hud` first.
+
+2. Get runtime absolute path (prefer bun for performance, fallback to node):
+   ```bash
+   command -v bun 2>/dev/null || command -v node 2>/dev/null
+   ```
+
+   If empty, stop and tell user to install Node.js or Bun.
+
+3. Verify the runtime exists:
+   ```bash
+   ls -la {RUNTIME_PATH}
+   ```
+   If it doesn't exist, re-detect or ask user to verify their installation.
+
+4. Determine source file based on runtime:
+   ```bash
+   basename {RUNTIME_PATH}
+   ```
+   If result is "bun", use `src/index.ts` (bun has native TypeScript support). Otherwise use `dist/index.js` (pre-compiled).
+
+5. Generate command (quotes around runtime path handle spaces):
+   ```
+   bash -c '"{RUNTIME_PATH}" "$(ls -td ~/.claude/plugins/cache/claude-hud/claude-hud/*/ 2>/dev/null | head -1){SOURCE}"'
+   ```
+
+**Windows** (native PowerShell/cmd.exe - if `uname` command is not available):
+
+1. Get plugin path:
+   ```powershell
+   (Get-ChildItem "$env:USERPROFILE\.claude\plugins\cache\claude-hud\claude-hud" | Sort-Object LastWriteTime -Descending | Select-Object -First 1).FullName
+   ```
+   If empty or errors, the plugin is not installed. Tell user to install via marketplace first.
+
+2. Get runtime absolute path (prefer bun, fallback to node):
+   ```powershell
+   if (Get-Command bun -ErrorAction SilentlyContinue) { (Get-Command bun).Source } elseif (Get-Command node -ErrorAction SilentlyContinue) { (Get-Command node).Source } else { Write-Error "Neither bun nor node found" }
+   ```
+
+   If neither found, stop and tell user to install Node.js or Bun.
+
+3. Check if runtime is bun (by filename). If bun, use `src\index.ts`. Otherwise use `dist\index.js`.
+
+4. Generate command (note: quotes around runtime path handle spaces in paths):
+   ```
+   powershell -Command "& {$p=(Get-ChildItem $env:USERPROFILE\.claude\plugins\cache\claude-hud\claude-hud | Sort-Object LastWriteTime -Descending | Select-Object -First 1).FullName; & '{RUNTIME_PATH}' (Join-Path $p '{SOURCE}')}"
+   ```
+
+**WSL (Windows Subsystem for Linux)**: If running in WSL, use the macOS/Linux instructions. Ensure the plugin is installed in the Linux environment (`~/.claude/plugins/...`), not the Windows side.
+
+## Step 2: Test Command
+
+Run the generated command. It should produce output (the HUD lines) within a few seconds.
+
+- If it errors, do not proceed to Step 3.
+- If it hangs for more than a few seconds, cancel and debug.
+- This test catches issues like broken runtime binaries, missing plugins, or path problems.
+
+## Step 3: Apply Configuration
+
+Read the settings file and merge in the statusLine config, preserving all existing settings:
+- **macOS/Linux/Git Bash**: `~/.claude/settings.json`
+- **Windows (native PowerShell)**: `$env:USERPROFILE\.claude\settings.json`
+
+If the file doesn't exist, create it. If it contains invalid JSON, report the error and do not overwrite.
+If a write fails with `File has been unexpectedly modified`, re-read the file and retry the merge once.
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "{GENERATED_COMMAND}"
+  }
+}
+```
+
+**Note**: The generated command dynamically finds and runs the latest installed plugin version. Updates are automatic - no need to re-run setup after plugin updates. If the HUD suddenly stops working, re-run `/claude-hud:setup` to verify the plugin is still installed.
+
+## Step 4: Verify With User
+
+Use AskUserQuestion:
+- Question: "The HUD should now appear below your input field. Is it working?"
+- Options: "Yes, I see it" / "No, something's wrong"
+
+**If yes**: Ask the user if they'd like to ⭐ star the claude-hud repository on GitHub to support the project. If they agree and `gh` CLI is available, run: `gh api -X PUT /user/starred/jarrodwatts/claude-hud`. Only run the star command if they explicitly say yes.
+
+**If no**: Debug systematically:
+
+1. **Verify config was applied**:
+   - Read settings file (`~/.claude/settings.json` or `$env:USERPROFILE\.claude\settings.json` on Windows)
+   - Check statusLine.command exists and looks correct
+   - If command contains a hardcoded version path (not using dynamic `ls -td` lookup), it may be a stale config from a previous setup
+
+2. **Test the command manually** and capture error output:
+   ```bash
+   {GENERATED_COMMAND} 2>&1
+   ```
+
+3. **Common issues to check**:
+
+   **"command not found" or empty output**:
+   - Runtime path might be wrong: `ls -la {RUNTIME_PATH}`
+   - On macOS with mise/nvm/asdf: the absolute path may have changed after a runtime update
+   - Symlinks may be stale: `command -v node` often returns a symlink that can break after version updates
+   - Solution: re-detect with `command -v bun` or `command -v node`, and verify with `realpath {RUNTIME_PATH}` (or `readlink -f {RUNTIME_PATH}`) to get the true absolute path
+
+   **"No such file or directory" for plugin**:
+   - Plugin might not be installed: `ls ~/.claude/plugins/cache/claude-hud/`
+   - Solution: reinstall plugin via marketplace
+
+   **Windows: "bash not recognized"**:
+   - Wrong command type for Windows
+   - Solution: use the PowerShell command variant
+
+   **Windows: PowerShell execution policy error**:
+   - Run: `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`
+
+   **Permission denied**:
+   - Runtime not executable: `chmod +x {RUNTIME_PATH}`
+
+   **WSL confusion**:
+   - If using WSL, ensure plugin is installed in Linux environment, not Windows
+   - Check: `ls ~/.claude/plugins/cache/claude-hud/`
+
+4. **If still stuck**: Show the user the exact command that was generated and the error, so they can report it or debug further