@hasna/hooks 0.0.7 → 0.1.0

package/hooks/hook-autostage/README.md

@@ -0,0 +1,70 @@
+# hook-autostage
+
+Claude Code hook that automatically stages files after Claude edits or writes them.
+
+## Event
+
+**PostToolUse** (matcher: `Edit|Write`)
+
+## What It Does
+
+After Claude modifies a file via `Edit` or `Write`, this hook automatically runs `git add <file>` to stage the change. This keeps your git staging area in sync with Claude's edits without manual intervention.
+
+### Safety Checks
+
+Before staging, the hook verifies:
+
+1. **Git repo exists** — checks that `cwd` is inside a git repository
+2. **File exists** — confirms the file was actually created/modified
+3. **Not gitignored** — runs `git check-ignore` to skip ignored files
+
+### What Gets Staged
+
+- Files modified by Claude's `Edit` tool
+- Files created/written by Claude's `Write` tool
+
+### What Does NOT Get Staged
+
+- Files in `.gitignore` (e.g., `node_modules/`, `.env`, `dist/`)
+- Files outside git repositories
+- Files from other tools (Bash, Read, etc.)
+
+## Installation
+
+Add to your `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run hooks/hook-autostage/src/hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Output
+
+Always `{ "continue": true }` — this hook never blocks.
+
+## Logs
+
+Activity is logged to stderr:
+
+```
+[hook-autostage] Staged: src/index.ts
+[hook-autostage] File is gitignored, skipping: dist/bundle.js
+[hook-autostage] Not a git repo, skipping
+```
+
+## License
+
+MIT

package/hooks/hook-autostage/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-autostage",
+  "version": "0.1.0",
+  "description": "Claude Code hook that auto-stages files after Claude edits them",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}

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

@@ -0,0 +1,167 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: autostage
+ *
+ * PostToolUse hook that automatically runs `git add <file>` after
+ * Claude edits or writes a file. Only stages if:
+ * - The project is a git repo (.git directory exists)
+ * - The file is not in .gitignore
+ *
+ * Matcher: Edit|Write
+ * Always outputs { continue: true } — never blocks.
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { execSync } from "child_process";
+import { join, resolve } from "path";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  tool_name: string;
+  tool_input: 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 a directory is inside a git repository
+ */
+function isGitRepo(cwd: string): boolean {
+  try {
+    execSync("git rev-parse --is-inside-work-tree", {
+      cwd,
+      stdio: "pipe",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a file is ignored by .gitignore
+ */
+function isGitIgnored(cwd: string, filePath: string): boolean {
+  try {
+    // git check-ignore exits 0 if file IS ignored, 1 if NOT ignored
+    execSync(`git check-ignore -q "${filePath}"`, {
+      cwd,
+      stdio: "pipe",
+    });
+    return true; // Exit 0 → file is ignored
+  } catch {
+    return false; // Exit 1 → file is NOT ignored
+  }
+}
+
+/**
+ * Stage a file with git add
+ */
+function stageFile(cwd: string, filePath: string): boolean {
+  try {
+    execSync(`git add "${filePath}"`, {
+      cwd,
+      stdio: "pipe",
+    });
+    return true;
+  } catch (error) {
+    const errMsg = error instanceof Error ? error.message : String(error);
+    console.error(`[hook-autostage] Failed to stage ${filePath}: ${errMsg}`);
+    return false;
+  }
+}
+
+/**
+ * Extract file path from tool input
+ */
+function getFilePath(toolInput: Record<string, unknown>): string | null {
+  return (toolInput.file_path as string) || null;
+}
+
+/**
+ * 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;
+  }
+
+  // Only handle Edit and Write tools
+  if (input.tool_name !== "Edit" && input.tool_name !== "Write") {
+    respond();
+    return;
+  }
+
+  const filePath = getFilePath(input.tool_input || {});
+
+  if (!filePath) {
+    console.error("[hook-autostage] No file_path found in tool_input");
+    respond();
+    return;
+  }
+
+  const cwd = input.cwd;
+
+  // Check if this is a git repo
+  if (!isGitRepo(cwd)) {
+    console.error("[hook-autostage] Not a git repo, skipping");
+    respond();
+    return;
+  }
+
+  // Resolve the file path relative to cwd
+  const absPath = resolve(cwd, filePath);
+
+  // Check if file exists
+  if (!existsSync(absPath)) {
+    console.error(`[hook-autostage] File does not exist: ${filePath}`);
+    respond();
+    return;
+  }
+
+  // Check if file is gitignored
+  if (isGitIgnored(cwd, filePath)) {
+    console.error(`[hook-autostage] File is gitignored, skipping: ${filePath}`);
+    respond();
+    return;
+  }
+
+  // Stage the file
+  if (stageFile(cwd, filePath)) {
+    console.error(`[hook-autostage] Staged: ${filePath}`);
+  }
+
+  respond();
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-commandlog/README.md

@@ -0,0 +1,45 @@
+# hook-commandlog
+
+Claude Code hook that logs every bash command Claude runs to a log file.
+
+## Overview
+
+Every time Claude executes a Bash command, this hook appends it to `.claude/commands.log` in the project directory. Provides a clear audit trail of all shell commands run during a session.
+
+## Event
+
+- **PostToolUse** (matcher: `Bash`)
+
+## Log Format
+
+Each line in the log file:
+
+```
+[2026-02-14T10:30:00.000Z] exit=0 npm install express
+[2026-02-14T10:30:05.000Z] exit=0 git status
+[2026-02-14T10:30:10.000Z] ls -la src/
+```
+
+- ISO 8601 timestamp in brackets
+- Exit code (if available in tool input)
+- The full command string
+
+## Behavior
+
+- Only logs `Bash` tool calls (other tools are ignored)
+- Creates `.claude/` directory if it does not exist
+- Appends to the log file (never overwrites)
+- Non-blocking: logging failures are logged to stderr but never interrupt Claude
+- Outputs `{ "continue": true }` always
+
+## Log Location
+
+```
+<project-root>/
+└── .claude/
+    └── commands.log
+```
+
+## License
+
+MIT

package/hooks/hook-commandlog/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-commandlog",
+  "version": "0.1.0",
+  "description": "Claude Code hook that logs every bash command Claude runs to a log file",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}

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

@@ -0,0 +1,92 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: commandlog
+ *
+ * PostToolUse hook that logs every bash command Claude runs to
+ * .claude/commands.log in the project directory.
+ *
+ * Format: [ISO timestamp] <exit_code> <command>
+ * One command per line.
+ */
+
+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 logCommand(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 logFile = join(claudeDir, "commands.log");
+  const timestamp = new Date().toISOString();
+  const command = (input.tool_input.command as string) || "(unknown command)";
+  const exitCode = input.tool_input.exit_code;
+
+  // Format: [timestamp] exit_code command
+  // If exit_code is available, include it; otherwise just log the command
+  let logLine: string;
+  if (exitCode !== undefined && exitCode !== null) {
+    logLine = `[${timestamp}] exit=${exitCode} ${command}\n`;
+  } else {
+    logLine = `[${timestamp}] ${command}\n`;
+  }
+
+  appendFileSync(logFile, logLine);
+}
+
+export function run(): void {
+  const input = readStdinJson();
+
+  if (!input) {
+    respond({ continue: true });
+    return;
+  }
+
+  // Only log Bash tool calls
+  if (input.tool_name !== "Bash") {
+    respond({ continue: true });
+    return;
+  }
+
+  try {
+    logCommand(input);
+  } catch (error) {
+    const errMsg = error instanceof Error ? error.message : String(error);
+    console.error(`[hook-commandlog] Warning: failed to log command: ${errMsg}`);
+  }
+
+  respond({ continue: true });
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-costwatch/README.md

@@ -0,0 +1,61 @@
+# hook-costwatch
+
+Claude Code hook that estimates session token usage and warns if a budget threshold is exceeded.
+
+## Overview
+
+When Claude stops, this hook attempts to estimate the session's token usage by examining the transcript file size. If a budget is configured and the estimated cost exceeds it, a warning is logged to stderr.
+
+## Event
+
+- **Stop** (no matcher)
+
+## Configuration
+
+### Budget (optional)
+
+Set a per-session budget via environment variable:
+
+```bash
+export COST_WATCH_BUDGET="5.00"  # Max $5.00 per session
+```
+
+If not set, the hook runs without budget enforcement and simply logs a reminder to check usage.
+
+## Cost Estimation
+
+The estimation is intentionally rough:
+
+- **~4 characters per token** (average for English text)
+- **~$30 per million tokens** (blended input/output estimate)
+- Based on transcript file size, not actual API usage
+
+This is a ballpark estimate. Always check actual usage at [console.anthropic.com](https://console.anthropic.com/).
+
+## Behavior
+
+- Reads the session transcript and estimates total tokens from file size
+- If `COST_WATCH_BUDGET` is set and estimated cost exceeds it, logs a WARNING to stderr
+- If no transcript is found, logs that cost could not be estimated
+- Never blocks the session from ending
+- Outputs `{ "continue": true }` always
+
+## Example Output
+
+```
+[hook-costwatch] Session estimate: ~125.0K tokens, ~$3.75
+[hook-costwatch] Budget: $5.00/session. Remember to check actual usage.
+```
+
+With budget exceeded:
+
+```
+[hook-costwatch] Session estimate: ~250.0K tokens, ~$7.50
+[hook-costwatch] WARNING: Estimated cost ($7.50) exceeds budget ($5.00)!
+[hook-costwatch] Check your actual usage at https://console.anthropic.com/
+[hook-costwatch] Budget: $5.00/session. Remember to check actual usage.
+```
+
+## License
+
+MIT

package/hooks/hook-costwatch/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-costwatch",
+  "version": "0.1.0",
+  "description": "Claude Code hook that estimates session cost and warns if budget is exceeded",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}

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

@@ -0,0 +1,178 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: costwatch
+ *
+ * Stop hook that estimates session token usage and warns if a budget
+ * threshold is exceeded.
+ *
+ * Configuration:
+ * - Environment variable: COST_WATCH_BUDGET (max $ per session, e.g. "5.00")
+ * - If not set, no budget enforcement (just logs a reminder)
+ *
+ * Token estimation is rough:
+ * - ~4 characters per token (English text average)
+ * - Claude Opus pricing: ~$15/M input tokens, ~$75/M output tokens
+ * - We estimate a blended rate of ~$30/M tokens for simplicity
+ *
+ * Since the Stop event provides limited session info, this hook
+ * primarily serves as a reminder to check actual usage.
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  hook_event_name: string;
+  transcript_path?: string;
+}
+
+interface HookOutput {
+  continue: boolean;
+}
+
+/** Approximate cost per million tokens (blended input/output estimate) */
+const BLENDED_COST_PER_MILLION_TOKENS = 30;
+
+/** Average characters per token */
+const CHARS_PER_TOKEN = 4;
+
+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 getBudget(): number | null {
+  const budgetStr = process.env.COST_WATCH_BUDGET;
+  if (!budgetStr) return null;
+
+  const budget = parseFloat(budgetStr);
+  if (isNaN(budget) || budget <= 0) {
+    console.error(
+      `[hook-costwatch] Invalid COST_WATCH_BUDGET value: "${budgetStr}". Must be a positive number.`
+    );
+    return null;
+  }
+  return budget;
+}
+
+function estimateTranscriptCost(transcriptPath: string): {
+  charCount: number;
+  estimatedTokens: number;
+  estimatedCost: number;
+} | null {
+  try {
+    if (!existsSync(transcriptPath)) return null;
+
+    const stat = statSync(transcriptPath);
+    const charCount = stat.size;
+    const estimatedTokens = Math.ceil(charCount / CHARS_PER_TOKEN);
+    const estimatedCost = (estimatedTokens / 1_000_000) * BLENDED_COST_PER_MILLION_TOKENS;
+
+    return { charCount, estimatedTokens, estimatedCost };
+  } catch {
+    return null;
+  }
+}
+
+function findSessionTranscript(cwd: string, sessionId: string): string | null {
+  // Check common transcript locations
+  const possibleDirs = [
+    join(cwd, ".claude"),
+    join(process.env.HOME || "", ".claude", "projects"),
+  ];
+
+  for (const dir of possibleDirs) {
+    if (!existsSync(dir)) continue;
+    try {
+      const files = readdirSync(dir, { recursive: true }) as string[];
+      for (const file of files) {
+        const filePath = join(dir, file);
+        if (typeof file === "string" && file.includes(sessionId)) {
+          return filePath;
+        }
+      }
+    } catch {
+      // Directory not readable, skip
+    }
+  }
+
+  return null;
+}
+
+export function run(): void {
+  const input = readStdinJson();
+
+  if (!input) {
+    respond({ continue: true });
+    return;
+  }
+
+  const budget = getBudget();
+
+  // Try to estimate cost from transcript
+  let estimate: {
+    charCount: number;
+    estimatedTokens: number;
+    estimatedCost: number;
+  } | null = null;
+
+  if (input.transcript_path) {
+    estimate = estimateTranscriptCost(input.transcript_path);
+  }
+
+  if (!estimate) {
+    // Try to find transcript by session ID
+    const transcriptPath = findSessionTranscript(input.cwd, input.session_id);
+    if (transcriptPath) {
+      estimate = estimateTranscriptCost(transcriptPath);
+    }
+  }
+
+  if (estimate) {
+    const costStr = estimate.estimatedCost.toFixed(2);
+    const tokensStr = (estimate.estimatedTokens / 1000).toFixed(1);
+
+    console.error(`[hook-costwatch] Session estimate: ~${tokensStr}K tokens, ~$${costStr}`);
+
+    if (budget !== null && estimate.estimatedCost > budget) {
+      console.error(
+        `[hook-costwatch] WARNING: Estimated cost ($${costStr}) exceeds budget ($${budget.toFixed(2)})!`
+      );
+      console.error(
+        `[hook-costwatch] Check your actual usage at https://console.anthropic.com/`
+      );
+    }
+  } else {
+    console.error(
+      `[hook-costwatch] Could not estimate session cost (no transcript found).`
+    );
+  }
+
+  if (budget !== null) {
+    console.error(
+      `[hook-costwatch] Budget: $${budget.toFixed(2)}/session. Remember to check actual usage.`
+    );
+  } else {
+    console.error(
+      `[hook-costwatch] No budget set. Set COST_WATCH_BUDGET env var to enable budget warnings.`
+    );
+  }
+
+  respond({ continue: true });
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-desktopnotify/README.md

@@ -0,0 +1,50 @@
+# hook-desktopnotify
+
+Claude Code hook that sends native desktop notifications when Claude stops.
+
+## Overview
+
+Get notified immediately when Claude finishes a task. Uses your OS's native notification system — no external services or accounts needed.
+
+## Platform Support
+
+| Platform | Method | Requirements |
+|----------|--------|--------------|
+| macOS | `osascript` (display notification) | None (built-in) |
+| Linux | `notify-send` | `libnotify` package |
+
+## Hook Event
+
+- **Stop** (no matcher)
+
+## Behavior
+
+1. Fires when Claude stops and waits for input
+2. Detects the current platform (`process.platform`)
+3. Sends a native notification with the project name
+4. Plays a sound on macOS (Glass)
+5. Outputs `{ continue: true }`
+
+## Notification Content
+
+- **Title**: "Claude Code — Done"
+- **Body**: "Claude has finished working on {project} and is waiting for your input."
+
+## Linux Setup
+
+If `notify-send` is not installed:
+
+```bash
+# Ubuntu/Debian
+sudo apt install libnotify-bin
+
+# Fedora
+sudo dnf install libnotify
+
+# Arch
+sudo pacman -S libnotify
+```
+
+## License
+
+MIT