Skip to content

Commit fd92189

Browse files
hannesrudolphhannesrudolph
committed
docs: Add v3.25.0 release documentation
- Add release notes for v3.25.0 - Add documentation for new features: - Slash commands with examples and screenshots - Message queueing functionality - Background editing (experimental feature) - Update experimental features index to include background editing - Update read-file tool documentation - Update custom modes documentation - Update Gemini provider documentation - Update sidebars to include new documentation pages - Add supporting images for all new features
1 parent bfd8596 commit fd92189

File tree

21 files changed

+1602
-60
lines changed

21 files changed

+1602
-60
lines changed

‎docs/advanced-usage/available-tools/read-file.md‎

Lines changed: 166 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11

22
---
3-
description: Explore the read_file tool's capabilities for examining file contents, supporting line ranges, PDF/DOCX extraction, and experimental multi-file concurrent reading.
3+
description: Explore the read_file tool's capabilities for examining file contents, supporting line ranges, PDF/DOCX extraction, image reading, and experimental multi-file concurrent reading.
44
keywords:
55
- read_file
66
- Roo Code tools
@@ -9,17 +9,21 @@ keywords:
99
- line numbers
1010
- PDF extraction
1111
- DOCX support
12+
- image support
13+
- OCR workflows
1214
- code analysis
1315
- VS Code AI
1416
image: /img/social-share.jpg
1517
---
1618

1719
# read_file
1820

19-
The `read_file` tool examines the contents of files in a project. It allows Roo to understand code, configuration files, and documentation to provide better assistance.
21+
The `read_file` tool examines the contents of files in a project. It allows Roo to understand code, configuration files, documentation, and now images to provide better assistance.
2022

2123
:::info Multi-File Support
22-
When the [Concurrent File Reads](/features/concurrent-file-reads) experimental feature is enabled, this tool can read multiple files simultaneously using an enhanced XML parameter format. This significantly improves efficiency for tasks requiring analysis of multiple related files.
24+
The `read_file` tool can read multiple files simultaneously when the `maxConcurrentFileReads` setting is greater than 1. This significantly improves efficiency for tasks requiring analysis of multiple related files.
25+
26+
**Note:** When reading files (even single files), the LLM will see a message encouraging multi-file reads: "Reading multiple files at once is more efficient for the LLM. If other files are relevant to your current task, please read them simultaneously."
2327
:::
2428

2529
---
@@ -38,20 +42,20 @@ The tool accepts parameters in two formats depending on your configuration:
3842
While the single-file parameters (`path`, `start_line`, `end_line`) are still supported for backward compatibility, we recommend using the newer `args` format for consistency and future compatibility.
3943
:::
4044

41-
### Enhanced Format (Multi-File - Experimental)
45+
### Enhanced Format (Multi-File)
4246

43-
When [Concurrent File Reads](/features/concurrent-file-reads) is enabled, the tool accepts an `args` parameter containing multiple file entries:
47+
When `maxConcurrentFileReads` is set to a value greater than 1 (found in Settings > Context > "Concurrent file reads limit"), the tool accepts an `args` parameter containing multiple file entries:
4448

4549
- `args` (required): Container for multiple file specifications
4650
- `file` (required): Individual file specification
4751
- `path` (required): The path of the file to read
48-
- `line_range` (optional): Line range specification (e.g., "1-50" or "100-150")
52+
- `line_range` (optional): Line range specification (e.g., "1-50" or "100-150"). Multiple `line_range` elements can be specified per file.
4953

5054
---
5155

5256
## What It Does
5357

54-
This tool reads the content of a specified file and returns it with line numbers for easy reference. It can read entire files or specific sections, and even extract text from PDFs and Word documents.
58+
This tool reads the content of a specified file and returns it with line numbers for easy reference. It can read entire files or specific sections, extract text from PDFs and Word documents, and display images in various formats.
5559

5660
---
5761

@@ -70,20 +74,27 @@ This tool reads the content of a specified file and returns it with line numbers
7074
- Displays file content with line numbers for easy reference
7175
- Can read specific portions of files by specifying line ranges
7276
- Extracts readable text from PDF and DOCX files
77+
- **Image support**: Displays images in multiple formats (PNG, JPG, JPEG, GIF, WebP, SVG, BMP, ICO, TIFF)
7378
- Automatically truncates large text files when no line range is specified, showing the beginning of the file
7479
- Provides method summaries with line ranges for truncated large code files
7580
- Efficiently streams only requested line ranges for better performance
7681
- Makes it easy to discuss specific parts of code with line numbering
77-
- **Multi-file support** (experimental): Read multiple files simultaneously with batch approval
82+
- **Multi-file support**: Read multiple files simultaneously with batch approval (when `maxConcurrentFileReads` > 1)
7883

