@hasna/hooks 0.0.6 → 0.1.0

package/hooks/hook-desktopnotify/src/hook.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: desktopnotify
+ *
+ * Stop hook that sends a native desktop notification when Claude stops.
+ *
+ * Platform support:
+ * - macOS: osascript (display notification)
+ * - Linux: notify-send
+ */
+
+import { readFileSync } from "fs";
+import { execSync } from "child_process";
+import { basename } from "path";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  hook_event_name?: string;
+  stop_hook_active?: boolean;
+}
+
+interface HookOutput {
+  continue: boolean;
+}
+
+function readStdinJson(): HookInput | null {
+  try {
+    const input = readFileSync(0, "utf-8").trim();
+    if (!input) return null;
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}
+
+function respond(output: HookOutput): void {
+  console.log(JSON.stringify(output));
+}
+
+function escapeForShell(str: string): string {
+  return str.replace(/'/g, "'\\''");
+}
+
+function sendMacNotification(title: string, message: string): void {
+  const escapedTitle = escapeForShell(title);
+  const escapedMessage = escapeForShell(message);
+  const script = `display notification "${escapedMessage}" with title "${escapedTitle}" sound name "Glass"`;
+
+  try {
+    execSync(`osascript -e '${script}'`, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    });
+    console.error("[hook-desktopnotify] macOS notification sent");
+  } catch (error: unknown) {
+    const execError = error as { message?: string };
+    console.error(`[hook-desktopnotify] macOS notification failed: ${execError.message}`);
+  }
+}
+
+function sendLinuxNotification(title: string, message: string): void {
+  const escapedTitle = escapeForShell(title);
+  const escapedMessage = escapeForShell(message);
+
+  try {
+    execSync(`notify-send '${escapedTitle}' '${escapedMessage}' --urgency=normal --expire-time=5000`, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    });
+    console.error("[hook-desktopnotify] Linux notification sent");
+  } catch (error: unknown) {
+    const execError = error as { message?: string };
+    console.error(`[hook-desktopnotify] Linux notification failed: ${execError.message}`);
+  }
+}
+
+function sendNotification(title: string, message: string): void {
+  const platform = process.platform;
+
+  if (platform === "darwin") {
+    sendMacNotification(title, message);
+  } else if (platform === "linux") {
+    sendLinuxNotification(title, message);
+  } else {
+    console.error(`[hook-desktopnotify] Unsupported platform: ${platform}`);
+  }
+}
+
+export function run(): void {
+  const input = readStdinJson();
+
+  if (!input) {
+    respond({ continue: true });
+    return;
+  }
+
+  const projectName = input.cwd ? basename(input.cwd) : "unknown";
+  const title = "Claude Code — Done";
+  const message = `Claude has finished working on ${projectName} and is waiting for your input.`;
+
+  sendNotification(title, message);
+
+  respond({ continue: true });
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-envsetup/README.md

@@ -0,0 +1,40 @@
+# hook-envsetup
+
+Claude Code hook that warns when environment activation may be needed before running commands.
+
+## Overview
+
+Detects when a project uses version managers (nvm, pyenv, asdf, rbenv) or virtual environments, and warns via stderr if the command being run might need them activated first. This is advisory only — it never blocks commands.
+
+## Hook Event
+
+- **PreToolUse** (matcher: `Bash`)
+
+## Detected Environments
+
+| Config File | Environment | Commands Watched |
+|-------------|-------------|------------------|
+| `.nvmrc`, `.node-version` | nvm | `node`, `npm`, `npx`, `yarn`, `pnpm` |
+| `.python-version`, `Pipfile`, `requirements.txt` | Python venv | `python`, `pip`, `pipenv` |
+| `poetry.lock` | Poetry | `python`, `pip`, `poetry` |
+| `.tool-versions` | asdf | `node`, `python`, `ruby`, `go`, etc. |
+| `.ruby-version` | rbenv | `ruby`, `gem`, `bundle`, `rails` |
+
+## Behavior
+
+1. Fires before every Bash command
+2. Checks if environment config files exist in the working directory
+3. Checks if the command involves tools that need the environment
+4. If env file exists but activation is not in the command, logs a warning to stderr
+5. Always outputs `{ decision: "approve" }` — never blocks
+
+## Smart Detection
+
+The hook skips warnings when:
+- The command already includes the activation step (`nvm use`, `source .venv/bin/activate`, etc.)
+- The relevant environment variable is already set (`VIRTUAL_ENV`, `NVM_DIR`)
+- The `.venv` directory doesn't exist yet (suggests creating one instead)
+
+## License
+
+MIT

package/hooks/hook-envsetup/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@hasna/hook-envsetup",
+  "version": "0.1.0",
+  "description": "Claude Code hook that warns when environment activation may be needed",
+  "type": "module",
+  "bin": {
+    "hook-envsetup": "./dist/cli.js"
+  },
+  "main": "./dist/hook.js",
+  "exports": {
+    ".": {
+      "import": "./dist/hook.js",
+      "types": "./dist/hook.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./src/hook.ts --outdir ./dist --target node",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "hook",
+    "environment",
+    "nvm",
+    "python",
+    "venv",
+    "asdf",
+    "cli"
+  ],
+  "author": "Hasna",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasna/open-hooks.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "@types/node": "^20",
+    "typescript": "^5.0.0"
+  }
+}

