feat: add full directory support and smart file handling

Major improvements to file handling capabilities:

- Add directory traversal support to all file-processing tools
- Tools now accept both individual files and entire directories
- Automatically expand directories and discover code files recursively
- Smart filtering: skip hidden files, __pycache__, and non-code files
- Progressive token loading: read as many files as possible within limits
- Clear file separation markers with full paths for Gemini

Key changes:
- Rewrite file_utils.py with expand_paths() and improved read_files()
- Update all tool descriptions to indicate directory support
- Add comprehensive tests for directory handling and token limits
- Document tool parameters and examples in README
- Bump version to 2.4.2

All tools (analyze, review_code, debug_issue, think_deeper) now support:
- Single files: "analyze main.py"
- Directories: "review src/"
- Mixed paths: "analyze config.py, src/, tests/"

This enables analyzing entire projects or specific subsystems efficiently
while respecting token limits and providing clear file boundaries.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

tools/analyze.py

@@ -16,7 +16,7 @@ from .base import BaseTool, ToolRequest
 class AnalyzeRequest(ToolRequest):
     """Request model for analyze tool"""
 
-    files: List[str] = Field(..., description="Files to analyze")
+    files: List[str] = Field(..., description="Files or directories to analyze")
     question: str = Field(..., description="What to analyze or look for")
     analysis_type: Optional[str] = Field(
         None,
@@ -36,6 +36,7 @@ class AnalyzeTool(BaseTool):
     def get_description(self) -> str:
         return (
             "ANALYZE FILES & CODE - General-purpose analysis for understanding code. "
+            "Supports both individual files and entire directories. "
             "Use this for examining files, understanding architecture, or investigating specific aspects. "
             "Triggers: 'analyze these files', 'examine this code', 'understand this'. "
             "Perfect for: codebase exploration, dependency analysis, pattern detection. "
@@ -49,7 +50,7 @@ class AnalyzeTool(BaseTool):
                 "files": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Files to analyze",
+                    "description": "Files or directories to analyze",
                 },
                 "question": {
                     "type": "string",

tools/debug_issue.py

@@ -23,7 +23,7 @@ class DebugIssueRequest(ToolRequest):
         None, description="Stack trace, logs, or additional error context"
     )
     relevant_files: Optional[List[str]] = Field(
-        None, description="Files that might be related to the issue"
+        None, description="Files or directories that might be related to the issue"
     )
     runtime_info: Optional[str] = Field(
         None, description="Environment, versions, or runtime information"

tools/review_code.py

@@ -16,7 +16,7 @@ from .base import BaseTool, ToolRequest
 class ReviewCodeRequest(ToolRequest):
     """Request model for review_code tool"""
 
-    files: List[str] = Field(..., description="Code files to review")
+    files: List[str] = Field(..., description="Code files or directories to review")
     review_type: str = Field(
         "full", description="Type of review: full|security|performance|quick"
     )
@@ -41,6 +41,7 @@ class ReviewCodeTool(BaseTool):
     def get_description(self) -> str:
         return (
             "PROFESSIONAL CODE REVIEW - Comprehensive analysis for bugs, security, and quality. "
+            "Supports both individual files and entire directories/projects. "
             "Use this for thorough code review with actionable feedback. "
             "Triggers: 'review this code', 'check for issues', 'find bugs', 'security audit'. "
             "I'll identify issues by severity (Critical→High→Medium→Low) with specific fixes. "
@@ -54,7 +55,7 @@ class ReviewCodeTool(BaseTool):
                 "files": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Code files to review",
+                    "description": "Code files or directories to review",
                 },
                 "review_type": {
                     "type": "string",

tools/think_deeper.py

@@ -27,7 +27,7 @@ class ThinkDeeperRequest(ToolRequest):
         description="Specific aspects to focus on (architecture, performance, security, etc.)",
     )
     reference_files: Optional[List[str]] = Field(
-        None, description="Optional file paths for additional context"
+        None, description="Optional file paths or directories for additional context"
     )