docs: update README and CLAUDE.md with git-aware features and hooks preview

- Add git-aware processing examples and flag documentation to README
- Include Claude Code hooks integration preview for v0.2.0
- Update CLAUDE.md architecture to reflect current dual-mode design
- Document completed git features and planned hooks integration
- Enhance project descriptions with current capabilities

CLAUDE.md

@@ -6,6 +6,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Shush is a CLI tool written in Go that removes comments from source code files using sed under the hood. It supports multiple programming languages and can process individual files or directories (with optional recursive traversal). The tool emphasizes preserving file structure while providing precise comment removal control.
 
+**Key Features**:
+- **Git-aware processing**: Surgical precision targeting only changed lines  
+- **Claude Code integration**: Automatic comment cleanup via hooks (planned v0.2.0)
+- **Dual processing modes**: Traditional sed-based + in-memory line-based for git operations
+
 ## Build and Development Commands
 
 ```bash
@@ -30,41 +35,53 @@ make dev
 # Example usage
 ./shush file.py
 ./shush src/ --recursive --dry-run --verbose
+
+# Git-aware examples
+./shush --staged --dry-run
+./shush --changes-only
 ```
 
 ## Architecture
 
 ### Project Structure
-- `cmd/shush/main.go` - Entry point, CLI parsing with kong, version management, LLM guide
+- `cmd/shush/main.go` - Entry point, CLI parsing with kong, version management, LLM guide, git flag validation
-- `internal/types/types.go` - Core type definitions (CLI struct, Language struct, BlockComment)
+- `internal/types/types.go` - Core type definitions (CLI struct with git flags, Language struct, BlockComment)
-- `internal/processor/processor.go` - Main processing logic, file/directory handling, sed command execution, colored preview
+- `internal/processor/processor.go` - Main processing logic, routing between sed and git modes
+- `internal/processor/git_processor.go` - Git-aware processing with line-based comment removal
 - `internal/processor/languages.go` - Language detection and mapping (file extension → comment syntax)
-- `ai_docs/` - Design documents for future features (GIT_FEATURE_PLAN.md)
+- `internal/git/` - Git operations: repo detection, diff parsing, line range extraction
+- `ai_docs/` - Design documents (GIT_FEATURE_PLAN.md, HOOKS_FEATURE_PLAN.md)
 
 ### Core Flow
-1. **CLI Parsing**: Kong parses arguments into `types.CLI` struct
+1. **CLI Parsing**: Kong parses arguments into `types.CLI` struct with git flag validation
-2. **Language Detection**: File extension mapped to comment patterns via `languageMap`
+2. **Mode Detection**: Route to git-aware or traditional processing
-3. **Processing Strategy**: 
+3. **Git Mode** (`--staged`, `--unstaged`, `--changes-only`):
-   - Single file: Direct processing
+   - Git repository detection and file change analysis
-   - Directory: Scan for supported files (recursive if `-r` flag)
+   - Diff parsing to extract precise line ranges
-   - Preview mode (`--dry-run`): Show colored diff with line numbers and counts
+   - Line-based comment removal with totals tracking
-   - LLM mode (`--llm`): Display comprehensive usage guide
+4. **Traditional Mode** (file/directory paths):
-4. **Sed Command Generation**: Build sed patterns based on language and flags (`--inline`, `--block`)
+   - Language detection from file extension
-5. **Execution**: Run sed commands or show preview with color-coded output using fatih/color
+   - Sed command generation and execution
+   - Directory scanning (recursive if `-r` flag)
+5. **Output**: Color-coded preview, totals summary, or file modification
 
 ### Key Design Principles
+- **Dual Processing Architecture**: 
+  - Traditional: sed-based for entire files/directories
+  - Git-aware: in-memory line-based for surgical precision
 - **Comment Removal Logic**: 
   - Comment-only lines are deleted entirely
   - Inline comments are stripped but lines preserved
-  - Original blank lines remain untouched (preserves file structure)
+  - Spacing preserved unless comments are actually removed
+- **Git Integration**: Surgical targeting of only changed lines
 - **Language Support**: Extensible via `languageMap` in `languages.go`
-- **Sed Integration**: Leverages existing sed for performance and reliability
 
 ### Comment Processing Rules
-- Line comments (`//`, `#`, `--`): Remove entire line if comment-only, strip inline comments
+- **Line comments** (`//`, `#`, `--`): Remove entire line if comment-only, strip inline comments
-- Block comments (`/* */`): Remove single-line or multi-line blocks
+- **Block comments** (`/* */`): Remove single-line or multi-line blocks
-- Mutual exclusion: `--inline` and `--block` flags cannot be used together
+- **Git mode**: Only processes lines within detected change ranges
-- Structure preservation: Never remove intentional blank lines
+- **Flag exclusions**: `--inline` and `--block` are mutually exclusive; git flags are mutually exclusive
+- **Structure preservation**: Never remove intentional blank lines; preserve spacing unless comments removed
 
 ## Release Process
 
