Code Scalpel: Reduce AI Costs by 200x

Latest Release: v2.2.0 | March 28, 2026

Stop copy-pasting entire files into Claude. Give your AI assistant surgical code analysis tools and reduce costs by up to 200x.

What's New in v2.2.0 — Telemetry Completeness & Crash Safety

This release adds crash-safe JSONL streaming, failure-path telemetry for all 23 tools, encrypted error fields, and automatic log retention policies. All telemetry events are now captured with proper error handling and flushed incrementally per tool call for maximum durability.

What's New in v2.1.1 — Metadata Sync

This patch release refreshes public packaging metadata so PyPI and Marketplace copy match the current 22-core-tool product framing.

Previous: v2.1.0 — Expanded Language Matrix

> [20260310_DOCS] The source-of-truth tier files currently advertise 13 languages

> on the tier-configured `analyze_code` and `unified_sink_detect` surfaces.

> [20260306_DOCS] Core parsing, extraction, and analysis surfaces span the full

> language set. Graph-oriented MCP tools such as `get_call_graph`,

> `get_graph_neighborhood`, and `get_cross_file_dependencies` remain

> Python-first today, with an initial JavaScript/TypeScript function-node parity

> slice now available in `get_call_graph` and `get_graph_neighborhood`, plus

> partial awareness in some shared JS/TS/Java paths.

285 new language tests added (v2.0: 262; v2.1: +23 Go tests). Zero breaking changes to existing APIs. See CHANGELOG for full details.

Standalone By Default, Enterprise-Compatible By Design

Code Scalpel delivers first-party parsing and analysis out of the box. Core value does not depend on licensed third-party scanners or external platforms.

• Standalone core: syntax parsing, structural analysis, IR normalization, taint analysis, symbolic execution, and baseline security findings work as native Code Scalpel capabilities.
• Open-tool support: license-free local CLI tools can be executed directly when practical.
• Enterprise adapters: tools like Coverity, SonarQube, ReSharper, Exakat, and similar platforms can be ingested through exported JSON, XML, SARIF, or API payloads and normalized into one internal analysis model.
• No hard dependency boundary: third-party scanners can extend enterprise workflows, but they are not required for basic product value.

This gives teams the right split:

• Standalone enough to work immediately in local and self-managed environments.
• Enterprise-friendly enough to plug into existing AppSec, compliance, and governance stacks.
• Architecturally honest about what Code Scalpel analyzes natively versus what it federates from external systems.

In short: Code Scalpel is standalone by default, enterprise-compatible by design.

What Is Code Scalpel? (30-Second Version)

Code Scalpel is an MCP (Model Context Protocol) server that gives AI assistants like Claude, GitHub Copilot, and Cursor the ability to surgically extract and analyze code instead of reading entire files.

Before Code Scalpel ❌

# You paste entire 500-line file into Claude
# Tokens: 10,247 tokens
# Cost: $0.030 per query
# Time: 12 seconds
# Claude has to read everything, even irrelevant code

After Code Scalpel ✅

# Ask: "Use Code Scalpel to extract calculate_tax function"
# Claude uses extract_code tool automatically
# Tokens: 287 tokens (just the function you need)
# Cost: $0.0009 per query  
# Time: 2 seconds

Savings: 97% cost reduction, 83% time reduction, zero workflow changes.

The Bridge: Stochastic AI → Reliable Engineering

Code Scalpel is the bridge between stochastic AI (LLMs that guess) and reliable software engineering (deterministic systems that know).

Your AI assistant is a probability engine. It generates the *most likely* answer based on patterns in training data. That works brilliantly for prose and boilerplate. It breaks down when precision is non-negotiable — refactoring a production service, tracing a SQL injection through four files, or proving that a rename touched every caller.

Code Scalpel wraps your stochastic agent in a deterministic glass box: every code operation backed by a real AST parse, a real call graph, a real theorem prover. The agent still generates; Code Scalpel verifies, executes, and logs.

Stochastic LLM  →  Code Scalpel  →  Deterministic Code Operations
  (guesses)           (glass box)          (verified facts)

The Four Pillars

1. 💸 Cheaper AI — 99% Context Reduction

Instead of feeding 10 full files (15,000 tokens) to the model, Code Scalpel's PDG engine surgically extracts only the relevant function and its live dependencies.