7984
---
8085

81-
## Multi-File Capabilities (Experimental)
86+
## Multi-File Capabilities
87+
88+
When the `maxConcurrentFileReads` setting is greater than 1, the `read_file` tool gains enhanced capabilities:
8289

83-
When the [Concurrent File Reads](/features/concurrent-file-reads) experimental feature is enabled, the `read_file` tool gains enhanced capabilities:
90+
### Configuration
91+
- **Location**: Settings > Context > "Concurrent file reads limit"
92+
- **Description**: "Maximum number of files the 'read_file' tool can process concurrently. Higher values may speed up reading multiple small files but increase memory usage."
93+
- **Range**: 1-100 (slider control)
94+
- **Default**: 5
8495

8596
### Batch Processing
86-
- Read up to 100 files in a single request (configurable, default 15)
97+
- Read up to 100 files in a single request (configurable, default 5)
8798
- Parallel processing for improved performance
8899
- Batch approval interface for user consent
89100

@@ -104,8 +115,11 @@ When the [Concurrent File Reads](/features/concurrent-file-reads) experimental f
104115
## Limitations
105116

106117
- May not handle extremely large files efficiently without using line range parameters
107-
- For binary files (except PDF and DOCX), may return content that isn't human-readable
108-
- **Multi-file mode**: Requires experimental feature to be enabled and may have stability issues
118+
- For binary files (except PDF, DOCX, and supported image formats), may return content that isn't human-readable
119+
- **Multi-file mode**: Requires `maxConcurrentFileReads` > 1 in settings
120+
- **Image files**: Returns base64-encoded data URLs which may be large for high-resolution images
121+
- Default max single image size: 20MB
122+
- Default max total image size: 20MB
109123

110124
---
111125

@@ -122,6 +136,7 @@ When the `read_file` tool is invoked, it follows this process:
122136
- Adds line numbers to the content (e.g., "1 | const x = 13") where `1 |` is the line number.
123137
- For truncated files, adds truncation notice and method definitions
124138
- For special formats (PDF, DOCX), extracts readable text
139+
- For image formats, returns base64-encoded data URLs with MIME type
125140

126141
---
127142

@@ -146,8 +161,9 @@ The tool uses a clear decision hierarchy to determine how to read a file:
146161
- **Special Case - Definitions Only Mode**: When `maxReadFileLine` is set to `0`, the tool returns only source code definitions without any file content.
147162

