Skip to content

get_file_context

Quickly assess file relevance by getting structure and metadata without loading full content. Useful for understanding what a file contains before deeper analysis.

Quick Reference

get_file_context(
    file_path: str               # Path to file
) -> FileContext

User Stories

Persona Story Tool Value
👤 Sarah (AI User) "I want to quickly check if a file is relevant before reading it all" Avoid unnecessary file reads
🔰 Alex (First-Timer) "Get a quick overview of what's in this file without reading all the code" Fast file assessment
👥 David (Team Lead) "Quickly assess file relevance during code reviews" Efficient reviews

→ See all user stories

Parameters

Parameter Type Required Default Description
file_path string Yes - Absolute path to file

Response Schema

{
  "data": {
    "file_path": "string",
    "file_name": "string",
    "language": "string",
    "size_bytes": "integer",
    "line_count": "integer",
    "last_modified": "string",
    "summary": {
      "functions": ["string"],
      "classes": ["string"],
      "imports": ["string"],
      "exports": ["string"]
    },
    "docstring": "string | null",
    "is_test_file": "boolean",
    "is_config_file": "boolean",
    "complexity_estimate": "string"
  },
  "tier_applied": "string",
  "duration_ms": "integer"
}

Examples

Get File Overview

What's in the user_service.py file?

{
  "file_path": "/project/services/user_service.py"
}

codescalpel get-file-context services/user_service.py

{
  "data": {
    "file_path": "/project/services/user_service.py",
    "file_name": "user_service.py",
    "language": "python",
    "size_bytes": 4250,
    "line_count": 145,
    "last_modified": "2025-02-01T10:30:00Z",
    "summary": {
      "functions": [],
      "classes": ["UserService"],
      "imports": [
        "from models.user import User",
        "from db import Database",
        "from typing import Optional, List"
      ],
      "exports": ["UserService"]
    },
    "docstring": "Service layer for user operations including CRUD and authentication.",
    "is_test_file": false,
    "is_config_file": false,
    "complexity_estimate": "medium"
  },
  "tier_applied": "community",
  "duration_ms": 25
}

Check Test File

Is test_users.py a test file and what does it test?

{
  "file_path": "/project/tests/test_users.py"
}

codescalpel get-file-context tests/test_users.py

{
  "data": {
    "file_path": "/project/tests/test_users.py",
    "file_name": "test_users.py",
    "language": "python",
    "size_bytes": 2100,
    "line_count": 78,
    "summary": {
      "functions": [
        "test_create_user",
        "test_get_user_by_id",
        "test_update_user",
        "test_delete_user",
        "test_invalid_email_raises"
      ],
      "classes": ["TestUserService"],
      "imports": [
        "import pytest",
        "from services.user_service import UserService"
      ]
    },
    "is_test_file": true,
    "is_config_file": false
  },
  "tier_applied": "community",
  "duration_ms": 18
}

Check Configuration File

What's in pyproject.toml?

{
  "file_path": "/project/pyproject.toml"
}

codescalpel get-file-context pyproject.toml

{
  "data": {
    "file_path": "/project/pyproject.toml",
    "file_name": "pyproject.toml",
    "language": "toml",
    "size_bytes": 1250,
    "line_count": 45,
    "summary": {
      "sections": [
        "[project]",
        "[project.dependencies]",
        "[project.optional-dependencies]",
        "[tool.pytest.ini_options]",
        "[tool.black]"
      ]
    },
    "is_test_file": false,
    "is_config_file": true,
    "config_type": "python_project"
  },
  "tier_applied": "community",
  "duration_ms": 12
}

Large File Assessment

Should I analyze the entire legacy_handler.py?

{
  "file_path": "/project/legacy/legacy_handler.py"
}

codescalpel get-file-context legacy/legacy_handler.py

{
  "data": {
    "file_path": "/project/legacy/legacy_handler.py",
    "file_name": "legacy_handler.py",
    "language": "python",
    "size_bytes": 45000,
    "line_count": 1250,
    "summary": {
      "functions": [
        "handle_request",
        "process_data",
        "validate_input",
        "format_response",
        "log_activity",
        "... 15 more"
      ],
      "classes": ["LegacyHandler", "RequestProcessor"],
      "imports": ["... 25 imports"]
    },
    "complexity_estimate": "high",
    "warning": "Large file with high complexity. Consider analyzing specific functions."
  },
  "tier_applied": "community",
  "duration_ms": 35
}

File Type Detection

File Pattern Detection
test_*.py, *_test.py Test file
conftest.py Pytest config
*.config.js, *.json Config file
pyproject.toml Python project config
setup.py Python setup
Dockerfile Docker config
*.md Documentation

Complexity Estimates

Level Indicators
low < 100 lines, few functions/classes
medium 100-500 lines, moderate structure
high > 500 lines, many functions/classes
very_high > 1000 lines, complex structure

Tier Limits

get_file_context capabilities vary by tier:

Feature Community Pro Enterprise
Max context lines 500 2,000 Unlimited
File size support Basic Extended Full
Symbol summary ✅ ✅ ✅
Complexity estimate ✅ ✅ ✅
Dependency analysis ❌ ✅ ✅
History info ❌ ❌ ✅ Git integration

Community Tier

  • ✅ Get file overview without reading full content
  • ✅ Basic symbol summary (functions, classes, imports)
  • ✅ File metadata (size, line count, last modified)
  • ✅ Complexity estimate
  • ⚠️ Limited to 500 context lines - Large files truncated
  • ❌ No dependency analysis
  • ❌ No Git history integration

Pro Tier

  • ✅ All Community features
  • ✅ Extended context lines (2,000) - Handle larger files
  • ✅ Dependency analysis - See what file imports/exports
  • ✅ Enhanced symbol detection
  • ✅ Better performance on large codebases

Enterprise Tier

  • ✅ All Pro features
  • ✅ Unlimited context lines - No file size restrictions
  • ✅ Git history integration - Last commit, author, blame info
  • ✅ Advanced metadata - Full repository context
  • ✅ Custom analyzers - Extend with organization-specific rules

Key Difference: Context Line Limits - Community: 500 lines max - Fast overview, may truncate large files - Pro: 2,000 lines - Handle most production files completely - Enterprise: Unlimited - Complete context for any file size

→ See tier comparison

Best Practices

  1. Check before analyzing - Avoid wasting tokens on irrelevant files
  2. Assess complexity - Large files may need targeted analysis
  3. Identify file purpose - Test, config, or source
  4. Use for navigation - Quick overview of unfamiliar codebase