@hasna/hooks 0.0.7 → 0.1.1

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

@@ -0,0 +1,100 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: sessionlog
+ *
+ * PostToolUse hook that logs every tool call to a session log file.
+ * Creates .claude/session-log-<date>.jsonl in the project directory.
+ *
+ * Each line is a JSON object with:
+ * - timestamp: ISO string
+ * - tool_name: name of the tool that was called
+ * - tool_input: first 500 characters of the stringified tool input
+ * - session_id: current session ID
+ */
+
+import { readFileSync, existsSync, mkdirSync, appendFileSync } from "fs";
+import { join } from "path";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+}
+
+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 getDateString(): string {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength) + "...";
+}
+
+function logToolCall(input: HookInput): void {
+  const claudeDir = join(input.cwd, ".claude");
+
+  // Create .claude/ directory if it doesn't exist
+  if (!existsSync(claudeDir)) {
+    mkdirSync(claudeDir, { recursive: true });
+  }
+
+  const dateStr = getDateString();
+  const logFile = join(claudeDir, `session-log-${dateStr}.jsonl`);
+
+  const toolInputStr = truncate(JSON.stringify(input.tool_input), 500);
+
+  const logEntry = {
+    timestamp: new Date().toISOString(),
+    tool_name: input.tool_name,
+    tool_input: toolInputStr,
+    session_id: input.session_id,
+  };
+
+  appendFileSync(logFile, JSON.stringify(logEntry) + "\n");
+}
+
+export function run(): void {
+  const input = readStdinJson();
+
+  if (!input) {
+    respond({ continue: true });
+    return;
+  }
+
+  try {
+    logToolCall(input);
+  } catch (error) {
+    const errMsg = error instanceof Error ? error.message : String(error);
+    console.error(`[hook-sessionlog] Warning: failed to log tool call: ${errMsg}`);
+  }
+
+  respond({ continue: true });
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-slacknotify/README.md

@@ -0,0 +1,62 @@
+# hook-slacknotify
+
+Claude Code hook that sends a Slack webhook notification when Claude Code finishes working.
+
+## Overview
+
+When Claude stops, this hook sends a notification to a configured Slack channel via an incoming webhook URL. Useful for being notified when long-running tasks complete.
+
+## Event
+
+- **Stop** (no matcher)
+
+## Configuration
+
+Configure the webhook URL via one of:
+
+### 1. Environment Variable (preferred)
+
+```bash
+export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/T.../B.../xxx"
+```
+
+### 2. Settings File
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "slackNotifyConfig": {
+    "webhookUrl": "https://hooks.slack.com/services/T.../B.../xxx",
+    "enabled": true
+  }
+}
+```
+
+## Slack Message Format
+
+The hook sends a message with:
+
+```json
+{
+  "text": "Claude Code finished in <project-name>",
+  "blocks": [{
+    "type": "section",
+    "text": {
+      "type": "mrkdwn",
+      "text": "*Claude Code* finished working in `<cwd>`"
+    }
+  }]
+}
+```
+
+## Behavior
+
+- If no webhook URL is configured, logs a warning to stderr and continues
+- If the webhook request fails, logs the error to stderr and continues
+- Never blocks the session from ending
+- Outputs `{ "continue": true }` always
+
+## License
+
+MIT

package/hooks/hook-slacknotify/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-slacknotify",
+  "version": "0.1.0",
+  "description": "Claude Code hook that sends Slack webhook notifications when Claude stops",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}

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

@@ -0,0 +1,146 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: slacknotify
+ *
+ * Stop hook that sends a Slack webhook notification when Claude Code
+ * finishes working in a project.
+ *
+ * Configuration:
+ * - Environment variable: SLACK_WEBHOOK_URL
+ * - Or ~/.claude/settings.json key: slackNotifyConfig.webhookUrl
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  hook_event_name: string;
+  transcript_path?: string;
+}
+
+interface HookOutput {
+  continue: boolean;
+}
+
+interface SlackNotifyConfig {
+  webhookUrl?: string;
+  enabled?: boolean;
+}
+
+const CONFIG_KEY = "slackNotifyConfig";
+
+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 getConfig(): SlackNotifyConfig {
+  // Try global settings
+  const settingsPath = join(homedir(), ".claude", "settings.json");
+  try {
+    if (existsSync(settingsPath)) {
+      const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+      if (settings[CONFIG_KEY]) {
+        return settings[CONFIG_KEY] as SlackNotifyConfig;
+      }
+    }
+  } catch {
+    // Settings file unreadable, fall through
+  }
+  return {};
+}
+
+function getWebhookUrl(): string | null {
+  // Priority 1: environment variable
+  const envUrl = process.env.SLACK_WEBHOOK_URL;
+  if (envUrl) return envUrl;
+
+  // Priority 2: settings.json config
+  const config = getConfig();
+  if (config.webhookUrl) return config.webhookUrl;
+
+  return null;
+}
+
+async function sendSlackNotification(webhookUrl: string, cwd: string): Promise<void> {
+  const projectName = cwd.split("/").filter(Boolean).pop() || cwd;
+
+  const payload = {
+    text: `Claude Code finished in ${projectName}`,
+    blocks: [
+      {
+        type: "section",
+        text: {
+          type: "mrkdwn",
+          text: `*Claude Code* finished working in \`${cwd}\``,
+        },
+      },
+    ],
+  };
+
+  try {
+    const response = await fetch(webhookUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      console.error(
+        `[hook-slacknotify] Slack webhook returned ${response.status}: ${response.statusText}`
+      );
+    }
+  } catch (error) {
+    const errMsg = error instanceof Error ? error.message : String(error);
+    console.error(`[hook-slacknotify] Failed to send Slack notification: ${errMsg}`);
+  }
+}
+
+export async function run(): Promise<void> {
+  const input = readStdinJson();
+
+  if (!input) {
+    respond({ continue: true });
+    return;
+  }
+
+  // Check if hook is explicitly disabled
+  const config = getConfig();
+  if (config.enabled === false) {
+    respond({ continue: true });
+    return;
+  }
+
+  const webhookUrl = getWebhookUrl();
+
+  if (!webhookUrl) {
+    console.error(
+      "[hook-slacknotify] No Slack webhook URL configured. " +
+        "Set SLACK_WEBHOOK_URL env var or add slackNotifyConfig.webhookUrl to ~/.claude/settings.json"
+    );
+    respond({ continue: true });
+    return;
+  }
+
+  await sendSlackNotification(webhookUrl, input.cwd);
+  respond({ continue: true });
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-soundnotify/README.md

@@ -0,0 +1,63 @@
+# hook-soundnotify
+
+Claude Code hook that plays a sound when Claude finishes a session.
+
+## Event
+
+**Stop** — fires when Claude's session ends.
+
+## What It Does
+
+Plays a system sound to notify you that Claude has finished working. Useful when you tab away and want an audible alert.
+
+### Platform Support
+
+| Platform | Player | Default Sound |
+|----------|--------|---------------|
+| macOS | `afplay` | `/System/Library/Sounds/Glass.aiff` |
+| Linux | `paplay` / `aplay` | `/usr/share/sounds/freedesktop/stereo/complete.oga` |
+
+### Configuration
+
+Set `HOOKS_SOUND_FILE` environment variable to use a custom sound:
+
+```bash
+export HOOKS_SOUND_FILE="/path/to/your/sound.wav"
+```
+
+## Installation
+
+Add to your `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run hooks/hook-soundnotify/src/hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Output
+
+Always `{ "continue": true }` — sound plays asynchronously (fire-and-forget) and never blocks session exit.
+
+## How It Works
+
+1. Looks for a sound file (env var > platform default)
+2. Spawns the audio player as a detached child process
+3. Immediately returns without waiting for playback to finish
+4. The sound plays in the background after Claude exits
+
+## License
+
+MIT

package/hooks/hook-soundnotify/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-soundnotify",
+  "version": "0.1.0",
+  "description": "Claude Code hook that plays a sound when Claude finishes",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: soundnotify
+ *
+ * Stop hook that plays a system sound when Claude finishes a session.
+ *
+ * Platform support:
+ * - macOS: afplay (built-in)
+ * - Linux: paplay (PulseAudio) or aplay (ALSA) fallback
+ *
+ * Configuration:
+ * - HOOKS_SOUND_FILE env var: path to a custom sound file
+ *
+ * Runs async (fire-and-forget) — does not block session exit.
+ * Always outputs { continue: true }.
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { spawn } from "child_process";
+import { platform } from "os";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+}
+
+interface HookOutput {
+  continue: true;
+}
+
+/**
+ * Default sound files per platform
+ */
+const DEFAULT_SOUNDS: Record<string, string> = {
+  darwin: "/System/Library/Sounds/Glass.aiff",
+  linux: "/usr/share/sounds/freedesktop/stereo/complete.oga",
+};
+
+/**
+ * Fallback sound files for Linux
+ */
+const LINUX_FALLBACK_SOUNDS: string[] = [
+  "/usr/share/sounds/freedesktop/stereo/complete.oga",
+  "/usr/share/sounds/freedesktop/stereo/bell.oga",
+  "/usr/share/sounds/freedesktop/stereo/message.oga",
+];
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * Find an available sound file
+ */
+function findSoundFile(): string | null {
+  // Check env var first
+  const envSound = process.env.HOOKS_SOUND_FILE;
+  if (envSound && existsSync(envSound)) {
+    return envSound;
+  }
+
+  const os = platform();
+
+  if (os === "darwin") {
+    const defaultSound = DEFAULT_SOUNDS.darwin;
+    if (existsSync(defaultSound)) {
+      return defaultSound;
+    }
+    return null;
+  }
+
+  if (os === "linux") {
+    for (const sound of LINUX_FALLBACK_SOUNDS) {
+      if (existsSync(sound)) {
+        return sound;
+      }
+    }
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Get the appropriate audio player command for the current platform
+ */
+function getPlayerCommand(soundFile: string): { cmd: string; args: string[] } | null {
+  const os = platform();
+
+  if (os === "darwin") {
+    return { cmd: "afplay", args: [soundFile] };
+  }
+
+  if (os === "linux") {
+    // Prefer paplay for PulseAudio, fallback to aplay for ALSA
+    if (soundFile.endsWith(".oga") || soundFile.endsWith(".ogg")) {
+      return { cmd: "paplay", args: [soundFile] };
+    }
+    return { cmd: "aplay", args: [soundFile] };
+  }
+
+  return null;
+}
+
+/**
+ * Play the sound asynchronously (fire-and-forget)
+ */
+function playSound(soundFile: string): void {
+  const player = getPlayerCommand(soundFile);
+  if (!player) {
+    console.error(`[hook-soundnotify] No audio player available for ${platform()}`);
+    return;
+  }
+
+  try {
+    const child = spawn(player.cmd, player.args, {
+      stdio: "ignore",
+      detached: true,
+    });
+
+    // Unref so the process doesn't keep the parent alive
+    child.unref();
+
+    console.error(`[hook-soundnotify] Playing: ${soundFile}`);
+  } catch (error) {
+    const errMsg = error instanceof Error ? error.message : String(error);
+    console.error(`[hook-soundnotify] Failed to play sound: ${errMsg}`);
+  }
+}
+
+/**
+ * Output hook response
+ */
+function respond(): void {
+  const output: HookOutput = { continue: true };
+  console.log(JSON.stringify(output));
+}
+
+/**
+ * Main hook execution
+ */
+export function run(): void {
+  // Read stdin (we don't really need the input, but follow the protocol)
+  readStdinJson();
+
+  const soundFile = findSoundFile();
+
+  if (!soundFile) {
+    console.error("[hook-soundnotify] No sound file found, skipping");
+    respond();
+    return;
+  }
+
+  // Fire-and-forget — play sound async
+  playSound(soundFile);
+
+  // Always continue
+  respond();
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-taskgate/README.md

@@ -0,0 +1,62 @@
+# hook-taskgate
+
+Claude Code hook that validates task completion before allowing a task to be marked done.
+
+## Event
+
+**TaskCompleted** — fires when Claude attempts to mark a task as complete.
+
+## What It Does
+
+A lightweight gate that checks whether a task is actually done:
+
+- **Task mentions "test" or "tests"** — verifies that test files exist in the project (looks for `*.test.*`, `*.spec.*`, `test_*`, `*_test.*`, or `test/`/`tests/`/`__tests__/` directories)
+- **Task mentions "lint" or "format"** — approves (cannot verify externally)
+- **All other tasks** — approves by default
+
+This hook is designed as a starting point. Extend the validation logic in `src/hook.ts` for your own project needs.
+
+## Installation
+
+Add to your `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "TaskCompleted": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run hooks/hook-taskgate/src/hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Output
+
+- `{ "decision": "approve" }` — task passes validation
+- `{ "decision": "block", "reason": "..." }` — task fails validation, provides reason
+
+## Extending
+
+To add custom validation, edit `src/hook.ts` and add checks in the `run()` function before the default approve. For example:
+
+```typescript
+// Block tasks mentioning "deploy" unless a deploy script exists
+if (/\bdeploy\b/.test(description)) {
+  if (!existsSync(join(cwd, "deploy.sh"))) {
+    respond({ decision: "block", reason: "No deploy.sh found" });
+    return;
+  }
+}
+```
+
+## License
+
+MIT

package/hooks/hook-taskgate/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-taskgate",
+  "version": "0.1.0",
+  "description": "Claude Code hook that validates task completion before marking done",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}