@@ -83,13 +100,17 @@ To add new language support, update `languageMap` in `internal/processor/languag
 
 ## Future Development
 
-### Planned Git Integration
+### Completed: Git-Aware Processing (v0.1.3)
-A major feature is planned for git-aware comment removal (see `ai_docs/GIT_FEATURE_PLAN.md`):
+The git-aware comment removal feature is now implemented:
-- `--staged`: Remove comments only from staged changes
+- `--staged`: Remove comments only from staged changes ✅
-- `--unstaged`: Remove comments only from unstaged changes  
+- `--unstaged`: Remove comments only from unstaged changes ✅  
-- `--changes-only`: Process all git changes (staged + unstaged + untracked)
+- `--changes-only`: Process all git changes (staged + unstaged + untracked) ✅
 
-This would enable surgical comment removal from only the lines you've changed, preserving existing codebase comments.
+### Planned: Claude Code Hooks Integration (v0.2.0)
+Seamless integration with Claude Code via hooks (see `ai_docs/HOOKS_FEATURE_PLAN.md`):
+- `--install-hooks`: Auto-configure Claude Code to run shush after file modifications
+- `--install-hooks project`: Project-specific hook installation
+- Automatic comment cleanup with zero manual intervention
 
 ## Development Notes
 

README.md

@@ -1,6 +1,6 @@
 # shush 🤫
 
-Remove comments from source code files blazingly fast using sed under the hood.
+Remove comments from source code files blazingly fast using sed under the hood. Features git-aware processing and Claude Code integration.
 
 ## Installation
 
@@ -41,6 +41,11 @@ shush config.lua --backup
 # Verbose output
 shush app.go --verbose
 
+# Git-aware processing (only process changed lines)
+shush --staged                    # Clean comments from staged changes
+shush --unstaged                  # Clean comments from unstaged changes  
+shush --changes-only              # Clean comments from all changes
+
 # Combine flags for complex operations
 shush src/ --recursive --inline --dry-run --verbose
 ```
@@ -69,6 +74,13 @@ shush src/ --recursive --inline --dry-run --verbose
 --dry-run      Show what would be removed without making changes
 --backup       Create backup files before modification
 --verbose      Show detailed output
+
+# Git-aware flags
+--changes-only Remove comments only from git changes (staged + unstaged + untracked)
+--staged       Remove comments only from staged git changes
+--unstaged     Remove comments only from unstaged git changes
+
+# Utility flags
 --version      Show version information
 --llm          Show LLM-friendly usage guide
 --help         Show help message
@@ -109,6 +121,22 @@ shush . --recursive --dry-run
 shush . --recursive --inline --backup
 ```
 
+### Git-Aware Processing
+```bash
+# Clean comments from staged changes before commit
+shush --staged --dry-run          # Preview changes
+shush --staged --backup           # Apply with backup
+
+# Clean comments from current work
+shush --unstaged --inline         # Remove only line comments
+shush --changes-only              # Clean all changes (staged + unstaged + untracked)
+
+# Pre-commit workflow
+shush --staged --dry-run          # 1. Review what will be cleaned  
+shush --staged                    # 2. Clean staged changes
+git commit -m "Clean code"        # 3. Commit cleaned code
+```
+
 ### Backup and Preview
 ```bash
 # Always create backup before modifying
@@ -118,13 +146,29 @@ shush important.go --backup
 shush config.yaml --dry-run --verbose
 ```
 
+## Claude Code Integration 🤖
+
+*Coming soon in v0.2.0* - Seamless integration with Claude Code via hooks:
+
+```bash
+# Install automatic comment cleanup after Claude modifies files
+shush --install-hooks              # User-wide (all projects)
+shush --install-hooks project      # Project-specific only
+
+# Check hook status  
+shush --hooks-status               # See current configuration
+```
+
+Once installed, comments will be automatically cleaned whenever Claude Code uses Write, Edit, or MultiEdit tools. No manual intervention required!
+
 ## How It Works
 
 shush uses optimized sed commands to remove comments while preserving code structure. It:
 - Auto-detects language from file extension
 - Builds appropriate sed patterns for the detected language
-- Removes comments and empty lines in a single pass
+- **Git-aware processing**: Only processes changed lines for surgical precision
 - Preserves strings and code that might look like comments
+- **Claude Code integration**: Automatic cleanup via PostToolUse hooks
 
 ## Building from Source