Beginner Tutorials¶

Welcome to Code Scalpel! These tutorials will teach you the fundamentals.

What You'll Learn¶

By completing the beginner tutorials, you'll be able to:

• ✅ Analyze code structure
• ✅ Extract functions and classes
• ✅ Update code safely
• ✅ Run basic security scans
• ✅ Validate paths before operations

Prerequisites¶

Before starting:

• Code Scalpel installed (Installation Guide)
• Access to an AI assistant (Claude, VS Code Copilot, or Cursor)
• Basic familiarity with Python

Tutorial Series¶

1. Analyze Your First File¶

Time: 5 minutes | Tools: analyze_code

Learn how analyze_code parses Python files and extracts structure information.

Start Tutorial →

2. Extract a Function¶

Time: 5 minutes | Tools: extract_code

Learn how to surgically extract functions by name, not by line numbers.

Start Tutorial →

3. Update Code Safely¶

Time: 10 minutes | Tools: update_symbol, rename_symbol

Learn how to replace and rename code without breaking things.

Start Tutorial →

4. Run a Security Scan¶

Time: 5 minutes | Tools: security_scan

Learn how to detect common vulnerabilities in your code.

Start Tutorial →

5. Putting It Together¶

Time: 15 minutes | Tools: Multiple

Complete a real-world workflow using everything you've learned.

Start Tutorial →

Sample Code¶

All tutorials use this sample project:

# sample_project/calculator.py

def add(a, b):
    """Add two numbers."""
    return a + b

def divide(a, b):
    """Divide a by b."""
    return a / b  # Bug: no zero check!

def calculate_tax(amount, rate=0.1):
    """Calculate tax on an amount."""
    if amount < 0:
        raise ValueError("Amount cannot be negative")
    return amount * rate

class Calculator:
    """Simple calculator class."""

    def __init__(self):
        self.history = []

    def compute(self, operation, *args):
        """Perform a calculation and store in history."""
        if operation == "add":
            result = add(*args)
        elif operation == "divide":
            result = divide(*args)
        else:
            raise ValueError(f"Unknown operation: {operation}")

        self.history.append((operation, args, result))
        return result

Create this file to follow along, or download from our sample projects.

Key Concepts¶

MCP Tools¶

Code Scalpel provides tools that AI assistants can use. When you ask:

"Analyze calculator.py"

The AI calls:

{
  "tool": "analyze_code",
  "parameters": {
    "file_path": "calculator.py"
  }
}

Surgical Precision¶

Unlike reading entire files, Code Scalpel tools work surgically:

Community Tier¶

All beginner tutorials use Community tier tools (free). You don't need a license.

Next Steps¶

Start with Analyze Your First File, or jump to any tutorial that interests you.

After completing beginner tutorials, continue to Intermediate Tutorials.