claude_hooks 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05073a7e1f50d4391f4afddff10e781bf70c1c1a5ec15b4d8c5cf7959827ca53
-  data.tar.gz: a477cb849efb154ac3452150030bde9a4219c82887afae7b3fded7d9d01b482c
+  metadata.gz: 518b315ef2a184008b91029cdb9735b77ceee67490618d9581be16ff0c42cdb2
+  data.tar.gz: c469281a8f36dce611c1aad3f60611d5951219d1718846739d711fc310219c6f
 SHA512:
-  metadata.gz: ca053e3783d088baebefa2ffed240a63f624e053dfbaa10e1513191b20428f152414d281a782e2a76ba24490b9d25033271c75c47f85e89785aec7570bcc92ff
-  data.tar.gz: 54baf322b8031460dfcf92998c86950dd84f25b67d6b3e78270f5951dce81d169b7d355a1e6498c31fd33442572943c93795bce1fbbcb359b32ceecb145af2d6
+  metadata.gz: c500ced26412c6666d19cbef211afe43b89dcaa1b6282f6fdeb5ec24874981621d3ef7b742a1c3fc45d9f68c91e838d0c16a6e90fb63c81a6f90facfb0f23e11
+  data.tar.gz: db4d7cc2ca66d8d6cb7c3582cda5433f2b6882998f600a43cda170f58951246fd5394704b4ce6136c461138160c509d0e5bbec3390530329b754b11aa62911dc

data/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-08-21
+
+### Added
+- **Dual Configuration System**: Support for both home-level (`$HOME/.claude`) and project-level (`$CLAUDE_PROJECT_DIR/.claude`) configurations
+- **Configuration Merging**: Intelligent merging of home and project configs with configurable precedence
+- New environment variable `CLAUDE_HOOKS_CONFIG_MERGE_STRATEGY` to control merge behavior ("project" or "home")
+- New directory access methods: `home_claude_dir`, `project_claude_dir`
+- New path utility methods: `home_path_for(path)`, `project_path_for(path)`
+- Enhanced `path_for(path, base_dir=nil)` method with optional base directory parameter
+- Comprehensive test suite for configuration functionality (`test/` directory)
+- Configuration validation and edge case handling for missing `CLAUDE_PROJECT_DIR`
+
+### Changed
+- **Logs Location**: Logs now always go to `$HOME/.claude/{logDirectory}` regardless of active configuration
+- Configuration loading now supports dual config file locations with intelligent merging
+- Enhanced documentation with comprehensive dual configuration examples
+- Updated API reference with new directory and path methods
+
+### Deprecated
+- `base_dir` method (still functional for backward compatibility)
+- `RUBY_CLAUDE_HOOKS_BASE_DIR` environment variable (still supported as fallback)
+
+### Fixed
+- Graceful handling of undefined `CLAUDE_PROJECT_DIR` environment variable
+- Proper path resolution when project directory is not available
+- Backward compatibility maintained for all existing hook scripts
+
+### Migration Notes
+- Existing configurations continue to work without changes
+- New projects can leverage dual configuration system
+- `base_dir` and legacy `path_for` methods remain functional
+- Environment variables maintain same precedence over config files
+
 ## [0.1.0] - 2025-08-17
 
 ### Added

data/README.md

@@ -4,6 +4,8 @@ A Ruby DSL (Domain Specific Language) for creating Claude Code hooks. This will
 
 [**Why use this instead of writing bash, or simple ruby scripts?**](WHY.md)
 
