@hasna/hooks 0.0.1

package/hooks/hook-agentmessages/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+Instructions for working with hook-agentmessages codebase.
+
+## Project Overview
+
+**hook-agentmessages** is a Claude Code hook package that integrates with service-message for automatic agent registration and message notifications.
+
+- **Package:** `@hasnaxyz/hook-agentmessages`
+- **CLI command:** `hook-agentmessages`
+- **Hooks location:** `~/.claude/settings.json`
+
+## What it Does
+
+### SessionStart Hook (`src/session-start.ts`)
+
+Runs when Claude Code session starts:
+1. Auto-registers agent with ID format: `{type}-{shortid}` (claude-abc123, codex-xyz789)
+2. Registers project from `$CLAUDE_PROJECT_DIR`
+3. Creates session linked to Claude session ID
+4. Exports env vars: `SMSG_AGENT_ID`, `SMSG_SESSION_ID`, `SMSG_PROJECT_ID`
+
+### Stop Hook (`src/check-messages.ts`)
+
+Runs after Claude finishes each response:
+1. Checks for unread messages (efficient, no polling)
+2. Returns notification if unread messages exist
+3. 5s timeout to avoid blocking
+
+## Development
+
+### Key Files
+
+```
+bin/cli.ts           # CLI entry point
+src/
+├── session-start.ts # SessionStart hook
+├── check-messages.ts # Stop hook
+├── install.ts       # Install hooks to Claude Code
+└── uninstall.ts     # Remove hooks
+```
+
+### Hook Input Format
+
+Hooks receive JSON via stdin:
+```json
+{
+  "session_id": "abc123",
+  "cwd": "/path/to/project",
+  "model": "claude-opus-4-5-20251101",
+  "hook_event_name": "SessionStart"
+}
+```
+
+### Hook Output Format
+
+```json
+{
+  "decision": "continue",
+  "message": "Optional message shown to Claude"
+}
+```
+
+## Testing
+
+```bash
+# Test session-start hook
+echo '{"session_id":"test","cwd":"/tmp"}' | bun run src/session-start.ts
+
+# Test check-messages hook
+SMSG_AGENT_ID=claude-1 bun run src/check-messages.ts
+
+# Install/uninstall
+bun run install-hook
+bun run uninstall-hook
+
+# Check status
+hook-agentmessages status
+```

package/hooks/hook-agentmessages/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hasna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/hooks/hook-agentmessages/README.md