148163
3. **Default Behavior: Read Entire File**
149-
- If neither an explicit range is given nor automatic truncation applies (e.g., the file is within the line limit, or it's a supported binary type), the tool reads the entire content.
150-
- For supported formats like PDF and DOCX, it attempts to extract the full text content.
164+
- If neither an explicit range is given nor automatic truncation applies (e.g., the file is within the line limit, or it's a supported binary type), the tool reads the entire content.
165+
- For supported formats like PDF and DOCX, it attempts to extract the full text content.
166+
- For image formats, it returns a base64-encoded data URL that can be displayed in the chat interface.
151167

152168
---
153169

@@ -246,7 +262,7 @@ When `maxReadFileLine` is set to `0` in user settings, the tool returns only sou
246262
method validateUser
247263
method generateToken
248264
</list_code_definition_names>
249-
<notice>Showing only 0 of 150 total lines. Use start_line and end_line to read specific ranges.</notice>
265+
<notice>Showing only 0 of 150 total lines. Use line_range if you need to read more lines</notice>
250266
</file>
251267
```
252268
*(This mode provides a quick overview of file structure without reading content.)*
@@ -279,15 +295,122 @@ If the file is excluded by rules in a `.rooignore` file:
279295
```
280296

281297
**Simulated Output (Error):**
298+
```xml
299+
<file>
300+
<path>.env</path>
301+
<error>Access denied by .rooignore rules</error>
302+
</file>
303+
```
304+
305+
---
306+
307+
## Image Reading Examples
308+
309+
The `read_file` tool now supports reading and displaying images directly in the chat interface. This enables powerful visual analysis workflows.
310+
311+
### Reading a Single Image
312+
313+
**Input:**
314+
```xml
315+
<read_file>
316+
<path>assets/logo.png</path>
317+
</read_file>
318+
```
319+
320+
**Output:**
321+
```xml
322+
<image_content>
323+
<path>assets/logo.png</path>
324+
<mime_type>image/png</mime_type>
325+
<dimensions>width: 512, height: 512</dimensions>
326+
<data_url>data:image/png;base64,iVBORw0KGgoAAAANS...</data_url>
327+
</image_content>
328+
```
329+
330+
The image will be displayed directly in the chat interface, allowing Roo to analyze visual content.
331+
332+
### OCR Workflow Example
333+
334+
Reading multiple images from a folder for text extraction:
335+
336+
**Input:**
337+
```xml
338+
<read_file>
339+
<args>
340+
<file>
341+
<path>screenshots/page1.png</path>
342+
</file>
343+
<file>
344+
<path>screenshots/page2.png</path>
345+
</file>
346+
<file>
347+
<path>screenshots/page3.png</path>
348+
</file>
349+
</args>
350+
</read_file>
351+
```
352+
353+
**Usage:**
282354
```
283-
Error: Access denied by .rooignore rules
355+
Please extract all text from these screenshot images and compile them into a single markdown document.
284356
```
285357

358+
### Design Review Workflow
359+
360+
Analyzing multiple design mockups:
361+
362+
**Input:**
363+
```xml
364+
<read_file>
365+
<args>
366+
<file>
367+
<path>designs/homepage-v1.jpg</path>
368+
</file>
369+
<file>
370+
<path>designs/homepage-v2.jpg</path>
371+
</file>
372+
<file>
373+
<path>designs/mobile-view.png</path>
374+
</file>
375+
</args>
376+
</read_file>
377+
```
378+
379+
**Usage:**
380+
```
381+
Compare these design mockups and provide feedback on:
382+
1. Visual consistency
383+
2. Mobile responsiveness
384+
3. Accessibility concerns
385+
4. UI/UX improvements
386+
```
387+
388+
### Supported Image Formats
389+
390+
The tool supports the following image formats:
391+
- **PNG** - With dimension extraction
392+
- **JPG/JPEG** - Standard and progressive
393+
- **GIF** - Static and animated
394+
- **WebP** - Modern web format
395+
- **SVG** - Scalable vector graphics
396+
- **BMP** - Bitmap images
397+
- **ICO** - Icon files
398+
- **TIFF** - Tagged image format
399+
400+
### Image Analysis Use Cases
401+
402+
1. **Documentation Screenshots**: Extract text and create documentation from UI screenshots
403+
2. **Error Debugging**: Analyze error screenshots to understand issues
404+
3. **Design Reviews**: Compare mockups and provide visual feedback
405+
4. **Diagram Analysis**: Understand architecture diagrams and flowcharts
406+
5. **Code Screenshots**: Extract code from images when text isn't available
407+
6. **UI Testing**: Verify visual elements and layouts
408+
286409
---
287410

288-
## Multi-File Examples (Experimental)
411+
## Multi-File Examples
289412

290-
When the [Concurrent File Reads](/features/concurrent-file-reads) experimental feature is enabled, you can read multiple files simultaneously using the enhanced XML format.
413+
When `maxConcurrentFileReads` is set to a value greater than 1, you can read multiple files simultaneously using the enhanced XML format.
291414

292415
### Reading Multiple Complete Files
293416

@@ -444,8 +567,29 @@ When requesting multiple files, you'll see a batch approval interface that allow
444567

445568
The interface displays each file path clearly, making it easy to understand what Roo wants to access before granting permission.
446569

447-
---
570+
### Mixed Content Types
571+
572+
You can read different types of files in a single request:
573+
574+
**Input:**
575+
```xml
576+
<read_file>
577+
<args>
578+
<file>
579+
<path>README.md</path>
580+
</file>
581+
<file>
582+
<path>architecture-diagram.png</path>
583+
</file>
584+
<file>
585+
<path>config.json</path>
586+
</file>
587+
<file>
588+
<path>requirements.pdf</path>
589+
</file>
590+
</args>
591+
</read_file>
592+
```
448593

449-
## Backward Compatibility
594+
This allows Roo to analyze documentation, visual diagrams, configuration, and specifications all in one context.
450595

451-
The enhanced multi-file format is fully backward compatible. Existing single-file requests using the `path` parameter continue to work exactly as before, regardless of whether the experimental feature is enabled or disabled.

0 commit comments

Comments
 (0)