File Tools

Yukkai provides five complementary tools for working with files on your Mac. Each is purpose-built for a specific operation — reading, writing, editing, searching file contents, or finding files by name pattern.

Overview

Tool	Purpose	Key Parameters
file_read	Read file content with line numbers	file_path, offset, limit
file_write	Write or append content to a file	file_path, content, append
file_edit	Replace a specific string in a file	file_path, old_string, new_string
glob	Find files by name pattern	pattern, path
grep	Search file contents by regex	pattern, path, include

---

file_read

Read the content of any text or code file with automatic line numbering. Ideal for inspecting source code, configuration files, logs, and plain-text documents.

Parameters

Parameter	Type	Required	Description
file_path	string	Yes	Absolute or relative path to the file
offset	integer	No	Starting line number (1-indexed). Default: 1
limit	integer	No	Maximum number of lines to read

Example

file_read(file_path: "src/main.swift", offset: 10, limit: 50)
→ Returns lines 10–59 with line numbers

Tips

• Use offset and limit together to read large files in manageable chunks.
• For PDFs, images, or Office documents, use read_document instead — file_read is for plain text and code.
• Line numbers are always included in the output, making it easy to reference specific lines in follow-up edits.

---

file_write

Write content to a file. Creates the file if it doesn't exist, and automatically creates intermediate directories as needed. Supports both overwrite and append modes.

Parameters

Parameter	Type	Required	Description
file_path	string	Yes	Path to the file to write
content	string	Yes	Content to write
append	boolean	No	If true, append to the end of the file instead of overwriting. Default: false

Rules

• Always use file_write for file creation — never use shell heredocs (cat << EOF).
• Write files sequentially (one at a time), never in parallel.
• Keep each call under ~300 lines / ~8000 characters of content. For larger files, use append: true across multiple calls:

1. file_write(file_path: "big.txt", content: "First 250 lines...")
2. file_write(file_path: "big.txt", content: "Next 250 lines...", append: true)
3. file_write(file_path: "big.txt", content: "Final part", append: true)

Example

file_write(file_path: "config.json", content: "{\"theme\": \"dark\"}")
file_write(file_path: "log.txt", content: "New entry\n", append: true)

---

file_edit

Edit a file by replacing an exact, unique string occurrence. This is the preferred method for making targeted changes to existing files without rewriting them entirely.

Parameters

Parameter	Type	Required	Description
file_path	string	Yes	Path to the file to edit
old_string	string	Yes	Exact text to find (must be unique in the file)
new_string	string	Yes	Replacement text

Rules

• old_string must match exactly, including indentation and newlines.
• Only one occurrence should match — if multiple matches exist, the replacement is ambiguous and may fail.
• Prefer minimal edits over rewriting entire files. Use file_read first to get the exact text and line numbers.

Example

file_edit(
  file_path: "src/config.swift",
  old_string: "let timeout = 30",
  new_string: "let timeout = 60"
)

---

glob

Find files matching a glob pattern. Supports * (single-level wildcard), ** (recursive), and ? (single character).

Parameters

Parameter	Type	Required	Description
pattern	string	Yes	Glob pattern (e.g., **/*.swift, src/*.ts)
path	string	No	Base directory for search (required when using **)

⚠️ Safety Rules

• Always specify path when using ** — omitting it triggers a full working-directory scan which is slow and CPU-intensive.
• Results are capped at 1,000 files.
• Timeout: 30 seconds.

Pattern Syntax

Pattern	Meaning
*	Matches anything within one directory level
**	Matches recursively across directories (expensive — always scope with path)
?	Matches a single character

Examples

glob(pattern: "**/*.swift", path: "~/Documents/GIT/MyProject")
glob(pattern: "src/*.ts", path: "~/Projects/myapp")
glob(pattern: "Tests/**/*Tests.swift", path: "~/Documents/GIT/MyProject")

---

grep

Search for a regex pattern in file contents, recursively. Works like grep -rn in the terminal.

Parameters

Parameter	Type	Required	Description
pattern	string	Yes	Search pattern (regex supported)
path	string	No	Directory or file to search (default: current directory)
include	string	No	Glob filter for file types (e.g., *.swift)

Example

grep(pattern: "func.*async", path: "src/", include: "*.swift")

Tips

• Combine include with a file extension to narrow results and speed up the search.
• Regex is fully supported — use . for any character, .* for any sequence, [] for character classes, etc.
• Results include file paths and line numbers, making it easy to jump to file_read for context.

---

Common Workflows

Read → Edit → Verify

1. file_read(file_path: "config.yaml")           // See current content
2. file_edit(file_path: "config.yaml",           // Make targeted change
     old_string: "port: 8080",
     new_string: "port: 3000")
3. file_read(file_path: "config.yaml")           // Verify the change

Find → Read → Understand

1. glob(pattern: "**/*.md", path: "~/Docs")      // Find all markdown files
2. grep(pattern: "TODO", path: "~/Docs")         // Find TODOs across them
3. file_read(file_path: "~/Docs/readme.md")      // Read the relevant file

Create a New File

file_write(file_path: "src/new_module.swift", content: "// Module start\n")
file_write(file_path: "src/new_module.swift", content: "// More code\n", append: true)