# workspace.fs.grep and workspace.fs.find Features in Cloudflare Computer

> Explore Cloudflare Computer's workspace.fs.grep and workspace.fs.find for efficient file system searching. Search file content with grep or locate files by path with find, both offering powerful pagination and filtering.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: deep-dive
- Published: 2026-09-04

---

**Both `workspace.fs.grep` and `workspace.fs.find` provide streaming-friendly file system search capabilities, with `grep` scanning file contents for literal or regex patterns and `find` locating files by glob-style path patterns, both supporting pagination via `limit`/`offset` and filtering via `include` and `ignoreCase` options.**

The Cloudflare Computer repository exposes a high-level file system API through `workspace.fs`, enabling developers to programmatically search codebases without loading entire directories into memory. The `grep` and `find` methods serve distinct but complementary roles in [`packages/computer/src/tools/fs/grep.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/grep.ts) and [`packages/computer/src/tools/fs/find.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/find.ts) respectively, and are documented extensively in [`docs/09_tool_interface.md`](https://github.com/cloudflare/computer/blob/main/docs/09_tool_interface.md) and [`docs/README.md`](https://github.com/cloudflare/computer/blob/main/docs/README.md).

## workspace.fs.grep Features

### Content Search Capabilities

`workspace.fs.grep` searches file contents recursively starting from a specified directory. It supports both literal string matching and regular expression patterns when the `regex` option is enabled. As implemented in [`packages/computer/src/tools/fs/grep.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/grep.ts), the method streams files through a line-by-line scanning interface that stops once the requested `limit` is reached, preventing memory exhaustion on large codebases.

### Configuration Options

The method accepts an options object supporting these parameters:

- **`ignoreCase`**: Enables case-insensitive matching across file contents.
- **`regex`**: Treats the query string as a JavaScript regular expression rather than a literal.
- **`include`**: Glob pattern to restrict search to specific file types (e.g., `"*.ts"`).
- **`limit`**: Maximum number of matches to return per call for pagination.
- **`offset`**: Number of matches to skip, enabling result set pagination.
- **`context`**: Number of surrounding lines to include with each match, useful for viewing code context.

### Match Results Structure

Each match returned by `workspace.fs.grep` contains:

- **`path`**: Absolute file path where the match occurred.
- **`line`**: Line number (1-indexed) of the match.
- **`column`**: Column number where the match begins.
- **`text`**: The actual matched text content.
- **`context`**: Optional array of surrounding lines when the `context` option is specified.

## workspace.fs.find Features

### Path-Based Search

`workspace.fs.find` locates files and directories whose paths match a glob-style pattern, starting from a root directory. Unlike `grep`, this method does not inspect file contents; it only evaluates path strings against the provided pattern. According to the implementation in [`packages/computer/src/tools/fs/find.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/find.ts) at line 44, the search leverages the underlying `@cloudflare/dofs` storage layer for efficient tree walking with early termination when limits are reached.

### Filtering and Pagination

The method supports controlled enumeration through these options:

- **`ignoreCase`**: Performs case-insensitive glob matching against file paths.
- **`include`**: Additional glob filter to further restrict results by file extension or naming convention.
- **`limit`**: Caps the maximum number of entries returned in a single call.
- **`offset`**: Skips the first *n* entries to support pagination through large result sets.

### File Metadata Results

Each result from `workspace.fs.find` returns a `ThinkFileInfo` object containing rich metadata:

- **`path`**: Absolute path to the file or directory.
- **`name`**: The filename or directory name.
- **`type`**: Either `"file"` or `"directory"`.
- **`mimeType`**: Detected MIME type for files.
- **`size`**: File size in bytes.
- **`createdAt`** and **`updatedAt`**: Unix timestamps for creation and modification.

## Implementation and Performance Details

Both methods utilize the `@cloudflare/dofs` storage layer for streaming results without loading complete file trees into memory. The `grep` implementation specifically avoids reading entire files unless necessary for matching, while `find` stops enumeration immediately upon reaching the specified `limit`. As noted in [`docs/09_tool_interface.md`](https://github.com/cloudflare/computer/blob/main/docs/09_tool_interface.md) lines 195-197, these methods respect the pagination contracts to prevent blocking the event loop on large repositories.

## Code Examples

### Grep for TODO Comments

The following example, referenced from [`docs/README.md`](https://github.com/cloudflare/computer/blob/main/docs/README.md) line 166, demonstrates case-insensitive content search:

```typescript
const hits = await workspace.fs.grep("TODO", "/workspace", {
  ignoreCase: true,
  limit: 20
});

// Result structure:
// {
//   path: '/workspace/src/app.ts',
//   line: 42,
//   column: 5,
//   text: ' // TODO: refactor this function'
// }

```

### Find Markdown Files

Locate all Markdown files under a documentation directory:

```typescript
const markdownFiles = await workspace.fs.find('/docs', '*.md', {
  ignoreCase: true,
  limit: 50
});

// Returns ThinkFileInfo objects:
// {
//   path: '/docs/README.md',
//   name: 'README.md',
//   type: 'file',
//   mimeType: 'text/markdown',
//   size: 1234,
//   createdAt: 1698392400000,
//   updatedAt: 1698392400000
// }

```

### Regex Search with Context

Search for error patterns with surrounding context lines:

```typescript
const errors = await workspace.fs.grep('\\bERROR\\b', '/logs', {
  regex: true,
  context: 2,
  include: "*.log",
  limit: 100
});

```

## Summary

- **`workspace.fs.grep`** scans file contents for literal text or regular expressions, supporting options for case insensitivity, file filtering, pagination (`limit`/`offset`), and result context.
- **`workspace.fs.find`** searches for files and directories by glob path patterns, returning `ThinkFileInfo` metadata including MIME types, sizes, and timestamps.
- **Source Locations**: [`packages/computer/src/tools/fs/grep.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/grep.ts) and [`packages/computer/src/tools/fs/find.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/find.ts) contain the core implementations.
- **Performance**: Both use streaming pagination via `@cloudflare/dofs` to handle large repositories efficiently.
- **Documentation**: Detailed specifications appear in [`docs/09_tool_interface.md`](https://github.com/cloudflare/computer/blob/main/docs/09_tool_interface.md) and usage examples in [`docs/README.md`](https://github.com/cloudflare/computer/blob/main/docs/README.md).

## Frequently Asked Questions

### What is the difference between workspace.fs.grep and workspace.fs.find?

`workspace.fs.grep` inspects the actual contents of files to locate text or regex matches, returning specific line numbers and column positions, while `workspace.fs.find` only evaluates file paths against glob patterns to locate items by name or extension, returning file metadata without examining content.

### How does pagination work with these search methods?

Both methods accept `limit` and `offset` options in their configuration objects. Set `limit` to define the maximum results per request and `offset` to skip previously retrieved items, enabling efficient pagination through large datasets without loading entire result sets into memory at once.

### Can workspace.fs.grep use regular expressions?

Yes. Pass `regex: true` in the options parameter to interpret the query as a JavaScript regular expression. The implementation compiles the pattern and performs efficient line-by-line matching across the file tree, as detailed in [`packages/computer/src/tools/fs/grep.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/tools/fs/grep.ts).

### What metadata does workspace.fs.find return?

Each result returns a `ThinkFileInfo` object containing the absolute path, filename, type classification (file or directory), MIME type, size in bytes, and Unix timestamps for creation and modification times, consistent with the metadata returned by `workspace.fs.stat`.