The read tool allows reading files with optional offset, limit, and line numbers. It's designed to be memory-efficient for large files by reading line-by-line instead of loading the entire file into memory.

Parameters

Parameter	Type	Required	Default	Description
`path`	string	Yes	-	The file path to read
`offset`	integer	No	1	Line number to start reading from (1-indexed)
`limit`	integer	No	null	Number of lines to read (null = all lines)
`line_numbers`	boolean	No	false	Include line numbers in output

Usage Examples

Example 1: Read entire file

{
  "path": "/path/to/file.txt"
}

Example 2: Read with line numbers

{
  "path": "/path/to/file.txt",
  "line_numbers": true
}

Example 3: Read first 10 lines

{
  "path": "/path/to/file.txt",
  "limit": 10
}

Example 4: Read lines 50-100

{
  "path": "/path/to/file.txt",
  "offset": 50,
  "limit": 50
}

Example 5: Read from line 100 to end

{
  "path": "/path/to/file.txt",
  "offset": 100
}

Return Value

The tool returns a JSON object with the following fields:

{
  "content": "The file content (with optional line numbers)",
  "path": "The file path that was read",
  "total_lines": 150,
  "lines_read": 10,
  "offset": 1,
  "limit": 10
}

Error Handling

If the file doesn't exist or an error occurs:

{
  "error": "File not found: /path/to/file.txt",
  "path": "/path/to/file.txt"
}

Write Tool

Description

The write tool allows writing, inserting, or replacing file content. It supports three modes:

Write mode (no start_line): Write/overwrite entire file
Insert mode (start_line only): Insert data at specified line
Replace mode (start_line + end_line): Replace lines in that range

Parameters

Parameter	Type	Required	Default	Description
`path`	string	Yes	-	The file path to write
`data`	string	Yes	-	The content to write
`start_line`	integer	No	null	Line number to insert at or start replacement (1-indexed)
`end_line`	integer	No	null	Line number to end replacement (only with start_line)

Usage Examples

Example 1: Write entire file (create or overwrite)

{
  "path": "/path/to/file.txt",
  "data": "Hello\nWorld\n"
}

Example 2: Insert at line 5

{
  "path": "/path/to/file.txt",
  "data": "New line\n",
  "start_line": 5
}

Example 3: Replace lines 10-20

{
  "path": "/path/to/file.txt",
  "data": "New content\nMultiple lines\n",
  "start_line": 10,
  "end_line": 20
}

Example 4: Prepend to file

{
  "path": "/path/to/file.txt",
  "data": "Header\n",
  "start_line": 1
}

Example 5: Append to file (insert after last line)

{
  "path": "/path/to/file.txt",
  "data": "Footer\n",
  "start_line": 999999
}

Return Value

The tool returns a JSON object with the following fields:

Write mode:

{
  "success": true,
  "path": "/path/to/file.txt",
  "bytes_written": 12,
  "mode": "write",
  "lines_affected": 2,
  "message": "File written successfully"
}

Insert mode:

{
  "success": true,
  "path": "/path/to/file.txt",
  "bytes_written": 14,
  "mode": "insert",
  "lines_affected": 1,
  "inserted_at": 5,
  "message": "Data inserted at line 5"
}

Replace mode:

{
  "success": true,
  "path": "/path/to/file.txt",
  "bytes_written": 25,
  "mode": "replace",
  "lines_affected": 2,
  "lines_replaced": 11,
  "range": "10-20",
  "message": "Replaced lines 10-20 (11 lines) with 2 new lines"
}

Error Handling

If an error occurs:

{
  "success": false,
  "error": "end_line requires start_line to be specified",
  "path": "/path/to/file.txt"
}

Special Features

Auto-create directories: If the directory doesn't exist, it will be created automatically
Padding: If start_line is beyond the current file length, empty lines are automatically added
Flexible replacement: Can replace any range with any number of new lines

Exec Tool

Description

The exec tool allows executing shell commands with timeout support, environment variables, and working directory control. By default, it uses bash with the user's .bashrc sourced.

Parameters

Parameter	Type	Required	Default	Description
`command`	string	Yes	-	The command to execute
`shell`	string	No	"bash"	Shell to use (bash, sh, zsh, etc.)
`timeout`	integer	No	30	Timeout in seconds
`cwd`	string	No	null	Working directory for command execution
`env`	object	No	null	Environment variables as key-value pairs
`source_rc`	boolean	No	true	Whether to source shell RC file