Result: $450/month → $22/month doing the same work. You save money *and* the model focuses better because it isn't drowning in irrelevant context.

2. 🎯 More Accurate AI — Graph Facts, Not LLM Guesses

When Code Scalpel reports *"this function has 3 callers"*, that is a graph fact derived from AST parsing — not an LLM estimate.

Symbolic execution with the Z3 theorem prover mathematically explores every code path — finding edge cases that humans and LLMs both miss. When `symbolic_execute` says a path is safe, it is provably safe.

3. 🛡️ Safer AI — The Syntax-Aware Gatekeeper

Every AI-generated edit passes through Code Scalpel's AST parser before it touches disk.

> Without Code Scalpel: Agent hallucinates a missing `)` → file written → build breaks → you find out later.

>

> With Code Scalpel: AST parser fails on the malformed output → edit rejected and logged → agent retries with corrected code.

The `simulate_refactor` tool runs a behavioral diff before any change is applied. If the semantics change unexpectedly, the operation is blocked.

4. 🏛️ Governable AI — The Invisible Audit Trail

Compliance isn't optional in regulated environments. Code Scalpel creates a `.code-scalpel/audit.jsonl` trail for every agent operation.

• Provenance: We log the decision path (graph trace), not just the diff output.
• Integrity: `verify_policy_integrity` cryptographically ensures your governance rules haven't drifted.
• Explainability: When a regulator asks *"why did the agent make that change?"*, you have a deterministic, reproducible answer — not *"the model seemed confident"*.

New? Start Here 👋

Never used Code Scalpel? Get started in 3 steps:

1. **📖 What is this?** — Understand Code Scalpel in 10 seconds with visual examples

2. **⚡ 2-Minute Setup** — Install and configure Claude Desktop in under 2 minutes

3. Ask your AI assistant — "Use Code Scalpel to extract [function_name] from [file.py]"

That's it. You'll see 200x token reduction on your first query.

Who Is This For?

Code Scalpel serves 4 primary user types:

👤 Individual Developers (Cost Reduction Focus)

You're spending $50-450/month on Claude API and want to cut costs 95%.

• ✅ Real example: $450/mo → $22/mo
• ✅ 2-minute installation, zero maintenance
• ✅ Works with Claude Desktop, GitHub Copilot, Cursor

**→ Cost Optimization Guide**

👥 Team Leads (Team ROI Focus)

You manage 8-15 developers and need to reduce team AI costs 40%+.

• ✅ Real example: $3,000/mo → $1,800/mo = $14,400/year saved
• ✅ 1-hour team rollout with templates and playbooks
• ✅ Usage analytics and ROI tracking included

**→ Team Quickstart Guide**

🛡️ Security Engineers (AppSec Evaluation Focus)

**You need OWASP Top 10 coverage with

🔑 Pro/Enterprise License Configuration

If you have a Pro or Enterprise license, you need to configure Code Scalpel to use your license file.

Method 1: Standard Location (Recommended)

Place your license file in the standard location:

mkdir -p .code-scalpel/license
cp /path/to/your/license.jwt .code-scalpel/license/license.jwt

Then use the standard installation command:

claude mcp add codescalpel uvx codescalpel mcp

Code Scalpel will automatically discover your license.

Standard license locations checked (in order):

• `.code-scalpel/license/license.jwt` (preferred)
• `.code-scalpel/license.jwt`
• `~/.config/code-scalpel/license.jwt` (user-wide)
• `~/.code-scalpel/license.jwt` (legacy)

Method 2: Environment Variable

Set the license path in your environment:

export CODE_SCALPEL_LICENSE_PATH=/path/to/license.jwt
claude mcp add codescalpel uvx codescalpel mcp

Method 3: Manual Configuration

Edit your `claude_desktop_config.json` manually:

{
  "mcpServers": {
    "codescalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/path/to/license.jwt"
      }
    }
  }
}

Verify Your License

Check that your license is recognized:

uvx codescalpel tier-info

Expected output for Pro/Enterprise:

Current Tier: pro (or enterprise)
License Status: Valid
Expires: 2025-12-31

Alternative: Manual Configuration

If you prefer to edit configuration files manually:

Claude Desktop (macOS/Windows/Linux):

Edit `~/.claude/claude_desktop_config.json` and add:

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

