File tools

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

file_path

string

required

Absolute path to the file to read.

offset

integer

1-based line number to start reading from. Omit to start at line 1.

limit

integer

Maximum number of lines to return. The Rust implementation defaults to 2 000 lines.

pages

string

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:

type

string

required

Discriminant: "text", "image", "notebook", "pdf", "parts", or "file_unchanged".

content

string

Line-numbered file content. Present when type is "text".

numLines

integer

Lines returned in this slice. Present when type is "text".

startLine

integer

First line number returned (1-based). Present when type is "text".

totalLines

integer

Total lines in the file. Present when type is "text".

base64

string

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

{
  "file_path": "/home/user/project/src/main.rs",
  "offset": 1,
  "limit": 50
}

fn main() {
   println!("Hello, world!");
}

Write

Create a new file or completely overwrite an existing one. Tool name: Write
Permission: Write (prompts unless AcceptEdits or BypassPermissions mode)

Parameters

file_path

string

required

Absolute path to the file to create or overwrite.

content

string

required

Full content to write. The file is replaced atomically.

Return value

type

string

required

"create" for new files, "update" for overwrites.

filePath

string

required

Absolute path that was written.

structuredPatch

object

Diff of changes applied, useful for display.

originalFile

string

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

{
  "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

file_path

string

required

Absolute path to the file to edit. The file must already exist.

old_string

string

required

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.

new_string

string

required

The replacement text. Must differ from old_string.

replace_all

boolean

default:"false"

When true, replace every occurrence of old_string. When false (default), the call fails if old_string appears more than once.

Return value

filePath

string

required

Path of the edited file.

structuredPatch

object

required

Diff of the applied change.

replaceAll

boolean

required

Whether replace_all was used.

userModified

boolean

required

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

{
  "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

pattern

string

required

Glob pattern to match against file paths (e.g. "**/*.rs", "src/**/*.ts", "*.toml").

path

string

Directory to search in. Defaults to the current working directory.

Return value

filenames

string[]

required

Matching file paths, relative to the working directory.

numFiles

integer

required

Number of files returned.

truncated

boolean

required

true if results were capped (the TypeScript implementation caps at 100; the Rust implementation at 250).

durationMs

number

required

Time taken to complete the search.

Example

{
  "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

pattern

string

required

Regular expression to search for (e.g. "fn\\s+\\w+", "TODO|FIXME").

path

string

File or directory to search. Defaults to the current working directory.

glob

string

Restrict search to files matching this glob (e.g. "*.rs", "**/*.tsx").

output_mode

string

default:"files_with_matches"

Controls output format:

"files_with_matches" — list of matching file paths (default)
"content" — matching lines with optional context
"count" — match count per file

-i

boolean

Case-insensitive matching.

-n

boolean

Show line numbers in content mode.

-A

integer

Lines of context after each match (output_mode: "content" only).

-B

integer

Lines of context before each match (output_mode: "content" only).

-C

integer

Lines of context before and after each match. Equivalent to setting both -A and -B.

context

integer

Alias for -C.

type

string

File type shortcut (e.g. "rs", "ts", "py", "js", "go"). Expands to the relevant file extensions.

head_limit

integer

default:"250"

Limit output to the first N lines or entries.

offset

integer

default:"0"

Skip the first N entries (for pagination).

multiline

boolean

default:"false"

Enable multiline matching (. matches newlines).

Return value

mode

string

required

The output_mode that was used.

numFiles

integer

required

Number of files that matched.

filenames

string[]

required

Matching file paths.

content

string

Matching lines. Present when mode is "content".

numMatches

integer

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

{
  "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

notebook_path

string

required

Absolute path to the .ipynb file.

new_source

string

required

New source content for the cell (for replace and insert modes).

edit_mode

string

default:"replace"

Operation to perform: "replace", "insert", or "delete".

cell_id

string

Target cell ID. Required for replace and delete. Omit when inserting a new cell.

cell_type

string

Cell type for new cells: "code" or "markdown". Used with insert mode.

Return value

notebook_path

string

required

Path of the modified notebook.

cell_id

string

Cell ID that was affected.

edit_mode

string

required

The operation that was applied.

original_file

string

required

Full notebook JSON before the edit.

updated_file

string

required

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

{
  "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"
}

Commands

Tools

Architecture

Read

Parameters

Return value

Notes

Example

Write

Parameters

Return value

Notes

Example

Edit

Parameters

Return value

Notes

Example

Glob

Parameters

Return value

Example

Grep

Parameters

Return value

Notes

Example

NotebookEdit

Parameters

Return value

Notes

Example

Build docs developers (and LLMs) love

Commands

Tools

Architecture

​Read

​Parameters

​Return value

​Notes

​Example

​Write

​Parameters

​Return value

​Notes

​Example

​Edit

​Parameters

​Return value

​Notes

​Example

​Glob

​Parameters

​Return value

​Example

​Grep

​Parameters

​Return value

​Notes

​Example

​NotebookEdit

​Parameters

​Return value

​Notes

​Example

Build docs developers (and LLMs) love

Read

Parameters

Return value

Notes

Example

Write

Parameters

Return value

Notes

Example

Edit

Parameters

Return value

Notes

Example

Glob

Parameters

Return value

Example

Grep

Parameters

Return value

Notes

Example

NotebookEdit

Parameters

Return value

Notes

Example