+> You might also be interested in my other project, a [Claude Code statusline](https://github.com/gabriel-dehan/claude_monitor_statusline) that shows your Claude usage in realtime ✨.
+
 ## 🚀 Quick Start
 
 > [!TIP]
@@ -44,10 +46,11 @@ if __FILE__ == $0
 end
 ```
 
-3. ⚠️ **Make it executable (and test it)**
+3. ⚠️ **Make it executable**
 ```bash
 chmod +x add_context_after_prompt.rb
-echo '{"session_id":"test","prompt":"Hello!"}' | ruby add_context_after_prompt.rb
+# Test it
+echo '{"session_id":"test","prompt":"Hello!"}' | ./add_context_after_prompt.rb
 ```
 
 4. **Register it in your `.claude/settings.json`**
@@ -87,6 +90,7 @@ Or add it to your Gemfile (you can add a Gemfile in your `.claude` directory if
 ```ruby
 # .claude/Gemfile
 source 'https://rubygems.org'
+
 gem 'claude_hooks'
 ```
 
@@ -101,63 +105,91 @@ $ bundle install
 
 ### 🔧 Configuration
 
-This gem uses either environment variables or a global configuration file.
-
+Claude Hooks supports both home-level (`$HOME/.claude`) and project-level (`$CLAUDE_PROJECT_DIR/.claude`) directories. Claude Hooks specific config files (`config/config.json`) found in either directory will be merged together.
 
-#### Required Configuration Options
+| Directory | Description | Purpose |
+|-----------|-------------|---------|
+| `$HOME/.claude` | Home Claude directory | Global user settings and logs |
+| `$CLAUDE_PROJECT_DIR/.claude` | Project Claude directory | Project-specific settings |
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `baseDir` | Base directory for all Claude files | `~/.claude` |
-| `logDirectory` | Directory for logs (relative to baseDir) | `logs` |
+> [!NOTE]
+> Logs always go to `$HOME/.claude/{logDirectory}`
 
-#### Environment Variables (Preferred)
+#### Environment Variables
 
-The gem uses environment variables with the `RUBY_CLAUDE_HOOKS_` prefix for configuration:
+You can configure Claude Hooks through environment variables with the `RUBY_CLAUDE_HOOKS_` prefix:
 
 ```bash
-export RUBY_CLAUDE_HOOKS_BASE_DIR="~/.claude"           # Default: ~/.claude
-export RUBY_CLAUDE_HOOKS_LOG_DIR="logs"                 # Default: logs (relative to base_dir)
+# Existing configuration options
+export RUBY_CLAUDE_HOOKS_LOG_DIR="logs"                 # Default: logs (relative to HOME/.claude)
+export CLAUDE_HOOKS_CONFIG_MERGE_STRATEGY="project"     # Config merge strategy: "project" or "home", default: "project"
+export RUBY_CLAUDE_HOOKS_BASE_DIR="~/.claude"           # Deprecated: fallback base directory
 
-# You can add any custom configuration
+# Any variable prefixed with RUBY_CLAUDE_HOOKS_ will also be available through the config object
 export RUBY_CLAUDE_HOOKS_API_KEY="your-api-key"
 export RUBY_CLAUDE_HOOKS_DEBUG_MODE="true"
 export RUBY_CLAUDE_HOOKS_USER_NAME="Gabriel"
 ```
 
-#### Configuration File
+#### Configuration Files
 
-You can choose to use a global configuration file by setting it up in `~/.claude/config/config.json`.
-The gem will read from it as fallback for any missing environment variables.
+You can also use configuration files in any of the two locations:
 
+**Home config** (`$HOME/.claude/config/config.json`):
 ```json
 {
-  "baseDir": "~/.claude",
+  // Existing configuration option
   "logDirectory": "logs",
-  "apiKey": "your-api-key",
-  "debugMode": true,
+  // Custom configuration options
+  "apiKey": "your-global-api-key",
   "userName": "Gabriel"
 }
 ```
 
-#### Accessing Custom Configuration
+**Project config** (`$CLAUDE_PROJECT_DIR/.claude/config/config.json`):
+```json
+{
+  // Custom configuration option
+  "projectSpecificConfig": "someValue",
+}
+```
+
+#### Configuration Merging
+
+When both config files exist, they will be merged with configurable precedence:
+
+- **Default (`project`)**: Project config values override home config values
+- **Home precedence (`home`)**: Home config values override project config values
+
+Set merge strategy: `export CLAUDE_HOOKS_CONFIG_MERGE_STRATEGY="home" | "project"` (default: "project")
+
+> [!WARNING]
+> Environment Variables > Merged Config Files
+
+#### Accessing Configuration Variables
 
 You can access any configuration value in your handlers:
 
 ```ruby
 class MyHandler < ClaudeHooks::UserPromptSubmit
   def call
-    # Access built-in config
-    log "Base dir: #{config.base_dir}"
+    # Access directory paths
+    log "Home Claude dir: #{home_claude_dir}"
+    log "Project Claude dir: #{project_claude_dir}" # nil if CLAUDE_PROJECT_DIR not set
+    log "Base dir (deprecated): #{base_dir}"
     log "Logs dir: #{config.logs_directory}"
 
+    # Path utilities
+    log "Home config path: #{home_path_for('config')}"
+    log "Project hooks path: #{project_path_for('hooks')}" # nil if no project dir
+
     # Access custom config via method calls
     log "API Key: #{config.api_key}"
     log "Debug mode: #{config.debug_mode}"
     log "User: #{config.user_name}"
 
     # Or use get_config_value for more control
-    user_name = config.get_config_value('USER_NAME', 'userName', )
+    user_name = config.get_config_value('USER_NAME', 'userName')
     log "Username: #{user_name}"
 
     output_data
@@ -165,18 +197,16 @@ class MyHandler < ClaudeHooks::UserPromptSubmit
 end
 ```
 
-**Configuration Priority:** Environment variables always take precedence over config file values.
-
 ## 📖 Table of Contents
 
 - [Ruby DSL for Claude Code hooks](#ruby-dsl-for-claude-code-hooks)
   - [🚀 Quick Start](#-quick-start)
   - [📦 Installation](#-installation)
     - [🔧 Configuration](#-configuration)
-      - [Required Configuration Options](#required-configuration-options)
-      - [Environment Variables (Preferred)](#environment-variables-preferred)
-      - [Configuration File](#configuration-file)
-      - [Accessing Custom Configuration](#accessing-custom-configuration)
+      - [Environment Variables](#environment-variables)
+      - [Configuration Files](#configuration-files)
+      - [Configuration Merging](#configuration-merging)
+      - [Accessing Configuration Variables](#accessing-configuration-variables)
   - [📖 Table of Contents](#-table-of-contents)
   - [🏗️ Architecture](#️-architecture)
     - [Core Components](#core-components)
@@ -184,7 +214,7 @@ end
   - [🪝 Hook Types](#-hook-types)
   - [🚀 Claude Hook Flow](#-claude-hook-flow)
     - [A very simplified view of how a hook works in Claude Code](#a-very-simplified-view-of-how-a-hook-works-in-claude-code)
-    - [🔄 Claude Hook Execution Flow](#-claude-hook-execution-flow)
+    - [🔄 Proposal: a more robust Claude Hook execution flow](#-proposal-a-more-robust-claude-hook-execution-flow)
     - [Basic Hook Handler Structure](#basic-hook-handler-structure)
     - [Input Fields](#input-fields)
   - [📚 API Reference](#-api-reference)
@@ -192,7 +222,9 @@ end
       - [Input Methods](#input-methods)
       - [Output Methods](#output-methods)
       - [Class Output Methods](#class-output-methods)
+    - [Configuration and Utility Methods](#configuration-and-utility-methods)
       - [Utility Methods](#utility-methods)
+      - [Configuration Methods](#configuration-methods)
     - [UserPromptSubmit API](#userpromptsubmit-api)
       - [Input Methods](#input-methods-1)
       - [Output Methods](#output-methods-1)
@@ -218,9 +250,6 @@ end
     - [SessionStart API](#sessionstart-api)
       - [Input Methods](#input-methods-8)
       - [Output Methods](#output-methods-8)
-    - [Configuration and Utility Methods](#configuration-and-utility-methods)
-      - [Configuration Methods](#configuration-methods)
-      - [Utility Methods](#utility-methods-2)
     - [📝 Logging](#-logging)
       - [Log File Location](#log-file-location)
       - [Log Output Format](#log-output-format)
@@ -298,10 +327,10 @@ The framework supports the following hook types:
 
 ```mermaid
 graph LR
-    A[Hook triggers] --> B[JSON from STDIN] --> C[Hook does its thing] --> D[JSON to STDOUT or STDERR]
+  A[Hook triggers] --> B[JSON from STDIN] --> C[Hook does its thing] --> D[JSON to STDOUT or STDERR] --> E[Yields back to Claude Code] --> A
 ```
 
-### 🔄 Claude Hook Execution Flow
+### 🔄 Proposal: a more robust Claude Hook execution flow
 
 1. An entrypoint for a hook is set in `~/.claude/settings.json`
 2. Claude Code calls the entrypoint script (e.g., `hooks/entrypoints/pre_tool_use.rb`)
@@ -318,8 +347,8 @@ graph TD
   C --> D[📋 Entrypoint<br />Parses JSON from STDIN]
   D --> E[📋 Entrypoint<br />Calls hook handlers]
 
-  E --> F[📝 AppendContextRules.call<br/><em>Returns output_data</em>]
-  E --> G[📝 PromptGuard.call<br/><em>Returns output_data</em>]
+  E --> F[📝 Handler<br />AppendContextRules.call<br/><em>Returns output_data</em>]
+  E --> G[📝 Handler<br />PromptGuard.call<br/><em>Returns output_data</em>]
 
   F --> J[📋 Entrypoint<br />Calls _ClaudeHooks::UserPromptSubmit.merge_outputs_ to 🔀 merge outputs]
   G --> J
@@ -422,11 +451,30 @@ Each hook type provides a **class method** `merge_outputs` that will try to inte
 |--------|-------------|
 | `merge_outputs(*outputs_data)` | Intelligently merge multiple outputs into a single output |
 
+### Configuration and Utility Methods
+
+Available in all hooks via the base `ClaudeHooks::Base` class:
+
 #### Utility Methods
 | Method | Description |
 |--------|-------------|
 | `log(message, level: :info)` | Log to session-specific file (levels: :info, :warn, :error) |
 
+#### Configuration Methods
+| Method | Description |
+|--------|-------------|
+| `home_claude_dir` | Get the home Claude directory (`$HOME/.claude`) |
+| `project_claude_dir` | Get the project Claude directory (`$CLAUDE_PROJECT_DIR/.claude`, or `nil`) |
+| `home_path_for(relative_path)` | Get absolute path relative to home Claude directory |
+| `project_path_for(relative_path)` | Get absolute path relative to project Claude directory (or `nil`) |
+| `base_dir` | Get the base Claude directory (**deprecated**) |
+| `path_for(relative_path, base_dir=nil)` | Get absolute path relative to specified or default base dir (**deprecated**) |
+| `config` | Access the merged configuration object |
+| `config.get_config_value(env_key, config_file_key, default)` | Get any config value with fallback |
+| `config.logs_directory` | Get logs directory path (always under home directory) |
+| `config.your_custom_key` | Access any custom config via method_missing |
+
+
 ### UserPromptSubmit API
 
 Available when inheriting from `ClaudeHooks::UserPromptSubmit`:
@@ -560,26 +608,6 @@ Available when inheriting from `ClaudeHooks::SessionStart`:
 | `add_context!(context)` | Alias for `add_additional_context!` |
 | `empty_additional_context!` | Clear additional context |
 
-### Configuration and Utility Methods
-
-Available in all hooks via the base `ClaudeHooks::Base` class:
-
-#### Configuration Methods
-| Method | Description |
-|--------|-------------|
-| `base_dir` | Get the base Claude directory |
-| `path_for(relative_path)` | Get absolute path relative to base dir |
-| `config` | Access the full configuration object |
-| `config.get_config_value(env_key, config_key, default)` | Get any config value with fallback |
-| `config.logs_directory` | Get logs directory path |
-| `config.your_custom_key` | Access any custom config via method_missing |
-
-#### Utility Methods
-| Method | Description |
-|--------|-------------|
-| `log(message, level: :info)` | Log to session-specific file (levels: :info, :warn, :error) |
-| `log(level: :info) { block }` | Multiline logging with block support |
-
 ### 📝 Logging
 
 `ClaudeHooks::Base` provides a **session logger** that will write logs to session-specific files.

data/example_dotclaude/hooks/entrypoints/user_prompt_submit.rb

@@ -2,8 +2,8 @@
 
 require 'claude_hooks'
 require 'json'
-require_relative '../user_prompt_submit/append_rules'
-require_relative '../user_prompt_submit/log_user_prompt'
+require_relative '../handlers/user_prompt_submit/append_rules'
+require_relative '../handlers/user_prompt_submit/log_user_prompt'
 
 begin
   # Read input from stdin

data/lib/claude_hooks/base.rb

@@ -111,8 +111,24 @@ module ClaudeHooks
       config.base_dir
     end
 
-    def path_for(relative_path)
-      config.path_for(relative_path)
+    def home_claude_dir
+      config.home_claude_dir
+    end
+
+    def project_claude_dir
+      config.project_claude_dir
+    end
+
+    def path_for(relative_path, base_directory = nil)
+      config.path_for(relative_path, base_directory)
+    end
+
+    def home_path_for(relative_path)
+      config.home_path_for(relative_path)
+    end
+
+    def project_path_for(relative_path)
+      config.project_path_for(relative_path)
     end
 
     # Supports both single messages and blocks for multiline logging

data/lib/claude_hooks/configuration.rb

@@ -16,29 +16,75 @@ module ClaudeHooks
       def reload!
         @config = nil
         @base_dir = nil
+        @home_claude_dir = nil
+        @project_claude_dir = nil
         @config_file_path = nil
+        @home_config_file_path = nil
+        @project_config_file_path = nil
       end
 
-      # Get the base directory from ENV or default
+      # Get the home Claude directory (always ~/.claude)
+      def home_claude_dir
+        @home_claude_dir ||= File.expand_path('~/.claude')
+      end
+
+      # Get the project Claude directory (from CLAUDE_PROJECT_DIR/.claude)
+      # Returns nil if CLAUDE_PROJECT_DIR environment variable is not set
+      def project_claude_dir
+        @project_claude_dir ||= begin
+          project_dir = ENV['CLAUDE_PROJECT_DIR']
+          if project_dir
+            File.expand_path(File.join(project_dir, '.claude'))
+          else
+            nil
+          end
+        end
+      end
+
+      # Get the base directory from ENV or default (backward compatibility)
+      # This method will determine which base directory to use based on context
       def base_dir
         @base_dir ||= begin
+          # Check for legacy environment variable first
           env_base_dir = ENV["#{ENV_PREFIX}BASE_DIR"]
-          File.expand_path(env_base_dir || '~/.claude')
+          if env_base_dir
+            File.expand_path(env_base_dir)
+          else
+            # Default to home directory for backward compatibility
+            home_claude_dir
+          end
         end
       end
 
       # Get the full path for a file/directory relative to base_dir
-      def path_for(relative_path)
-        File.join(base_dir, relative_path)
+      # Can optionally specify which base directory to use
+      def path_for(relative_path, base_directory = nil)
+        base_directory ||= base_dir
+        File.join(base_directory, relative_path)
       end
 
-      # Get the log directory path
+      # Get the full path for a file/directory relative to home_claude_dir
+      def home_path_for(relative_path)
+        File.join(home_claude_dir, relative_path)
+      end
+
+      # Get the full path for a file/directory relative to project_claude_dir
+      # Returns nil if CLAUDE_PROJECT_DIR environment variable is not set
+      def project_path_for(relative_path)
+        if project_claude_dir
+          File.join(project_claude_dir, relative_path)
+        else
+          nil
+        end
+      end
+
+      # Get the log directory path (always relative to home_claude_dir)
       def logs_directory
         log_dir = get_config_value('LOG_DIR', 'logDirectory') || 'logs'
         if log_dir.start_with?('/')
           log_dir  # Absolute path
         else
-          path_for(log_dir)  # Relative to base_dir
+          File.join(home_claude_dir, log_dir)  # Always relative to home_claude_dir
         end
       end
 
@@ -92,25 +138,63 @@ module ClaudeHooks
         @config_file_path ||= path_for('config/config.json')
       end
 
+      def home_config_file_path
+        @home_config_file_path ||= File.join(home_claude_dir, 'config/config.json')
+      end
+
+      def project_config_file_path
+        @project_config_file_path ||= begin
+          if project_claude_dir
+            File.join(project_claude_dir, 'config/config.json')
+          else
+            nil
+          end
+        end
+      end
+
       def load_config
-        # Start with config file
-        file_config = load_config_file
+        # Load and merge config files from both locations
+        merged_file_config = load_and_merge_config_files
         
         # Merge with ENV variables
         env_config = load_env_config
         
-        # ENV variables take precedence
-        file_config.merge(env_config)
+        # ENV variables take precedence over file configs
+        merged_file_config.merge(env_config)
+      end
+
+      def load_and_merge_config_files
+        home_config = load_config_file_from_path(home_config_file_path)
+        project_config = load_config_file_from_path(project_config_file_path) if project_config_file_path
+        
+        # Determine merge strategy
+        merge_strategy = ENV['CLAUDE_HOOKS_CONFIG_MERGE_STRATEGY'] || 'project'
+        
+        if project_config && merge_strategy == 'project'
+          # Project config takes precedence
+          home_config.merge(project_config)
+        elsif project_config && merge_strategy == 'home'
+          # Home config takes precedence
+          project_config.merge(home_config)
+        else
+          # Only home config exists or no project config
+          home_config
+        end
       end
 
       def load_config_file
         config_file = config_file_path
+        load_config_file_from_path(config_file)
+      end
+
+      def load_config_file_from_path(config_file_path)
+        return {} unless config_file_path
 
-        if File.exist?(config_file)
+        if File.exist?(config_file_path)
           begin
-            JSON.parse(File.read(config_file))
+            JSON.parse(File.read(config_file_path))
           rescue JSON::ParserError => e
-            warn "Warning: Error parsing config file #{config_file}: #{e.message}"
+            warn "Warning: Error parsing config file #{config_file_path}: #{e.message}"
             {}
           end
         else

data/lib/claude_hooks/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeHooks
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude_hooks
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Gabriel Dehan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-17 00:00:00.000000000 Z
+date: 2025-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json