VS Code / Cursor:

Edit `.vscode/mcp.json` in your workspace:

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

Network Deployments: HTTP Transports

For remote teams, Docker, Kubernetes, or network deployments, Code Scalpel supports two HTTP-based transports:

SSE (Server-Sent Events) - Best for remote teams and Docker:

codescalpel mcp --transport sse --host 0.0.0.0 --port 8080

streamable-http - Best for production systems and load balancers:

codescalpel mcp --transport streamable-http --host 0.0.0.0 --port 8080

With HTTPS for production:

codescalpel mcp --transport sse --ssl-cert cert.pem --ssl-key key.pem

Client configuration (SSE):

{
  "mcpServers": {
    "code-scalpel": {
      "url": "http://localhost:8080/sse",
      "transport": "sse"
    }
  }
}

Client configuration (streamable-http):

{
  "mcpServers": {
    "code-scalpel": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

See the MCP Transports Guide for comprehensive setup instructions, security configuration, and deployment examples.

Troubleshooting

"Command not found: uvx"?

pip install uv

MCP server not showing up in Claude?

1. Restart Claude Code or Claude Desktop

2. Check that `uvx codescalpel` works in your terminal:

uvx codescalpel --version

3. If still not working, try manual configuration (see above)

Debug mode:

Enable verbose logging:

export SCALPEL_MCP_OUTPUT=DEBUG
claude mcp add codescalpel uvx codescalpel mcp

Debug license validation:

export SCALPEL_MCP_OUTPUT=DEBUG
export CODE_SCALPEL_LICENSE_PATH=/path/to/license.jwt  # If needed
claude mcp add codescalpel uvx codescalpel mcp

CLI Usage

All 23 tools are now available directly from the command line!

In addition to the MCP server interface, Code Scalpel provides dedicated CLI commands for every tool. This is perfect for:

• Scripts and automation - Integrate into CI/CD pipelines
• Manual analysis - Quick command-line access without an MCP client
• Shell workflows - Pipe JSON output between tools

Quick Start

# Install Code Scalpel
pip install codescalpel

# View all available commands
codescalpel --help

# Get help for any specific command
codescalpel extract-code --help

Common CLI Commands

See all 23 commands: Complete CLI Tools Reference →

Example Workflows

Extract and Analyze a Function

# Extract function with dependencies
codescalpel extract-code src/api.py --function process_payment --include-deps > extracted.py

# Analyze the extracted code
codescalpel analyze extracted.py --json

# Generate comprehensive tests
codescalpel generate-unit-tests extracted.py

Security Audit Pipeline

# Run basic security scan
codescalpel scan src/

# Deep cross-file taint analysis
codescalpel cross-file-security-scan --max-depth 10

# Check policy compliance
codescalpel code-policy-check src/ --strict

Refactoring with Impact Analysis

# Get current call graph
codescalpel get-call-graph src/auth.py

# Find all references
codescalpel get-symbol-references UserAuthentication

# Simulate refactor
codescalpel simulate-refactor src/auth.py --changes "rename UserAuthentication to AuthService"

# Perform rename
codescalpel rename-symbol src/auth.py UserAuthentication AuthService

JSON Output for Automation

All commands support `--json` flag for machine-readable output:

# Get JSON output
codescalpel analyze src/main.py --json | jq '.functions[] | .name'

# Pipe between commands
codescalpel crawl-project --json | jq '.high_complexity_files[]' | \
  xargs -I {} codescalpel analyze {} --json

Tier System

All CLI tools respect the same three-tier licensing system as the MCP server:

• Community (Free): All tools available with basic limits
• Pro: Enhanced limits, cross-file analysis, parallel processing
• Enterprise: Unlimited thresholds, advanced features

Check your current tier and limits:

codescalpel capabilities

**For complete CLI documentation, see CLI Tools Reference.**

Release Information

Launch Date: January 2026

Version: v2.2.0

License: MIT (Community)

Code Scalpel is built for the new era of Agentic Engineering. It is not just a linter; it is the sensory and actuator system for the next generation of AI developers.

Documentation

• **Getting Started** - Detailed setup guide
• **Configuration Guide** - All configuration options
• **API Reference** - Complete tool documentation
• **Security Analysis** - How vulnerability detection works

Community

Have questions? Open an issue or start a discussion.