hail-hydra-cc 1.2.0 → 1.2.1

package/README.md

@@ -44,7 +44,7 @@ npx hail-hydra-cc --help         # Show help
 
 ```
 ~/.claude/                       (or ./.claude/ for local)
-├── agents/
+├── agents/                      # 7 agent definitions
 │   ├── hydra-scout.md
 │   ├── hydra-runner.md
 │   ├── hydra-scribe.md
@@ -52,8 +52,21 @@ npx hail-hydra-cc --help         # Show help
 │   ├── hydra-git.md
 │   ├── hydra-coder.md
 │   └── hydra-analyst.md
-└── hydra/
-    ├── SKILL.md
+├── commands/hydra/              # 7 slash commands
+│   ├── help.md                  # /hydra:help
+│   ├── status.md                # /hydra:status
+│   ├── update.md                # /hydra:update
+│   ├── config.md                # /hydra:config
+│   ├── guard.md                 # /hydra:guard
+│   ├── quiet.md                 # /hydra:quiet
+│   └── verbose.md               # /hydra:verbose
+├── hooks/                       # 3 lifecycle hooks
+│   ├── hydra-check-update.js    # SessionStart — version check
+│   ├── hydra-statusline.js      # StatusLine — status bar
+│   └── hydra-auto-guard.js      # PostToolUse — file tracker
+└── skills/hydra/                # Skill (Claude Code discoverable via /skills)
+    ├── SKILL.md                 # Orchestrator instructions
+    ├── VERSION                  # Installed version
     └── references/
         ├── routing-guide.md
         └── model-capabilities.md

package/bin/cli.js

@@ -39,8 +39,8 @@ Examples:
 
 What gets installed:
   ~/.claude/agents/              7 Hydra agent .md files
-  ~/.claude/hydra/SKILL.md       Core framework instructions
-  ~/.claude/hydra/references/    Model capabilities & routing guides
+  ~/.claude/skills/hydra/SKILL.md       Core framework instructions
+  ~/.claude/skills/hydra/references/    Model capabilities & routing guides
 `);
 
 // ── Main action ───────────────────────────────────────────────────────────────

package/files/SKILL.md

@@ -1,15 +1,12 @@
 ---
 name: hydra
 description: >
-  Hydra — multi-headed task execution framework for Claude Code that dramatically reduces
-  latency and API costs. Inspired by speculative decoding in LLM inference, Hydra makes
-  the main Opus agent an intelligent orchestrator that delegates work to Haiku 4.5 and Sonnet 4.6
-  "heads," reserving Opus-level reasoning only for tasks that truly require it. ALWAYS
-  activate this skill during any Claude Code session. This skill should be triggered for
-  EVERY task — it is the default operating mode, not an optional optimization. Think of it
-  as "always on" infrastructure, like an OS scheduler. If you are running as Opus and about
-  to do work that a faster model could handle, delegate it. "Cut off one head, two more
-  shall take its place" — except here, every head is working FOR you.
+  Multi-agent orchestration framework for Claude Code. Automatically delegates
+  tasks to cheaper, faster sub-agents (Haiku 4.5, Sonnet 4.6) while maintaining
+  Opus-level quality through verification. Use when working on any coding task —
+  Hydra activates automatically to route file exploration, test running,
+  documentation, code writing, debugging, security scanning, and git operations
+  to the optimal agent. Saves ~50% on API costs.
 ---
 
 # 🐉 Hydra — Multi-Headed Speculative Execution
@@ -718,8 +715,8 @@ Hydra's heads live in `agents/`. Install them where Claude Code discovers subage
 ## Configuration
 
 At session start, check for a Hydra configuration file at:
-1. `.claude/hydra/hydra.config.md` (project-level, takes precedence)
-2. `~/.claude/hydra/hydra.config.md` (user-level, fallback)
+1. `.claude/skills/hydra/config/hydra.config.md` (project-level, takes precedence)
+2. `~/.claude/skills/hydra/config/hydra.config.md` (user-level, fallback)
 
 If found, apply the settings. If not found, use defaults:
 - **mode**: balanced

package/files/commands/hydra/config.md

@@ -0,0 +1,37 @@
+---
+description: Show current Hydra configuration and how to customize it
+allowed-tools: Read, Bash
+---
+
+# Hydra Config
+
+Show the current Hydra configuration:
+
+1. Check for project-level config first:
+```bash
+   cat .claude/skills/hydra/config/hydra.config.md 2>/dev/null
+```
+
+2. If not found, check global config:
+```bash
+   cat ~/.claude/skills/hydra/config/hydra.config.md 2>/dev/null
+```
+
+3. If neither found, show defaults:
+
+```
+🐉 Hydra Configuration (defaults — no config file found)
+─────────────────────────────
+Mode:          balanced
+Dispatch Log:  on
+Auto-Guard:    on
+Model Overrides: none
+─────────────────────────────
+To customize, create a config file:
+  Global:  ~/.claude/skills/hydra/config/hydra.config.md
+  Project: .claude/skills/hydra/config/hydra.config.md
+
+Run /hydra:status to see current agent assignments.
+```
+
+4. If a config file IS found, display its contents and note where it was loaded from.

