feat: add claude code hook

Author: pedronauck

bun.lock

@@ -0,0 +1,43 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "gograph-claude-hook",
+      "dependencies": {
+        "@anthropic-ai/claude-code": "^1.0.41",
+      },
+      "devDependencies": {
+        "@types/node": "^20.0.0",
+      },
+    },
+  },
+  "packages": {
+    "@anthropic-ai/claude-code": ["@anthropic-ai/[email protected]", "", { "optionalDependencies": { "@img/sharp-darwin-arm64": "^0.33.5", "@img/sharp-darwin-x64": "^0.33.5", "@img/sharp-linux-arm": "^0.33.5", "@img/sharp-linux-arm64": "^0.33.5", "@img/sharp-linux-x64": "^0.33.5", "@img/sharp-win32-x64": "^0.33.5" }, "bin": { "claude": "cli.js" } }, "sha512-6E5SCb1I/pC4WCEFGwmyo4M4bL9vBuk7qkC78v9ZFX9PAxmKX94SEj422igdLeucBYX99ZqKSMYfsJEqTeIo2Q=="],
+
+    "@img/sharp-darwin-arm64": ["@img/[email protected]", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-arm64": "1.0.4" }, "os": "darwin", "cpu": "arm64" }, "sha512-UT4p+iz/2H4twwAoLCqfA9UH5pI6DggwKEGuaPy7nCVQ8ZsiY5PIcrRvD1DzuY3qYL07NtIQcWnBSY/heikIFQ=="],
+
+    "@img/sharp-darwin-x64": ["@img/[email protected]", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-x64": "1.0.4" }, "os": "darwin", "cpu": "x64" }, "sha512-fyHac4jIc1ANYGRDxtiqelIbdWkIuQaI84Mv45KvGRRxSAa7o7d1ZKAOBaYbnepLC1WqxfpimdeWfvqqSGwR2Q=="],
+
+    "@img/sharp-libvips-darwin-arm64": ["@img/[email protected]", "", { "os": "darwin", "cpu": "arm64" }, "sha512-XblONe153h0O2zuFfTAbQYAX2JhYmDHeWikp1LM9Hul9gVPjFY427k6dFEcOL72O01QxQsWi761svJ/ev9xEDg=="],
+
+    "@img/sharp-libvips-darwin-x64": ["@img/[email protected]", "", { "os": "darwin", "cpu": "x64" }, "sha512-xnGR8YuZYfJGmWPvmlunFaWJsb9T/AO2ykoP3Fz/0X5XV2aoYBPkX6xqCQvUTKKiLddarLaxpzNe+b1hjeWHAQ=="],
+
+    "@img/sharp-libvips-linux-arm": ["@img/[email protected]", "", { "os": "linux", "cpu": "arm" }, "sha512-gvcC4ACAOPRNATg/ov8/MnbxFDJqf/pDePbBnuBDcjsI8PssmjoKMAz4LtLaVi+OnSb5FK/yIOamqDwGmXW32g=="],
+
+    "@img/sharp-libvips-linux-arm64": ["@img/[email protected]", "", { "os": "linux", "cpu": "arm64" }, "sha512-9B+taZ8DlyyqzZQnoeIvDVR/2F4EbMepXMc/NdVbkzsJbzkUjhXv/70GQJ7tdLA4YJgNP25zukcxpX2/SueNrA=="],
+
+    "@img/sharp-libvips-linux-x64": ["@img/[email protected]", "", { "os": "linux", "cpu": "x64" }, "sha512-MmWmQ3iPFZr0Iev+BAgVMb3ZyC4KeFc3jFxnNbEPas60e1cIfevbtuyf9nDGIzOaW9PdnDciJm+wFFaTlj5xYw=="],
+
+    "@img/sharp-linux-arm": ["@img/[email protected]", "", { "optionalDependencies": { "@img/sharp-libvips-linux-arm": "1.0.5" }, "os": "linux", "cpu": "arm" }, "sha512-JTS1eldqZbJxjvKaAkxhZmBqPRGmxgu+qFKSInv8moZ2AmT5Yib3EQ1c6gp493HvrvV8QgdOXdyaIBrhvFhBMQ=="],
+
+    "@img/sharp-linux-arm64": ["@img/[email protected]", "", { "optionalDependencies": { "@img/sharp-libvips-linux-arm64": "1.0.4" }, "os": "linux", "cpu": "arm64" }, "sha512-JMVv+AMRyGOHtO1RFBiJy/MBsgz0x4AWrT6QoEVVTyh1E39TrCUpTRI7mx9VksGX4awWASxqCYLCV4wBZHAYxA=="],
+
+    "@img/sharp-linux-x64": ["@img/[email protected]", "", { "optionalDependencies": { "@img/sharp-libvips-linux-x64": "1.0.4" }, "os": "linux", "cpu": "x64" }, "sha512-opC+Ok5pRNAzuvq1AG0ar+1owsu842/Ab+4qvU879ippJBHvyY5n2mxF1izXqkPYlGuP/M556uh53jRLJmzTWA=="],
+
+    "@img/sharp-win32-x64": ["@img/[email protected]", "", { "os": "win32", "cpu": "x64" }, "sha512-MpY/o8/8kj+EcnxwvrP4aTJSWw/aZ7JIGR4aBeZkZw5B7/Jn+tY9/VNwtcoGmdT7GfggGIU4kygOMSbYnOrAbg=="],
+
+    "@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-OP+We5WV8Xnbuvw0zC2m4qfB/BJvjyCwtNjhHdJxV1639SGSKrLmJkc3fMnp2Qy8nJyHp8RO6umxELN/dS1/EA=="],
+
+    "undici-types": ["[email protected]", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
+  }
+}

package.json

@@ -0,0 +1,27 @@
+{
+  "name": "gograph",
+  "version": "1.0.0",
+  "description": "Go codebase dependency graph analysis tool with Claude Code integration",
+  "type": "module",
+  "scripts": {
+    "hook": "bun run scripts/gograph-hook.ts",
+    "test-hook": "bun run scripts/test-hook.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-code": "^1.0.41"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "go": ">=1.21.0"
+  },
+  "keywords": [
+    "go",
+    "dependency-graph", 
+    "code-analysis",
+    "claude-code",
+    "mcp"
+  ]
+}

scripts/HOOK_ARCHITECTURE.md

@@ -0,0 +1,138 @@
+# gograph Claude Code Hook Architecture
+
+## Overview
+
+This hook implements Claude Code's PreToolUse hook system to provide intelligent Go code analysis before file operations.
+
+## Implementation Details
+
+### Hook Configuration Format
+
+The hook uses the correct Claude Code hooks structure:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd /path/to/gograph && bun run scripts/gograph-hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Input Processing
+
+The hook receives JSON input via stdin with this structure:
+
+```typescript
+interface PreToolUseInput {
+  session_id: string;
+  transcript_path: string;
+  tool_name: string;
+  tool_input: Record<string, any>;
+}
+```
+
+### Output Format
+
+The hook returns structured JSON output for advanced control:
+
+```typescript
+interface HookOutput {
+  // Common fields
+  continue?: boolean;       // Whether Claude should continue (default: true)
+  stopReason?: string;      // Message shown when continue is false
+  suppressOutput?: boolean; // Hide stdout from transcript mode (default: false)
+  
+  // PreToolUse specific
+  decision?: "approve" | "block" | undefined;
+  reason?: string;          // Explanation for decision
+}
+```
+
+### Decision Logic
+
+- **Approve**: The hook always approves Go file operations but provides analysis
+- **Reason**: Contains the formatted analysis output shown to Claude
+- **Continue**: Always true to allow operation to proceed
+- **Exit Codes**: 
+  - 0: Success with JSON output
+  - 1: Non-blocking error (operation continues)
+  - 2: Would block operation (not used in our implementation)
+
+## Features
+
+### 1. Automatic Go File Detection
+- Checks `file_path` parameter for `.go` extension
+- Handles MultiEdit operations with multiple edits
+- Skips non-Go files silently
+
+### 2. gograph Configuration Detection
+- Looks for `gograph.yaml` in project hierarchy
+- Provides appropriate analysis based on configuration presence
+
+### 3. Claude SDK Integration
+- Uses existing Claude Code session (no API key needed)
+- Includes `allowedTools` for MCP permissions
+- Graceful fallback to static analysis on failures
+
+### 4. Comprehensive Logging
+- Logs all operations to `~/.claude/gograph-hook.log`
+- Includes timestamps and detailed error messages
+- Helps with debugging hook issues
+
+## Security Considerations
+
+- Runs with user permissions in current directory
+- No sensitive data exposed in logs
+- Uses structured JSON output to prevent injection
+- Validates all input data before processing
+
+## Testing
+
+The `test-hook.ts` script provides comprehensive testing:
+
+```bash
+bun run test-hook
+```
+
+Tests include:
+- Write operations on Go files
+- Edit operations on Go files  
+- MultiEdit operations with multiple changes
+- Non-Go file handling (should skip)
+- Error handling and edge cases
+
+## Integration Flow
+
+1. Claude Code triggers hook before Write/Edit/MultiEdit
+2. Hook receives tool information via stdin
+3. Hook analyzes Go file context
+4. Returns approval with analysis feedback
+5. Claude sees analysis and proceeds with operation
+6. User benefits from contextual guidance
+
+## Troubleshooting
+
+### Hook Not Triggering
+- Check matcher regex in settings.json
+- Verify command path is absolute
+- Ensure bun is accessible in PATH
+
+### Analysis Not Showing
+- Check exit code is 0
+- Verify JSON output format
+- Review logs for errors
+
+### Permission Issues  
+- Hook includes allowedTools configuration
+- Add global permissions if needed
+- Ensure gograph MCP server is running

scripts/INTEGRATION.md

@@ -0,0 +1,178 @@
+# gograph Claude Code Hook Integration
+
+This guide shows how to manually integrate the gograph hook with your Claude Code settings.
+
+## Prerequisites
+
+- [bun](https://bun.sh) installed
+- Claude Code CLI installed and authenticated
+- gograph project with `gograph.yaml` configuration
+
+## Setup Steps
+
+### 1. Install Dependencies
+
+```bash
+# From project root
+bun install
+```
+
+### 2. Update Claude Code Settings
+
+Add the hook configuration to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd /path/to/your/gograph && bun run scripts/gograph-hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Important**: Replace `/path/to/your/gograph` with the actual absolute path to your gograph project root directory.
+
+### 3. Optional: Configure Global MCP Tool Permissions
+
+The hook includes `allowedTools` configuration to permit gograph MCP tools automatically. However, you can also add global permissions to your `~/.claude/settings.json` if preferred:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__gograph__analyze_project",
+      "mcp__gograph__get_package_structure", 
+      "mcp__gograph__query_dependencies",
+      "mcp__gograph__get_function_info",
+      "mcp__gograph__natural_language_query"
+    ]
+  }
+}
+```
+
+Note: The hook automatically includes these permissions via `allowedTools` configuration, so this step is optional.
+
+### 4. Complete Settings Example
+
+Here's a minimal `~/.claude/settings.json` example:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd /Users/username/projects/gograph && bun run scripts/gograph-hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The hook handles tool permissions automatically via the SDK's `allowedTools` configuration.
+
+## Testing the Integration
+
+### 1. Test the Hook Directly
+
+```bash
+cd scripts/
+bun run test-hook.ts
+```
+
+### 2. Test with Claude Code
+
+1. Open Claude Code in a Go project with gograph configuration
+2. Try editing or creating a `.go` file
+3. The hook should trigger and provide analysis before the operation
+4. Check logs at `~/.claude/gograph-hook.log` if needed
+
+## How It Works
+
+1. **Trigger**: Hook activates before `Write`, `Edit`, or `MultiEdit` operations on `.go` files
+2. **Analysis**: Uses Claude Code SDK with your existing session to analyze via gograph MCP
+3. **Output**: Provides dependency analysis, architectural recommendations, and integration guidance
+4. **Fallback**: If MCP analysis fails, provides static analysis based on gograph configuration
+
+## Configuration Options
+
+### Hook Matchers
+
+You can customize which operations trigger the hook:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd /path/to/your/gograph && bun run scripts/gograph-hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+You can also use more specific regex patterns:
+- `"Write"` - Only Write operations
+- `"Edit|MultiEdit"` - Only Edit operations
+- `".*"` - All tools
+- `"Notebook.*"` - All notebook operations
+
+### Working Directory
+
+The hook automatically detects your project's working directory from the Claude Code session.
+
+### Permissions
+
+Without the permissions configuration, Claude Code will prompt you to approve each MCP tool use. Adding the permissions list prevents these prompts for a smoother experience.
+
+## Troubleshooting
+
+### Hook Not Triggering
+- Check that the path in your settings.json is correct and absolute
+- Ensure bun is installed and accessible
+- Verify the hook file is executable: `chmod +x scripts/gograph-hook.ts`
+
+### Permission Errors
+- Add the gograph MCP tool permissions to your settings.json
+- Ensure your gograph MCP server is running and connected
+
+### Analysis Failures
+- Check that you have a `gograph.yaml` file in your project
+- Verify gograph MCP tools are working: test with Claude Code directly
+- Check logs at `~/.claude/gograph-hook.log`
+
+## Security Considerations
+
+- The hook uses your existing Claude Code authentication session
+- No API keys or additional authentication required
+- Only processes Go files in projects with gograph configuration
+- Logs activity to `~/.claude/gograph-hook.log` for transparency
+
+## Uninstalling
+
+To remove the hook integration:
+
+1. Remove the hook entry from your `~/.claude/settings.json`
+2. Optionally remove the gograph MCP permissions
+3. Delete the scripts directory if no longer needed