Skip to content

extract_code

Extract specific code symbols (functions, classes, methods) from source files with optional dependency resolution.

Quick Reference

extract_code(
    file_path: str,                      # Path to file
    target_type: str,                    # "function", "class", "method"
    target_name: str,                    # Symbol name
    code: str = None,                    # Or provide code directly
    language: str = None,                # Language hint
    include_context: bool = False,       # Include surrounding code
    context_depth: int = 1,              # Context levels
    include_cross_file_deps: bool = False,  # Resolve imports
    include_token_estimate: bool = True  # Estimate tokens
) -> ExtractionResult

User Stories

Persona Story Tool Value
👤 Sarah (AI User) "I need to extract just one function without Claude reading the entire 5,000-line file" 200x token reduction
🔰 Alex (First-Timer) "Extract exactly one function by name - no line numbers needed" Clear value demonstration
👥 David (Team Lead) "Calculate token savings: 5000 lines → 20 lines extracted" Quantified cost reduction
🔧 Chris (OSS Contributor) "Extract specific modules for focused testing" Targeted development

→ See all user stories

Parameters

Parameter Type Required Default Description
file_path string Yes* - Absolute path to file
target_type string Yes - "function", "class", or "method"
target_name string Yes - Name of the symbol to extract
code string No None Source code as string (alternative to file_path)
language string No auto python, javascript, typescript, java, jsx, tsx
include_context bool No false Include dependencies in same file
context_depth int No 1 How many levels of dependencies
include_cross_file_deps bool No false Resolve cross-file imports
include_token_estimate bool No true Include token count estimate

Response Schema

{
  "data": {
    "target_type": "string",
    "target_name": "string",
    "code": "string",
    "line_start": "integer",
    "line_end": "integer",
    "file_path": "string",
    "language": "string",
    "dependencies": ["string"],
    "cross_file_dependencies": [
      {
        "symbol": "string",
        "source_file": "string",
        "code": "string"
      }
    ],
    "token_estimate": "integer",
    "docstring": "string | null",
    "signature": "string"
  },
  "error": null,
  "tier_applied": "string",
  "duration_ms": "integer"
}

Examples

Extract a Function

Extract the validate_email function from src/utils/validators.py

{
  "file_path": "/project/src/utils/validators.py",
  "target_type": "function",
  "target_name": "validate_email"
}

codescalpel extract-code src/utils/validators.py --function validate_email

{
  "data": {
    "target_type": "function",
    "target_name": "validate_email",
    "code": "def validate_email(email: str) -> bool:\n    \"\"\"Validate email format.\"\"\"\n    pattern = r'^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$'\n    return bool(re.match(pattern, email))",
    "line_start": 15,
    "line_end": 19,
    "file_path": "/project/src/utils/validators.py",
    "language": "python",
    "dependencies": ["re"],
    "token_estimate": 45,
    "docstring": "Validate email format.",
    "signature": "def validate_email(email: str) -> bool"
  },
  "tier_applied": "community",
  "duration_ms": 28
}

Extract a Class

Extract the UserService class from services/user_service.py

{
  "file_path": "/project/services/user_service.py",
  "target_type": "class",
  "target_name": "UserService"
}

codescalpel extract-code services/user_service.py --class UserService

{
  "data": {
    "target_type": "class",
    "target_name": "UserService",
    "code": "class UserService:\n    \"\"\"Service for user operations.\"\"\"\n    \n    def __init__(self, db: Database):\n        self.db = db\n    \n    def get_user(self, user_id: int) -> User:\n        return self.db.query(User).filter(User.id == user_id).first()\n    \n    def create_user(self, data: dict) -> User:\n        user = User(**data)\n        self.db.add(user)\n        self.db.commit()\n        return user",
    "line_start": 10,
    "line_end": 24,
    "dependencies": ["Database", "User"],
    "token_estimate": 120
  },
  "tier_applied": "community",
  "duration_ms": 35
}

Extract a Method

Extract the process method from the DataProcessor class in processor.py

{
  "file_path": "/project/processor.py",
  "target_type": "method",
  "target_name": "DataProcessor.process"
}

codescalpel extract-code processor.py \
  --function process \
  --class DataProcessor

{
  "data": {
    "target_type": "method",
    "target_name": "process",
    "parent_class": "DataProcessor",
    "code": "def process(self, data: list) -> list:\n    \"\"\"Process data items.\"\"\"\n    results = []\n    for item in data:\n        transformed = self.transform(item)\n        validated = self.validate(transformed)\n        results.append(validated)\n    return results",
    "line_start": 25,
    "line_end": 33,
    "dependencies": ["transform", "validate"],
    "token_estimate": 65
  },
  "tier_applied": "community",
  "duration_ms": 32
}

Extract with Dependencies

Extract process_order with all its dependencies from order_service.py

{
  "file_path": "/project/services/order_service.py",
  "target_type": "function",
  "target_name": "process_order",
  "include_context": true,
  "context_depth": 2,
  "include_cross_file_deps": true
}

