diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index f7e408eac..5d5a88eb7 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -59,9 +59,22 @@ repos:
   hooks:
   - id: check-github-workflows
 
+# Ansys pre-commit hooks for license headers and version management
 - repo: https://github.com/ansys/pre-commit-hooks
   rev: v0.5.2
   hooks:
   - id: add-license-headers
     args:
     - --start_year=2021
+
+# Automatic version increment on pre-push
+- repo: local
+  hooks:
+  - id: auto-version-increment
+    name: Auto Version Increment
+    entry: cmd /c "chcp 65001 > NUL && python .script/pre_push_version_increment.py"
+    language: system
+    stages: [pre-push]
+    always_run: true
+    pass_filenames: false
+    description: "Automatically increment version based on changes"
diff --git a/.script/auto_version_increment.py b/.script/auto_version_increment.py
new file mode 100644
index 000000000..6abbdee13
--- /dev/null
+++ b/.script/auto_version_increment.py
@@ -0,0 +1,418 @@
+#!/usr/bin/env python3
+"""
+Automatic Version Incrementer for PySherlock
+
+This script automatically increments the version in pyproject.toml based on:
+1. Changelog entries (using towncrier fragments)
+2. Git commit messages
+3. File changes analysis
+
+It runs as a pre-push hook to automatically bump version before merging.
+"""
+
+from enum import Enum
+from pathlib import Path
+import re
+import subprocess
+import sys
+from typing import List, Optional, Tuple
+
+import toml
+
+
+class VersionBumpType(Enum):
+    PATCH = "patch"
+    MINOR = "minor"
+    MAJOR = "major"
+
+
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    BOLD = "\033[1m"
+    NC = "\033[0m"
+
+
+def log(message: str, color: str = Colors.NC):
+    """Print colored log message."""
+    print(f"{color}{message}{Colors.NC}")
+
+
+def run_git_command(command: List[str]) -> Tuple[bool, str]:
+    """Run git command and return success status and output."""
+    try:
+        result = subprocess.run(["git"] + command, capture_output=True, text=True, check=True)
+        return True, result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        return False, e.stderr.strip() if e.stderr else str(e)
+
+
+def parse_version(version_str: str) -> Tuple[int, int, int, str]:
+    """Parse semantic version string into components."""
+    # Handle dev versions like "0.12.dev0"
+    if ".dev" in version_str:
+        version_str = version_str.split(".dev")[0]
+
+    # Parse semantic version
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)(.*)$", version_str)
+    if match:
+        major = int(match.group(1))
+        minor = int(match.group(2))
+        patch = int(match.group(3))
+        suffix = match.group(4)
+        return major, minor, patch, suffix
+
+    # Fallback for incomplete versions
+    parts = version_str.split(".")
+    major = int(parts[0]) if len(parts) > 0 else 0
+    minor = int(parts[1]) if len(parts) > 1 else 0
+    patch = int(parts[2]) if len(parts) > 2 else 0
+    return major, minor, patch, ""
+
+
+def increment_version(version_str: str, bump_type: VersionBumpType) -> str:
+    """Increment version based on bump type."""
+    major, minor, patch, suffix = parse_version(version_str)
+
+    if bump_type == VersionBumpType.MAJOR:
+        major += 1
+        minor = 0
+        patch = 0
+    elif bump_type == VersionBumpType.MINOR:
+        minor += 1
+        patch = 0
+    else:  # PATCH
+        patch += 1
+
+    # Remove dev suffix for releases
+    return f"{major}.{minor}.{patch}"
+
+
+def analyze_changelog_fragments() -> VersionBumpType:
+    """Analyze towncrier changelog fragments to determine version bump."""
+    changelog_dir = Path("doc/changelog.d")
+    if not changelog_dir.exists():
+        return VersionBumpType.PATCH
+
+    fragment_files = list(changelog_dir.glob("*.*.md"))
+    if not fragment_files:
+        return VersionBumpType.PATCH
+
+    # Analyze fragment types for version bump determination
+    has_breaking = False
+    has_feature = False
+    has_fix = False
+
+    for fragment in fragment_files:
+        fragment_name = fragment.stem
+        if any(keyword in fragment_name.lower() for keyword in ["added", "changed"]):
+            if any(
+                breaking in fragment.read_text().lower()
+                for breaking in ["breaking", "breaking change", "incompatible"]
+            ):
+                has_breaking = True
+            else:
+                has_feature = True
+        elif "fixed" in fragment_name.lower():
+            has_fix = True
+
+    # Determine bump type based on changes
+    if has_breaking:
+        return VersionBumpType.MAJOR
+    elif has_feature:
+        return VersionBumpType.MINOR
+    else:
+        return VersionBumpType.PATCH
+
+
+def analyze_commit_messages() -> VersionBumpType:
+    """Analyze commit messages since last tag to determine version bump."""
+    # Get commits since last tag
+    success, output = run_git_command(["describe", "--tags", "--abbrev=0"])
+    if not success:
+        # No tags exist, analyze all commits on branch
+        success, output = run_git_command(["log", "--oneline", "origin/main..HEAD"])
+    else:
+        last_tag = output
+        success, output = run_git_command(["log", f"{last_tag}..HEAD", "--oneline"])
+
+    if not success or not output:
+        return VersionBumpType.PATCH
+
+    commit_messages = output.lower()
+
+    # Check for breaking changes
+    breaking_keywords = [
+        "breaking change",
+        "breaking:",
+        "break:",
+        "major:",
+        "incompatible",
+        "remove",
+        "delete api",
+    ]
+    if any(keyword in commit_messages for keyword in breaking_keywords):
+        return VersionBumpType.MAJOR
+
+    # Check for new features
+    feature_keywords = [
+        "feat:",
+        "feature:",
+        "add:",
+        "new:",
+        "minor:",
+        "implement",
+        "enhance",
+        "improvement",
+    ]
+    if any(keyword in commit_messages for keyword in feature_keywords):
+        return VersionBumpType.MINOR
+
+    # Default to patch for fixes, docs, etc.
+    return VersionBumpType.PATCH
+
+
+def analyze_code_changes() -> VersionBumpType:
+    """Analyze code changes to determine appropriate version bump."""
+    # Get changed files
+    success, output = run_git_command(["diff", "--name-only", "origin/main..HEAD"])
+
+    if not success:
+        return VersionBumpType.PATCH
+
+    changed_files = output.split("\n") if output else []
+
+    # Analyze types of changes
+    has_api_changes = False
+    has_new_features = False
+    has_breaking_changes = False
+
+    for file in changed_files:
+        file_lower = file.lower()
+
+        # Check for API changes
+        if any(
+            pattern in file
+            for pattern in ["src/ansys/sherlock/core/", "__init__.py", "api", "interface"]
+        ):
+            # Get the actual diff to analyze
+            success, diff_output = run_git_command(["diff", "origin/main..HEAD", "--", file])
+
+            if success and diff_output:
+                diff_lower = diff_output.lower()
+
+                # Look for breaking changes
+                if any(
+                    pattern in diff_lower
+                    for pattern in [
+                        "-def ",
+                        "-class ",
+                        "removed",
+                        "deprecated",
+                        "raise notimplementederror",
+                        "breaking",
+                    ]
+                ):
+                    has_breaking_changes = True
+
+                # Look for new features (new functions/classes)
+                if any(
+                    pattern in diff_lower
+                    for pattern in ["+def ", "+class ", "new feature", "implement"]
+                ):
+                    has_new_features = True
+
+                # Look for API changes
+                if "+def " in diff_lower or "+class " in diff_lower:
+                    has_api_changes = True
+
+    # Determine version bump
+    if has_breaking_changes:
+        return VersionBumpType.MAJOR
+    elif has_new_features or has_api_changes:
+        return VersionBumpType.MINOR
+    else:
+        return VersionBumpType.PATCH
+
+
+def determine_version_bump() -> VersionBumpType:
+    """Determine the appropriate version bump by analyzing multiple sources."""
+    log("🔍 Analyzing changes to determine version bump...", Colors.BLUE)
+
+    # Analyze different sources
+    changelog_bump = analyze_changelog_fragments()
+    commit_bump = analyze_commit_messages()
+    code_bump = analyze_code_changes()
+
+    log(f"📋 Changelog analysis suggests: {changelog_bump.value}", Colors.BLUE)
+    log(f"💬 Commit message analysis suggests: {commit_bump.value}", Colors.BLUE)
+    log(f"📝 Code changes analysis suggests: {code_bump.value}", Colors.BLUE)
+
+    # Choose the highest priority bump type
+    bump_priority = {VersionBumpType.MAJOR: 3, VersionBumpType.MINOR: 2, VersionBumpType.PATCH: 1}
+
+    all_bumps = [changelog_bump, commit_bump, code_bump]
+    final_bump = max(all_bumps, key=lambda x: bump_priority[x])
+
+    log(f"🎯 Final decision: {final_bump.value} version bump", Colors.GREEN)
+    return final_bump
+
+
+def get_current_version() -> Optional[str]:
+    """Get current version from pyproject.toml."""
+    try:
+        with open("pyproject.toml", "r") as f:
+            data = toml.load(f)
+            return data.get("project", {}).get("version")
+    except Exception as e:
+        log(f"Error reading pyproject.toml: {e}", Colors.RED)
+        return None
+
+
+def update_version_in_pyproject(new_version: str) -> bool:
+    """Update version in pyproject.toml file."""
+    try:
+        with open("pyproject.toml", "r") as f:
+            content = f.read()
+
+        # Replace version using regex to preserve formatting
+        updated_content = re.sub(
+            r'^version = "[^"]*"', f'version = "{new_version}"', content, flags=re.MULTILINE
+        )
+
+        if updated_content == content:
+            log("❌ Could not find version field in pyproject.toml", Colors.RED)
+            return False
+
+        with open("pyproject.toml", "w") as f:
+            f.write(updated_content)
+
+        return True
+    except Exception as e:
+        log(f"Error updating pyproject.toml: {e}", Colors.RED)
+        return False
+
+
+def should_skip_version_increment() -> bool:
+    """Check if version increment should be skipped."""
+    current_branch = ""
+    success, output = run_git_command(["rev-parse", "--abbrev-ref", "HEAD"])
+    if success:
+        current_branch = output
+
+    # Skip on main branch
+    if current_branch in ["main", "master"]:
+        log("ℹ️  On main branch, skipping auto-increment", Colors.YELLOW)
+        return True
+
+    # Skip if no changes since main
+    success, output = run_git_command(["diff", "--name-only", "origin/main..HEAD"])
+
+    if not success or not output.strip():
+        log("ℹ️  No changes detected, skipping auto-increment", Colors.YELLOW)
+        return True
+
+    # Always allow version increment in test branches
+    if "optimization/version-check" in current_branch:
+        return False
+
+    # Check if version was already manually updated
+    success, output = run_git_command(
+        ["diff", "origin/main..HEAD", "--name-only", "pyproject.toml"]
+    )
+
+    if success and "pyproject.toml" in output:
+        # Check if version line was changed
+        success, diff_output = run_git_command(["diff", "origin/main..HEAD", "pyproject.toml"])
+
+        if success and "version = " in diff_output:
+            log("ℹ️  Version already manually updated, skipping auto-increment", Colors.YELLOW)
+            return True
+
+    return False
+
+
+def commit_version_change(old_version: str, new_version: str, bump_type: VersionBumpType):
+    """Commit the version change."""
+    log("📝 Committing version change...", Colors.BLUE)
+
+    # Stage the pyproject.toml file
+    success, _ = run_git_command(["add", "pyproject.toml"])
+    if not success:
+        log("❌ Failed to stage pyproject.toml", Colors.RED)
+        return False
+
+    # Create commit message
+    commit_msg = f"chore: bump version from {old_version} to {new_version} ({bump_type.value})"
+
+    # Commit the change
+    success, _ = run_git_command(["commit", "-m", commit_msg])
+    if not success:
+        log("❌ Failed to commit version change", Colors.RED)
+        return False
+
+    log(f"✅ Committed version bump: {old_version} → {new_version}", Colors.GREEN)
+    return True
+
+
+def main():
+    """Main entry point for automatic version incrementer."""
+    log("🚀 Automatic Version Incrementer for PySherlock", Colors.BOLD)
+
+    # Check if we're in a git repository
+    if not Path(".git").exists():
+        log("❌ Not in a git repository", Colors.RED)
+        return 1
+
+    # Check if pyproject.toml exists
+    if not Path("pyproject.toml").exists():
+        log("❌ pyproject.toml not found", Colors.RED)
+        return 1
+
+    # Check if we should skip version increment
+    if should_skip_version_increment():
+        return 0
+
+    # Get current version
+    current_version = get_current_version()
+    if not current_version:
+        log("❌ Could not read current version", Colors.RED)
+        return 1
+
+    log(f"📦 Current version: {current_version}", Colors.BLUE)
+
+    # Determine version bump type
+    bump_type = determine_version_bump()
+
+    # Calculate new version
+    new_version = increment_version(current_version, bump_type)
+
+    log(f"🎯 Bumping version: {current_version} → {new_version} ({bump_type.value})", Colors.GREEN)
+
+    # Confirm with user (optional - can be disabled for full automation)
+    if "--no-confirm" not in sys.argv:
+        response = input(f"\nProceed with version bump to {new_version}? (Y/n): ").lower().strip()
+        if response and response not in ["y", "yes"]:
+            log("❌ Version bump cancelled by user", Colors.YELLOW)
+            return 1
+
+    # Update version in pyproject.toml
+    if not update_version_in_pyproject(new_version):
+        return 1
+
+    log(f"✅ Updated pyproject.toml with version {new_version}", Colors.GREEN)
+
+    # Commit the change
+    if not commit_version_change(current_version, new_version, bump_type):
+        return 1
+
+    log("\n🎉 Version auto-increment completed successfully!", Colors.GREEN)
+    log(f"📦 New version: {new_version}", Colors.BOLD)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.script/pre_push_version_increment.py b/.script/pre_push_version_increment.py
new file mode 100644
index 000000000..a9124cba3
--- /dev/null
+++ b/.script/pre_push_version_increment.py
@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""
+Pre-push hook for automatic version increment
+
+This script is called as a pre-push hook to automatically increment
+the version before pushing changes to the repository.
+"""
+
+from pathlib import Path
+import subprocess
+import sys
+
+
+def main():
+    """Pre-push hook entry point."""
+    # Get the directory where this script is located
+    script_dir = Path(__file__).parent
+
+    # Path to the main auto increment script
+    auto_increment_script = script_dir / "auto_version_increment.py"
+
+    if not auto_increment_script.exists():
+        print("❌ Auto increment script not found:", auto_increment_script)
+        return 1
+
+    # Run the auto increment script with no confirmation (automated)
+    try:
+        result = subprocess.run(
+            [sys.executable, str(auto_increment_script), "--no-confirm"], check=False
+        )
+
+        return result.returncode
+    except Exception as e:
+        print(f"❌ Error running auto increment: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.script/setup_pysherlock_automation.py b/.script/setup_pysherlock_automation.py
new file mode 100644
index 000000000..0eb206200
--- /dev/null
+++ b/.script/setup_pysherlock_automation.py
@@ -0,0 +1,387 @@
+#!/usr/bin/env python3
+"""
+Setup automatic version increment for PySherlock
+
+This script sets up the automation to automatically increment versions
+in PySherlock when changes are pushed.
+"""
+
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+
+
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    BOLD = "\033[1m"
+    NC = "\033[0m"
+
+
+def log(message: str, color: str = Colors.NC):
+    """Print colored log message."""
+    print(f"{color}{message}{Colors.NC}")
+
+
+def run_command(command: list, check: bool = True) -> tuple[bool, str]:
+    """Run a command and return success status and output."""
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, check=check)
+        return True, result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        return False, e.stderr.strip() if e.stderr else str(e)
+
+
+def check_prerequisites():
+    """Check if all prerequisites are installed."""
+    log("🔍 Checking prerequisites...", Colors.BLUE)
+
+    # Check if we're in PySherlock repository
+    if not Path("pyproject.toml").exists():
+        log("❌ pyproject.toml not found. Are you in the PySherlock repository?", Colors.RED)
+        return False
+
+    # Check if it's actually PySherlock
+    try:
+        with open("pyproject.toml", "r") as f:
+            content = f.read()
+            if "ansys-sherlock-core" not in content and "pysherlock" not in content.lower():
+                log("❌ This doesn't appear to be the PySherlock repository", Colors.RED)
+                return False
+    except Exception as e:
+        log(f"❌ Error reading pyproject.toml: {e}", Colors.RED)
+        return False
+
+    # Check git
+    success, _ = run_command(["git", "--version"])
+    if not success:
+        log("❌ Git is not installed or not accessible", Colors.RED)
+        return False
+
+    # Check Python
+    success, _ = run_command([sys.executable, "--version"])
+    if not success:
+        log("❌ Python is not accessible", Colors.RED)
+        return False
+
+    log("✅ Prerequisites check passed", Colors.GREEN)
+    return True
+
+
+def install_dependencies():
+    """Install required dependencies."""
+    log("📦 Installing dependencies...", Colors.BLUE)
+
+    dependencies = ["toml", "pre-commit"]
+
+    for dep in dependencies:
+        log(f"Installing {dep}...", Colors.BLUE)
+        success, output = run_command([sys.executable, "-m", "pip", "install", dep])
+
+        if not success:
+            log(f"❌ Failed to install {dep}: {output}", Colors.RED)
+            return False
+
+        log(f"✅ {dep} installed successfully", Colors.GREEN)
+
+    return True
+
+
+def setup_automation_scripts():
+    """Copy automation scripts to PySherlock repository."""
+    log("📄 Setting up automation scripts...", Colors.BLUE)
+
+    # Create automation directory in PySherlock
+    automation_dir = Path(".pysherlock-automation")
+    automation_dir.mkdir(exist_ok=True)
+
+    # Get current script directory
+    current_dir = Path(__file__).parent
+
+    # Scripts to copy
+    scripts_to_copy = ["auto_version_increment.py", "pre_push_version_increment.py"]
+
+    for script in scripts_to_copy:
+        source = current_dir / script
+        dest = automation_dir / script
+
+        if not source.exists():
+            log(f"❌ Source script not found: {source}", Colors.RED)
+            return False
+
+        try:
+            shutil.copy2(source, dest)
+            # Make executable
+            dest.chmod(0o755)
+            log(f"✅ Copied {script}", Colors.GREEN)
+        except Exception as e:
+            log(f"❌ Failed to copy {script}: {e}", Colors.RED)
+            return False
+
+    log("✅ Automation scripts set up successfully", Colors.GREEN)
+    return True
+
+
+def update_precommit_config():
+    """Update or create pre-commit configuration."""
+    log("⚙️  Updating pre-commit configuration...", Colors.BLUE)
+
+    precommit_config = Path(".pre-commit-config.yaml")
+    current_dir = Path(__file__).parent
+    template_config = current_dir / "pysherlock_precommit_config.yaml"
+
+    if not template_config.exists():
+        log("❌ Template pre-commit config not found", Colors.RED)
+        return False
+
+    # Backup existing config if it exists
+    if precommit_config.exists():
+        backup_path = Path(".pre-commit-config.yaml.backup")
+        shutil.copy2(precommit_config, backup_path)
+        log(f"✅ Backed up existing config to {backup_path}", Colors.YELLOW)
+
+    # Read template and update paths
+    try:
+        with open(template_config, "r") as f:
+            config_content = f.read()
+
+        # Update the entry path to use the automation directory
+        config_content = config_content.replace(
+            "entry: python pre_push_version_increment.py",
+            "entry: python .pysherlock-automation/pre_push_version_increment.py",
+        )
+
+        with open(precommit_config, "w") as f:
+            f.write(config_content)
+
+        log("✅ Pre-commit configuration updated", Colors.GREEN)
+        return True
+
+    except Exception as e:
+        log(f"❌ Failed to update pre-commit config: {e}", Colors.RED)
+        return False
+
+
+def install_precommit_hooks():
+    """Install pre-commit hooks."""
+    log("🪝 Installing pre-commit hooks...", Colors.BLUE)
+
+    # Install pre-commit hooks
+    success, output = run_command(["pre-commit", "install"])
+    if not success:
+        log(f"❌ Failed to install pre-commit hooks: {output}", Colors.RED)
+        return False
+
+    # Install pre-push hooks specifically
+    success, output = run_command(["pre-commit", "install", "--hook-type", "pre-push"])
+    if not success:
+        log(f"❌ Failed to install pre-push hooks: {output}", Colors.RED)
+        return False
+
+    log("✅ Pre-commit hooks installed successfully", Colors.GREEN)
+    return True
+
+
+def test_setup():
+    """Test the setup by running a dry-run."""
+    log("🧪 Testing setup...", Colors.BLUE)
+
+    # Test the auto increment script
+    script_path = Path(".pysherlock-automation/auto_version_increment.py")
+    if not script_path.exists():
+        log("❌ Auto increment script not found", Colors.RED)
+        return False
+
+    # Run with --help to test if it works
+    success, output = run_command([sys.executable, str(script_path), "--help"], check=False)
+
+    if success or "usage:" in output.lower() or "automatic version" in output.lower():
+        log("✅ Auto increment script is working", Colors.GREEN)
+    else:
+        log("⚠️  Auto increment script test inconclusive", Colors.YELLOW)
+
+    # Test pre-commit
+    success, output = run_command(["pre-commit", "--version"])
+    if not success:
+        log("❌ Pre-commit test failed", Colors.RED)
+        return False
+
+    log("✅ Setup test completed", Colors.GREEN)
+    return True
+
+
+def create_usage_instructions():
+    """Create usage instructions file."""
+    log("📚 Creating usage instructions...", Colors.BLUE)
+
+    instructions = """# PySherlock Automatic Version Increment
+
+This automation has been set up to automatically increment the version in `pyproject.toml`
+when you push changes to the repository.
+
+## How it works
+
+1. **Pre-push Hook**: When you run `git push`, the pre-push hook automatically analyzes your changes
+2. **Smart Analysis**: The system looks at:
+   - Towncrier changelog fragments in `doc/changelog.d/`
+   - Git commit messages
+   - Code changes in the repository
+3. **Version Bump**: Based on the analysis, it determines whether to do a:
+   - **PATCH** bump (x.y.Z) - for bug fixes, docs, small changes
+   - **MINOR** bump (x.Y.0) - for new features, enhancements
+   - **MAJOR** bump (X.0.0) - for breaking changes, API changes
+4. **Automatic Update**: Updates `pyproject.toml` and commits the change
+
+## Usage
+
+### Normal Development Flow
+```bash
+# Make your changes
+git add .
+git commit -m "fix: resolve issue with connection timeout"
+
+# Push your changes - version will be auto-incremented
+git push origin your-branch
+```
+
+### Manual Version Control
+If you want to manually control the version increment, you can run:
+
+```bash
+# Run manually with confirmation prompt
+python .pysherlock-automation/auto_version_increment.py
+
+# Run without confirmation (automated)
+python .pysherlock-automation/auto_version_increment.py --no-confirm
+```
+
+### Changelog Integration
+The system works best with towncrier changelog fragments:
+
+```bash
+# Create changelog fragment for a bug fix
+echo "Fixed connection timeout issue." > doc/changelog.d/123.fixed.md
+
+# Create changelog fragment for a new feature
+echo "Added new authentication method." > doc/changelog.d/124.added.md
+
+# Commit and push - version will be incremented appropriately
+git add . && git commit -m "fix: connection timeout" && git push
+```
+
+## Configuration
+
+### Version Bump Rules
+- **MAJOR** (breaking changes):
+  - Breaking changes in commit messages
+  - API changes that remove/modify existing functions
+  - Changelog fragments indicating breaking changes
+
+- **MINOR** (new features):
+  - New features in commit messages (`feat:`, `feature:`, `add:`)
+  - New functions/classes added to API
+  - Changelog fragments with new features
+
+- **PATCH** (bug fixes):
+  - Bug fixes, documentation updates, small improvements
+  - Default for changes that don't match MAJOR/MINOR criteria
+
+### Skipping Auto-increment
+The system automatically skips version increment when:
+- You're on the main branch
+- No changes detected since main branch
+- Version was already manually updated in the PR
+
+### Troubleshooting
+
+If the auto-increment fails:
+1. Check that all dependencies are installed: `pip install toml pre-commit`
+2. Ensure you're in the PySherlock repository root
+3. Check that `pyproject.toml` exists and is readable
+4. Run manually to see detailed error messages
+
+### Disabling
+To temporarily disable auto-increment:
+```bash
+# Skip pre-push hooks for one push
+git push --no-verify
+
+# Or remove the hook temporarily
+pre-commit uninstall --hook-type pre-push
+```
+
+To re-enable:
+```bash
+pre-commit install --hook-type pre-push
+```
+
+## Files Created
+- `.pysherlock-automation/` - Contains automation scripts
+- `.pre-commit-config.yaml` - Updated with version increment hook
+- `PYSHERLOCK_VERSION_AUTOMATION.md` - This documentation
+
+## Support
+If you encounter issues with the version automation, check:
+1. The automation scripts in `.pysherlock-automation/`
+2. Pre-commit hook configuration in `.pre-commit-config.yaml`
+3. Run the automation manually for debugging
+"""
+
+    try:
+        with open("PYSHERLOCK_VERSION_AUTOMATION.md", "w") as f:
+            f.write(instructions)
+        log("✅ Usage instructions created: PYSHERLOCK_VERSION_AUTOMATION.md", Colors.GREEN)
+        return True
+    except Exception as e:
+        log(f"❌ Failed to create instructions: {e}", Colors.RED)
+        return False
+
+
+def main():
+    """Main setup function."""
+    log("🚀 PySherlock Automatic Version Increment Setup", Colors.BOLD)
+    log("=" * 50, Colors.BOLD)
+
+    # Check prerequisites
+    if not check_prerequisites():
+        return 1
+
+    # Install dependencies
+    if not install_dependencies():
+        return 1
+
+    # Setup automation scripts
+    if not setup_automation_scripts():
+        return 1
+
+    # Update pre-commit configuration
+    if not update_precommit_config():
+        return 1
+
+    # Install pre-commit hooks
+    if not install_precommit_hooks():
+        return 1
+
+    # Test setup
+    if not test_setup():
+        log("⚠️  Setup completed but tests failed. Please check manually.", Colors.YELLOW)
+
+    # Create usage instructions
+    create_usage_instructions()
+
+    log("\n" + "=" * 50, Colors.BOLD)
+    log("🎉 Setup completed successfully!", Colors.GREEN)
+    log("\nNext steps:", Colors.BOLD)
+    log("1. Review PYSHERLOCK_VERSION_AUTOMATION.md for usage instructions", Colors.BLUE)
+    log("2. Test the setup by making a small change and pushing", Colors.BLUE)
+    log("3. The version will be automatically incremented on git push", Colors.BLUE)
+    log("\nHappy coding! 🐍✨", Colors.GREEN)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.script/test_version_automation.py b/.script/test_version_automation.py
new file mode 100644
index 000000000..92ba194ac
--- /dev/null
+++ b/.script/test_version_automation.py
@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""
+Test script for PySherlock automatic version increment
+
+This script tests the version increment functionality in different scenarios.
+"""
+
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+
+import toml
+
+
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    BOLD = "\033[1m"
+    NC = "\033[0m"
+
+
+def log(message: str, color: str = Colors.NC):
+    """Print colored log message."""
+    print(f"{color}{message}{Colors.NC}")
+
+
+def run_command(command: list, cwd: Path = None) -> tuple[bool, str]:
+    """Run a command and return success status and output."""
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, check=True, cwd=cwd)
+        return True, result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        return False, e.stderr.strip() if e.stderr else str(e)
+
+
+def create_test_pyproject_toml(test_dir: Path, version: str = "0.12.dev0"):
+    """Create a test pyproject.toml file."""
+    pyproject_content = f"""[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "ansys-sherlock-core"
+version = "{version}"
+description = "A Python wrapper for Ansys Sherlock"
+readme = "README.rst"
+requires-python = ">=3.10,<4"
+license = {{file = "LICENSE"}}
+
+[project.urls]
+Source = "https://github.com/ansys/pysherlock"
+Tracker = "https://github.com/ansys/pysherlock/issues"
+"""
+
+    pyproject_file = test_dir / "pyproject.toml"
+    with open(pyproject_file, "w") as f:
+        f.write(pyproject_content)
+
+    return pyproject_file
+
+
+def create_test_git_repo(test_dir: Path):
+    """Initialize a test git repository."""
+    commands = [
+        ["git", "init"],
+        ["git", "config", "user.email", "test@example.com"],
+        ["git", "config", "user.name", "Test User"],
+        ["git", "add", "."],
+        ["git", "commit", "-m", "Initial commit"],
+    ]
+
+    for cmd in commands:
+        success, output = run_command(cmd, test_dir)
+        if not success:
+            log(f"Failed to run {' '.join(cmd)}: {output}", Colors.RED)
+            return False
+
+    return True
+
+
+def test_version_parsing():
+    """Test version parsing functionality."""
+    log("🧪 Testing version parsing...", Colors.BLUE)
+
+    # Import the auto increment module
+    current_dir = Path(__file__).parent
+    auto_increment_script = current_dir / "auto_version_increment.py"
+
+    if not auto_increment_script.exists():
+        log("❌ Auto increment script not found", Colors.RED)
+        return False
+
+    # Test version parsing by running the script with a test
+    test_cases = [
+        ("0.12.dev0", "patch", "0.12.1"),
+        ("0.12.1", "minor", "0.13.0"),
+        ("0.12.1", "major", "1.0.0"),
+        ("1.2.3", "patch", "1.2.4"),
+    ]
+
+    # Create a simple test
+    test_code = """
+import sys
+sys.path.append(".")
+from auto_version_increment import parse_version, increment_version, VersionBumpType
+
+test_cases = [
+    ("0.12.dev0", VersionBumpType.PATCH, "0.12.1"),
+    ("0.12.1", VersionBumpType.MINOR, "0.13.0"),
+    ("0.12.1", VersionBumpType.MAJOR, "1.0.0"),
+    ("1.2.3", VersionBumpType.PATCH, "1.2.4"),
+]
+
+all_passed = True
+for version, bump_type, expected in test_cases:
+    result = increment_version(version, bump_type)
+    if result != expected:
+        print(f"FAIL: {version} + {bump_type.value} = {result}, expected {expected}")
+        all_passed = False
+    else:
+        print(f"PASS: {version} + {bump_type.value} = {result}")
+
+sys.exit(0 if all_passed else 1)
+"""
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+        f.write(test_code)
+        test_file = f.name
+
+    try:
+        success, output = run_command([sys.executable, test_file], current_dir)
+        if success:
+            log("✅ Version parsing tests passed", Colors.GREEN)
+            return True
+        else:
+            log(f"❌ Version parsing tests failed: {output}", Colors.RED)
+            return False
+    finally:
+        Path(test_file).unlink(missing_ok=True)
+
+
+def test_version_increment_in_isolated_repo():
+    """Test version increment in an isolated test repository."""
+    log("🧪 Testing version increment in isolated repository...", Colors.BLUE)
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        test_dir = Path(temp_dir)
+
+        # Create test pyproject.toml
+        create_test_pyproject_toml(test_dir, "0.12.dev0")
+
+        # Create test git repo
+        if not create_test_git_repo(test_dir):
+            return False
+
+        # Copy auto increment script
+        current_dir = Path(__file__).parent
+        auto_increment_script = current_dir / "auto_version_increment.py"
+        shutil.copy2(auto_increment_script, test_dir / "auto_version_increment.py")
+        shutil.copy2(
+            current_dir / "pre_push_version_increment.py",
+            test_dir / "pre_push_version_increment.py",
+        )
+
+        # Create some changelog fragments
+        changelog_dir = test_dir / "doc" / "changelog.d"
+        changelog_dir.mkdir(parents=True)
+
+        # Add a bug fix fragment
+        with open(changelog_dir / "123.fixed.md", "w") as f:
+            f.write("Fixed connection timeout issue.")
+
+        # Commit the changelog
+        run_command(["git", "add", "."], test_dir)
+        run_command(["git", "commit", "-m", "Add changelog fragment"], test_dir)
+
+        # Run the auto increment script
+        success, output = run_command(
+            [sys.executable, "auto_version_increment.py", "--no-confirm"], test_dir
+        )
+
+        if not success:
+            log(f"❌ Auto increment failed: {output}", Colors.RED)
+            return False
+
+        # Check if version was updated
+        try:
+            with open(test_dir / "pyproject.toml", "r") as f:
+                data = toml.load(f)
+                new_version = data["project"]["version"]
+
+            if new_version == "0.12.1":
+                log(f"✅ Version correctly incremented: 0.12.dev0 → {new_version}", Colors.GREEN)
+                return True
+            else:
+                log(
+                    f"❌ Version increment incorrect: expected 0.12.1, got {new_version}",
+                    Colors.RED,
+                )
+                return False
+
+        except Exception as e:
+            log(f"❌ Failed to read updated version: {e}", Colors.RED)
+            return False
+
+
+def test_bump_type_detection():
+    """Test bump type detection based on commit messages."""
+    log("🧪 Testing bump type detection...", Colors.BLUE)
+
+    test_scenarios = [
+        {
+            "commit_msg": "fix: resolve connection timeout",
+            "expected_bump": "patch",
+            "description": "Bug fix should trigger patch bump",
+        },
+        {
+            "commit_msg": "feat: add new authentication method",
+            "expected_bump": "minor",
+            "description": "New feature should trigger minor bump",
+        },
+        {
+            "commit_msg": "BREAKING CHANGE: remove deprecated API",
+            "expected_bump": "major",
+            "description": "Breaking change should trigger major bump",
+        },
+    ]
+
+    all_passed = True
+
+    for scenario in test_scenarios:
+        # This is a simplified test - in practice we'd need to create commits
+        # and test the actual commit message analysis
+        log(f"  📝 {scenario['description']}", Colors.BLUE)
+
+        # Check if commit message contains expected keywords
+        commit_msg = scenario["commit_msg"].lower()
+        expected_bump = scenario["expected_bump"]
+
+        if expected_bump == "major" and any(
+            keyword in commit_msg for keyword in ["breaking change", "breaking:", "major:"]
+        ):
+            log(f"    ✅ Correctly detected {expected_bump} bump", Colors.GREEN)
+        elif expected_bump == "minor" and any(
+            keyword in commit_msg for keyword in ["feat:", "feature:", "add:", "new:"]
+        ):
+            log(f"    ✅ Correctly detected {expected_bump} bump", Colors.GREEN)
+        elif expected_bump == "patch":
+            log(f"    ✅ Correctly detected {expected_bump} bump (default)", Colors.GREEN)
+        else:
+            log(f"    ❌ Failed to detect {expected_bump} bump", Colors.RED)
+            all_passed = False
+
+    return all_passed
+
+
+def test_script_integration():
+    """Test that scripts can be imported and run."""
+    log("🧪 Testing script integration...", Colors.BLUE)
+
+    current_dir = Path(__file__).parent
+    scripts = [
+        "auto_version_increment.py",
+        "pre_push_version_increment.py",
+        "setup_pysherlock_automation.py",
+    ]
+
+    all_passed = True
+
+    for script in scripts:
+        script_path = current_dir / script
+        if not script_path.exists():
+            log(f"❌ Script not found: {script}", Colors.RED)
+            all_passed = False
+            continue
+
+        # Test that script can be executed (at least imported/parsed)
+        success, output = run_command([sys.executable, "-m", "py_compile", str(script_path)])
+
+        if success:
+            log(f"✅ {script} syntax is valid", Colors.GREEN)
+        else:
+            log(f"❌ {script} has syntax errors: {output}", Colors.RED)
+            all_passed = False
+
+    return all_passed
+
+
+def main():
+    """Run all tests."""
+    log("🚀 Testing PySherlock Automatic Version Increment", Colors.BOLD)
+    log("=" * 60, Colors.BOLD)
+
+    tests = [
+        ("Script Integration", test_script_integration),
+        ("Version Parsing", test_version_parsing),
+        ("Bump Type Detection", test_bump_type_detection),
+        ("Version Increment (Isolated)", test_version_increment_in_isolated_repo),
+    ]
+
+    passed = 0
+    failed = 0
+
+    for test_name, test_func in tests:
+        log(f"\n🔍 Running test: {test_name}", Colors.BOLD)
+        try:
+            if test_func():
+                passed += 1
+                log(f"✅ {test_name} PASSED", Colors.GREEN)
+            else:
+                failed += 1
+                log(f"❌ {test_name} FAILED", Colors.RED)
+        except Exception as e:
+            failed += 1
+            log(f"❌ {test_name} ERROR: {e}", Colors.RED)
+
+    log("\n" + "=" * 60, Colors.BOLD)
+    log(f"📊 Test Results: {passed} passed, {failed} failed", Colors.BOLD)
+
+    if failed == 0:
+        log("🎉 All tests passed!", Colors.GREEN)
+        return 0
+    else:
+        log("❌ Some tests failed. Check the output above.", Colors.RED)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/doc/changelog.d/658.miscellaneous.md b/doc/changelog.d/658.miscellaneous.md
new file mode 100644
index 000000000..e37967bb0
--- /dev/null
+++ b/doc/changelog.d/658.miscellaneous.md
@@ -0,0 +1 @@
+Feat: Optimization version check