package/files/commands/hydra/guard.md

@@ -0,0 +1,71 @@
+---
+description: Manually run the Hydra security and quality scan on specified files or directories
+allowed-tools: Read, Grep, Glob, Bash
+model: haiku
+---
+
+# Hydra Guard — Manual Security Scan
+
+Run a focused security and quality scan on the specified files.
+
+**Target**: $ARGUMENTS
+
+If no arguments provided, scan all files changed since the last commit:
+```bash
+git diff --name-only HEAD 2>/dev/null || echo "Not a git repository or no changes"
+```
+
+## Scan Checklist
+
+For each target file, check for:
+
+### CRITICAL (security)
+- Hardcoded secrets, API keys, tokens, passwords (patterns: `sk-`, `ghp_`, `AKIA`, `password =`, `secret =`, `token =`, `api_key =`)
+- SQL injection vulnerabilities (string concatenation in queries)
+- XSS vulnerabilities (unescaped user input in HTML output)
+- Unsafe deserialization (`eval()`, `pickle.loads()`, `unserialize()`)
+- Path traversal (`../` in file operations without validation)
+- Command injection (user input passed to shell commands)
+
+### WARNING (quality)
+- `console.log` / `print()` debug leftovers
+- TODO/FIXME/HACK comments
+- Unused imports (obvious cases only)
+- Missing error handling on async operations (no try/catch, no .catch())
+- Empty catch blocks
+- Hardcoded URLs or magic numbers without constants
+
+### INFO (style)
+- Functions longer than 100 lines
+- Deeply nested conditionals (3+ levels)
+- Inconsistent naming conventions within the same file
+
+## Output Format
+
+```
+🐉 Hydra Guard — Security & Quality Report
+═══════════════════════════════════════════
+Files scanned: 3
+
+🔴 CRITICAL (2 findings)
+  src/auth.py:45     Hardcoded API key: OPENAI_KEY = "sk-..."
+  src/db.py:78       SQL injection: f-string in query construction
+
+⚠️  WARNING (3 findings)
+  src/auth.py:12     console.log left in production code
+  src/utils.py:89    Empty catch block — errors silently swallowed
+  src/api.py:34      TODO: "fix this later" (line 34)
+
+ℹ️  INFO (1 finding)
+  src/handler.py:1   Function process_request is 142 lines long
+
+Summary: 2 critical · 3 warnings · 1 info
+```
+
+If no issues found:
+```
+🐉 Hydra Guard — All Clear ✅
+Files scanned: 3 | No issues found.
+```
+
+**Important**: This is a FAST scan, not a deep audit. For thorough security review, use hydra-analyst instead.

package/files/commands/hydra/help.md

@@ -0,0 +1,41 @@
+---
+description: Show all available Hydra commands, agents, and a quick reference guide
+---
+
+# Hydra Help
+
+Display the following help reference directly — do NOT search files or run commands:
+
+```
+🐉 Hydra Framework — Quick Reference
+═══════════════════════════════════════
+COMMANDS
+  /hydra:help      Show this help screen
+  /hydra:status    Show installed agents, version, config
+  /hydra:update    Update Hydra to the latest version
+  /hydra:config    Show current configuration
+  /hydra:guard     Run security scan on files (usage: /hydra:guard src/auth.py)
+  /hydra:quiet     Suppress dispatch logs for this session
+  /hydra:verbose   Enable verbose dispatch logs with timing
+
+AGENTS
+  🟢 hydra-scout    (Haiku 4.5)   — Explore codebase, find files, map structure
+  🟢 hydra-runner   (Haiku 4.5)   — Run tests, linters, build commands
+  🟢 hydra-scribe   (Haiku 4.5)   — Write docs, comments, READMEs
+  🟢 hydra-guard    (Haiku 4.5)   — Security scan, quality gate
+  🟢 hydra-git      (Haiku 4.5)   — Git operations, commits, branches
+  🔵 hydra-coder    (Sonnet 4.6)  — Write and edit code
+  🔵 hydra-analyst  (Sonnet 4.6)  — Debug, diagnose, review
+
+HOW IT WORKS
+  The Opus 4.6 orchestrator automatically delegates tasks to cheaper,
+  faster agents (Haiku 4.5 and Sonnet 4.6) — saving ~50% on API costs
+  while maintaining Opus-level quality through verification.
+
+  You don't need to do anything. Just work normally.
+  Hydra operates invisibly unless you check the dispatch log.
+
+LINKS
+  GitHub:  https://github.com/AR6420/Hail_Hydra
+  npm:     https://www.npmjs.com/package/hail-hydra-cc
+```

