Vibe Coder's Guide to Code Scalpel¶

Welcome! This guide is written specifically for you – someone who doesn't personally write code but uses AI agents (like Claude, Cursor, or GitHub Copilot) that do. We're here to help you give your AI superpowers with Code Scalpel.

What's a Vibe Coder?¶

You are! A vibe coder is someone who: - Uses AI to write code for them - Understands what they want to build, even if they don't know the syntax - Works with AI assistants like Claude Desktop, Cursor, or VS Code with Copilot - Gets things done by describing what they need, not by writing for loops

If that sounds like you, you're in the right place. And if you're feeling a bit overwhelmed by all the technical stuff – that's totally normal. We've got you.

Why Should I Care About Code Scalpel?¶

Imagine your AI assistant is a surgeon who needs to operate on your code. Right now, it's like they're working with a dull kitchen knife – functional, but not ideal.

Code Scalpel gives your AI a precision surgical toolkit. Here's what changes:

Without Code Scalpel¶

Your AI has to: - Read entire files (expensive, slow) - Guess which line numbers to change - Manually track where functions are used - Hope nothing breaks when it makes changes

With Code Scalpel¶

Your AI can: - Extract just the specific function it needs by name - Find all the places that function is called - Safely rename variables across your entire project - Run security scans to catch vulnerabilities - Generate call graphs to understand how code connects

Think of it as upgrading from "find and replace" to "smart refactoring assistant."

What You'll Need¶

Before we start, make sure you have:

• Python 3.10 or newer - Don't worry if you're not sure, we'll check in a moment
• An AI assistant - Claude Desktop, VS Code with Copilot, Cursor, or similar
• A code project - Any Python, JavaScript, TypeScript, or Java project (even a small test project works!)
• 10 minutes - That's it!

Quick Reality Check: Do I Have Python?¶

Let's find out! Open your terminal (also called "command prompt" on Windows) and type:

On Mac/Linux:

python3 --version

On Windows:

python --version

What you should see:

Python 3.10.5

If you see an error or a version lower than 3.10, don't panic! Here's how to install Python:

brew install python@3.12

sudo apt update
sudo apt install python3.10

sudo dnf install python3.10

Installing Code Scalpel (The Easy Part)¶

You've got two options: uvx (modern, recommended) or pip (classic). Both work great!

Option 1: Using uvx (Recommended - Super Easy!)¶

The magic of uvx is that you don't even need to install Code Scalpel! It automatically downloads and runs it when needed.

First, install uv (one-time setup):

Mac/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

Why uvx? It's faster, handles dependencies automatically, and doesn't pollute your global Python environment. Think of it as the "new and improved" way to run Python tools.

Test it works:

uvx codescalpel --version

You should see: Code Scalpel v1.4.0 (or similar)

🎉 Success! You just set up Code Scalpel with zero installation. uvx will handle everything automatically!

Option 2: Using pip (Traditional Method)¶

If you prefer the traditional way:

pip install codescalpel

What you should see:

Collecting codescalpel...
Successfully installed codescalpel-1.4.0

If you see "pip: command not found": Try pip3 install codescalpel instead (on some systems it's called pip3).

Verify it worked:

codescalpel --version

Connecting Your AI to Code Scalpel¶

Now comes the fun part – telling your AI assistant that Code Scalpel exists. The exact steps depend on which AI tool you use. Pick your platform below:

Setup for Claude Desktop¶

Claude Desktop is one of the most popular AI assistants. Let's connect it to Code Scalpel!

Step 1: Find Your Config File¶

Claude Desktop uses a config file to know about tools like Code Scalpel. Here's where to find it:

On Mac:

~/Library/Application Support/Claude/claude_desktop_config.json

How to get there: 1. Open Finder 2. Press Cmd + Shift + G (this opens "Go to Folder") 3. Paste the path above 4. You'll see the file claude_desktop_config.json

On Windows:

%APPDATA%\Claude\claude_desktop_config.json

How to get there: 1. Open File Explorer 2. Click in the address bar at the top 3. Type %APPDATA%\Claude 4. You'll see the file claude_desktop_config.json

On Linux:

~/.config/Claude/claude_desktop_config.json

Step 2: Edit the Config File¶

Open claude_desktop_config.json with any text editor (Notepad, TextEdit, VS Code, whatever you like).

What you'll see: The file might be empty {} or have some existing content. That's totally fine!

What to do: Copy and paste this into the file, replacing everything:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "code-scalpel": {
      "command": "codescalpel",
      "args": []
    }
  }
}