@@ -0,0 +1,107 @@
+# hook-agentmessages
+
+Claude Code hook for service-message integration.
+
+Automatically registers projects and sessions when Claude Code starts, and checks for unread messages after each response.
+
+## Installation
+
+```bash
+# Install globally
+bun install -g @hasnaxyz/hook-agentmessages
+
+# Install hooks into Claude Code
+hook-agentmessages install
+```
+
+## Prerequisites
+
+Before using this hook, you must initialize an agent with service-message:
+
+```bash
+service-message init
+```
+
+This hook does NOT auto-generate agents. It only works if an agent is already configured.
+
+## What it does
+
+### SessionStart Hook
+
+When a Claude Code session starts:
+
+1. **Reads existing agent** from service-message config
+2. **Registers the project** from `$CLAUDE_PROJECT_DIR` (folder name becomes project ID)
+3. **Starts a session** linked to the Claude session ID
+4. **Exports environment variables** for the session:
+   - `SMSG_AGENT_ID`
+   - `SMSG_SESSION_ID`
+   - `SMSG_PROJECT_ID`
+
+### Stop Hook
+
+After Claude finishes each response:
+
+1. Checks for unread messages (efficient, no polling)
+2. Notifies Claude if there are pending messages
+3. Runs with 5s timeout to avoid blocking
+
+## CLI Commands
+
+```bash
+hook-agentmessages install    # Install hooks
+hook-agentmessages uninstall  # Remove hooks
+hook-agentmessages status     # Check installation status
+```
+
+## Configuration
+
+Hooks are stored in `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun /path/to/hook-agentmessages/src/session-start.ts",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun /path/to/hook-agentmessages/src/check-messages.ts",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Efficiency
+
+The hook is designed to be lightweight:
+
+- **SessionStart**: Runs once per session (10s timeout)
+- **Stop**: Only checks for messages after Claude responds (5s timeout)
+- **No polling**: Doesn't continuously monitor, only checks on events
+- **Fast file reads**: Uses Bun's native file APIs
+
+## Requirements
+
+- Bun runtime
+- service-message (`@hasnaxyz/service-message`) installed and initialized
+- Claude Code with hooks support
+
+## License
+
+MIT

package/hooks/hook-agentmessages/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@hasnaxyz/hook-agentmessages",
+  "version": "0.2.1",
+  "type": "module",
+  "description": "Claude Code hook for service-message integration - auto-registers agents, sessions, and checks messages",
+  "bin": {
+    "hook-agentmessages": "./bin/cli.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasnaxyz/hook-agentmessages.git"
+  },
+  "homepage": "https://github.com/hasnaxyz/hook-agentmessages#readme",
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "session-start": "bun run src/session-start.ts",
+    "check-messages": "bun run src/check-messages.ts",
+    "install-hook": "bun run src/install.ts",
+    "uninstall-hook": "bun run src/uninstall.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "typescript": "^5.7.2"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}

package/hooks/hook-agentmessages/src/check-messages.ts

@@ -0,0 +1,151 @@
+#!/usr/bin/env bun
+/**
+ * Stop hook for service-message
+ *
+ * Runs when Claude finishes a response. Checks for unread messages
+ * and notifies Claude if there are any pending messages.
+ *
+ * This is efficient because it only runs after Claude completes a turn,
+ * not continuously polling.
+ */
+
+import { homedir } from 'os';
+import { join } from 'path';
+import { readdir } from 'fs/promises';
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  hook_event_name: string;
+  stop_hook_active?: boolean;
+}
+
+interface Message {
+  id: string;
+  timestamp: number;
+  from: string;
+  to: string;
+  project: string;
+  subject: string;
+  body: string;
+  read?: boolean;
+}
+
+const SERVICE_DIR = join(homedir(), '.service', 'service-message');
+
+/**
+ * Sanitize ID to prevent path traversal attacks
+ */
+function sanitizeId(id: string): string | null {
+  if (!id || typeof id !== 'string') return null;
+  // Only allow alphanumeric, dash, underscore
+  if (!/^[a-zA-Z0-9_-]+$/.test(id)) return null;
+  // Reject path traversal attempts
+  if (id.includes('..') || id.includes('/') || id.includes('\\')) return null;
+  return id;
+}
+
+async function readJson<T>(path: string): Promise<T | null> {
+  try {
+    const file = Bun.file(path);
+    if (await file.exists()) {
+      return await file.json();
+    }
+  } catch {}
+  return null;
+}
+
+async function getUnreadMessages(agentId: string, projectId?: string): Promise<Message[]> {
+  const messages: Message[] = [];
+  const messagesDir = join(SERVICE_DIR, 'messages');
+
+  try {
+    const rawProjects = projectId ? [projectId] : await readdir(messagesDir);
+    // Sanitize all project names to prevent path traversal
+    const projects = rawProjects.map(p => sanitizeId(p)).filter((p): p is string => p !== null);
+
+    for (const proj of projects) {
+      // Check inbox
+      const inboxDir = join(messagesDir, proj, 'inbox', agentId);
+      try {
+        const files = await readdir(inboxDir);
+        for (const file of files) {
+          if (!file.endsWith('.json')) continue;
+          // Sanitize filename to prevent path traversal
+          const safeFile = sanitizeId(file.replace('.json', ''));
+          if (!safeFile) continue;
+          const msg = await readJson<Message>(join(inboxDir, `${safeFile}.json`));
+          if (msg && !msg.read) {
+            messages.push(msg);
+          }
+        }
+      } catch {}
+
+      // Check broadcast
+      const broadcastDir = join(messagesDir, proj, 'broadcast');
+      try {
+        const files = await readdir(broadcastDir);
+        for (const file of files) {
+          if (!file.endsWith('.json')) continue;
+          // Sanitize filename to prevent path traversal
+          const safeFile = sanitizeId(file.replace('.json', ''));
+          if (!safeFile) continue;
+          const msg = await readJson<Message>(join(broadcastDir, `${safeFile}.json`));
+          if (msg && !msg.read && msg.from !== agentId) {
+            messages.push(msg);
+          }
+        }
+      } catch {}
+    }
+  } catch {}
+
+  return messages.sort((a, b) => b.timestamp - a.timestamp);
+}
+
+async function main() {
+  // Get agent ID from environment (set by session-start hook)
+  const rawAgentId = process.env.SMSG_AGENT_ID;
+  const rawProjectId = process.env.SMSG_PROJECT_ID;
+
+  // Sanitize IDs to prevent path traversal
+  const agentId = rawAgentId ? sanitizeId(rawAgentId) : null;
+  const projectId = rawProjectId ? sanitizeId(rawProjectId) : undefined;
+
+  if (!agentId) {
+    // Agent not configured or invalid, skip silently
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  // Check for unread messages
+  const unreadMessages = await getUnreadMessages(agentId, projectId);
+
+  if (unreadMessages.length === 0) {
+    // No messages, continue normally
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  // Format message summary in a friendly way
+  const msgList = unreadMessages.slice(0, 3).map(msg => {
+    const time = new Date(msg.timestamp).toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit' });
+    const preview = msg.body.slice(0, 60).replace(/\n/g, ' ');
+    return `📨 **${msg.subject}** from \`${msg.from}\` (${time})\n   ${preview}${msg.body.length > 60 ? '...' : ''}`;
+  }).join('\n\n');
+
+  const moreNote = unreadMessages.length > 3
+    ? `\n\n_...and ${unreadMessages.length - 3} more message(s)_`
+    : '';
+
+  // Inject message in a friendly, readable format
+  console.log(JSON.stringify({
+    continue: true,
+    stopReason: `📬 **You have ${unreadMessages.length} unread message(s):**\n\n${msgList}${moreNote}\n\n💡 Use \`service-message inbox\` to see all messages or \`service-message read <id>\` to read one.`
+  }));
+}
+
+main().catch(() => {
+  // Don't block on errors
+  console.log(JSON.stringify({ continue: true }));
+  process.exit(0);
+});

