> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/yocxy2/claurst/llms.txt > Use this file to discover all available pages before exploring further. # File tools > Read, write, edit, and search files in your project. These are the most frequently used tools in Claurst. Claurst provides six built-in file tools. All file-path parameters must be **absolute paths**. Tools that write files require a permission prompt unless the session is in `AcceptEdits` or `BypassPermissions` mode. Before Claude can edit or overwrite a file, it must have read that file in the same session. This **read-before-write** enforcement prevents clobbering concurrent changes. *** ## Read Read file contents. Returns text lines prefixed with line numbers, or a typed result for images, PDFs, and notebooks. **Tool name:** `Read` ### Parameters Absolute path to the file to read. 1-based line number to start reading from. Omit to start at line 1. Maximum number of lines to return. The Rust implementation defaults to 2 000 lines. PDF page range to extract (e.g. `"1-5"`, `"3"`, `"10-20"`). PDF files only. Maximum 20 pages per call. ### Return value The return type varies by file format: Discriminant: `"text"`, `"image"`, `"notebook"`, `"pdf"`, `"parts"`, or `"file_unchanged"`. Line-numbered file content. Present when `type` is `"text"`. Lines returned in this slice. Present when `type` is `"text"`. First line number returned (1-based). Present when `type` is `"text"`. Total lines in the file. Present when `type` is `"text"`. Base64-encoded binary data. Present when `type` is `"image"` or `"pdf"`. ### Notes * Blocked device paths (`/dev/zero`, `/dev/random`, `/dev/urandom`, etc.) are rejected to prevent infinite reads. * Binary files that are not images or PDFs return an error. * Reading a file registers it in the session's read-state cache, which enables `Edit` and `Write` to operate on it. ### Example ```json theme={null} { "file_path": "/home/user/project/src/main.rs", "offset": 1, "limit": 50 } ``` ``` 1 fn main() { 2 println!("Hello, world!"); 3 } ``` *** ## Write Create a new file or completely overwrite an existing one. **Tool name:** `Write`\ **Permission:** `Write` (prompts unless `AcceptEdits` or `BypassPermissions` mode) ### Parameters Absolute path to the file to create or overwrite. Full content to write. The file is replaced atomically. ### Return value `"create"` for new files, `"update"` for overwrites. Absolute path that was written. Diff of changes applied, useful for display. Previous file content. `null` for new files. ### Notes * Parent directories are created automatically. * For existing files, the file must have been read in this session first (read-before-write). * If the file has been modified on disk since the last read, the write is rejected to avoid clobbering concurrent changes. * `.ipynb` files are automatically redirected to `NotebookEdit`. * Maximum file size: 1 GiB. ### Example ```json theme={null} { "file_path": "/home/user/project/src/config.toml", "content": "[server]\nport = 8080\n" } ``` *** ## Edit Make an exact string replacement inside an existing file. Prefer `Edit` over `Write` when you only need to change part of a file — it is faster and produces a cleaner diff. **Tool name:** `Edit`\ **Permission:** `Write` (prompts unless `AcceptEdits` or `BypassPermissions` mode) ### Parameters Absolute path to the file to edit. The file must already exist. The exact text to find and replace. Must be present in the file. Unless `replace_all` is `true`, this string must appear **exactly once** — if it appears multiple times the call fails. The replacement text. Must differ from `old_string`. When `true`, replace every occurrence of `old_string`. When `false` (default), the call fails if `old_string` appears more than once. ### Return value Path of the edited file. Diff of the applied change. Whether `replace_all` was used. Whether you modified the proposed diff before it was applied. ### Notes * Read-before-write and mtime staleness checks apply (same as `Write`). * The tool normalizes straight/curly quotes when matching `old_string`, and preserves the original quote style in the output. * `.ipynb` files are redirected to `NotebookEdit`. * A set of protected files (`.gitconfig`, `.bashrc`, `.zshrc`, `.mcp.json`, `.claude.json`) resist automatic editing. ### Example ```json theme={null} { "file_path": "/home/user/project/src/lib.rs", "old_string": "fn hello() {\n println!(\"hello\");\n}", "new_string": "fn hello() {\n println!(\"Hello, Claurst!\");\n}" } ``` *** ## Glob Find files by name pattern. Results are sorted by modification time (most recent first). **Tool name:** `Glob` ### Parameters Glob pattern to match against file paths (e.g. `"**/*.rs"`, `"src/**/*.ts"`, `"*.toml"`). Directory to search in. Defaults to the current working directory. ### Return value Matching file paths, relative to the working directory. Number of files returned. `true` if results were capped (the TypeScript implementation caps at 100; the Rust implementation at 250). Time taken to complete the search. ### Example ```json theme={null} { "pattern": "**/*.rs", "path": "/home/user/project/src" } ``` ``` src/main.rs src/lib.rs src/tools/bash.rs ``` *** ## Grep Search file contents using a regular expression. Backed by `ripgrep` in the TypeScript implementation and a Rust `walkdir`+`regex` traversal in the Claurst Rust codebase. **Tool name:** `Grep` ### Parameters Regular expression to search for (e.g. `"fn\\s+\\w+"`, `"TODO|FIXME"`). File or directory to search. Defaults to the current working directory. Restrict search to files matching this glob (e.g. `"*.rs"`, `"**/*.tsx"`). Controls output format: * `"files_with_matches"` — list of matching file paths (default) * `"content"` — matching lines with optional context * `"count"` — match count per file Case-insensitive matching. Show line numbers in `content` mode. Lines of context after each match (`output_mode: "content"` only). Lines of context before each match (`output_mode: "content"` only). Lines of context before and after each match. Equivalent to setting both `-A` and `-B`. Alias for `-C`. File type shortcut (e.g. `"rs"`, `"ts"`, `"py"`, `"js"`, `"go"`). Expands to the relevant file extensions. Limit output to the first N lines or entries. Skip the first N entries (for pagination). Enable multiline matching (`.` matches newlines). ### Return value The `output_mode` that was used. Number of files that matched. Matching file paths. Matching lines. Present when `mode` is `"content"`. Total match count. Present when `mode` is `"count"`. ### Notes * VCS directories (`.git`, `.svn`, `.hg`, `.jj`) and build directories (`node_modules/`, `target/`, `__pycache__/`) are excluded automatically. * The TypeScript implementation caps individual lines at 500 characters. ### Example ```json theme={null} { "pattern": "async fn", "path": "/home/user/project/src", "glob": "*.rs", "output_mode": "content", "-n": true, "-C": 2 } ``` *** ## NotebookEdit Edit a cell in a Jupyter `.ipynb` notebook. Supports inserting, replacing, and deleting cells. **Tool name:** `NotebookEdit`\ **Permission:** `Write` ### Parameters Absolute path to the `.ipynb` file. New source content for the cell (for `replace` and `insert` modes). Operation to perform: `"replace"`, `"insert"`, or `"delete"`. Target cell ID. Required for `replace` and `delete`. Omit when inserting a new cell. Cell type for new cells: `"code"` or `"markdown"`. Used with `insert` mode. ### Return value Path of the modified notebook. Cell ID that was affected. The operation that was applied. Full notebook JSON before the edit. Full notebook JSON after the edit. ### Notes * Read-before-write and mtime staleness checks apply. * On `replace`, `execution_count` and `outputs` are cleared to avoid stale output display. * In the Rust implementation, cells can also be targeted by a `cell-N` index pattern (e.g. `"cell-0"` for the first cell). ### Example ```json theme={null} { "notebook_path": "/home/user/project/analysis.ipynb", "cell_id": "abc123", "new_source": "import pandas as pd\ndf = pd.read_csv('data.csv')\ndf.head()", "edit_mode": "replace" } ```