@hasnaxyz/hook-checktasks 0.1.1

package/README.md

@@ -0,0 +1,152 @@
+# @hasnaxyz/hook-checktasks
+
+A Claude Code hook that prevents Claude from stopping when there are pending tasks in your task list.
+
+## What it does
+
+When you have a task list configured (`CLAUDE_CODE_TASK_LIST_ID`), this hook:
+
+1. Checks if the session name or task list ID contains "dev" (configurable)
+2. Reads the task list from `~/.claude/tasks/{taskListId}/`
+3. If there are pending or in-progress tasks, **blocks the stop** and prompts Claude to continue working
+4. Only allows stopping when all tasks are completed
+
+This ensures Claude doesn't abandon work mid-session.
+
+## Installation
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) runtime installed
+- Access to `@hasnaxyz` npm organization
+
+### Quick Install
+
+```bash
+# Install globally (applies to all Claude Code sessions)
+bunx @hasnaxyz/hook-checktasks install --global
+
+# Install for current project only
+bunx @hasnaxyz/hook-checktasks install
+```
+
+### Check Installation Status
+
+```bash
+bunx @hasnaxyz/hook-checktasks status
+```
+
+### Uninstall
+
+```bash
+# Remove from global settings
+bunx @hasnaxyz/hook-checktasks uninstall --global
+
+# Remove from current project
+bunx @hasnaxyz/hook-checktasks uninstall
+```
+
+## Configuration
+
+Configure via environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLAUDE_CODE_TASK_LIST_ID` | Task list to monitor (required for task checking) | - |
+| `CHECK_TASKS_KEYWORDS` | Comma-separated keywords that trigger the check | `dev` |
+| `CHECK_TASKS_DISABLED` | Set to `1` to disable the hook | - |
+
+### Examples
+
+```bash
+# Standard usage with dev task list
+CLAUDE_CODE_TASK_LIST_ID=myproject-dev claude
+
+# Check for "dev" or "sprint" sessions
+CHECK_TASKS_KEYWORDS=dev,sprint CLAUDE_CODE_TASK_LIST_ID=myproject-dev claude
+
+# Temporarily disable the hook
+CHECK_TASKS_DISABLED=1 claude
+```
+
+## How it works
+
+1. **On Stop hook trigger**: Claude is about to stop/exit
+2. **Check session name**: Reads the session name from transcript (if available)
+3. **Keyword matching**: Checks if session name or task list ID contains configured keywords
+4. **Task count**: Reads task files from `~/.claude/tasks/{taskListId}/`
+5. **Decision**:
+   - If tasks remain: Block stop with instructions to continue
+   - If all complete: Allow stop
+
+## What Gets Added to settings.json
+
+The install command adds this to your Claude Code settings:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bunx @hasnaxyz/hook-checktasks run",
+            "timeout": 120
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Task File Format
+
+Tasks are stored as JSON files in `~/.claude/tasks/{taskListId}/`:
+
+```json
+{
+  "id": "task-001",
+  "subject": "Implement user authentication",
+  "status": "pending"
+}
+```
+
+Status values: `pending`, `in_progress`, `completed`
+
+## CLI Commands
+
+```
+bunx @hasnaxyz/hook-checktasks <command> [options]
+
+Commands:
+  install [--global]   Install the hook to Claude Code settings
+  uninstall [--global] Remove the hook from Claude Code settings
+  run                  Execute the hook (called by Claude Code automatically)
+  status               Show current hook configuration
+
+Options:
+  --global, -g         Apply to global settings (~/.claude/settings.json)
+```
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/hasnaxyz/hook-checktasks.git
+cd hook-checktasks
+
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# Test locally
+bun ./dist/cli.js status
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,394 @@
+#!/usr/bin/env bun
+// @bun
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/hook.ts
+var exports_hook = {};
+__export(exports_hook, {
+  run: () => run
+});
+import { readdirSync, readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+function readStdinJson() {
+  try {
+    const stdin = readFileSync(0, "utf-8");
+    return JSON.parse(stdin);
+  } catch {
+    return null;
+  }
+}
+function getSessionName(transcriptPath) {
+  if (!existsSync(transcriptPath))
+    return null;
+  try {
+    const content = readFileSync(transcriptPath, "utf-8");
+    let lastTitle = null;
+    let searchStart = 0;
+    while (true) {
+      const titleIndex = content.indexOf('"custom-title"', searchStart);
+      if (titleIndex === -1)
+        break;
+      const lineStart = content.lastIndexOf(`
+`, titleIndex) + 1;
+      const lineEnd = content.indexOf(`
+`, titleIndex);
+      const line = content.slice(lineStart, lineEnd === -1 ? undefined : lineEnd);
+      try {
+        const entry = JSON.parse(line);
+        if (entry.type === "custom-title" && entry.customTitle) {
+          lastTitle = entry.customTitle;
+        }
+      } catch {}
+      searchStart = titleIndex + 1;
+    }
+    return lastTitle;
+  } catch {
+    return null;
+  }
+}
+function approve() {
+  console.log(JSON.stringify({ decision: "approve" }));
+  process.exit(0);
+}
+function block(reason) {
+  console.log(JSON.stringify({ decision: "block", reason }));
+  process.exit(0);
+}
+function run() {
+  if (process.env.CHECK_TASKS_DISABLED === "1") {
+    approve();
+  }
+  const taskListId = process.env.CLAUDE_CODE_TASK_LIST_ID;
+  if (!taskListId) {
+    approve();
+  }
+  const hookInput = readStdinJson();
+  let sessionName = null;
+  if (hookInput?.transcript_path) {
+    sessionName = getSessionName(hookInput.transcript_path);
+  }
+  const nameToCheck = sessionName || taskListId || "";
+  const keywords = (process.env.CHECK_TASKS_KEYWORDS || "dev").split(",").map((k) => k.trim().toLowerCase()).filter(Boolean);
+  const matchesKeyword = keywords.some((keyword) => nameToCheck.toLowerCase().includes(keyword));
+  if (!matchesKeyword) {
+    approve();
+  }
+  const tasksDir = join(homedir(), ".claude", "tasks", taskListId);
+  if (!existsSync(tasksDir)) {
+    approve();
+  }
+  const taskFiles = readdirSync(tasksDir).filter((f) => f.endsWith(".json"));
+  if (taskFiles.length === 0) {
+    approve();
+  }
+  const tasks = taskFiles.map((file) => {
+    const content = readFileSync(join(tasksDir, file), "utf-8");
+    return JSON.parse(content);
+  });
+  const pending = tasks.filter((t) => t.status === "pending");
+  const inProgress = tasks.filter((t) => t.status === "in_progress");
+  const completed = tasks.filter((t) => t.status === "completed");
+  const remainingCount = pending.length + inProgress.length;
+  if (remainingCount > 0) {
+    const nextTasks = pending.slice(0, 3).map((t) => `- ${t.subject}`).join(`
+`);
+    const prompt = `
+STOP BLOCKED: You have ${remainingCount} tasks remaining (${pending.length} pending, ${inProgress.length} in progress, ${completed.length} completed).
+
+You MUST continue working. Do NOT stop until all tasks are completed.
+
+Next pending tasks:
+${nextTasks}
+${pending.length > 3 ? `... and ${pending.length - 3} more pending tasks` : ""}
+
+INSTRUCTIONS:
+1. Use TaskList to see all tasks
+2. Pick the next pending task
+3. Use TaskUpdate to mark it as in_progress
+4. Complete the task
+5. Use TaskUpdate to mark it as completed
+6. Repeat until all tasks are done
+
+DO NOT STOP. Continue working now.
+`.trim();
+    block(prompt);
+  }
+  approve();
+}
+var init_hook = __esm(() => {
+  if (false) {}
+});
+
+// src/cli.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync, mkdirSync } from "fs";
+import { join as join2, dirname, resolve } from "path";
+import { homedir as homedir2 } from "os";
+import * as readline from "readline";
+var PACKAGE_NAME = "@hasnaxyz/hook-checktasks";
+var c = {
+  red: (s) => `\x1B[31m${s}\x1B[0m`,
+  green: (s) => `\x1B[32m${s}\x1B[0m`,
+  yellow: (s) => `\x1B[33m${s}\x1B[0m`,
+  cyan: (s) => `\x1B[36m${s}\x1B[0m`,
+  dim: (s) => `\x1B[2m${s}\x1B[0m`,
+  bold: (s) => `\x1B[1m${s}\x1B[0m`
+};
+function printUsage() {
+  console.log(`
+${c.bold("hook-checktasks")} - Prevents Claude from stopping with pending tasks
+
+${c.bold("USAGE:")}
+  hook-checktasks install [path]     Install the hook
+  hook-checktasks uninstall [path]   Remove the hook
+  hook-checktasks status             Show hook status
+  hook-checktasks run                Execute hook ${c.dim("(called by Claude Code)")}
+
+${c.bold("INSTALL OPTIONS:")}
+  ${c.dim("(no args)")}      Auto-detect: if in git repo \u2192 install there, else \u2192 prompt
+  --global, -g   Install to ~/.claude/settings.json
+  /path/to/repo  Install to specific project path
+
+${c.bold("EXAMPLES:")}
+  hook-checktasks install              ${c.dim("# Smart install")}
+  hook-checktasks install --global     ${c.dim("# Global install")}
+  hook-checktasks install ~/my-project ${c.dim("# Specific project")}
+  hook-checktasks status               ${c.dim("# Check what's installed")}
+
+${c.bold("GLOBAL INSTALL:")} ${c.dim("(to use without bunx)")}
+  bun add -g ${PACKAGE_NAME}
+`);
+}
+function isGitRepo(path) {
+  return existsSync2(join2(path, ".git"));
+}
+function getSettingsPath(targetPath) {
+  if (targetPath === "global") {
+    return join2(homedir2(), ".claude", "settings.json");
+  }
+  return join2(targetPath, ".claude", "settings.json");
+}
+function readSettings(path) {
+  if (!existsSync2(path))
+    return {};
+  try {
+    return JSON.parse(readFileSync2(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function writeSettings(path, settings) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(settings, null, 2) + `
+`);
+}
+function getHookCommand() {
+  return `bunx ${PACKAGE_NAME} run`;
+}
+function hookExists(settings) {
+  const hooks = settings.hooks;
+  if (!hooks?.Stop)
+    return false;
+  const stopHooks = hooks.Stop;
+  return stopHooks.some((group) => group.hooks?.some((h) => h.command?.includes(PACKAGE_NAME)));
+}
+function addHook(settings) {
+  const hookConfig = {
+    type: "command",
+    command: getHookCommand(),
+    timeout: 120
+  };
+  if (!settings.hooks)
+    settings.hooks = {};
+  const hooks = settings.hooks;
+  if (!hooks.Stop) {
+    hooks.Stop = [{ hooks: [hookConfig] }];
+  } else {
+    const stopHooks = hooks.Stop;
+    if (stopHooks[0]?.hooks) {
+      stopHooks[0].hooks.push(hookConfig);
+    } else {
+      stopHooks.push({ hooks: [hookConfig] });
+    }
+  }
+  return settings;
+}
+function removeHook(settings) {
+  const hooks = settings.hooks;
+  if (!hooks?.Stop)
+    return settings;
+  const stopHooks = hooks.Stop;
+  for (const group of stopHooks) {
+    if (group.hooks) {
+      group.hooks = group.hooks.filter((h) => !h.command?.includes(PACKAGE_NAME));
+    }
+  }
+  hooks.Stop = stopHooks.filter((g) => g.hooks && g.hooks.length > 0);
+  if (hooks.Stop.length === 0)
+    delete hooks.Stop;
+  return settings;
+}
+async function prompt(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve2) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve2(answer.trim());
+    });
+  });
+}
+async function resolveTarget(args) {
+  if (args.includes("--global") || args.includes("-g")) {
+    return { path: "global", label: "global (~/.claude/settings.json)" };
+  }
+  const pathArg = args.find((a) => !a.startsWith("-"));
+  if (pathArg) {
+    const fullPath = resolve(pathArg);
+    if (!existsSync2(fullPath)) {
+      console.log(c.red("\u2717"), `Path does not exist: ${fullPath}`);
+      return null;
+    }
+    return { path: fullPath, label: `project (${fullPath})` };
+  }
+  const cwd = process.cwd();
+  if (isGitRepo(cwd)) {
+    console.log(c.green("\u2713"), `Detected git repo: ${c.cyan(cwd)}`);
+    return { path: cwd, label: `project (${cwd})` };
+  }
+  console.log(c.yellow("!"), `Not in a git repository
+`);
+  console.log(`Where would you like to install?
+`);
+  console.log("  1. Global", c.dim("(~/.claude/settings.json)"));
+  console.log(`  2. Enter a path
+`);
+  const choice = await prompt("Choice (1/2): ");
+  if (choice === "1") {
+    return { path: "global", label: "global (~/.claude/settings.json)" };
+  } else if (choice === "2") {
+    const inputPath = await prompt("Path: ");
+    if (!inputPath) {
+      console.log(c.red("\u2717"), "No path provided");
+      return null;
+    }
+    const fullPath = resolve(inputPath);
+    if (!existsSync2(fullPath)) {
+      console.log(c.red("\u2717"), `Path does not exist: ${fullPath}`);
+      return null;
+    }
+    return { path: fullPath, label: `project (${fullPath})` };
+  } else {
+    console.log(c.red("\u2717"), "Invalid choice");
+    return null;
+  }
+}
+async function install(args) {
+  console.log(`
+${c.bold("hook-checktasks install")}
+`);
+  const target = await resolveTarget(args);
+  if (!target)
+    return;
+  const settingsPath = getSettingsPath(target.path);
+  const settings = readSettings(settingsPath);
+  if (hookExists(settings)) {
+    console.log(c.yellow("!"), `Already installed in ${target.label}`);
+    return;
+  }
+  const updated = addHook(settings);
+  writeSettings(settingsPath, updated);
+  console.log(c.green("\u2713"), `Installed to ${target.label}
+`);
+  console.log(c.bold("Usage:"));
+  console.log(`  CLAUDE_CODE_TASK_LIST_ID=myproject-dev claude
+`);
+}
+async function uninstall(args) {
+  console.log(`
+${c.bold("hook-checktasks uninstall")}
+`);
+  const target = await resolveTarget(args);
+  if (!target)
+    return;
+  const settingsPath = getSettingsPath(target.path);
+  if (!existsSync2(settingsPath)) {
+    console.log(c.yellow("!"), `No settings file at ${settingsPath}`);
+    return;
+  }
+  const settings = readSettings(settingsPath);
+  if (!hookExists(settings)) {
+    console.log(c.yellow("!"), `Hook not found in ${target.label}`);
+    return;
+  }
+  const updated = removeHook(settings);
+  writeSettings(settingsPath, updated);
+  console.log(c.green("\u2713"), `Removed from ${target.label}`);
+}
+function status() {
+  console.log(`
+${c.bold("hook-checktasks status")}
+`);
+  const globalPath = getSettingsPath("global");
+  const globalSettings = readSettings(globalPath);
+  const globalInstalled = hookExists(globalSettings);
+  console.log(globalInstalled ? c.green("\u2713") : c.red("\u2717"), "Global:", globalInstalled ? "Installed" : "Not installed", c.dim(`(${globalPath})`));
+  const cwd = process.cwd();
+  const projectPath = getSettingsPath(cwd);
+  if (isGitRepo(cwd)) {
+    const projectSettings = readSettings(projectPath);
+    const projectInstalled = hookExists(projectSettings);
+    console.log(projectInstalled ? c.green("\u2713") : c.red("\u2717"), "Project:", projectInstalled ? "Installed" : "Not installed", c.dim(`(${projectPath})`));
+  } else {
+    console.log(c.dim("\xB7"), "Project:", c.dim("Not in a git repo"));
+  }
+  console.log();
+  console.log(c.bold("Environment:"));
+  const taskListId = process.env.CLAUDE_CODE_TASK_LIST_ID;
+  const keywords = process.env.CHECK_TASKS_KEYWORDS;
+  const disabled = process.env.CHECK_TASKS_DISABLED === "1";
+  console.log("  CLAUDE_CODE_TASK_LIST_ID:", taskListId || c.yellow("(not set)"));
+  console.log("  CHECK_TASKS_KEYWORDS:", keywords || c.dim("dev (default)"));
+  console.log("  CHECK_TASKS_DISABLED:", disabled ? c.yellow("yes") : "no");
+  console.log();
+}
+var args = process.argv.slice(2);
+var command = args[0];
+var commandArgs = args.slice(1);
+switch (command) {
+  case "install":
+    install(commandArgs);
+    break;
+  case "uninstall":
+    uninstall(commandArgs);
+    break;
+  case "run":
+    Promise.resolve().then(() => (init_hook(), exports_hook)).then((m) => m.run());
+    break;
+  case "status":
+    status();
+    break;
+  case "--help":
+  case "-h":
+  case undefined:
+    printUsage();
+    break;
+  default:
+    console.error(c.red(`Unknown command: ${command}`));
+    printUsage();
+    process.exit(1);
+}

package/dist/hook.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env bun
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/hook.ts
+import { readdirSync, readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+function readStdinJson() {
+  try {
+    const stdin = readFileSync(0, "utf-8");
+    return JSON.parse(stdin);
+  } catch {
+    return null;
+  }
+}
+function getSessionName(transcriptPath) {
+  if (!existsSync(transcriptPath))
+    return null;
+  try {
+    const content = readFileSync(transcriptPath, "utf-8");
+    let lastTitle = null;
+    let searchStart = 0;
+    while (true) {
+      const titleIndex = content.indexOf('"custom-title"', searchStart);
+      if (titleIndex === -1)
+        break;
+      const lineStart = content.lastIndexOf(`
+`, titleIndex) + 1;
+      const lineEnd = content.indexOf(`
+`, titleIndex);
+      const line = content.slice(lineStart, lineEnd === -1 ? undefined : lineEnd);
+      try {
+        const entry = JSON.parse(line);
+        if (entry.type === "custom-title" && entry.customTitle) {
+          lastTitle = entry.customTitle;
+        }
+      } catch {}
+      searchStart = titleIndex + 1;
+    }
+    return lastTitle;
+  } catch {
+    return null;
+  }
+}
+function approve() {
+  console.log(JSON.stringify({ decision: "approve" }));
+  process.exit(0);
+}
+function block(reason) {
+  console.log(JSON.stringify({ decision: "block", reason }));
+  process.exit(0);
+}
+function run() {
+  if (process.env.CHECK_TASKS_DISABLED === "1") {
+    approve();
+  }
+  const taskListId = process.env.CLAUDE_CODE_TASK_LIST_ID;
+  if (!taskListId) {
+    approve();
+  }
+  const hookInput = readStdinJson();
+  let sessionName = null;
+  if (hookInput?.transcript_path) {
+    sessionName = getSessionName(hookInput.transcript_path);
+  }
+  const nameToCheck = sessionName || taskListId || "";
+  const keywords = (process.env.CHECK_TASKS_KEYWORDS || "dev").split(",").map((k) => k.trim().toLowerCase()).filter(Boolean);
+  const matchesKeyword = keywords.some((keyword) => nameToCheck.toLowerCase().includes(keyword));
+  if (!matchesKeyword) {
+    approve();
+  }
+  const tasksDir = join(homedir(), ".claude", "tasks", taskListId);
+  if (!existsSync(tasksDir)) {
+    approve();
+  }
+  const taskFiles = readdirSync(tasksDir).filter((f) => f.endsWith(".json"));
+  if (taskFiles.length === 0) {
+    approve();
+  }
+  const tasks = taskFiles.map((file) => {
+    const content = readFileSync(join(tasksDir, file), "utf-8");
+    return JSON.parse(content);
+  });
+  const pending = tasks.filter((t) => t.status === "pending");
+  const inProgress = tasks.filter((t) => t.status === "in_progress");
+  const completed = tasks.filter((t) => t.status === "completed");
+  const remainingCount = pending.length + inProgress.length;
+  if (remainingCount > 0) {
+    const nextTasks = pending.slice(0, 3).map((t) => `- ${t.subject}`).join(`
+`);
+    const prompt = `
+STOP BLOCKED: You have ${remainingCount} tasks remaining (${pending.length} pending, ${inProgress.length} in progress, ${completed.length} completed).
+
+You MUST continue working. Do NOT stop until all tasks are completed.
+
+Next pending tasks:
+${nextTasks}
+${pending.length > 3 ? `... and ${pending.length - 3} more pending tasks` : ""}
+
+INSTRUCTIONS:
+1. Use TaskList to see all tasks
+2. Pick the next pending task
+3. Use TaskUpdate to mark it as in_progress
+4. Complete the task
+5. Use TaskUpdate to mark it as completed
+6. Repeat until all tasks are done
+
+DO NOT STOP. Continue working now.
+`.trim();
+    block(prompt);
+  }
+  approve();
+}
+if (__require.main == __require.module) {
+  run();
+}
+export {
+  run
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@hasnaxyz/hook-checktasks",
+  "version": "0.1.1",
+  "description": "Claude Code hook that prevents stopping when there are pending tasks",
+  "type": "module",
+  "bin": {
+    "hook-checktasks": "./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/cli.ts ./src/hook.ts --outdir ./dist --target node",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "hook",
+    "tasks",
+    "automation",
+    "cli"
+  ],
+  "author": "Hasna",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasnaxyz/hook-checktasks.git"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20",
+    "typescript": "^5.0.0"
+  }
+}