package/files/commands/hydra/quiet.md

@@ -0,0 +1,14 @@
+---
+description: Suppress Hydra dispatch logs for the rest of this session
+---
+
+# Hydra Quiet Mode
+
+Acknowledge this command and remember for the rest of this session:
+
+**Do NOT display the Hydra Dispatch Log footer after tasks.**
+
+Respond with:
+"🐉 Quiet mode enabled. Dispatch logs suppressed for this session. Use /hydra:verbose to re-enable."
+
+Continue operating Hydra normally (delegation, verification, auto-guard) — just don't show the dispatch log table.

package/files/commands/hydra/status.md

@@ -0,0 +1,72 @@
+---
+description: Show Hydra framework status — installed agents, version, config, and update availability
+allowed-tools: Bash, Read, Glob
+---
+
+# Hydra Status
+
+Show a comprehensive status report for the Hydra framework.
+
+## 1. Version Info
+```bash
+INSTALLED=$(cat ~/.claude/skills/hydra/VERSION 2>/dev/null || echo "unknown")
+echo "Installed: $INSTALLED"
+LATEST=$(npm view hail-hydra-cc version 2>/dev/null || echo "unknown")
+echo "Latest: $LATEST"
+```
+
+## 2. Installed Agents
+```bash
+echo "=== Global Agents ==="
+ls -1 ~/.claude/agents/hydra-*.md 2>/dev/null || echo "None found"
+echo "=== Local Agents ==="
+ls -1 .claude/agents/hydra-*.md 2>/dev/null || echo "None found"
+```
+
+## 3. Installed Commands
+```bash
+echo "=== Global Commands ==="
+ls -1 ~/.claude/commands/hydra/*.md 2>/dev/null || echo "None found"
+echo "=== Local Commands ==="
+ls -1 .claude/commands/hydra/*.md 2>/dev/null || echo "None found"
+```
+
+## 4. Hooks
+```bash
+ls -1 ~/.claude/hooks/hydra-*.js 2>/dev/null || echo "None found"
+```
+
+## 5. Configuration
+```bash
+cat ~/.claude/skills/hydra/config/hydra.config.md 2>/dev/null || \
+cat .claude/skills/hydra/config/hydra.config.md 2>/dev/null || \
+echo "No config file found (using defaults)"
+```
+
+## Display Format
+
+Present results as a clean status card:
+
+```
+🐉 Hydra Framework Status
+──────────────────────────────
+Version:     1.0.0 (latest: 1.0.0 ✅)  OR  (update available: 1.1.0 ⚡)
+Install:     Global (~/.claude/)
+Agents (7):
+  🟢 hydra-scout    (Haiku 4.5)   ✅
+  🟢 hydra-runner   (Haiku 4.5)   ✅
+  🟢 hydra-scribe   (Haiku 4.5)   ✅
+  🟢 hydra-guard    (Haiku 4.5)   ✅
+  🟢 hydra-git      (Haiku 4.5)   ✅
+  🔵 hydra-coder    (Sonnet 4.6)  ✅
+  🔵 hydra-analyst  (Sonnet 4.6)  ✅
+Commands (7): update, status, help, config, guard, quiet, verbose
+Hooks (3):    check-update ✅, statusline ✅, auto-guard ✅
+Config:       balanced mode, dispatch log on, auto-guard on
+──────────────────────────────
+```
+
+If an update is available, add:
+```
+⚡ Update available! Run /hydra:update to get the latest version.
+```

package/files/commands/hydra/update.md

@@ -0,0 +1,35 @@
+---
+description: Update the Hydra framework to the latest version from npm
+allowed-tools: Bash
+---
+
+# Hydra Update
+
+Run the following steps to update Hydra to the latest version:
+
+1. First, check the current installed version:
+```bash
+   cat ~/.claude/skills/hydra/VERSION 2>/dev/null || echo "VERSION file not found"
+```
+
+2. Check the latest available version on npm:
+```bash
+   npm view hail-hydra-cc version 2>/dev/null || echo "Package not found on npm"
+```
+
+3. If an update is available (versions differ), run the installer:
+```bash
+   npx hail-hydra-cc@latest --global
+```
+
+4. After installation completes, verify the new version:
+```bash
+   cat ~/.claude/skills/hydra/VERSION
+```
+
+5. Report to the user:
+   - If updated: "🐉 Hydra updated from [old] → [new]. All heads refreshed."
+   - If already current: "🐉 Hydra is already at the latest version ([version])."
+   - If error: Show the error and suggest running `npx hail-hydra-cc@latest --global` manually in their terminal.
+
+**Important**: After updating, the user should restart Claude Code to reload the updated agent files, commands, and hooks.

package/files/commands/hydra/verbose.md