package/hooks/hook-agentmessages/src/install.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env bun
+/**
+ * Install hook-agentmessages into Claude Code settings
+ *
+ * Adds hooks to ~/.claude/settings.json:
+ * - SessionStart: Auto-register agent, project, session
+ * - Stop: Check for unread messages
+ */
+
+import { homedir } from 'os';
+import { join } from 'path';
+
+const CLAUDE_SETTINGS_DIR = join(homedir(), '.claude');
+const CLAUDE_SETTINGS_FILE = join(CLAUDE_SETTINGS_DIR, 'settings.json');
+const HOOK_DIR = import.meta.dir.replace('/src', '');
+
+interface HookConfig {
+  type: 'command';
+  command: string;
+  timeout?: number;
+}
+
+interface HookMatcher {
+  matcher?: string;
+  hooks: HookConfig[];
+}
+
+interface Settings {
+  hooks?: {
+    SessionStart?: HookMatcher[];
+    Stop?: HookMatcher[];
+    [key: string]: HookMatcher[] | undefined;
+  };
+  [key: string]: unknown;
+}
+
+async function readSettings(): Promise<Settings> {
+  try {
+    const file = Bun.file(CLAUDE_SETTINGS_FILE);
+    if (await file.exists()) {
+      return await file.json();
+    }
+  } catch {}
+  return {};
+}
+
+async function writeSettings(settings: Settings): Promise<void> {
+  // Ensure .claude directory exists
+  await Bun.write(join(CLAUDE_SETTINGS_DIR, '.gitkeep'), '');
+  await Bun.write(CLAUDE_SETTINGS_FILE, JSON.stringify(settings, null, 2));
+}
+
+function findHookIndex(hooks: HookMatcher[], command: string): number {
+  return hooks.findIndex(h =>
+    h.hooks.some(hook => hook.command.includes('hook-agentmessages'))
+  );
+}
+
+async function main() {
+  console.log('Installing hook-agentmessages into Claude Code...\n');
+
+  const settings = await readSettings();
+
+  // Initialize hooks object if not exists
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  // SessionStart hook
+  const sessionStartHook: HookMatcher = {
+    hooks: [
+      {
+        type: 'command',
+        command: `bun ${join(HOOK_DIR, 'src/session-start.ts')}`,
+        timeout: 10,
+      },
+    ],
+  };
+
+  if (!settings.hooks.SessionStart) {
+    settings.hooks.SessionStart = [];
+  }
+
+  // Remove existing hook-agentmessages hooks
+  const existingSessionStartIdx = findHookIndex(settings.hooks.SessionStart, 'hook-agentmessages');
+  if (existingSessionStartIdx >= 0) {
+    settings.hooks.SessionStart.splice(existingSessionStartIdx, 1);
+  }
+  settings.hooks.SessionStart.push(sessionStartHook);
+
+  // Stop hook (check messages after each response)
+  const stopHook: HookMatcher = {
+    hooks: [
+      {
+        type: 'command',
+        command: `bun ${join(HOOK_DIR, 'src/check-messages.ts')}`,
+        timeout: 5,
+      },
+    ],
+  };
+
+  if (!settings.hooks.Stop) {
+    settings.hooks.Stop = [];
+  }
+
+  const existingStopIdx = findHookIndex(settings.hooks.Stop, 'hook-agentmessages');
+  if (existingStopIdx >= 0) {
+    settings.hooks.Stop.splice(existingStopIdx, 1);
+  }
+  settings.hooks.Stop.push(stopHook);
+
+  // Write updated settings
+  await writeSettings(settings);
+
+  console.log('Hooks installed successfully!\n');
+  console.log('Installed hooks:');
+  console.log('  - SessionStart: Auto-registers agent, project, and session');
+  console.log('  - Stop: Checks for unread messages after each response\n');
+  console.log(`Settings file: ${CLAUDE_SETTINGS_FILE}`);
+  console.log('\nRestart Claude Code for hooks to take effect.');
+}
+
+main().catch((err) => {
+  console.error('Installation failed:', err.message);
+  process.exit(1);
+});