codemap_peek

Get comprehensive file overview — imports, importedBy, all symbols with call graph data (calls + calledBy per symbol always included), groups, labels, and file metadata. The 'show everything' tool for a single file.

iopeekoverviewsymbolscall-graphmetadatainspect

Parameters

Name	Type	Required	Description
`target`	`string`	✅ Required	Relative path to the file
`annotations`	`boolean`	❌ Optional	Include annotations (both core and categorized). Default: false (default: `false`)
`content`	`boolean`	❌ Optional	Include full file content, line count, and character count. Default: false (default: `false`)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_peek",
  "arguments": {
    "target": "src/services/UserService.ts"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "relativePath": "src/services/UserService.ts",
    "name": "UserService.ts",
    "dirPath": "src/services",
    "lastModified": 1775608976028,
    "lastModifiedDate": "2026-04-07T15:42:56.028Z",
    "contentHash": "a3f5b2c",
    "imports": [
      "src/lib/database.ts",
      "src/types/user.ts",
      "src/utils/validators.ts"
    ],
    "importedBy": [
      "src/api/routes/users.ts",
      "src/middleware/auth.ts"
    ],
    "groups": [
      {
        "name": "user-domain",
        "description": "User management layer",
        "memberCount": 6,
        "notationCount": 2
      }
    ],
    "groupCount": 1,
    "labels": [
      {
        "id": "lbl_complete",
        "emoji": "✅",
        "name": "Complete",
        "description": "Implementation is complete"
      }
    ],
    "labelCount": 1,
    "summary": "User CRUD service",
    "tags": [
      "service",
      "users"
    ],
    "symbolCount": 3,
    "symbols": [
      {
        "kind": "class",
        "name": "UserService",
        "startLine": 8,
        "endLine": 60,
        "exported": true,
        "calls": [
          "src/lib/database.ts$query",
          "src/utils/validators.ts$validateEmail"
        ],
        "calledBy": []
      },
      {
        "kind": "method",
        "name": "getUser",
        "startLine": 15,
        "endLine": 24,
        "exported": false,
        "calls": [
          "src/lib/database.ts$query"
        ],
        "calledBy": [
          "src/api/routes/users.ts$getUserHandler"
        ]
      },
      {
        "kind": "method",
        "name": "deleteUser",
        "startLine": 26,
        "endLine": 38,
        "exported": false,
        "calls": [
          "src/lib/database.ts$query"
        ],
        "calledBy": []
      }
    ]
  }
}

ℹ️When to Use This Tool

codemap_peek

Inspect file metadata before editing (size, modified date, hash)
Check dependencies (what file imports and what imports it)
Verify file organization (groups, labels)
Quick symbol overview without reading full file
Validate file state before operations

💡Common Patterns

Pre-Edit Inspection

1. Peek file to check metadata
2. Verify not locked/readonly
3. Check modification date
4. Proceed with edit

Dependency Analysis

1. Peek with symbols: true
2. Count imports and importedBy
3. Assess coupling
4. Plan refactoring if needed

Group Discovery

1. Peek file
2. Check groups field
3. Navigate to related files

💡Pro Tips

Start without optional flags: Basic peek is fast. Only add symbols/annotations/content if needed.
Use for quick dependency checks: peek shows imports/importedBy without heavy analysis.
Check groups for context: Groups reveal related files and architectural patterns.
Verify before operations: Peek before delete/rename to understand impact.
Content preview is limited: For full content, use read tool instead.

✅Best Practices

Use basic peek first, add flags only if needed
Check importedBy before deleting files
Verify groups to understand file's role in architecture
Use peek before refactoring to assess impact
Combine with list for directory analysis
Cache peek results if analyzing multiple times

⚠️Common Mistakes

❌ Mistake: Always using symbols/annotations/content flags, slowing performance
✅ Instead: Start with basic peek, add flags only when you need that specific data

❌ Mistake: Not checking importedBy before deleting files
✅ Instead: Always peek first to see what depends on the file

❌ Mistake: Using peek for full file content when you need to edit
✅ Instead: Use read tool for complete content, peek for overview

❌ Mistake: Ignoring groups field, missing architectural context
✅ Instead: Check groups to understand file's role and find related files

❌ Mistake: Peeking same file repeatedly instead of caching
✅ Instead: Store peek results if you'll analyze multiple times

❌ Mistake: Expecting real-time content in contentPreview
✅ Instead: contentPreview is a snapshot - use read for current content

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_io_read

codemap_io_get-symbols

codemap_io_get-annotations

codemap_graph_get-dependencies