@@ -0,0 +1,27 @@
+---
+description: Enable verbose Hydra dispatch logs with timing and token estimates
+---
+
+# Hydra Verbose Mode
+
+Acknowledge this command and remember for the rest of this session:
+
+**Display DETAILED Hydra Dispatch Logs after every task that involves delegation.**
+
+The verbose log includes extra columns for timing:
+
+```
+🐉 Hydra Dispatch Log (verbose)
+| Step | Agent               | Task                  | Time  | Verdict     |
+|------|---------------------|-----------------------|-------|-------------|
+| 1    | hydra-scout (Haiku 4.5)  | Explored auth module | 3.2s  | ✅ Accepted |
+| 2    | hydra-coder (Sonnet 4.6) | Fixed null check     | 8.1s  | ✅ Accepted |
+| 3    | hydra-guard (Haiku 4.5)  | Security scan        | 1.4s  | ✅ Passed   |
+| 4    | hydra-runner (Haiku 4.5) | Ran test suite       | 4.7s  | ✅ Accepted |
+
+Delegation: 4/4 (100%) | Accepted: 4 | Adjusted: 0 | Rejected: 0
+Total delegation time: 17.4s | Waves: 2
+```
+
+Respond with:
+"🐉 Verbose mode enabled. Dispatch logs will include timing details. Use /hydra:quiet to suppress."

package/files/hooks/hydra-auto-guard.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+// Hydra Auto-Guard Hook — PostToolUse (matcher: Write|Edit|MultiEdit)
+// Records changed file paths to a temp file for hydra-guard to scan later.
+// Does NOT run the scan itself — that would slow down every edit.
+// Overhead: <1ms per edit. Files deduped by path.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+let input = '';
+process.stdin.on('data', (chunk) => (input += chunk));
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+
+    // Extract the file path from the tool input
+    const filePath = data.tool_input?.file_path ||
+                     data.tool_input?.path ||
+                     null;
+
+    if (!filePath) {
+      process.exit(0);
+    }
+
+    // Append to session-scoped changed files list
+    const sessionId = data.session_id || 'unknown';
+    const trackingDir = path.join(os.tmpdir(), 'hydra-guard');
+    const trackingFile = path.join(trackingDir, `${sessionId}.txt`);
+
+    // Ensure directory exists
+    if (!fs.existsSync(trackingDir)) {
+      fs.mkdirSync(trackingDir, { recursive: true });
+    }
+
+    // Read existing tracked files
+    let existing = '';
+    try {
+      existing = fs.readFileSync(trackingFile, 'utf8');
+    } catch (e) {
+      // File doesn't exist yet — that's fine
+    }
+
+    // Only append if not already tracked (dedup)
+    if (!existing.split('\n').includes(filePath)) {
+      fs.appendFileSync(trackingFile, filePath + '\n');
+    }
+
+  } catch (e) {
+    // Silently fail — NEVER block Claude Code
+  }
+  process.exit(0);
+});

package/files/hooks/hydra-check-update.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+// Hydra Update Checker — SessionStart hook
+// Spawns a DETACHED background process to check npm for updates.
+// Writes result to ~/.claude/cache/hydra-update-check.json
+// The statusline hook reads this cache file.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const homeDir = os.homedir();
+const cacheDir = path.join(homeDir, '.claude', 'cache');
+const cacheFile = path.join(cacheDir, 'hydra-update-check.json');
+
+// VERSION file locations (check project first, then global)
+const projectVersionFile = path.join(process.cwd(), '.claude', 'hydra', 'VERSION');
+const globalVersionFile = path.join(homeDir, '.claude', 'hydra', 'VERSION');
+
+// Ensure cache directory exists
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+// Skip check if we checked within the last hour
+try {
+  const existing = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+  const age = Date.now() - (existing.checked_at || 0);
+  if (age < 3600000) { // 1 hour
+    process.exit(0);
+  }
+} catch (e) {
+  // No cache or invalid — proceed with check
+}
+
+// Read stdin to prevent EPIPE (Claude Code pipes JSON to all hooks)
+let stdinData = '';
+process.stdin.on('data', (chunk) => (stdinData += chunk));
+process.stdin.on('end', () => {
+  // Spawn background process (MUST be detached to not block Claude Code)
+  const child = spawn(process.execPath, ['-e', `
+    const fs = require('fs');
+    const { execSync } = require('child_process');
+
+    const cacheFile = ${JSON.stringify(cacheFile)};
+    const projectVersionFile = ${JSON.stringify(projectVersionFile)};
+    const globalVersionFile = ${JSON.stringify(globalVersionFile)};
+
+    try {
+      // Read installed version
+      let installed = 'unknown';
+      try {
+        installed = fs.readFileSync(projectVersionFile, 'utf8').trim();
+      } catch (e) {
+        try {
+          installed = fs.readFileSync(globalVersionFile, 'utf8').trim();
+        } catch (e2) {}
+      }
+
+      // Fetch latest version from npm (with timeout)
+      const latest = execSync('npm view hail-hydra-cc version', {
+        encoding: 'utf8',
+        timeout: 10000,
+        windowsHide: true,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+
+      // Compare and write cache
+      const updateAvailable = installed !== 'unknown' && latest !== installed;
+
+      const result = {
+        installed: installed,
+        latest: latest,
+        update_available: updateAvailable,
+        checked_at: Date.now()
+      };
+
+      fs.writeFileSync(cacheFile, JSON.stringify(result, null, 2));
+    } catch (e) {
+      // Network error or npm not available — write a "no check" result
+      const result = {
+        installed: 'unknown',
+        latest: 'unknown',
+        update_available: false,
+        checked_at: Date.now(),
+        error: e.message
+      };
+      fs.writeFileSync(cacheFile, JSON.stringify(result, null, 2));
+    }
+  `], {
+    stdio: 'ignore',
+    windowsHide: true,
+    detached: true  // CRITICAL: prevents blocking Claude Code input on Windows
+  });
+
+  child.unref();
+  process.exit(0);
+});