package/hooks/hook-envsetup/src/hook.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: envsetup
+ *
+ * PreToolUse hook that checks if the environment might need activation
+ * before running commands. Since PreToolUse cannot modify commands,
+ * this hook logs warnings to stderr when it detects that:
+ *
+ * - .nvmrc or .node-version exists and command uses node/npm
+ * - .python-version or Pipfile exists and command uses python/pip
+ * - .tool-versions (asdf) exists
+ * - .venv directory exists but command doesn't activate it
+ *
+ * Always approves — this is advisory only.
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+}
+
+interface HookOutput {
+  decision: "approve";
+}
+
+interface EnvCheck {
+  name: string;
+  files: string[];
+  commandPatterns: RegExp[];
+  warning: string;
+  activationHint: string;
+}
+
+function readStdinJson(): HookInput | null {
+  try {
+    const input = readFileSync(0, "utf-8").trim();
+    if (!input) return null;
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}
+
+function respond(output: HookOutput): void {
+  console.log(JSON.stringify(output));
+}
+
+const ENV_CHECKS: EnvCheck[] = [
+  {
+    name: "Node.js (nvm)",
+    files: [".nvmrc", ".node-version"],
+    commandPatterns: [
+      /\bnode\s/,
+      /\bnpm\s/,
+      /\bnpx\s/,
+      /\byarn\s/,
+      /\bpnpm\s/,
+    ],
+    warning: "Project has .nvmrc/.node-version but nvm may not be activated",
+    activationHint: "source ~/.nvm/nvm.sh && nvm use",
+  },
+  {
+    name: "Python (venv)",
+    files: [".python-version", "Pipfile", "requirements.txt"],
+    commandPatterns: [
+      /\bpython\b/,
+      /\bpython3\b/,
+      /\bpip\b/,
+      /\bpip3\b/,
+      /\bpipenv\b/,
+    ],
+    warning: "Project has Python config but virtualenv may not be activated",
+    activationHint: "source .venv/bin/activate",
+  },
+  {
+    name: "asdf",
+    files: [".tool-versions"],
+    commandPatterns: [
+      /\bnode\s/,
+      /\bnpm\s/,
+      /\bpython\b/,
+      /\bruby\b/,
+      /\belixir\b/,
+      /\berlang\b/,
+      /\bjava\b/,
+      /\bgo\s/,
+    ],
+    warning: "Project has .tool-versions but asdf may not be sourced",
+    activationHint: "source ~/.asdf/asdf.sh",
+  },
+  {
+    name: "Python (Poetry)",
+    files: ["poetry.lock"],
+    commandPatterns: [
+      /\bpython\b/,
+      /\bpython3\b/,
+      /\bpip\b/,
+      /\bpoetry\b/,
+    ],
+    warning: "Project uses Poetry but virtualenv may not be activated",
+    activationHint: "poetry shell",
+  },
+  {
+    name: "Ruby (rbenv)",
+    files: [".ruby-version"],
+    commandPatterns: [
+      /\bruby\b/,
+      /\bgem\b/,
+      /\bbundle\b/,
+      /\brails\b/,
+      /\brake\b/,
+    ],
+    warning: "Project has .ruby-version but rbenv may not be initialized",
+    activationHint: "eval \"$(rbenv init -)\"",
+  },
+];
+
+function checkEnvironment(cwd: string, command: string): void {
+  for (const check of ENV_CHECKS) {
+    // Check if any of the config files exist
+    const hasConfigFile = check.files.some((file) => existsSync(join(cwd, file)));
+    if (!hasConfigFile) continue;
+
+    // Check if the command matches any of the patterns
+    const matchesCommand = check.commandPatterns.some((pattern) => pattern.test(command));
+    if (!matchesCommand) continue;
+
+    // Check if the command already includes the activation
+    if (command.includes("nvm use") || command.includes("nvm.sh")) continue;
+    if (command.includes(".venv/bin/activate") || command.includes("venv/bin/activate")) continue;
+    if (command.includes("asdf.sh")) continue;
+    if (command.includes("poetry shell") || command.includes("poetry run")) continue;
+    if (command.includes("rbenv init")) continue;
+
+    // For Python: check if .venv exists (if not, no point warning)
+    if (check.name === "Python (venv)") {
+      const hasVenv = existsSync(join(cwd, ".venv")) || existsSync(join(cwd, "venv"));
+      if (!hasVenv) {
+        // Check if VIRTUAL_ENV is set
+        if (!process.env.VIRTUAL_ENV) {
+          console.error(`[hook-envsetup] Warning: ${check.warning} (no .venv directory found, consider creating one)`);
+        }
+        continue;
+      }
+      // Check if already in a venv
+      if (process.env.VIRTUAL_ENV) continue;
+    }
+
+    // For nvm: check if NVM_DIR is set
+    if (check.name === "Node.js (nvm)") {
+      if (!process.env.NVM_DIR) {
+        console.error(`[hook-envsetup] Warning: ${check.warning} (NVM_DIR not set)`);
+        console.error(`[hook-envsetup] Hint: ${check.activationHint}`);
+        continue;
+      }
+    }
+
+    console.error(`[hook-envsetup] Warning: ${check.warning}`);
+    console.error(`[hook-envsetup] Hint: ${check.activationHint}`);
+  }
+}
+
+export function run(): void {
+  const input = readStdinJson();
+
+  if (!input) {
+    respond({ decision: "approve" });
+    return;
+  }
+
+  if (input.tool_name !== "Bash") {
+    respond({ decision: "approve" });
+    return;
+  }
+
+  const command = input.tool_input?.command as string;
+  if (!command || typeof command !== "string") {
+    respond({ decision: "approve" });
+    return;
+  }
+
+  const cwd = input.cwd || process.cwd();
+  checkEnvironment(cwd, command);
+
+  // Always approve — this hook is advisory only
+  respond({ decision: "approve" });
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-errornotify/README.md

@@ -0,0 +1,66 @@
+# hook-errornotify
+
+Claude Code hook that detects tool failures and logs errors for tracking.
+
+## Event
+
+**PostToolUse** — fires after any tool execution completes.
+
+## What It Does
+
+Inspects tool output for error indicators and provides two layers of notification:
+
+1. **stderr warnings** — immediate visibility in the terminal
+2. **`.claude/errors.log`** — persistent error log file for later review
+
+### Error Detection
+
+The hook checks for:
+
+- Non-zero exit codes (`exit_code`, `exitCode`, `code` fields)
+- Explicit `error` field in output
+- Error patterns in output text:
+  - `error:`, `fatal:`, `panic:`
+  - `command not found`, `permission denied`, `no such file or directory`
+  - `ENOENT`, `EACCES`, `EPERM`, `ENOMEM`
+  - Python/JS/Go exceptions (`TypeError`, `ImportError`, `FileNotFoundError`, etc.)
+  - Python tracebacks
+
+## Installation
+
+Add to your `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run hooks/hook-errornotify/src/hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Output
+
+Always `{ "continue": true }` — this hook never blocks. It only observes and logs.
+
+## Error Log Format
+
+Errors are written to `.claude/errors.log`:
+
+```
+[2026-02-14T10:30:00.000Z] [session:abc12345] Bash: npm test — Exit code 1: Tests failed
+[2026-02-14T10:31:00.000Z] [session:abc12345] Write: src/index.ts — Error: EACCES permission denied
+```
+
+## License
+
+MIT

package/hooks/hook-errornotify/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-errornotify",
+  "version": "0.1.0",
+  "description": "Claude Code hook that detects tool failures and logs errors",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}

package/hooks/hook-errornotify/src/hook.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: errornotify
+ *
+ * PostToolUse hook that detects tool failures and logs errors.
+ * Checks tool output for error indicators (non-zero exit codes,
+ * error messages) and logs warnings to stderr. Optionally writes
+ * to a .claude/errors.log file for persistent error tracking.
+ *
+ * Never blocks — always outputs { continue: true }.
+ */
+
+import { readFileSync, appendFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_output?: Record<string, unknown>;
+}
+
+interface HookOutput {
+  continue: true;
+}
+
+/**
+ * Read and parse JSON from stdin
+ */
+function readStdinJson(): HookInput | null {
+  try {
+    const input = readFileSync(0, "utf-8").trim();
+    if (!input) return null;
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the tool output indicates a failure
+ */
+function detectError(input: HookInput): { isError: boolean; message: string } {
+  const output = input.tool_output || {};
+
+  // Check for explicit exit code
+  const exitCode = output.exit_code ?? output.exitCode ?? output.code;
+  if (exitCode !== undefined && exitCode !== null && exitCode !== 0) {
+    const stderr = (output.stderr as string) || (output.output as string) || "unknown error";
+    return {
+      isError: true,
+      message: `Exit code ${exitCode}: ${truncate(stderr, 200)}`,
+    };
+  }
+
+  // Check for error field
+  if (output.error && typeof output.error === "string") {
+    return {
+      isError: true,
+      message: `Error: ${truncate(output.error, 200)}`,
+    };
+  }
+
+  // Check output text for common error indicators
+  const outputText =
+    (output.stderr as string) ||
+    (output.output as string) ||
+    (output.content as string) ||
+    (output.text as string) ||
+    "";
+
+  if (typeof outputText === "string" && outputText.length > 0) {
+    // Check for common error patterns in output
+    const errorPatterns = [
+      /^error:/im,
+      /^fatal:/im,
+      /^panic:/im,
+      /command not found/i,
+      /permission denied/i,
+      /no such file or directory/i,
+      /segmentation fault/i,
+      /killed/i,
+      /ENOENT/,
+      /EACCES/,
+      /EPERM/,
+      /ENOMEM/,
+      /TypeError:/,
+      /ReferenceError:/,
+      /SyntaxError:/,
+      /ModuleNotFoundError:/,
+      /ImportError:/,
+      /FileNotFoundError:/,
+      /PermissionError:/,
+      /traceback \(most recent call last\)/i,
+    ];
+
+    for (const pattern of errorPatterns) {
+      if (pattern.test(outputText)) {
+        // Extract the first relevant line
+        const lines = outputText.split("\n").filter((l: string) => l.trim());
+        const errorLine = lines.find((l: string) => pattern.test(l)) || lines[0] || "";
+        return {
+          isError: true,
+          message: truncate(errorLine.trim(), 200),
+        };
+      }
+    }
+  }
+
+  return { isError: false, message: "" };
+}
+
+/**
+ * Truncate a string to a maximum length
+ */
+function truncate(str: string, maxLen: number): string {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen) + "...";
+}
+
+/**
+ * Get a human-readable description of what was being executed
+ */
+function getToolContext(input: HookInput): string {
+  const toolName = input.tool_name;
+  const toolInput = input.tool_input || {};
+
+  switch (toolName) {
+    case "Bash":
+      return `Bash: ${truncate((toolInput.command as string) || "unknown command", 100)}`;
+    case "Write":
+    case "Edit":
+      return `${toolName}: ${(toolInput.file_path as string) || "unknown file"}`;
+    case "Read":
+      return `Read: ${(toolInput.file_path as string) || "unknown file"}`;
+    default:
+      return toolName;
+  }
+}
+
+/**
+ * Write error to .claude/errors.log
+ */
+function writeErrorLog(cwd: string, toolContext: string, errorMessage: string, sessionId: string): void {
+  try {
+    const claudeDir = join(cwd, ".claude");
+    if (!existsSync(claudeDir)) {
+      mkdirSync(claudeDir, { recursive: true });
+    }
+
+    const logFile = join(claudeDir, "errors.log");
+    const timestamp = new Date().toISOString();
+    const entry = `[${timestamp}] [session:${sessionId.slice(0, 8)}] ${toolContext} — ${errorMessage}\n`;
+    appendFileSync(logFile, entry);
+  } catch {
+    // Silently fail — logging should never cause issues
+  }
+}
+
+/**
+ * Output hook response
+ */
+function respond(): void {
+  const output: HookOutput = { continue: true };
+  console.log(JSON.stringify(output));
+}
+
+/**
+ * Main hook execution
+ */
+export function run(): void {
+  const input = readStdinJson();
+
+  if (!input) {
+    respond();
+    return;
+  }
+
+  const { isError, message } = detectError(input);
+
+  if (isError) {
+    const toolContext = getToolContext(input);
+    console.error(`[hook-errornotify] FAILURE in ${toolContext}`);
+    console.error(`[hook-errornotify] ${message}`);
+
+    // Write to persistent error log
+    writeErrorLog(input.cwd, toolContext, message, input.session_id);
+  }
+
+  respond();
+}
+
+if (import.meta.main) {
+  run();
+}