Skip to content

Commit afd7a65

Browse files
hannesrudolphhannesrudolph
committed
feat: Add comprehensive documentation for concurrent file reads experimental feature
- Add new experimental feature documentation for concurrent file reads - Update read_file tool documentation with multi-file capabilities - Add concurrent file reads to experimental features overview - Update sidebar navigation to include new documentation Key changes: - Created docs/features/experimental/concurrent-file-reads.md with user-focused documentation - Enhanced docs/advanced-usage/available-tools/read-file.md with multi-file examples and technical details - Updated docs/features/experimental/experimental-features.md to list new feature - Modified sidebars.ts to include new page in navigation The documentation emphasizes the key benefit of reducing LLM conversation turns by allowing Roo to read multiple files simultaneously instead of requesting them one by one, significantly improving workflow efficiency and reducing user interruptions. Based on PR #2886 implementation details.
1 parent 2ec362a commit afd7a65

File tree

4 files changed

+349
-1
lines changed

4 files changed

+349
-1
lines changed

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

Lines changed: 202 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,29 @@
33

44
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.
55

6+
:::info Multi-File Support
7+
When the [Concurrent File Reads](/features/experimental/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.
8+
:::
9+
610
## Parameters
711

8-
The tool accepts these parameters:
12+
The tool accepts parameters in two formats depending on your configuration:
13+
14+
### Standard Format (Single File)
915

1016
- `path` (required): The path of the file to read relative to the current working directory
1117
- `start_line` (optional): The starting line number to read from (1-based indexing)
1218
- `end_line` (optional): The ending line number to read to (1-based, inclusive)
1319

20+
### Enhanced Format (Multi-File - Experimental)
21+
22+
When [Concurrent File Reads](/features/experimental/concurrent-file-reads) is enabled, the tool accepts an `args` parameter containing multiple file entries:
23+
24+
- `args` (required): Container for multiple file specifications
25+
- `file` (required): Individual file specification
26+
- `path` (required): The path of the file to read
27+
- `lines` (optional): Line range specification (e.g., "1-50" or "100-150")
28+
1429
## What It Does
1530

1631
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.
@@ -32,11 +47,34 @@ This tool reads the content of a specified file and returns it with line numbers
3247
- Provides method summaries with line ranges for truncated large code files
3348
- Efficiently streams only requested line ranges for better performance
3449
- Makes it easy to discuss specific parts of code with line numbering
50+
- **Multi-file support** (experimental): Read multiple files simultaneously with batch approval
51+
52+
## Multi-File Capabilities (Experimental)
53+
54+
When the [Concurrent File Reads](/features/experimental/concurrent-file-reads) experimental feature is enabled, the `read_file` tool gains enhanced capabilities:
55+
56+
### Batch Processing
57+
- Read up to 100 files in a single request (configurable, default 15)
58+
- Parallel processing for improved performance
59+
- Batch approval interface for user consent
60+
61+
### Enhanced User Experience
62+
- Single approval dialog for multiple files
63+
- Individual file override options
64+
- Clear visibility into which files will be accessed
65+
- Graceful handling of mixed success/failure scenarios
66+
67+
### Improved Efficiency
68+
- Reduces interruptions from multiple approval dialogs
69+
- Faster processing through parallel file reading
70+
- Smart batching of related files
71+
- Configurable concurrency limits to match system capabilities
3572

3673
## Limitations
3774

3875
- May not handle extremely large files efficiently without using line range parameters
3976
- For binary files (except PDF and DOCX), may return content that isn't human-readable
77+
- **Multi-file mode**: Requires experimental feature to be enabled and may have stability issues
4078

4179
## How It Works
4280

@@ -178,3 +216,166 @@ If the file is excluded by rules in a `.rooignore` file:
178216
```
179217
Error: Access denied to file '.env' due to .rooignore rules.
180218
```
219+
220+
## Multi-File Examples (Experimental)
221+
222+
When the [Concurrent File Reads](/features/experimental/concurrent-file-reads) experimental feature is enabled, you can read multiple files simultaneously using the enhanced XML format.
223+
224+
### Reading Multiple Complete Files
225+
226+
To read several complete files at once:
227+
228+
**Input:**
229+
```xml
230+
<read_file>
231+
<args>
232+
<file>
233+
<path>src/app.ts</path>
234+
</file>
235+
<file>
236+
<path>src/utils.ts</path>
237+
</file>
238+
<file>
239+
<path>src/config.json</path>
240+
</file>
241+
</args>
242+
</read_file>
243+
```
244+
245+
**Simulated Output:**
246+
```xml
247+
<files>
248+
<file>
249+
<path>src/app.ts</path>
250+
<content>
251+
1 | import React from 'react'
252+
2 | import { Utils } from './utils'
253+
3 | // ... rest of file content
254+
</content>
255+
</file>
256+
<file>
257+
<path>src/utils.ts</path>
258+
<content>
259+
1 | export class Utils {
260+
2 | static formatDate(date: Date): string {
261+
3 | // ... utility functions
262+
</content>
263+
</file>
264+
<file>
265+
<path>src/config.json</path>
266+
<content>
267+
1 | {
268+
2 | "apiUrl": "https://api.example.com",
269+
3 | "timeout": 5000
270+
4 | }
271+
</content>
272+
</file>
273+
</files>
274+
```
275+
276+
### Reading Specific Line Ranges from Multiple Files
277+
278+
To read specific sections from multiple files:
279+
280+
**Input:**
281+
```xml
282+
<read_file>
283+
<args>
284+
<file>
285+
<path>src/app.ts</path>
286+
<lines>1-20</lines>
287+
<lines>45-60</lines>
288+
</file>
289+
<file>
290+
<path>src/utils.ts</path>
291+
<lines>10-25</lines>
292+
</file>
293+
</args>
294+
</read_file>
295+
```
296+
297+
**Simulated Output:**
298+
```xml
299+
<files>
300+
<file>
301+
<path>src/app.ts</path>
302+
<content>
303+
1 | import React from 'react'
304+
2 | import { Utils } from './utils'
305+
...
306+
20 | const App = () => {
307+
308+
45 | const handleSubmit = () => {
309+
46 | // Handle form submission
310+
...
311+
60 | }
312+
</content>
313+
</file>
314+
<file>
315+
<path>src/utils.ts</path>
316+
<content>
317+
10 | static formatDate(date: Date): string {
318+
11 | return date.toISOString().split('T')[0]
319+
...
320+
25 | }
321+
</content>
322+
</file>
323+
</files>
324+
```
325+
326+
### Handling Mixed Results (Some Files Denied/Blocked)
327+
328+
When some files are approved and others are denied or blocked:
329+
330+
**Input:**
331+
```xml
332+
<read_file>
333+
<args>
334+
<file>
335+
<path>src/app.ts</path>
336+
</file>
337+
<file>
338+
<path>.env</path>
339+
</file>
340+
<file>
341+
<path>src/secret-config.ts</path>
342+
</file>
343+
</args>
344+
</read_file>
345+
```
346+
347+
**Simulated Output:**
348+
```xml
349+
<files>
350+
<file>
351+
<path>src/app.ts</path>
352+
<content>
353+
1 | import React from 'react'
354+
2 | // ... file content successfully read
355+
</content>
356+
</file>
357+
<file>
358+
<path>.env</path>
359+
<error>Access denied by .rooignore rules</error>
360+
</file>
361+
<file>
362+
<path>src/secret-config.ts</path>
363+
<error>User denied access</error>
364+
</file>
365+
</files>
366+
```
367+
368+
### Batch Approval Interface
369+
370+
When requesting multiple files, you'll see a batch approval interface that allows you to:
371+
372+
- **Approve All**: Grant access to all requested files
373+
- **Deny All**: Deny access to all requested files
374+
- **Individual Control**: Override decisions for specific files
375+
- **File Preview**: Click file headers to open them in your editor
376+
377+
The interface displays each file path clearly, making it easy to understand what Roo wants to access before granting permission.
378+
379+
## Backward Compatibility
380+
381+
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.

‎docs/features/experimental/concurrent-file-reads.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Concurrent File Reads
2+
3+
:::warning Experimental Feature
4+
Concurrent file reads is an experimental feature that allows Roo to read multiple files simultaneously in a single request. This feature is under active development and may change significantly in future releases.
5+
:::
6+
7+
This feature dramatically improves your workflow by allowing Roo to gather context from multiple files in a single conversation turn, rather than asking to read files one by one. Instead of waiting through multiple back-and-forth exchanges, Roo can understand your entire project structure much faster.
8+
9+
## Why This Matters
10+
11+
**Faster Context Building**: Previously, when Roo needed to understand your project, you'd see multiple requests like:
12+
- "Can I read `src/app.js`?" → You approve
13+
- "Now can I read `src/utils.js`?" → You approve
14+
- "And can I read `src/config.json`?" → You approve
15+
16+
**With concurrent file reads**: Roo asks once to read all related files together, getting the full picture immediately and providing better assistance faster.
17+
18+
## Key Benefits
19+
20+
- **Fewer interruptions** - One approval dialog instead of many
21+
- **Faster assistance** - Roo understands your project context immediately
22+
- **Better analysis** - Roo can see relationships between files from the start
23+
- **Smoother workflow** - Less waiting, more productive conversations
24+
25+
## Enabling Concurrent File Reads
26+
27+
To enable this experimental feature:
28+
29+
1. Open Roo Code settings (<Codicon name="gear" /> icon in the top right corner)
30+
2. Navigate to **Advanced Settings** → **Experimental Features**
31+
3. Check **"Enable concurrent file reads"**
32+
33+
<img src="/img/experimental/concurrent-file-reads-setting.png" alt="Concurrent file reads setting toggle" width="600" />
34+
35+
Once enabled, you can configure the maximum number of concurrent files (2-100) using the slider that appears below the toggle.
36+
37+
## Configuration Options
38+
39+
### Maximum Concurrent Files
40+
41+
- **Default**: 15 files when enabled, 1 file when disabled
42+
- **Range**: 2-100 files (when experimental feature is enabled)
43+
- **Location**: Settings → Advanced Settings → Context Management → "Concurrent file reads limit"
44+
45+
The setting automatically adjusts when you toggle the experimental feature:
46+
- Enabling sets the limit to 15 files
47+
- Disabling resets the limit to 1 file (standard behavior)
48+
49+
## User Experience
50+
51+
### Batch Approval Interface
52+
53+
When Roo requests to read multiple files, you'll see a new batch approval interface that displays:
54+
55+
- List of all files to be read
56+
- File paths with line range indicators (if specified)
57+
- Clickable file headers to open files in your editor
58+
- **Approve All** and **Deny All** buttons for quick decisions
59+
- Individual file permission controls
60+
61+
### Enhanced Tool Behavior
62+
63+
The [`read_file`](/advanced-usage/available-tools/read-file) tool automatically adapts based on your settings:
64+
65+
- **Single-file mode** (disabled): Uses traditional one-file-at-a-time approach
66+
- **Multi-file mode** (enabled): Accepts multiple files in a single request using XML format
67+
68+
## How It Works Behind the Scenes
69+
70+
When you enable concurrent file reads, Roo can request multiple files at once instead of one at a time. You don't need to understand the technical details - it just works more efficiently.
71+
72+
### What You Control
73+
74+
- **Enable/disable the feature** - Simple checkbox in settings
75+
- **Set file limits** - Choose how many files Roo can request at once (2-100, default 15)
76+
- **Individual file approval** - Still approve or deny specific files if needed
77+
78+
### What Happens Automatically
79+
80+
- Roo groups related files together in single requests
81+
- Files are processed in parallel for faster results
82+
- If some files are blocked or denied, Roo still gets the approved ones
83+
- Everything falls back gracefully if there are any issues
84+
85+
## What You'll Experience
86+
87+
### Before Concurrent File Reads
88+
When working on a feature that spans multiple files, you might see:
89+
1. Roo: "I need to understand your authentication system. Can I read `auth.js`?"
90+
2. You: *Approve*
91+
3. Roo: "Now I need to see the user model. Can I read `user.js`?"
92+
4. You: *Approve*
93+
5. Roo: "And the database config. Can I read `database.js`?"
94+
6. You: *Approve*
95+
7. Finally, Roo can help with your request
96+
97+
### With Concurrent File Reads
98+
1. Roo: "I need to understand your authentication system. Can I read these files: `auth.js`, `user.js`, `database.js`?"
99+
2. You: *Approve all at once*
100+
3. Roo immediately provides comprehensive help
101+
102+
### Real-World Impact
103+
104+
- **Faster debugging** - Roo can see the full picture of related files instantly
105+
- **Better code reviews** - Understanding entire features at once, not piece by piece
106+
- **Smoother refactoring** - Analyzing dependencies across multiple files simultaneously
107+
- **Less clicking** - One approval instead of many interruptions
108+
109+
## Backward Compatibility
110+
111+
The feature maintains full backward compatibility:
112+
113+
- Existing single-file requests continue to work unchanged
114+
- Legacy `path` parameter format is still supported
115+
- No breaking changes for current workflows
116+
- Smooth transition between single and multi-file modes
117+
118+
## Common Questions
119+
120+
**"I enabled the feature but don't see any difference"**
121+
- Restart VS Code after enabling the experimental feature
122+
- The feature only activates when Roo needs to read multiple files
123+
124+
**"Roo is asking for too many files at once"**
125+
- Lower the concurrent file limit in settings (try 5-10 instead of 15)
126+
- You can still approve or deny individual files in the batch dialog
127+
128+
**"Some files were denied but others approved"**
129+
- This is normal - Roo gets the files you approve and works with those
130+
- Files might be blocked by your `.rooignore` settings
131+
132+
## Need Help?
133+
134+
If you run into issues:
135+
1. Check the [FAQ section](/faq) for common solutions
136+
2. Report problems on [GitHub Issues](https://github.com/RooCodeInc/Roo-Code/issues)
137+
3. Include what you were trying to do and any error messages
138+
139+
## What's Next
140+
141+
This experimental feature is actively being improved based on user feedback. We're working on making the approval interface even smoother and helping Roo make smarter decisions about which files to request together.
142+
143+
Your experience matters - let us know how this feature works for your workflow!
144+
145+
For more about experimental features, see [Experimental Features Overview](/features/experimental/experimental-features).

‎docs/features/experimental/experimental-features.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ To enable or disable experimental features:
1717
The following experimental features are currently available:
1818

1919
- [Codebase Indexing](/features/experimental/codebase-indexing) - Semantic search through AI-powered codebase indexing
20+
- [Concurrent File Reads](/features/experimental/concurrent-file-reads) - Read multiple files simultaneously for improved efficiency
2021
- [Power Steering](/features/experimental/power-steering)
2122

2223
## Providing Feedback

‎sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ const sidebars: SidebarsConfig = {
6262
items: [
6363
'features/experimental/experimental-features',
6464
'features/experimental/codebase-indexing',
65+
'features/experimental/concurrent-file-reads',
6566
'features/experimental/power-steering',
6667
],
6768
},

0 commit comments

Comments
 (0)