Usage Examples

Example 1: Simple command

{
  "command": "echo Hello World"
}

Example 2: Command with pipes

{
  "command": "cat file.txt | grep pattern | wc -l"
}

Example 3: Command with timeout

{
  "command": "long-running-process",
  "timeout": 60
}

Example 4: Command with working directory

{
  "command": "npm test",
  "cwd": "/path/to/project"
}

Example 5: Command with environment variables

{
  "command": "node script.js",
  "env": {
    "NODE_ENV": "production",
    "DEBUG": "true"
  }
}

Example 6: Use different shell

{
  "command": "echo $SHELL",
  "shell": "zsh"
}

Example 7: Skip RC file sourcing

{
  "command": "clean-command",
  "source_rc": false
}

Return Value

The tool returns a JSON object with the following fields:

Successful execution:

{
  "success": true,
  "command": "echo Hello World",
  "stdout": "Hello World\n",
  "stderr": "",
  "exit_code": 0,
  "timed_out": false,
  "shell": "bash",
  "cwd": null
}

Failed execution:

{
  "success": false,
  "command": "exit 1",
  "stdout": "",
  "stderr": "",
  "exit_code": 1,
  "timed_out": false,
  "shell": "bash",
  "cwd": null
}

Timeout:

{
  "success": false,
  "error": "Command timed out after 30 seconds",
  "command": "sleep 60",
  "stdout": "",
  "stderr": "",
  "exit_code": -1,
  "timed_out": true
}

Error Handling

If an error occurs during execution:

{
  "success": false,
  "error": "Failed to execute command: No such file or directory",
  "command": "nonexistent-command",
  "exit_code": -1,
  "timed_out": false
}

Special Features

RC file sourcing: Automatically sources .bashrc or .zshrc for bash/zsh shells
Timeout protection: Commands are automatically terminated if they exceed the timeout
Environment control: Full control over environment variables
Working directory: Execute commands in any directory
Capture output: Both stdout and stderr are captured separately

Best Practices

Read Tool

Use offset and limit for large files: Don't read entire large files into memory
```
{
  "path": "large-log.txt",
  "offset": 1000,
  "limit": 100
}
```
Use line_numbers for debugging: Makes it easier to reference specific lines
```
{
  "path": "config.yaml",
  "line_numbers": true
}
```
Check total_lines: Use the total_lines field to understand file size before reading more

Write Tool

Use insert mode for logging: Insert new entries at specific positions

{
  "path": "log.txt",
  "data": "New log entry\n",
  "start_line": 1
}

Use replace mode for updates: Replace specific sections without rewriting entire file

{
  "path": "config.txt",
  "data": "new_value=value\n",
  "start_line": 10,
  "end_line": 10
}

Create backups for important files: Read the file first, then write

Exec Tool

Always set appropriate timeouts: Don't let commands run indefinitely
```
{
  "command": "build-script.sh",
  "timeout": 300
}
```
Check exit_code: A non-zero exit code indicates failure
```
{
  "success": false,
  "exit_code": 1
}
```
Use cwd for project commands: Execute commands in the correct directory
```
{
  "command": "make build",
  "cwd": "/path/to/project"
}
```
Validate command output: Check both stdout and stderr for errors
Set source_rc=false for clean environment: When you need a pristine environment
```
{
  "command": "env",
  "source_rc": false
}
```

Error Handling

All tools follow a consistent error handling pattern:

Success Response

{
  "success": true,
  "path": "...",
  "message": "..."
}

Error Response

{
  "success": false,
  "error": "Error description",
  "path": "..."
}

Common Errors

File not found (read tool):

{
  "error": "File not found: /path/to/file.txt",
  "path": "/path/to/file.txt"
}

Invalid parameters (write tool):

{
  "success": false,
  "error": "end_line must be >= start_line",
  "path": "/path/to/file.txt"
}

Command timeout (exec tool):

{
  "success": false,
  "error": "Command timed out after 30 seconds",
  "command": "...",
  "timed_out": true
}

Command execution failure (exec tool):

{
  "success": false,
  "error": "Failed to execute command: permission denied",
  "command": "...",
  "exit_code": -1
}

