kdeps-tools-read_file

version: 1.0.0
category: file
description: 'Read a file from the local filesystem. Returns the contents with a 1-based line number on every line (`  42\tcode$`) - use those numbers for edit_file insert/view. Tabs render as ^I, other control characters as ^X, and a $ marks the true end of each line, so indentation, trailing whitespace, and stray control characters are visible instead of hidden. IMPORTANT: ^I, ^X, and the trailing $ are a display convention this tool adds - the real file does NOT contain those literal characters. When quoting text back into edit_file''s old_str, write the real tab/control character (or match a whole line via view_range/anchor instead), never the literal caret sequence - copying "^I" as text will not match a real tab byte. Plain text, source code, configuration files, and documentation are read directly; PDF, DOCX, EPUB, RTF, and ODT documents have their text extracted automatically. Use load_document instead for CSV/HTML structured parsing or RAG chunking. Pass match_id (from a search_local result) instead of file_path/offset to jump straight to that hit.'
constraints: max ~2000 lines per read; use offset/limit for large files; must use absolute path; do not re-read a file already in this conversation unless it changed; you MUST read a file (here or via edit_file command:view) before edit_file str_replace/insert can change it; DOCX/EPUB/RTF/ODT extraction requires pandoc on PATH, PDF needs no external tool
outputFormat: text with a 1-based line number on each line; tabs shown as ^I, control chars as ^X, $ marks true end of line (display only - not literal file content)
seeAlso: list_files, search_local, edit_file, load_document
parameters:
  context_after:
    type: number
    description: 'Only with match_id: lines of context after the match (default 20)'
  context_before:
    type: number
    description: 'Only with match_id: lines of context before the match (default 20)'
  file_path:
    type: string
    description: Absolute path to the file to read. Omit to re-read the file most recently accessed this session (e.g. to read more of it with offset/limit), or use match_id instead.
  limit:
    type: number
    description: Maximum number of lines to read. Optional; reads entire file up to the size limit if omitted.
  match_id:
    type: string
    description: A match_id from a search_local result, instead of file_path. Reads the region around that hit (context_before/context_after lines, default 20 each).
  offset:
    type: number
    description: Line number to start reading from (1-based). Optional; reads from beginning if omitted.