> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Filesystem Tools

> File operations available in AutonomousAgent

The `AutonomousFilesystemToolKit` provides comprehensive file operations, all sandboxed to the workspace directory.

## Available Tools

| Tool | Description |
| - | - |
| `read_file` | Read file contents with optional line offset/limit |
| `write_file` | Create or overwrite files |
| `edit_file` | Replace text in files (requires reading first) |
| `list_files` | List directory contents (recursive or non-recursive) |
| `search_files` | Search for files by name pattern |
| `grep_files` | Search file contents using regex |
| `file_info` | Get file metadata (size, dates, permissions) |
| `create_directory` | Create directories recursively |
| `move_file` | Move or rename files |
| `copy_file` | Copy files or directories |
| `delete_file` | Delete files or directories |

## Example: Code Analysis

```python theme={null}
from upsonic import AutonomousAgent, Task

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace="/path/to/project"
)

# Search and analyze code
task = Task("Find all Python files that contain 'TODO' comments and list them with line numbers")
agent.print_do(task)
```

## Example: Bulk File Operations

```python theme={null}
from upsonic import AutonomousAgent, Task

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace="/path/to/project"
)

# Create project structure
task = Task("""
Create a basic Python package structure:
- src/mypackage/__init__.py
- src/mypackage/core.py with a sample function
- tests/__init__.py
- tests/test_core.py with a basic test
""")
agent.print_do(task)
```

## Read-Before-Edit Safety

The filesystem toolkit enforces reading a file before editing it. This prevents accidental modifications to files the agent hasn't seen:

```python theme={null}
from upsonic import AutonomousAgent, Task

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace="/path/to/project"
)

# The agent will automatically read first, then edit
task = Task("Add type hints to all functions in utils.py")
agent.print_do(task)
```

## Direct Toolkit Access

Access the toolkit directly for programmatic use:

```python theme={null}
from upsonic import AutonomousAgent

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace="/path/to/project"
)

# Read a file
content = agent.filesystem_toolkit.read_file("README.md")
print(content)

# List files in a directory
files = agent.filesystem_toolkit.list_files("src", recursive=True)
print(files)

# Search for files by pattern
python_files = agent.filesystem_toolkit.search_files("*.py")
print(python_files)

# Check what files were read
print(agent.filesystem_toolkit.get_read_files())

# Reset tracking if needed
agent.filesystem_toolkit.reset_read_tracking()
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.