Tool Registration

These tools are automatically registered when the application starts. They can be accessed through the global tool registry:

# Get the global tool registry
registry = ToolRegistry.global

# Check if a tool is registered
registry.registered?("read")  # => true
registry.registered?("write") # => true
registry.registered?("exec")  # => true

# Execute a tool
result = registry.execute("read", {"path" => "/tmp/test.txt"}.to_json)

# Get tool instance
read_tool = registry.get("read")

Integration with Agents

These tools can be enabled or disabled for specific agents through the agent configuration:

# agent.config.yaml
agents:
  - name: file-assistant
    model: qwen3-coder
    tools:
      - read
      - write
      # exec is not listed, so it won't be available

Or enable all tools:

agents:
  - name: full-access-agent
    model: qwen3-coder
    tools: all  # All registered tools are available

Security Considerations

Read Tool

✅ Safe: Only reads files, doesn't modify anything
⚠️ Warning: Can read any file the process has access to
💡 Recommendation: Run agent with appropriate file permissions

Write Tool

⚠️ Warning: Can create, modify, and overwrite files
⚠️ Warning: Can create directories
💡 Recommendation: Restrict write access to specific directories
💡 Recommendation: Implement file backup strategy

Exec Tool

⚠️ Warning: Can execute any shell command
⚠️ Warning: Inherits process permissions
⚠️ Warning: Can access environment variables
💡 Recommendation: Use env parameter to control environment
💡 Recommendation: Use cwd to restrict execution context
💡 Recommendation: Always set appropriate timeouts
💡 Recommendation: Consider sandboxing for untrusted agents

Performance Characteristics

Read Tool

Memory efficient: Uses line-by-line reading
Scales well: Only loads requested lines into memory
Fast: No parsing overhead for plain text

Write Tool

Memory usage: Loads entire file for insert/replace operations
Performance: Linear with file size for modifications
Recommendation: For very large files, consider writing in chunks

Exec Tool

Timeout overhead: Minimal (uses Crystal fibers)
Process isolation: Each command runs in separate process
Output capture: Uses IO::Memory for efficient buffering

Troubleshooting

Read Tool Issues

Problem: File not found error

Check file path is absolute or relative to correct directory
Verify file exists with ls command
Check file permissions

Problem: Offset beyond file length

Tool returns empty content
Check total_lines in response to understand file size

Write Tool Issues

Problem: Permission denied

Check directory permissions
Ensure process has write access
Check disk space

Problem: Insert/replace not working as expected

Remember: lines are 1-indexed (not 0-indexed)
Verify the line numbers are correct
Check lines_affected in response

Exec Tool Issues

Problem: Command times out

Increase timeout parameter
Check if command is hanging
Verify command works in terminal

Problem: Environment variables not available

Set source_rc: true (default)
Use env parameter to pass variables explicitly
Check shell RC file exists

Problem: Command not found

Verify command is installed
Check PATH environment variable
Use full path to command

Examples

Example 1: Read configuration and update it

// Step 1: Read the config file
{
  "tool": "read",
  "params": {
    "path": "/etc/app/config.yaml",
    "line_numbers": true
  }
}

// Step 2: Update specific line
{
  "tool": "write",
  "params": {
    "path": "/etc/app/config.yaml",
    "data": "debug: false\n",
    "start_line": 15,
    "end_line": 15
  }
}

Example 2: Execute build process

// Step 1: Run tests
{
  "tool": "exec",
  "params": {
    "command": "npm test",
    "cwd": "/project",
    "timeout": 60
  }
}

// Step 2: Build if tests pass
{
  "tool": "exec",
  "params": {
    "command": "npm run build",
    "cwd": "/project",
    "timeout": 120
  }
}

Example 3: Log file analysis

// Step 1: Read last 100 lines of log
{
  "tool": "read",
  "params": {
    "path": "/var/log/app.log",
    "offset": -100,
    "line_numbers": true
  }
}

// Step 2: Search for errors
{
  "tool": "exec",
  "params": {
    "command": "grep ERROR /var/log/app.log | tail -n 20",
    "timeout": 10
  }
}

Version History

v0.1.0 (2025-03-21): Initial implementation
- Read tool with offset, limit, line numbers
- Write tool with insert and replace modes
- Exec tool with timeout and environment support