Why this works: You're telling Claude "Hey, when you need Code Scalpel, run this command." The command is what your terminal would run, and args are optional arguments (we don't need any).

Step 3: Restart Claude Desktop¶

Close Claude Desktop completely (make sure it's not just minimized!) and open it again.

Step 4: Test It!¶

Ask Claude:

"Use Code Scalpel to analyze the structure of this Python file: [paste a simple Python file]"

If it works, Claude will use Code Scalpel to analyze the file and tell you about the functions, classes, and structure.

If you see an error, jump to the Troubleshooting section below.

Setup for VS Code with GitHub Copilot¶

VS Code is a popular code editor, and GitHub Copilot is its AI assistant. Let's connect them to Code Scalpel!

Step 1: Install the MCP Extension¶

1. Open VS Code
2. Click the Extensions icon on the left sidebar (looks like four squares)
3. Search for "MCP" or "Model Context Protocol"
4. Click "Install" on the official MCP extension

Step 2: Configure Code Scalpel¶

1. Press Cmd + , (Mac) or Ctrl + , (Windows/Linux) to open Settings
2. Search for "MCP"
3. Click "Edit in settings.json"
4. Add this to your settings.json:

{
  "servers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "${workspaceFolder}/.code-scalpel/license/"
      }
    }
  }
}

{
  "servers": {
    "code-scalpel": {
      "command": "codescalpel",
      "args": ["mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "${workspaceFolder}/.code-scalpel/license/"
      }
    }
  }
}

Step 3: Reload VS Code¶

Press Cmd + Shift + P (Mac) or Ctrl + Shift + P (Windows/Linux) and type "Reload Window". Press Enter.

Step 4: Test It!¶

Open a Python file and ask Copilot:

"Use Code Scalpel to extract the process_data function from this file."

Setup for Cursor¶

Cursor is a fork of VS Code designed for AI coding. Setup is similar but slightly different.

Step 1: Open Cursor Settings¶

1. Click the gear icon in the bottom-left
2. Select "Settings"
3. Search for "MCP Servers"

Step 2: Add Code Scalpel¶

1. Click "Add MCP Server"
2. Name: code-scalpel
3. Command:
4. If using uvx: uvx
5. If using pip: codescalpel
6. Args:
7. If using uvx: ["codescalpel", "mcp"]
8. If using pip: ["mcp"]
9. Click "Save"

Step 3: Restart Cursor¶

Close and reopen Cursor completely.

Step 4: Test It!¶

Ask Cursor's AI:

"Use Code Scalpel to analyze the structure of this file."

Setup for Other Tools¶

If you're using another MCP-compatible tool (like Windsurf, Zed, or a custom client), the pattern is usually:

{
  "servers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    }
  }
}

Check your tool's MCP server documentation for the exact config format.