codescalpel extract-code services/order_service.py \
  --function process_order \
  --include-context \
  --context-depth 2 \
  --include-cross-file-deps

{
  "data": {
    "target_type": "function",
    "target_name": "process_order",
    "code": "def process_order(order_data: dict) -> Order:\n    ...",
    "dependencies": ["validate_order", "calculate_total", "Order"],
    "cross_file_dependencies": [
      {
        "symbol": "Order",
        "source_file": "models/order.py",
        "code": "class Order:\n    ..."
      },
      {
        "symbol": "validate_order",
        "source_file": "validators/order_validator.py",
        "code": "def validate_order(data: dict) -> bool:\n    ..."
      }
    ],
    "combined_code": "# From models/order.py\nclass Order:\n    ...\n\n# From validators/order_validator.py\ndef validate_order(data: dict) -> bool:\n    ...\n\n# From services/order_service.py\ndef process_order(order_data: dict) -> Order:\n    ...",
    "token_estimate": 350
  },
  "tier_applied": "pro",
  "duration_ms": 125
}

Extract React Component

Extract the UserCard component from components/UserCard.tsx

{
  "file_path": "/project/components/UserCard.tsx",
  "target_type": "function",
  "target_name": "UserCard",
  "language": "tsx"
}

codescalpel extract-code components/UserCard.tsx \
  --function UserCard \
  --language tsx

{
  "data": {
    "target_type": "function",
    "target_name": "UserCard",
    "code": "export function UserCard({ user, onEdit }: UserCardProps) {\n  const [isEditing, setIsEditing] = useState(false);\n  \n  return (\n    <div className=\"card\">\n      <h2>{user.name}</h2>\n      <p>{user.email}</p>\n      <button onClick={() => setIsEditing(true)}>Edit</button>\n    </div>\n  );\n}",
    "component_type": "functional",
    "is_server_component": false,
    "token_estimate": 85
  },
  "tier_applied": "community",
  "duration_ms": 42
}

Tier Differences

This tool is available at all tiers. What differs are the limits and capabilities:

Feature Community Pro Enterprise
Availability ✅ Available ✅ Available ✅ Available
Basic extraction ✅ ✅ ✅
include_context ✅ ✅ ✅
context_depth 1 5 Unlimited
include_cross_file_deps Not available ✅ ✅ Advanced
Max file size 500 KB 5 MB Unlimited
Token estimation ✅ ✅ ✅
Dependency resolution Same file only Cross-file Advanced resolution

Error Handling

Symbol Not Found

{
  "data": null,
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Function 'calculte_total' not found in order_service.py",
    "suggestions": [
      "calculate_total",
      "calculate_subtotal"
    ],
    "available_symbols": {
      "functions": ["calculate_total", "calculate_subtotal", "process_order"],
      "classes": ["OrderService"]
    }
  }
}

Wrong Symbol Type

{
  "data": null,
  "error": {
    "code": "WRONG_SYMBOL_TYPE",
    "message": "'UserService' is a class, not a function",
    "suggestion": "Use target_type='class' instead"
  }
}

Tier Limits

Extraction capabilities vary by tier:

Feature Community Pro Enterprise
Cross-file deps ❌ Disabled ✅ Depth 1 ✅ Unlimited
Max depth 0 1 Unlimited (-1)
Max extraction size 1 MB 10 MB 100 MB
Languages Python, JS, TS, Java Python, JS, TS, Java All
Organization-wide ❌ ❌ ✅

Community Tier

  • ✅ Extract functions, classes, methods by name
  • ✅ Intra-file context extraction
  • ✅ Multi-language support (Python, JS, TS, Java)
  • ✅ Token estimates
  • ⚠️ Cross-file dependencies disabled
  • ⚠️ Max 1 MB extraction size

Pro Tier

  • ✅ All Community features
  • ✅ Cross-file dependency extraction (Python only, depth 1)
  • ✅ Confidence scoring for dependencies
  • ✅ React component metadata (JSX/TSX)
  • ✅ Up to 10 MB extraction size
  • ✅ Decorator/annotation preservation
  • ✅ Type hint preservation

Enterprise Tier

  • ✅ All Pro features
  • ✅ Unlimited cross-file depth
  • ✅ Organization-wide resolution (monorepo/multi-repo)
  • ✅ Custom extraction patterns
  • ✅ Service boundary detection
  • ✅ Up to 100 MB extraction size
  • ✅ Function-to-microservice packaging

Key Difference: Cross-File Dependencies - Community: Extracts symbol only (no dependency resolution) - Pro: Resolves direct dependencies (depth 1) with confidence scores - Enterprise: Full dependency chain resolution across entire codebase

→ See tier comparison

Best Practices

  1. Use analyze_code first - Know what symbols exist before extracting
  2. Extract before modifying - Get the exact current code
  3. Use cross-file deps for complex functions - Get full context
  4. Check token estimates - Know context window impact

Workflow Example

graph LR
    A[analyze_code] --> B{Symbol exists?}
    B -->|Yes| C[extract_code]
    B -->|No| D[Check suggestions]
    C --> E[Modify code]
    E --> F[update_symbol]