Read Tool

The Read tool lets Nilux AI read file contents from your filesystem. It supports text files, images (PNG, JPG, GIF, WebP, BMP, TIFF), PDFs, and Jupyter notebooks. For large text files, you can read specific sections using offset and limit parameters.

Parameters

Reading Text Files

Basic Read

When the agent reads a file, it gets the raw content exactly as stored on disk:

> Read src/auth/login.ts

Agent invokes Read:
  file_path: src/auth/login.ts

Result:
  1  import { validateCredentials } from './utils';
  2  import { createTokens } from './tokens';
  3
  4  export async function login(email: string, password: string) {
  5    const user = await findUserByEmail(email);
  6    if (!user) throw new Error('Invalid credentials');
  7    ...

Reading Large Files

For files over 2000 lines, the agent uses a two-step approach:

1. Use Grep to find the relevant line numbers
2. Use Read with offset and limit to read the specific section

> Find and read the login function in auth.ts

Step 1 — Agent uses Grep:
  search_pattern: "function login"
  search_path: src/auth/login.ts

Result: Line 42

Step 2 — Agent uses Read:
  file_path: src/auth/login.ts
  offset: 40
  limit: 30

Reading Images

The Read tool automatically detects image files by both extension and content (magic bytes). When the agent reads an image, it sees the image visually — no OCR or external tools are needed.

Supported image formats:

• PNG
• JPG / JPEG
• GIF
• WebP
• BMP
• TIFF

> Read this screenshot

Agent invokes Read:
  file_path: screenshot.png

Result: [Image displayed visually to the agent]

Note: Image size is limited to 5MB. For analyzing image content with a specific prompt, use the image analysis tool after reading.

Reading PDFs

PDF files are read page by page, with extracted text and visual content:

> Read docs/api-reference.pdf

Agent invokes Read:
  file_path: docs/api-reference.pdf

Result:
  [Page 1]
  API Reference v2.0
  ...

  [Page 2]
  Authentication Endpoints
  ...

Reading Jupyter Notebooks

.ipynb files are read with all cells and their outputs displayed:

> Read analysis.ipynb

Agent invokes Read:
  file_path: analysis.ipynb

Result:
  [Cell 1 — Code]
  import pandas as pd
  df = pd.read_csv('data.csv')
  df.head()

  [Output]
     name  value
  0  foo   42
  1  bar   17

Large Files

For very large files, the Read tool returns a partial result. The agent handles this automatically by:

1. Using Grep to find the relevant line numbers
2. Using Read with offset and limit to read the specific section

Tip: For navigating large files, combine Grep with Read. Search for the relevant symbol or pattern with Grep, note the line number, then Read that section.

Binary Files

Binary files (executables, compiled objects, archives) are rejected with an error message. The agent is instructed not to attempt reading them.

Directories

The Read tool does not list directory contents. To explore a directory, the agent uses Bash with ls:

> What's in the components directory?

Agent invokes Bash:
  command: ls -la src/components/
  timeout: 5000
  description: List components directory

Common Patterns

Read a single file:

Read src/lib/utils.ts

Read from a specific line:

Read src/lib/utils.ts, offset: 150, limit: 50

Read an image for analysis:

Read docs/screenshots/dashboard-error.png

Read the start of a large file:

Read CHANGELOG.md, limit: 50

Edit Prerequisite

Warning: The Edit tool requires that the file has been read first in the current conversation. The agent must use Read before making any edits. This ensures the agent works with the current file content, not stale context.

Next Steps

• Edit — Making targeted file changes
• Write — Creating new files
• Grep — Searching file contents
• Tools Overview — All available tools