Your First Analysis (Let's Try It!)¶

Now that everything's connected, let's see Code Scalpel in action!

Step 1: Create a Test File¶

Create a new file called calculator.py with this code:

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

def multiply(a, b):
    """Multiply two numbers."""
    return a * b

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."""
        if operation == "add":
            result = add(*args)
        elif operation == "multiply":
            result = multiply(*args)
        else:
            raise ValueError(f"Unknown operation: {operation}")

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

Step 2: Ask Your AI to Analyze It¶

Ask your AI:

"Use Code Scalpel to analyze the structure of calculator.py. What functions and classes does it contain?"

Step 3: What You Should See¶

Your AI will tell you something like:

"I used Code Scalpel to analyze calculator.py. It contains:

Functions: - add(a, b) - Adds two numbers - multiply(a, b) - Multiplies two numbers - calculate_tax(amount, rate=0.1) - Calculates tax with optional rate

Classes: - Calculator - A class with methods: - __init__(self) - Initializes with empty history - compute(self, operation, *args) - Performs calculations and stores history"

🎉 You did it! Your AI just used Code Scalpel to surgically analyze your code.

What Can Your AI Do Now?¶

Now that Code Scalpel is set up, your AI has some serious new capabilities. Here are some things you can ask it to do:

1. Extract Specific Functions¶

You ask:

"Extract just the calculate_tax function from calculator.py, including any dependencies."

Your AI will: - Use Code Scalpel to extract exactly that function - Include any other functions it depends on - Give you clean, runnable code

Why this matters: No more copy-pasting chunks of code and hoping you got everything!

2. Find All Function Calls¶

You ask:

"Show me everywhere in my project where the add function is called."

Your AI will: - Use Code Scalpel to search your entire codebase - List every file and line where add is used - Show you the context around each call

Why this matters: Before making changes, you'll know exactly what might break!

3. Safely Rename Variables¶

You ask:

"Rename the amount parameter in calculate_tax to base_amount everywhere it's used."

Your AI will: - Use Code Scalpel to find all usages - Rename it consistently across your codebase - Create a backup before making changes

Why this matters: No more find-and-replace accidents that break your code!

4. Generate Call Graphs¶

You ask:

"Create a call graph showing how the functions in calculator.py relate to each other."

Your AI will: - Use Code Scalpel to analyze function relationships - Generate a visual diagram (in Mermaid format) - Show you the flow of your code

Why this matters: Visual understanding of complex codebases!

5. Run Security Scans¶

You ask:

"Check calculator.py for security vulnerabilities."

Your AI will: - Use Code Scalpel to scan for common issues - Detect problems like SQL injection, XSS, hardcoded secrets - Suggest fixes

Why this matters: Catch security issues before they become problems!

6. Understand Project Structure¶

You ask:

"Give me an overview of my entire project's structure."

Your AI will: - Use Code Scalpel to crawl your project - Show you the file organization - List all the main functions and classes - Identify entry points

Why this matters: Perfect for understanding codebases you didn't write!

Understanding Tiers (Don't Worry, You're Already Set!)¶

Code Scalpel has three tiers: Community (free), Pro, and Enterprise. Here's the good news:

You're Using Community (And That's Great!)¶

By default, you're using the Community tier, which is free forever. It includes:

• ✅ All 22 tools available (yes, ALL of them!)
• ✅ Single-file analysis
• ✅ Basic security scanning
• ✅ Function extraction
• ✅ Symbol renaming
• ✅ Project mapping (up to 100 files)
• ✅ Call graphs (up to 3 levels deep, 50 nodes)
• ✅ Symbolic execution (up to 10 paths)

What About Pro and Enterprise?¶

Important: All tools are available at all tiers. Higher tiers just give you bigger limits:

Do you need Pro or Enterprise? Probably not yet! Start with Community and upgrade only if you hit the limits.

How will you know if you hit a limit? Code Scalpel will tell you in the response:

{
  "was_truncated": true,
  "tier_applied": "community",
  "message": "Results limited to Community tier. Upgrade to Pro for full analysis."
}

Your AI will explain this in plain English.

Common Questions¶

"Do I need to understand the config file?"¶

Nope! Just copy-paste what we showed you. It works and you don't need to understand the details.

Think of it like using a TV remote – you don't need to understand infrared signals, you just press the buttons.

"Is my code being sent somewhere?"¶

No. Code Scalpel runs entirely on your computer. Your code never leaves your machine.

When your AI uses Code Scalpel, it's running a local program (like opening a calculator app). Nothing is uploaded to the cloud.

"What if I see an error?"¶

Check the Troubleshooting section below! We cover all the common issues.

"Can I break anything?"¶

Very unlikely. Code Scalpel: - Never executes your code (it only reads and analyzes it) - Creates backups before making changes - Validates syntax before writing files - Only does what you (via your AI) explicitly ask

The worst that could happen is a tool returns an error, which your AI will handle gracefully.

"What if Python isn't installed (and I can't install it)?"¶

If you truly can't install Python (maybe on a locked-down work computer), consider:

1. Use Docker - Docker bundles everything, no Python needed
2. Use a cloud environment - GitHub Codespaces or similar
3. Talk to IT - Explain you need Python for development tools

"My AI doesn't see Code Scalpel!"¶

This usually means the config file isn't in the right place or has a typo. Jump to Troubleshooting.

Troubleshooting¶

"My AI says 'Code Scalpel tool not found'"¶

Cause: The config file is wrong or in the wrong location.

Fix: 1. Double-check the config file location (scroll up to your platform's section) 2. Make sure the file is named exactly claude_desktop_config.json (or settings.json for VS Code) 3. Check for typos in the JSON (missing commas, quotes, brackets) 4. Pro tip: Paste your config into jsonlint.com to check for errors

"I see 'command not found: codescalpel'"¶

Cause: Code Scalpel isn't installed, or Python isn't in your PATH.

Fix: 1. Run codescalpel --version in your terminal - If it works: Your PATH might be different in your IDE - If it fails: Reinstall Code Scalpel: pip install codescalpel 2. Try using the full path:

{
  "command": "/usr/local/bin/codescalpel"
}

"I see 'permission denied'"¶

Cause: The codescalpel executable doesn't have execute permissions.

Fix (Mac/Linux):

chmod +x $(which codescalpel)

Fix (Windows): Usually not an issue on Windows. If you see this, reinstall Code Scalpel.

"JSON error: unexpected token"¶

Cause: Your config file has a syntax error (missing comma, extra quote, etc.).

Fix: 1. Copy your config file contents 2. Go to jsonlint.com 3. Paste and click "Validate JSON" 4. It will tell you exactly what's wrong 5. Fix the error and save

Common mistakes:

// ❌ Wrong (trailing comma)
{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],  // <- Extra comma!
    }
  }
}

// ✅ Correct
{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    }
  }
}

"The file ~/.../claude_desktop_config.json doesn't exist"¶

Cause: Claude Desktop hasn't created it yet, or you're looking in the wrong place.

Fix: 1. Create the file manually in the right location (see platform-specific paths above) 2. Or, run Claude Desktop once, then close it – it should create the file

"uvx: command not found"¶

Cause: You haven't installed uv yet.

Fix: Either install uv (see the Installing Code Scalpel section), or switch to using pip:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "codescalpel",
      "args": []
    }
  }
}

Still Stuck?¶

If none of these fix your issue:

1. Check GitHub Issues: github.com/cyanheads/code-scalpel/issues
2. Ask the Community: GitHub Discussions
3. Include this info:
4. Which AI tool you're using (Claude Desktop, VS Code, Cursor, etc.)
5. Your operating system (Mac, Windows, Linux)
6. The exact error message you're seeing
7. What you've already tried

Next Steps: Leveling Up¶

Congratulations! You've successfully installed Code Scalpel and given your AI superpowers. Here's what to explore next:

1. Try More Tools¶

You've seen basic analysis. Now try: - Extracting functions with dependencies - Generating call graphs - Running security scans - Renaming symbols across your project

Ask your AI: "What Code Scalpel tools can you use?" and it will list them all!

2. Read the Beginner Tutorials¶

If you want to learn more about what Code Scalpel can do (with examples!), check out: - Beginner Tutorials - Step-by-step walkthroughs - Tool Reference - Detailed docs on all 22 tools

3. Understand Your AI Better¶

Code Scalpel is a tool your AI uses. To get the most out of it: - Ask your AI to explain what it's doing when it uses Code Scalpel - Request specific tools: "Use Code Scalpel's extract_code tool to..." - Check the tool responses to see what data Code Scalpel returned

4. Join the Community¶

Other vibe coders are using Code Scalpel too! Join us: - GitHub Discussions - Ask questions, share tips - GitHub Issues - Report bugs or request features

5. Share Your Success!¶

Did Code Scalpel help you understand or improve your code? We'd love to hear about it! - Tweet about it with #CodeScalpel - Star the GitHub repo - Tell other vibe coders!

You Did It! 🎉¶

You've successfully: - ✅ Installed Code Scalpel - ✅ Connected it to your AI assistant - ✅ Run your first analysis - ✅ Learned what your AI can now do

You're now equipped with one of the most powerful code analysis tools available, and you didn't have to write a single line of code yourself. That's the magic of being a vibe coder!

Remember: you don't need to understand how Code Scalpel works internally. You just need to know what it can do for you through your AI assistant.

Happy coding (via AI)! 🚀

Quick Reference Card¶

Keep this handy for future reference:

Installation¶

# Option 1: pip
pip install codescalpel

# Option 2: uvx (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

Config Template (Claude Desktop)¶

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    }
  }
}

Test Command¶

Ask your AI:

"Use Code Scalpel to analyze the structure of [filename]"

Common Questions¶

• All tools available? Yes, at all tiers!
• Data sent anywhere? No, runs locally.
• Can I break things? Very unlikely, backups are created.
• Need help? Check Troubleshooting or GitHub Issues

This guide was written with love for vibe coders everywhere. You're building amazing things with AI, and we're thrilled to be part of your toolkit. Now go forth and vibe! ✨