Skip to main content

File Operations

📖 Best for: Developers / ops / content editors / platform admins — people who want AI to read, write, edit, search, and batch-process multi-format files (plain text, Office, PDF, images) directly in their workspace

📖 Reading time: 4 minutes

📖 In one sentence: YingClaw's complete file operations toolkit covering read/write/edit/search/batch-processing, supports plain text, Office, PDF, and images. Runs safely in the workspace with chunked reads for large files, string-level precise editing, ripgrep-powered cross-file search, and structured Office/PDF parsing. Invoked as part of the YingClaw conversation at any time — no standalone menu, all roles.

I. Core Value​

ValueDescription
Multi-format coverageOne toolkit handles plain text, Office, PDF, and images — no need to learn different commands per format
Precise editingString-level exact-match replacement (file_edit); only edits if old_string is unique, avoiding collateral damage
High-speed searchripgrep-powered content_search does cross-file regex search; thousands of files in seconds
Batch processingglob_search + content_search combo makes "find a class of files + edit a chunk" trivial
Large-file friendlylimit / offset chunked reads, byte offsets, auto-paginated PDF reads (200K char cap)

II. Main Capabilities​

1. Multi-Format Read​

  • Plain text: txt / md / json / yaml / xml / csv / log — file_read shows with line numbers
  • Office documents: docx paragraph-level extraction · xlsx cell / sheet access · pptx slide structure
  • PDF: pdf_read plain-text extraction (auto-paginated for large docs, max 200K chars)
  • Image: image_info reads format / dimensions / size, optional base64 encoding

2. Write & Overwrite​

  • file_write creates or overwrites files, auto-creates parent directories
  • Supports arbitrary text content (code, configs, Markdown, long-form)
  • Binary writes need base64 encoding first (images / PDFs, etc.)

