feat: Add pycli bash wrapper with hierarchical vector database support

- Create unified bash wrapper (pycli) for Python CLI tools - Implement hierarchical vector database with smart parent discovery - Add comprehensive installation script with auto-configuration - Remove redundant analyzer.py and api_indexer.py files - Enhance Python scripts with environment variable support - Update documentation to focus on pycli unified interface Key Features: - Automatic parent directory vector DB discovery - No redundant vectorization in subdirectories - Central vector database storage in ~/.claude/vector_db - Configurable Python interpreter paths - One-command installation and setup 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-10 02:24:35 +08:00 · 2025-09-23 22:09:55 +08:00
parent 194d2722a3
commit c337204242
9 changed files with 1353 additions and 726 deletions
--- a/.claude/scripts/README.md
+++ b/.claude/scripts/README.md
@@ -0,0 +1,152 @@
+# pycli - Python CLI Wrapper with Hierarchical Vector Database
+
+This directory contains the bash wrapper and configuration for the enhanced Python-based analysis CLI with hierarchical vector database support.
+
+## 📁 Files
+
+- **`pycli`** - Main bash wrapper script
+- **`pycli.conf`** - Configuration file
+- **`install_pycli.sh`** - Installation script
+- **`README.md`** - This documentation
+
+## 🚀 Quick Installation
+
+```bash
+# Run the installation script
+bash install_pycli.sh
+
+# Follow the prompts to configure your shell
+# The script will automatically detect your Python installation
+
+# Verify installation
+pycli --help
+```
+
+## 🎯 Key Features
+
+### Hierarchical Vector Database
+- **Smart Parent Discovery**: Subdirectories automatically use parent's vector database
+- **No Redundant Processing**: Avoids duplicate vectorization in project subdirectories
+- **Central Storage**: All vector databases stored in `~/.claude/vector_db/`
+- **Path-based Organization**: Organized by project directory structure
+
+### Unified Interface
+- **Single Command**: `pycli` replaces complex Python script calls
+- **Intelligent Context**: Automatic file discovery with semantic search
+- **Tool Integration**: Seamless integration with Gemini and Codex
+- **Configuration Management**: Environment-specific Python interpreter paths
+
+## 📋 Common Commands
+
+```bash
+# Initialize new project
+cd /path/to/your/project
+pycli --init
+
+# Smart analysis
+pycli --analyze --query "authentication patterns" --tool gemini
+
+# Direct analysis
+pycli --analyze --tool codex -p "implement user login"
+
+# Maintenance
+pycli --update-embeddings
+pycli --status
+```
+
+## 🔧 Configuration
+
+Edit `~/.claude/scripts/pycli.conf` after installation:
+
+```bash
+# Python interpreter path
+PYTHON_PATH="/usr/bin/python3"
+
+# Vector database root directory
+VECTOR_DB_ROOT="$HOME/.claude/vector_db"
+
+# Python scripts directory
+PYTHON_SCRIPT_DIR="$HOME/.claude/python_script"
+```
+
+## 🏗️ How Hierarchical DB Works
+
+```
+Project Structure:          Vector Database:
+/home/user/myproject/       ~/.claude/vector_db/
+├── src/                    └── home_user_myproject/
+│   ├── auth/                   ├── embeddings.pkl
+│   └── api/                    └── index.json
+└── tests/
+
+# All subdirectories use the single parent DB
+```
+
+## 📖 Documentation
+
+For complete usage information, see:
+- **Strategy Guide**: `~/.claude/workflows/python-tools-strategy.md`
+- **Installation Guide**: Run `bash install_pycli.sh` for guided setup
+
+## 🎪 Migration from Legacy Tools
+
+```bash
+# Replace gemini-wrapper
+# OLD: ~/.claude/scripts/gemini-wrapper -p "prompt"
+# NEW: pycli --analyze --tool gemini -p "prompt"
+
+# Replace codex commands
+# OLD: codex --full-auto exec "task"
+# NEW: pycli --analyze --tool codex -p "task"
+
+# Enhanced with context discovery
+pycli --analyze --query "relevant context" --tool both
+```
+
+## 🐛 Troubleshooting
+
+```bash
+# Check system status
+pycli --status
+
+# Rebuild everything
+pycli --init
+
+# Test search functionality
+pycli --test-search
+
+# View configuration
+cat ~/.claude/scripts/pycli.conf
+```
+
+## 💡 Advanced Usage
+
+### Project Integration
+```bash
+# Add to package.json
+{
+  "scripts": {
+    "analyze": "pycli --analyze --query",
+    "ai-init": "pycli --init",
+    "ai-update": "pycli --update-embeddings"
+  }
+}
+
+# Use in Makefiles
+analyze:
+	pycli --analyze --query "$(QUERY)" --tool gemini
+```
+
+### CI/CD Integration
+```yaml
+# GitHub Actions example
+- name: Update AI Context
+  run: pycli --update-embeddings
+
+- name: Analyze Changes
+  run: pycli --analyze --query "code review" --tool gemini
+```
+
+---
+
+For questions or issues, check the documentation or run `pycli --help`.
--- a/.claude/scripts/install_pycli.sh
+++ b/.claude/scripts/install_pycli.sh
@@ -0,0 +1,302 @@
+#!/bin/bash
+
+#==============================================================================
+# pycli Installation Script
+#
+# This script installs the pycli bash wrapper and configuration files
+# to the ~/.claude directory structure.
+#==============================================================================
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Print colored output
+print_status() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+print_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+#==============================================================================
+# Configuration
+#==============================================================================
+
+SOURCE_DIR="$(cd "$(dirname "$0")" && pwd)"
+INSTALL_BASE="$HOME/.claude"
+INSTALL_DIR="$INSTALL_BASE/scripts"
+PYTHON_SCRIPT_DIR="$INSTALL_BASE/python_script"
+VECTOR_DB_DIR="$INSTALL_BASE/vector_db"
+CONFIG_DIR="$INSTALL_BASE/config"
+LOGS_DIR="$INSTALL_BASE/logs"
+
+#==============================================================================
+# Pre-installation Checks
+#==============================================================================
+
+print_status "Starting pycli installation..."
+print_status "Source directory: $SOURCE_DIR"
+print_status "Install directory: $INSTALL_DIR"
+
+# Check if source files exist
+if [[ ! -f "$SOURCE_DIR/pycli" ]]; then
+    print_error "pycli script not found in $SOURCE_DIR"
+    exit 1
+fi
+
+if [[ ! -f "$SOURCE_DIR/pycli.conf" ]]; then
+    print_error "pycli.conf not found in $SOURCE_DIR"
+    exit 1
+fi
+
+# Check if Python script directory exists
+if [[ ! -d "$PYTHON_SCRIPT_DIR" ]]; then
+    print_warning "Python script directory not found: $PYTHON_SCRIPT_DIR"
+    print_status "Please ensure the Python scripts are installed in ~/.claude/python_script/"
+    read -p "Continue installation anyway? (y/N): " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        print_status "Installation cancelled."
+        exit 0
+    fi
+fi
+
+#==============================================================================
+# Create Directory Structure
+#==============================================================================
+
+print_status "Creating directory structure..."
+
+# Create all required directories
+directories=(
+    "$INSTALL_BASE"
+    "$INSTALL_DIR"
+    "$VECTOR_DB_DIR"
+    "$CONFIG_DIR"
+    "$LOGS_DIR"
+)
+
+for dir in "${directories[@]}"; do
+    if [[ ! -d "$dir" ]]; then
+        mkdir -p "$dir"
+        print_status "Created directory: $dir"
+    else
+        print_status "Directory exists: $dir"
+    fi
+done
+
+#==============================================================================
+# Install Files
+#==============================================================================
+
+print_status "Installing pycli files..."
+
+# Backup existing files if they exist
+if [[ -f "$INSTALL_DIR/pycli" ]]; then
+    backup_file="$INSTALL_DIR/pycli.backup.$(date +%Y%m%d_%H%M%S)"
+    cp "$INSTALL_DIR/pycli" "$backup_file"
+    print_warning "Backed up existing pycli to: $backup_file"
+fi
+
+if [[ -f "$INSTALL_DIR/pycli.conf" ]]; then
+    backup_file="$INSTALL_DIR/pycli.conf.backup.$(date +%Y%m%d_%H%M%S)"
+    cp "$INSTALL_DIR/pycli.conf" "$backup_file"
+    print_warning "Backed up existing pycli.conf to: $backup_file"
+fi
+
+# Copy files
+cp "$SOURCE_DIR/pycli" "$INSTALL_DIR/"
+cp "$SOURCE_DIR/pycli.conf" "$INSTALL_DIR/"
+
+# Make executable
+chmod +x "$INSTALL_DIR/pycli"
+
+print_success "Files installed successfully"
+
+#==============================================================================
+# Configuration Updates
+#==============================================================================
+
+print_status "Updating configuration..."
+
+# Detect Python path
+PYTHON_CANDIDATES=(
+    "/usr/bin/python3"
+    "/usr/local/bin/python3"
+    "/opt/conda/bin/python"
+    "$(which python3 2>/dev/null || echo "")"
+    "$(which python 2>/dev/null || echo "")"
+)
+
+DETECTED_PYTHON=""
+for candidate in "${PYTHON_CANDIDATES[@]}"; do
+    if [[ -n "$candidate" ]] && [[ -x "$candidate" ]]; then
+        # Test if it's Python 3
+        if "$candidate" -c "import sys; exit(0 if sys.version_info >= (3, 6) else 1)" 2>/dev/null; then
+            DETECTED_PYTHON="$candidate"
+            break
+        fi
+    fi
+done
+
+if [[ -n "$DETECTED_PYTHON" ]]; then
+    print_success "Detected Python: $DETECTED_PYTHON"
+
+    # Update configuration file
+    sed -i.bak "s|^PYTHON_PATH=.*|PYTHON_PATH=\"$DETECTED_PYTHON\"|" "$INSTALL_DIR/pycli.conf"
+    print_status "Updated PYTHON_PATH in configuration"
+else
+    print_warning "Could not detect Python 3.6+. Please manually update PYTHON_PATH in:"
+    print_warning "  $INSTALL_DIR/pycli.conf"
+fi
+
+#==============================================================================
+# Shell Integration Setup
+#==============================================================================
+
+print_status "Setting up shell integration..."
+
+# Detect shell
+SHELL_RC=""
+if [[ -n "${BASH_VERSION:-}" ]] || [[ "$SHELL" == *"bash"* ]]; then
+    SHELL_RC="$HOME/.bashrc"
+elif [[ -n "${ZSH_VERSION:-}" ]] || [[ "$SHELL" == *"zsh"* ]]; then
+    SHELL_RC="$HOME/.zshrc"
+fi
+
+# Function to add alias/path to shell config
+add_to_shell_config() {
+    local config_file="$1"
+    local content="$2"
+
+    if [[ -f "$config_file" ]]; then
+        if ! grep -q "pycli" "$config_file"; then
+            echo "" >> "$config_file"
+            echo "# pycli - Python CLI Wrapper" >> "$config_file"
+            echo "$content" >> "$config_file"
+            print_success "Added pycli to $config_file"
+            return 0
+        else
+            print_warning "pycli already configured in $config_file"
+            return 1
+        fi
+    fi
+    return 1
+}
+
+# Try to add alias automatically
+ALIAS_ADDED=false
+PATH_ADDED=false
+
+if [[ -n "$SHELL_RC" ]]; then
+    # Try to add alias
+    if add_to_shell_config "$SHELL_RC" "alias pycli='$INSTALL_DIR/pycli'"; then
+        ALIAS_ADDED=true
+    fi
+
+    # Also add to PATH
+    if add_to_shell_config "$SHELL_RC" "export PATH=\"\$PATH:$INSTALL_DIR\""; then
+        PATH_ADDED=true
+    fi
+fi
+
+#==============================================================================
+# Test Installation
+#==============================================================================
+
+print_status "Testing installation..."
+
+# Test that the script is executable
+if [[ -x "$INSTALL_DIR/pycli" ]]; then
+    print_success "pycli script is executable"
+else
+    print_error "pycli script is not executable"
+    exit 1
+fi
+
+# Test configuration loading
+if "$INSTALL_DIR/pycli" --help >/dev/null 2>&1; then
+    print_success "pycli configuration loads correctly"
+else
+    print_warning "pycli configuration test failed - check Python path"
+fi
+
+#==============================================================================
+# Installation Summary
+#==============================================================================
+
+print_success "Installation completed successfully!"
+echo
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "📁 Installation Summary:"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  • Executable:   $INSTALL_DIR/pycli"
+echo "  • Config:       $INSTALL_DIR/pycli.conf"
+echo "  • Vector DB:    $VECTOR_DB_DIR/"
+echo "  • Logs:         $LOGS_DIR/"
+echo
+
+echo "🚀 Quick Start:"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+if [[ "$ALIAS_ADDED" == true ]]; then
+    echo "  1. Reload your shell configuration:"
+    echo "     source $SHELL_RC"
+    echo
+    echo "  2. Initialize vector DB for a project:"
+    echo "     cd /path/to/your/project"
+    echo "     pycli --init"
+    echo
+    echo "  3. Start analyzing code:"
+    echo "     pycli --analyze --query \"authentication patterns\" --tool gemini"
+else
+    echo "  1. Add pycli to your shell configuration:"
+    if [[ -n "$SHELL_RC" ]]; then
+        echo "     echo \"alias pycli='$INSTALL_DIR/pycli'\" >> $SHELL_RC"
+        echo "     source $SHELL_RC"
+    else
+        echo "     alias pycli='$INSTALL_DIR/pycli'"
+    fi
+    echo
+    echo "  2. Or add to PATH:"
+    echo "     export PATH=\"\$PATH:$INSTALL_DIR\""
+    echo
+    echo "  3. Initialize vector DB for a project:"
+    echo "     cd /path/to/your/project"
+    echo "     pycli --init"
+    echo
+    echo "  4. Start analyzing code:"
+    echo "     pycli --analyze --query \"authentication patterns\" --tool gemini"
+fi
+
+echo
+echo "📚 Documentation:"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  • Help:         pycli --help"
+echo "  • Strategy:     ~/.claude/workflows/python-tools-strategy.md"
+echo
+echo "⚙️  Configuration:"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  • Edit config:  $INSTALL_DIR/pycli.conf"
+
+if [[ -z "$DETECTED_PYTHON" ]]; then
+    echo "  • ⚠️  Please update PYTHON_PATH in pycli.conf"
+fi
+
+echo
+print_success "Installation complete! 🎉"
--- a/.claude/scripts/pycli
+++ b/.claude/scripts/pycli
@@ -0,0 +1,225 @@
+#!/bin/bash
+
+#==============================================================================
+# pycli - Python CLI Wrapper with Hierarchical Vector Database Support
+#
+# This script provides a bash wrapper for the Python-based analysis CLI,
+# with intelligent hierarchical vector database management.
+#
+# Features:
+# - Hierarchical vector database support (subdirs use parent's DB)
+# - Configurable Python environment
+# - Central vector database storage
+# - Smart project root detection
+#==============================================================================
+
+set -euo pipefail
+
+# Load configuration
+CONFIG_FILE="$(dirname "$0")/pycli.conf"
+if [[ -f "$CONFIG_FILE" ]]; then
+    source "$CONFIG_FILE"
+else
+    echo "Error: Configuration file not found: $CONFIG_FILE"
+    echo "Please ensure pycli.conf exists in the same directory as this script."
+    exit 1
+fi
+
+# Validate required configuration
+if [[ -z "${PYTHON_PATH:-}" ]]; then
+    echo "Error: PYTHON_PATH not set in configuration"
+    exit 1
+fi
+
+if [[ -z "${PYTHON_SCRIPT_DIR:-}" ]]; then
+    echo "Error: PYTHON_SCRIPT_DIR not set in configuration"
+    exit 1
+fi
+
+if [[ -z "${VECTOR_DB_ROOT:-}" ]]; then
+    echo "Error: VECTOR_DB_ROOT not set in configuration"
+    exit 1
+fi
+
+# Check if Python is available
+if ! command -v "$PYTHON_PATH" &> /dev/null; then
+    echo "Error: Python not found at $PYTHON_PATH"
+    echo "Please update PYTHON_PATH in $CONFIG_FILE"
+    exit 1
+fi
+
+# Check if Python script directory exists
+if [[ ! -d "$PYTHON_SCRIPT_DIR" ]]; then
+    echo "Error: Python script directory not found: $PYTHON_SCRIPT_DIR"
+    exit 1
+fi
+
+# Get current directory (will be used as project root for indexing)
+CURRENT_DIR=$(pwd)
+
+#==============================================================================
+# Helper Functions
+#==============================================================================
+
+# Convert current path to vector DB path
+# e.g., /home/user/project/subdir -> ~/.claude/vector_db/home_user_project_subdir
+get_vector_db_path() {
+    local path="$1"
+    # Replace / with _ and remove leading /
+    local safe_path="${path//\//_}"
+    safe_path="${safe_path#_}"
+    # Handle Windows paths (C: -> C_)
+    safe_path="${safe_path//:/_}"
+    echo "$VECTOR_DB_ROOT/$safe_path"
+}
+
+# Find nearest parent with existing vector DB
+find_project_root() {
+    local dir="$CURRENT_DIR"
+    local max_depth=10  # Prevent infinite loops
+    local depth=0
+
+    while [[ "$dir" != "/" ]] && [[ "$depth" -lt "$max_depth" ]]; do
+        local db_path=$(get_vector_db_path "$dir")
+
+        # Check if vector DB exists and has required files
+        if [[ -d "$db_path" ]] && ([[ -f "$db_path/embeddings.pkl" ]] || [[ -f "$db_path/index.json" ]]); then
+            echo "$dir"
+            return 0
+        fi
+
+        # Move to parent directory
+        local parent_dir=$(dirname "$dir")
+        if [[ "$parent_dir" == "$dir" ]]; then
+            break  # Reached root
+        fi
+        dir="$parent_dir"
+        ((depth++))
+    done
+
+    # No parent vector DB found, use current directory
+    echo "$CURRENT_DIR"
+}
+
+# Show help message
+show_help() {
+    cat << EOF
+pycli - Python CLI Wrapper with Hierarchical Vector Database Support
+
+USAGE:
+    pycli [OPTIONS]
+
+INITIALIZATION:
+    --init                    Initialize vector DB for current directory
+    --rebuild-index           Rebuild file index from scratch
+    --update-embeddings       Update vector embeddings for changed files
+
+ANALYSIS:
+    --analyze                 Run analysis with tool
+    --query TEXT              Semantic search query for context discovery
+    -p, --prompt TEXT         Direct prompt for analysis
+    --tool [gemini|codex|both] Which tool to use (default: $DEFAULT_TOOL)
+    --top-k INTEGER          Number of similar files to find (default: $DEFAULT_TOP_K)
+
+STATUS:
+    --status                 Show system status
+    --test-search            Test vector search functionality
+
+EXAMPLES:
+    # Initialize vector DB for current project
+    pycli --init
+
+    # Smart analysis with context discovery
+    pycli --analyze --query "authentication patterns" --tool gemini
+
+    # Direct analysis with known prompt
+    pycli --analyze --tool codex -p "implement user login"
+
+    # Update embeddings after code changes
+    pycli --update-embeddings
+
+    # Check system status
+    pycli --status
+
+For more information, see: ~/.claude/workflows/python-tools-strategy.md
+EOF
+}
+
+#==============================================================================
+# Main Logic
+#==============================================================================
+
+# Handle help
+if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]] || [[ $# -eq 0 ]]; then
+    show_help
+    exit 0
+fi
+
+# Determine action based on arguments
+case "${1:-}" in
+    --init|--rebuild-index)
+        # For initialization, always use current directory
+        PROJECT_ROOT="$CURRENT_DIR"
+        echo "Initializing vector database for: $PROJECT_ROOT"
+        ;;
+    *)
+        # For other operations, find nearest project root
+        PROJECT_ROOT=$(find_project_root)
+        if [[ "$PROJECT_ROOT" != "$CURRENT_DIR" ]]; then
+            echo "Using existing vector database from: $PROJECT_ROOT"
+        fi
+        ;;
+esac
+
+VECTOR_DB_PATH=$(get_vector_db_path "$PROJECT_ROOT")
+
+# Create vector DB directory if needed
+mkdir -p "$VECTOR_DB_PATH"
+
+# Determine which Python script to call
+if [[ "${1:-}" == "--update-embeddings" ]] || [[ "${1:-}" == "--rebuild-index" ]] || [[ "${1:-}" == "--init" ]]; then
+    # Use indexer.py for indexing operations
+    PYTHON_SCRIPT="$PYTHON_SCRIPT_DIR/indexer.py"
+
+    # Map --init to --rebuild-index --update-embeddings
+    if [[ "${1:-}" == "--init" ]]; then
+        set -- "--rebuild-index" "--update-embeddings"
+    fi
+
+    if [[ ! -f "$PYTHON_SCRIPT" ]]; then
+        echo "Error: indexer.py not found at $PYTHON_SCRIPT"
+        exit 1
+    fi
+else
+    # Use cli.py for analysis operations
+    PYTHON_SCRIPT="$PYTHON_SCRIPT_DIR/cli.py"
+
+    if [[ ! -f "$PYTHON_SCRIPT" ]]; then
+        echo "Error: cli.py not found at $PYTHON_SCRIPT"
+        exit 1
+    fi
+fi
+
+#==============================================================================
+# Environment Setup and Execution
+#==============================================================================
+
+# Set environment variables for Python scripts
+export PYCLI_VECTOR_DB_PATH="$VECTOR_DB_PATH"
+export PYCLI_PROJECT_ROOT="$PROJECT_ROOT"
+export PYCLI_CONFIG_FILE="$CONFIG_FILE"
+
+# Add some debugging info in verbose mode
+if [[ "${PYCLI_VERBOSE:-}" == "1" ]]; then
+    echo "Debug: PROJECT_ROOT=$PROJECT_ROOT"
+    echo "Debug: VECTOR_DB_PATH=$VECTOR_DB_PATH"
+    echo "Debug: PYTHON_SCRIPT=$PYTHON_SCRIPT"
+    echo "Debug: Arguments: $*"
+fi
+
+# Execute Python script with all arguments
+echo "Executing: $PYTHON_PATH $PYTHON_SCRIPT --root-path \"$PROJECT_ROOT\" $*"
+
+exec "$PYTHON_PATH" "$PYTHON_SCRIPT" \
+    --root-path "$PROJECT_ROOT" \
+    "$@"
--- a/.claude/scripts/pycli.conf
+++ b/.claude/scripts/pycli.conf
@@ -0,0 +1,159 @@
+#==============================================================================
+# pycli Configuration File
+#
+# This file contains configuration settings for the pycli bash wrapper.
+# Modify these settings according to your environment.
+#==============================================================================
+
+#------------------------------------------------------------------------------
+# Python Environment Configuration
+#------------------------------------------------------------------------------
+
+# Path to Python interpreter
+# Examples:
+#   - System Python: /usr/bin/python3
+#   - Conda: /opt/conda/bin/python
+#   - Virtual env: /home/user/.virtualenvs/myenv/bin/python
+#   - Windows: /c/Python39/python.exe
+PYTHON_PATH="/usr/bin/python3"
+
+# Alternative Python paths for different environments
+# Uncomment and modify as needed:
+# PYTHON_PATH="/opt/conda/bin/python"              # Conda
+# PYTHON_PATH="$HOME/.pyenv/versions/3.11.0/bin/python"  # pyenv
+# PYTHON_PATH="/c/Python311/python.exe"           # Windows
+
+#------------------------------------------------------------------------------
+# Directory Configuration
+#------------------------------------------------------------------------------
+
+# Python script location (should point to ~/.claude/python_script)
+PYTHON_SCRIPT_DIR="$HOME/.claude/python_script"
+
+# Central vector database storage location
+VECTOR_DB_ROOT="$HOME/.claude/vector_db"
+
+# Cache directory for temporary files
+CACHE_DIR="$HOME/.claude/cache"
+
+#------------------------------------------------------------------------------
+# Default Tool Settings
+#------------------------------------------------------------------------------
+
+# Default tool to use when not specified
+# Options: gemini, codex, both
+DEFAULT_TOOL="gemini"
+
+# Default number of similar files to return in vector search
+DEFAULT_TOP_K="10"
+
+# Default similarity threshold for vector search (0.0-1.0)
+SIMILARITY_THRESHOLD="0.3"
+
+# Default timeout for tool execution (seconds)
+TOOL_TIMEOUT="300"
+
+#------------------------------------------------------------------------------
+# Vector Database Configuration
+#------------------------------------------------------------------------------
+
+# Enable hierarchical vector database mode
+# When true, subdirectories will use parent directory's vector database
+HIERARCHICAL_MODE="true"
+
+# Maximum depth to search for parent vector databases
+MAX_SEARCH_DEPTH="10"
+
+# Minimum files required to create a separate vector database
+MIN_FILES_FOR_SEPARATE_DB="50"
+
+#------------------------------------------------------------------------------
+# Performance Settings
+#------------------------------------------------------------------------------
+
+# Enable verbose output for debugging
+# Set to "1" to enable, "0" to disable
+PYCLI_VERBOSE="0"
+
+# Enable caching of analysis results
+ENABLE_CACHING="true"
+
+# Cache TTL in seconds (1 hour default)
+CACHE_TTL="3600"
+
+#------------------------------------------------------------------------------
+# Integration Settings
+#------------------------------------------------------------------------------
+
+# Gemini wrapper compatibility mode
+# Set to "true" to enable compatibility with existing gemini-wrapper scripts
+GEMINI_COMPAT_MODE="true"
+
+# Codex integration settings
+CODEX_COMPAT_MODE="true"
+
+# Auto-build index if not found
+AUTO_BUILD_INDEX="true"
+
+# Auto-update embeddings when files change
+AUTO_UPDATE_EMBEDDINGS="true"
+
+#------------------------------------------------------------------------------
+# Logging Configuration
+#------------------------------------------------------------------------------
+
+# Log level: DEBUG, INFO, WARNING, ERROR
+LOG_LEVEL="INFO"
+
+# Log file location
+LOG_FILE="$HOME/.claude/logs/pycli.log"
+
+# Enable log rotation
+ENABLE_LOG_ROTATION="true"
+
+# Maximum log file size (MB)
+MAX_LOG_SIZE="10"
+
+#------------------------------------------------------------------------------
+# Advanced Configuration
+#------------------------------------------------------------------------------
+
+# Custom configuration file for Python scripts
+# Leave empty to use default config.yaml
+PYTHON_CONFIG_FILE=""
+
+# Additional Python path directories
+# Uncomment and modify if you need to add custom modules
+# ADDITIONAL_PYTHON_PATH="/path/to/custom/modules"
+
+# Environment variables to pass to Python scripts
+# Uncomment and modify as needed
+# CUSTOM_ENV_VAR1="value1"
+# CUSTOM_ENV_VAR2="value2"
+
+#------------------------------------------------------------------------------
+# Platform-Specific Settings
+#------------------------------------------------------------------------------
+
+# Windows-specific settings
+if [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "cygwin" ]]; then
+    # Adjust paths for Windows
+    VECTOR_DB_ROOT="${VECTOR_DB_ROOT//\\//}"
+    PYTHON_SCRIPT_DIR="${PYTHON_SCRIPT_DIR//\\//}"
+fi
+
+# macOS-specific settings
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    # macOS-specific optimizations
+    export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
+fi
+
+#------------------------------------------------------------------------------
+# User Customization
+#------------------------------------------------------------------------------
+
+# Load user-specific configuration if it exists
+USER_CONFIG="$HOME/.claude/config/pycli.user.conf"
+if [[ -f "$USER_CONFIG" ]]; then
+    source "$USER_CONFIG"
+fi