codemap_read_file

Read file contents with pagination. Supports symbol references (file.ts$symbolName) to read just that symbol. Use offset/length for large files.

filereadiosymbolpaginationview

Parameters

Name	Type	Required	Description
`path`	`string`	✅ Required	File path (relative or absolute)
`offset`	`number`	❌ Optional	Start line (1-based, like editors). Line 1 = first line. Negative values read last N lines (default: 1)
`length`	`number`	❌ Optional	Max lines to read (default: 250)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_read_file",
  "arguments": {
    "path": "src/utils/helpers.ts"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "path": "src/utils/helpers.ts",
  "content": "import { format } from 'date-fns';\n\nexport function formatDate(date: Date): string {\n  return format(date, 'yyyy-MM-dd');\n}\n\nexport function formatCurrency(amount: number): string {\n  return new Intl.NumberFormat('en-US', {\n    style: 'currency',\n    currency: 'USD'\n  }).format(amount);\n}",
  "totalLines": 45,
  "linesRead": 45,
  "pagination": "Reading 45 lines (1-45 of 45)",
  "size": 1247
}

ℹ️When to Use This Tool

codemap_read_file

Inspect file contents before making changes
Read configuration files or data files
Extract specific functions or classes using symbol references
View logs or output files
Read the last N lines of growing files (like logs)
Get file content for analysis or processing

💡Common Patterns

Inspect Before Edit Workflow

1. Read file: {"name": "codemap_read_file", "arguments": {"path": "file.ts"}}
2. Identify what needs changing
3. Make targeted edits with replace_text
4. Verify changes by reading again

Always read before editing to understand context.

Symbol-Specific Reading

1. Read just the function: {"name": "codemap_read_file", "arguments": {"path": "file.ts$funcName"}}
2. Analyze implementation
3. Make changes to that specific symbol
4. No need to process entire file

Symbol references are faster and more focused than reading entire files.

Log Tailing Pattern

1. Read last N lines: {"name": "codemap_read_file", "arguments": {"path": "app.log", "offset": -100}}
2. Check for errors or recent activity
3. Repeat as needed

Negative offset is perfect for log monitoring.

💡Pro Tips

Use symbol references for large files: Reading src/huge-file.ts$myFunction is much faster than reading the entire 5000-line file and searching for the function yourself.
Negative offsets for log files: Use offset: -50 to read the last 50 lines. This is essential for log tailing and checking recent activity without loading the entire log.
Respect the pagination defaults: The 250-line default limit exists for good reason. Large files can overwhelm your context window. Use offset/length to read in chunks.
Check totalLines before full reads: The response includes totalLines and linesRead. If totalLines > linesRead, you know the file was truncated and you can decide whether to read more.
Symbol syntax is path$symbolName: Use a dollar sign to separate the file path from the symbol name. Works with functions, classes, interfaces, types, etc.

✅Best Practices

Always check file size (totalLines) before reading large files - you may want to read in chunks instead
Use symbol references when you only need specific functions or classes, not the entire file
For configuration files, read once and cache the content rather than reading repeatedly
When debugging, read the specific symbol that's failing rather than the entire module
Use negative offsets for log files and growing data files to see recent content

⚠️Common Mistakes

❌ Mistake: Reading entire large files when you only need one function
✅ Instead: Use symbol reference: read only the specific symbol you need

❌ Mistake: Using offset: 0 to read from the beginning
✅ Instead: Omit offset entirely - it defaults to line 1 (files are 1-indexed like editors)

❌ Mistake: Reading the same file multiple times in a session
✅ Instead: Read once and store the content in a variable for reuse

❌ Mistake: Forgetting that large files are paginated automatically
✅ Instead: Check pagination field in response. If linesRead < totalLines, the file was truncated. Use offset/length to read the rest.

❌ Mistake: Using read_file for binary files or very large files (>10,000 lines)
✅ Instead: Use peek for file overview, or use offset/length to read specific sections. CodeMap is designed for code files, not binary or massive data files.

❌ Mistake: Reading files just to check if they exist
✅ Instead: Use peek or list tools for metadata without reading content

Changelog

1 release

- 🐛FixedLine-range targets (file.ts:10-20) now resolve correctly. A stray double-escape (\\d instead of \d) in the line-range regex caused ranges to fail silently — all line-range reads affected before this fix.
- 🐛FixedSymbol reads (file.ts$symbolName) now work on multi-line files of any size. A newline-handling bug in TargetResolver.extractSymbolContent (splitting on the literal two-character string \n rather than a newline character) caused symbol reads to return undefined from the first symbol onward on any multi-line file.

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_io_write

codemap_io_peek

codemap_io_read-multiple