3. Precise Edit (String-Level)​

  • file_edit replaces a chunk of text via exact match — only executes if the match is unique
  • Perfect for "change one place without touching others" (rename a function, fix a typo, adjust a config)
  • Avoids the format loss / accidental-delete risk of full overwrites
  • glob_search finds files by wildcard (e.g. **/*.md for all markdown)
  • Supports ** cross-dir, *.ext extension match, ? single char
  • Returns sorted path list — fits "find then process" workflows

5. Content Search (ripgrep-powered)​

  • content_search does cross-file regex search
  • Thousands of files returned in seconds; auto-skips .git / node_modules etc.
  • Supports case-sensitive toggle, file-type filter, context output

6. Chunked Read for Large Files​

  • file_read supports offset start line + limit max lines
  • Multi-GB logs can be paginated; never blows context
  • pdf_read supports max_chars (default 50K, max 200K)
  • Use content_search to locate, then file_read for the key section

7. PDF Extraction & Analysis​

  • pdf_read plain-text extraction (rasterized scanned PDFs don't support text extraction)
  • Large docs auto-paginate; can set max_chars per call
  • Suits: contract review / paper summarization / report analysis / regulation lookup

8. Image Metadata​

  • image_info reads format, dimensions, size, optional base64 encoding
  • Multimodal models can view images directly (understand content, extract text)
  • Suits: screenshot interpretation / OCR alternative / visual Q&A / image classification

III. Typical Use Cases​

Use Case 1: Read a PDF — "Tell me what chapter 3 of this contract covers"​

# 1. extract PDF text
text = pdf_read("contract.pdf", max_chars=50000)
# 2. locate the chapter with search
result = content_search("chapter 3", include="*.pdf", path="contracts/")
# 3. multimodal can read image-based PDFs

YingClaw auto-locates the chapter, summarizes the key content, annotates the page number — answer in 3 steps, no need to flip 50 pages yourself.

Use Case 2: Split Excel by Department — "Split this Excel by the 'department' column into multiple sheets"​

# 1. read Excel
import openpyxl
wb = openpyxl.load_workbook("employees.xlsx")
ws = wb.active
# 2. group by department
groups = {}
for row in ws.iter_rows(min_row=2, values_only=True):
    dept = row[2]
    groups.setdefault(dept, []).append(row)
# 3. one sheet per department
for dept, rows in groups.items():
    new_ws = wb.create_sheet(dept)
    for row in rows:
        new_ws.append(row)
wb.save("employees_by_dept.xlsx")

YingClaw completes read → group → write end-to-end, returning per-sheet row count / department list — a multi-sheet report in seconds.

Use Case 3: Cross-File Search — "Find every file in workspace containing TODO"​

# content search (ripgrep-powered)
content_search("TODO", path="src/", include="*.py", output_mode="files_with_matches")
# output: every file with TODO + line number + context

Supports regex + file-type filter; thousands of files in seconds — much faster than manual search.

Use Case 4: Precise Edit — "Change every oldName in this md to newName"​

# 1. read full text
text = file_read("doc.md")
# 2. full replacement
new_text = text.replace("oldName", "newName")
# 3. overwrite
file_write("doc.md", new_text)

Or use the safer file_edit tool: matches one place at a time and confirms before changing — suited to uncertain replacement scopes.

Use Case 5: Image Metadata & Interpretation — "How big is this image? What format?"​

# read metadata
image_info("screenshot.png", include_base64=False)
# output: format=PNG, size=1920x1080, file_size=345KB
# multimodal understanding (view image directly)
# with vision model: image_info + base64 → "this image is a product homepage screenshot, top nav has 5 menu items..."

From basic metadata (size / format) to deep understanding (content / OCR / visual Q&A) — one toolkit covers it all.

IV. Usage Guide​

Step 1: Read a file — for simple text use file_read("path/to/file.md"), shown with line numbers; for large files add limit=200 offset=100 for chunked read; for PDF use pdf_read; for Office the corresponding library is called automatically.

Step 2: Edit a file — for precise edits use file_edit("path", old_string="original", new_string="replacement"); old_string must be unique in the file; for large rewrites use file_write to overwrite fully (carefully).

Step 3: Search for files — by name use glob_search("**/*.py"); by content use content_search("TODO", include="*.py"); supports regex, case-sensitive toggle, context line count.

Step 4: Handle PDFs — pdf_read("doc.pdf", max_chars=100000) extracts text; rasterized scans need OCR first or a multimodal model to read as image; for large docs, paginate and use content_search to find key sections.

Step 5: Handle Office — docx reads by paragraph · xlsx by sheet / cell · pptx by slide; writes use libraries like openpyxl / python-docx (YingClaw installs them automatically).

Step 6: Batch tasks — for complex batch processing (change a header across all company docs, rename thousands of files) use shell-command + file-operations combo; YingClaw auto-decomposes via a todo list and reports progress step by step.

V. Best Practices​

  • Always chunk large files — files over 1000 lines / 50KB use limit + offset to read in chunks; don't blow context in one go
  • Prefer file_edit over full rewrite — for one-place changes use file_edit (precise, rollback-able); for multi-place use file_write but read fully first
  • file_edit requires old_string to be unique — if not, add surrounding context (a few lines before/after) and retry; otherwise it refuses to execute
  • Use content_search for search — ripgrep is thousands of times faster than manual scanning; thousands of files in seconds
  • Unified cross-format interface — just describe what you need in natural language for PDF / Word / Excel; YingClaw picks the right tool — no API to remember
  • Read before edit / overwrite — always file_read first to see the current state; avoid editing wrong or overwriting existing content
  • Back up before delete — copy important files before delete / overwrite (cp file file.bak) so mistakes are recoverable
  • Don't return base64 for large images by default — image reads return metadata only by default; only set include_base64=True when actually needed, to avoid context bloat
  • PDF: text first, OCR second — text-based PDFs are fast and accurate via text extraction; scanned versions need multimodal (expensive) — choose by use case
  • Dry-run before batch ops — before find ... -delete / full rewrites, add -print or "list all files to change" first; confirm before running for real