package/files/hooks/hydra-statusline.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+// Hydra StatusLine — persistent status bar at bottom of Claude Code
+// Receives session JSON via stdin, outputs one formatted line to stdout.
+//
+// Display format:
+//   🐉 │ Opus │ Ctx: 37% ████░░░░░░ │ $0.42 │ my-project │ ⚡ Update available
+//
+// Context bar is color-coded:
+//   Green (0-49%) → Yellow (50-79%) → Red (80%+)
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const cacheFile = path.join(os.homedir(), '.claude', 'cache', 'hydra-update-check.json');
+
+let input = '';
+process.stdin.on('data', (chunk) => (input += chunk));
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+
+    // === Model ===
+    const model = data.model?.display_name || 'Unknown';
+
+    // === Context Usage ===
+    // Use precomputed used_percentage from Claude Code (most reliable)
+    const ctxPct = Math.round(data.context_window?.used_percentage || 0);
+
+    // Build visual context bar (10 chars wide)
+    const filled = Math.round(ctxPct / 10);
+    const empty = 10 - filled;
+    const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(empty);
+
+    // Color-code: Green <50%, Yellow 50-79%, Red 80%+
+    let ctxColor;
+    if (ctxPct < 50) {
+      ctxColor = '\x1b[32m'; // Green
+    } else if (ctxPct < 80) {
+      ctxColor = '\x1b[33m'; // Yellow
+    } else {
+      ctxColor = '\x1b[31m'; // Red
+    }
+    const reset = '\x1b[0m';
+    const dim = '\x1b[2m';
+
+    const ctxDisplay = `${ctxColor}Ctx: ${ctxPct}% ${bar}${reset}`;
+
+    // === Session Cost ===
+    const cost = (data.cost?.total_cost_usd || 0).toFixed(2);
+
+    // === Working Directory ===
+    const dirName = path.basename(data.workspace?.current_dir || data.cwd || '');
+
+    // === Update Check (read from cache) ===
+    let updateNotice = '';
+    try {
+      const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+      if (cache.update_available) {
+        updateNotice = ` \x1b[33m\u26A1 v${cache.latest} available${reset}`;
+      }
+    } catch (e) {
+      // No cache — skip update notice
+    }
+
+    // === Compose Status Line ===
+    const parts = [
+      '\x1b[32m\uD83D\uDC32\x1b[0m',         // Green dragon emoji (🐉)
+      `${dim}${model}${reset}`,                 // Dim model name
+      ctxDisplay,                               // Color-coded context bar
+      `${dim}$${cost}${reset}`,                // Dim cost
+      `${dim}${dirName}${reset}`,              // Dim directory
+    ];
+
+    // Append update notice if available
+    if (updateNotice) {
+      parts.push(updateNotice);
+    }
+
+    process.stdout.write(parts.join(' \u2502 '));
+
+  } catch (e) {
+    // Fallback if JSON parse fails
+    process.stdout.write('\uD83D\uDC32 Hydra');
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hail-hydra-cc",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Multi-headed speculative execution framework for Claude Code",
   "bin": {
     "hail-hydra-cc": "bin/cli.js"

package/src/display.js

@@ -37,17 +37,36 @@ function showFileInstalled(displayName, success, errorMsg) {
   }
 }
 
-function showInstallComplete() {
+function showInstallComplete(statusLineConfigured = true) {
   console.log();
-  console.log(chalk.cyan.bold('  🐉 Hail Hydra! 7 heads deployed and ready.'));
+  console.log(chalk.cyan.bold('  \uD83D\uDC09 Hail Hydra! Framework deployed and ready.'));
+  console.log(chalk.gray('  ' + '\u2500'.repeat(45)));
+  console.log(chalk.green(`    \u2714 7 agents installed`));
+  console.log(chalk.green(`    \u2714 7 slash commands installed`));
+  console.log(chalk.green(`    \u2714 3 hooks registered`));
+  if (statusLineConfigured) {
+    console.log(chalk.green(`    \u2714 StatusLine configured`));
+  } else {
+    console.log(chalk.yellow(`    \u26a0 StatusLine skipped (existing config preserved)`));
+  }
+  console.log(chalk.green(`    \u2714 Version tracked (${VERSION})`));
   console.log();
-  console.log(chalk.gray('  Launch Claude Code to start using the framework.'));
+  console.log(chalk.gray('  Quick start:  /hydra:help'));
+  console.log(chalk.gray('  Check status: /hydra:status'));
   console.log(chalk.gray('  GitHub: https://github.com/AR6420/Hail_Hydra'));
   console.log();
 }
 
 function showStatusTable(globalStatus, localStatus) {
-  const divider = chalk.gray('  ' + '─'.repeat(50));
+  const os = require('os');
+  const path = require('path');
+  const fs = require('fs');
+
+  function fileExists(p) {
+    try { fs.accessSync(p, fs.constants.F_OK); return true; } catch { return false; }
+  }
+
+  const divider = chalk.gray('  ' + '\u2500'.repeat(50));
 
   console.log();
   console.log(chalk.bold('  Installation Status'));
@@ -65,7 +84,9 @@ function showStatusTable(globalStatus, localStatus) {
     const anyInstalled =
       status.agents.some((a) => a.installed) ||
       status.skill ||
-      status.references.some((r) => r.installed);
+      status.references.some((r) => r.installed) ||
+      (status.commands && status.commands.some((c) => c.installed)) ||
+      status.version;
 
     if (!anyInstalled) {
       console.log(chalk.gray('    (not installed)'));
@@ -73,29 +94,60 @@ function showStatusTable(globalStatus, localStatus) {
     }
 
     for (const agent of status.agents) {
-      const dot = agent.model === 'Haiku' ? chalk.green('🟢') : chalk.blue('🔵');
-      const name = chalk.bold(agent.display.split('—')[0].trim());
-      const role = chalk.gray('— ' + agent.display.split('—')[1].trim());
+      const dot = agent.model === 'Haiku' ? chalk.green('\uD83D\uDFE2') : chalk.blue('\uD83D\uDD35');
+      const name = chalk.bold(agent.display.split('\u2014')[0].trim());
+      const role = chalk.gray('\u2014 ' + agent.display.split('\u2014')[1].trim());
       if (agent.installed) {
-        console.log(`    ${dot} ${chalk.green('✔')} ${name} ${role}`);
+        console.log(`    ${dot} ${chalk.green('\u2714')} ${name} ${role}`);
       } else {
-        console.log(`    ${dot} ${chalk.gray('✖')} ${chalk.gray(name)} ${chalk.gray(role + ' (not installed)')}`);
+        console.log(`    ${dot} ${chalk.gray('\u2716')} ${chalk.gray(name)} ${chalk.gray(role + ' (not installed)')}`);
       }
     }
 
     if (status.skill) {
-      console.log(chalk.green('    ✔ SKILL.md'));
+      console.log(chalk.green('    \u2714 SKILL.md'));
     } else {
-      console.log(chalk.gray('    ✖ SKILL.md (not installed)'));
+      console.log(chalk.gray('    \u2716 SKILL.md (not installed)'));
     }
 
     for (const ref of status.references) {
       if (ref.installed) {
-        console.log(chalk.green(`    ✔ ${ref.name}`));
+        console.log(chalk.green(`    \u2714 ${ref.name}`));
       } else {
-        console.log(chalk.gray(`    ✖ ${ref.name} (not installed)`));
+        console.log(chalk.gray(`    \u2716 ${ref.name} (not installed)`));
+      }
+    }
+
+    // Commands
+    if (status.commands) {
+      for (const cmd of status.commands) {
+        if (cmd.installed) {
+          console.log(chalk.green(`    \u2714 ${cmd.name}`));
+        } else {
+          console.log(chalk.gray(`    \u2716 ${cmd.name} (not installed)`));
+        }
       }
     }
+
+    // Version
+    if (status.version) {
+      console.log(chalk.green(`    \u2714 hydra/VERSION (${status.version})`));
+    } else {
+      console.log(chalk.gray('    \u2716 hydra/VERSION (not installed)'));
+    }
+  }
+
+  // Global hooks (always ~/.claude/hooks/)
+  console.log();
+  console.log(chalk.bold('  Global Hooks (~/.claude/hooks/)'));
+  const hookKeys = ['hydra-check-update', 'hydra-statusline', 'hydra-auto-guard'];
+  for (const key of hookKeys) {
+    const dest = path.join(os.homedir(), '.claude', 'hooks', `${key}.js`);
+    if (fileExists(dest)) {
+      console.log(chalk.green(`    \u2714 ${key}.js`));
+    } else {
+      console.log(chalk.gray(`    \u2716 ${key}.js (not installed)`));
+    }
   }
 
   console.log();

package/src/files.js

@@ -62,4 +62,20 @@ const references = {
   'model-capabilities': readBundled('references/model-capabilities.md'),
 };
 
-module.exports = { agents, skill, references };
+const commands = {
+  'update':   readBundled('commands/hydra/update.md'),
+  'status':   readBundled('commands/hydra/status.md'),
+  'help':     readBundled('commands/hydra/help.md'),
+  'config':   readBundled('commands/hydra/config.md'),
+  'guard':    readBundled('commands/hydra/guard.md'),
+  'quiet':    readBundled('commands/hydra/quiet.md'),
+  'verbose':  readBundled('commands/hydra/verbose.md'),
+};
+
+const hooks = {
+  'hydra-check-update': readBundled('hooks/hydra-check-update.js'),
+  'hydra-statusline':   readBundled('hooks/hydra-statusline.js'),
+  'hydra-auto-guard':   readBundled('hooks/hydra-auto-guard.js'),
+};
+
+module.exports = { agents, skill, references, commands, hooks };

package/src/installer.js

@@ -5,8 +5,8 @@ const path = require('path');
 const os = require('os');
 const chalk = require('chalk');
 
-const { agents, skill, references } = require('./files');
-const { showInstallHeader, showFileInstalled, showInstallComplete, showStatusTable } = require('./display');
+const { agents, skill, references, commands, hooks } = require('./files');
+const { showInstallHeader, showFileInstalled, showInstallComplete, showStatusTable, VERSION } = require('./display');
 
 // ── Install locations ────────────────────────────────────────────────────────
 
@@ -28,9 +28,9 @@ function buildManifest(base) {
   const skillEntry = {
     type:    'skill',
     key:     'SKILL.md',
-    display: 'SKILL.md',
+    display: 'skills/hydra/SKILL.md',
     content: skill,
-    dest:    path.join(base, 'hydra', 'SKILL.md'),
+    dest:    path.join(base, 'skills', 'hydra', 'SKILL.md'),
   };
 
   const refEntries = Object.entries(references).map(([key, content]) => ({
@@ -38,10 +38,26 @@ function buildManifest(base) {
     key,
     display: `references/${key}.md`,
     content,
-    dest:    path.join(base, 'hydra', 'references', `${key}.md`),
+    dest:    path.join(base, 'skills', 'hydra', 'references', `${key}.md`),
   }));
 
-  return [...agentEntries, skillEntry, ...refEntries];
+  const commandEntries = Object.entries(commands).map(([key, content]) => ({
+    type:    'command',
+    key,
+    display: `commands/hydra/${key}.md`,
+    content,
+    dest:    path.join(base, 'commands', 'hydra', `${key}.md`),
+  }));
+
+  const versionEntry = {
+    type:    'version',
+    key:     'VERSION',
+    display: 'skills/hydra/VERSION',
+    content: VERSION,
+    dest:    path.join(base, 'skills', 'hydra', 'VERSION'),
+  };
+
+  return [...agentEntries, skillEntry, ...refEntries, ...commandEntries, versionEntry];
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -68,6 +84,94 @@ function hasAnyInstalled(base) {
   return buildManifest(base).some((entry) => fileExists(entry.dest));
 }
 
+// ── Hooks & settings ─────────────────────────────────────────────────────────
+
+function installHooks() {
+  const hooksDir = path.join(GLOBAL_BASE, 'hooks');
+  ensureDir(hooksDir);
+
+  for (const [key, content] of Object.entries(hooks)) {
+    const dest = path.join(hooksDir, `${key}.js`);
+    try {
+      writeFileSafe(dest, content);
+      try { fs.chmodSync(dest, 0o755); } catch {}
+      showFileInstalled(`hooks/${key}.js`, true);
+    } catch (err) {
+      showFileInstalled(`hooks/${key}.js`, false, err.message);
+    }
+  }
+}
+
+function registerHooksInSettings() {
+  const settingsFile = path.join(GLOBAL_BASE, 'settings.json');
+
+  let settings = {};
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+  } catch {}
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+  if (!settings.hooks.PostToolUse)  settings.hooks.PostToolUse  = [];
+
+  const isHydraHook = (entry) =>
+    Array.isArray(entry.hooks) && entry.hooks.some(h => h.command && h.command.includes('hydra-'));
+
+  // Remove stale Hydra entries (clean reinstall)
+  settings.hooks.SessionStart = settings.hooks.SessionStart.filter(x => !isHydraHook(x));
+  settings.hooks.PostToolUse  = settings.hooks.PostToolUse.filter(x => !isHydraHook(x));
+
+  settings.hooks.SessionStart.push({
+    hooks: [{ type: 'command', command: 'node ~/.claude/hooks/hydra-check-update.js' }]
+  });
+
+  settings.hooks.PostToolUse.push({
+    matcher: 'Write|Edit|MultiEdit',
+    hooks:   [{ type: 'command', command: 'node ~/.claude/hooks/hydra-auto-guard.js' }]
+  });
+
+  let statusLineConfigured = false;
+  if (!settings.statusLine || (settings.statusLine.command && settings.statusLine.command.includes('hydra-'))) {
+    settings.statusLine = {
+      type: 'command',
+      command: 'node ~/.claude/hooks/hydra-statusline.js',
+      padding: 0,
+    };
+    statusLineConfigured = true;
+  }
+
+  writeFileSafe(settingsFile, JSON.stringify(settings, null, 2));
+  return { statusLineConfigured };
+}
+
+function deregisterHooks() {
+  const settingsFile = path.join(GLOBAL_BASE, 'settings.json');
+
+  try {
+    let settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+
+    const isHydraHook = (entry) =>
+      Array.isArray(entry.hooks) && entry.hooks.some(h => h.command && h.command.includes('hydra-'));
+
+    if (settings.hooks?.SessionStart) {
+      settings.hooks.SessionStart = settings.hooks.SessionStart.filter(x => !isHydraHook(x));
+      if (!settings.hooks.SessionStart.length) delete settings.hooks.SessionStart;
+    }
+    if (settings.hooks?.PostToolUse) {
+      settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(x => !isHydraHook(x));
+      if (!settings.hooks.PostToolUse.length) delete settings.hooks.PostToolUse;
+    }
+    if (settings.hooks && !Object.keys(settings.hooks).length) delete settings.hooks;
+
+    if (settings.statusLine?.command?.includes('hydra-')) delete settings.statusLine;
+
+    writeFileSafe(settingsFile, JSON.stringify(settings, null, 2));
+    console.log(chalk.green('  \u2714 Hooks deregistered from settings.json'));
+  } catch (err) {
+    console.log(chalk.yellow(`  \u26a0 Could not update settings.json: ${err.message}`));
+  }
+}
+
 // ── Core install ─────────────────────────────────────────────────────────────
 
 function installToBase(base, label) {
@@ -125,10 +229,14 @@ async function runInstall(scope) {
     if (results.some((r) => !r.success)) anyFailed = true;
   }
 
+  // Hooks and settings are always global (once, not per-base)
+  installHooks();
+  const { statusLineConfigured } = registerHooksInSettings();
+
   if (!anyFailed) {
-    showInstallComplete();
+    showInstallComplete(statusLineConfigured);
   } else {
-    console.log(chalk.yellow('  ⚠ Some files failed to install. Check errors above.\n'));
+    console.log(chalk.yellow('  \u26a0 Some files failed to install. Check errors above.\n'));
   }
 }
 
@@ -189,11 +297,28 @@ async function runUninstall({ interactive = true } = {}) {
     }
   }
 
+  // Remove hook .js files from ~/.claude/hooks/
+  for (const key of Object.keys(hooks)) {
+    const dest = path.join(GLOBAL_BASE, 'hooks', `${key}.js`);
+    if (fileExists(dest)) {
+      try { fs.unlinkSync(dest); console.log(chalk.green(`  \u2714 Removed hooks/${key}.js`)); }
+      catch (err) { console.log(chalk.red(`  \u2716 Failed: hooks/${key}.js \u2014 ${err.message}`)); }
+    }
+  }
+
+  // Remove cache file
+  const cacheFile = path.join(GLOBAL_BASE, 'cache', 'hydra-update-check.json');
+  if (fileExists(cacheFile)) {
+    try { fs.unlinkSync(cacheFile); } catch {}
+  }
+
+  deregisterHooks();
+
   console.log();
   if (failed === 0) {
-    console.log(chalk.cyan.bold('  🐉 All heads severed. Hydra sleeps.\n'));
+    console.log(chalk.cyan.bold('  \uD83D\uDC09 All heads severed. Hydra sleeps.\n'));
   } else {
-    console.log(chalk.yellow(`  ⚠ ${removed} removed, ${failed} failed.\n`));
+    console.log(chalk.yellow(`  \u26a0 ${removed} removed, ${failed} failed.\n`));
   }
 }
 
@@ -214,10 +339,19 @@ function getStatus(base) {
     installed: fileExists(e.dest),
   }));
 
+  const commandEntries = manifest.filter((e) => e.type === 'command').map((e) => ({
+    name:      e.display,
+    installed: fileExists(e.dest),
+  }));
+
+  const versionEntry = manifest.find((e) => e.type === 'version');
+
   return {
     agents:     agentEntries,
     skill:      skillEntry ? fileExists(skillEntry.dest) : false,
     references: refEntries,
+    commands:   commandEntries,
+    version:    versionEntry ? (fileExists(versionEntry.dest) ? fs.readFileSync(versionEntry.dest, 'utf8').trim() : null) : null,
   };
 }