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

# File Editing

> Fuzzy find-and-replace across files, scoped to a workspace

File editing tools provide secure, workspace-scoped file operations with fuzzy find-and-replace capabilities for precise code and content modifications.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "File Editing Flow"
        A[🤖 Agent] --> S[🔍 Search Files]
        S --> F[📄 Find Pattern]
        F --> E[✏️ Edit/Replace]
        E --> W[📁 Workspace Check]
        W --> V[✅ Verify & Save]
    end
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef security fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef complete fill:#10B981,stroke:#7C90A0,color:#fff
    class A agent
    class S,F,E process
    class W security
    class V complete
```

## Quick Start

<Steps>
  <Step title="Basic File Editing">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Code Editor",
        instructions="Edit code files carefully using fuzzy search and replace.",
        tools=["edit_file", "search_files", "read_file"]
    )

    agent.start("Replace 'getUserName' with 'getUserEmail' in all JavaScript files.")
    ```
  </Step>

  <Step title="Search and Edit Workflow">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Agent workflow:
    # 1. search_files("./src", "getUserName", "*.js") - Find occurrences
    # 2. edit_file("src/user.js", "getUserName", "getUserEmail") - Make changes
    # 3. read_file("src/user.js") - Verify results
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant A as 🤖 Agent
    participant S as 🔍 Search
    participant W as 📁 Workspace
    participant F as 📄 File
    
    A->>S: search_files("./src", "pattern")
    S->>W: validate path containment
    W-->>S: ✅ allowed
    S->>F: scan files for pattern
    F-->>S: match locations
    S-->>A: JSON results
    A->>F: edit_file(path, old, new)
    F->>W: validate workspace boundary  
    W-->>F: ✅ contained
    F-->>A: success message
```

File editing operations use workspace containment for security:

| Operation         | Risk Level | Workspace Required | Purpose                |
| ----------------- | ---------- | ------------------ | ---------------------- |
| **search\_files** | Low        | No                 | Find patterns in files |
| **read\_file**    | Low        | No                 | Read file contents     |
| **list\_files**   | Low        | No                 | Directory listings     |
| **edit\_file**    | High       | Recommended        | Modify file contents   |
| **write\_file**   | High       | Recommended        | Create/overwrite files |

***

## Configuration Options

### File Editing Functions

| Function       | Args                                                        | Description                    |
| -------------- | ----------------------------------------------------------- | ------------------------------ |
| `edit_file`    | `filepath`, `old_string`, `new_string`, `replace_all=False` | Fuzzy find-and-replace in file |
| `search_files` | `directory`, `pattern`, `file_pattern="*"`                  | Search for text patterns       |
| `read_file`    | `filepath`                                                  | Read file contents             |
| `write_file`   | `filepath`, `content`                                       | Write/overwrite file           |
| `list_files`   | `directory`                                                 | List directory contents        |

### Search Parameters

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Basic text search
search_files("./src", "function getUserName")

# File type filtering
search_files("./src", "useState", "*.jsx")
search_files("./docs", "# Introduction", "*.md")

# Recursive directory search
search_files("./", "TODO:", "*.py")
```

### Edit Options

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Single replacement (default)
edit_file("config.js", "port: 3000", "port: 8080")

# Replace all occurrences
edit_file("styles.css", "color: blue", "color: green", replace_all=True)

# Case-sensitive replacement
edit_file("README.md", "PraisonAI", "PraisonAI Framework")
```

### Workspace Integration

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.tools import create_edit_tools
from praisonaiagents.workspace import Workspace

workspace = Workspace(root=Path("./project"), access="rw")
edit_tools = create_edit_tools(workspace=workspace)

# All operations scoped to workspace
result = edit_tools.edit_file("src/app.js", "old", "new")
```

***

## Common Patterns

### Code Refactoring

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(
    name="Refactoring Assistant",
    instructions="""
    For refactoring tasks:
    1. Search for pattern occurrences first
    2. Show user what will be changed
    3. Apply edits systematically
    4. Verify results by reading modified files
    """,
    tools=["search_files", "edit_file", "read_file"]
)

# User: "Rename all instances of 'oldFunction' to 'newFunction'"
# Agent workflow:
# search_files("./src", "oldFunction")  # Find all occurrences
# edit_file("src/utils.js", "oldFunction", "newFunction", replace_all=True)
# read_file("src/utils.js")  # Verify changes
```

### Configuration Updates

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Update environment variables
edit_file(".env", "DATABASE_URL=localhost", "DATABASE_URL=production.db")

# Update package versions  
search_files(".", "\"react\": \"16", "package.json")
edit_file("package.json", "\"react\": \"16.14.0\"", "\"react\": \"18.2.0\"")

# Update documentation
edit_file("README.md", "## Version 1.0", "## Version 2.0")
```

### Bulk Content Changes

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Update copyright notices
search_files("./src", "Copyright 2023", "*.js")
edit_file("src/header.js", "Copyright 2023", "Copyright 2024", replace_all=True)

# Update API endpoints
search_files("./src", "/api/v1/", "*.js")
edit_file("src/api.js", "/api/v1/", "/api/v2/", replace_all=True)
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Search Before Edit">
    Always use `search_files` to locate patterns before making edits. This provides visibility into the scope of changes and prevents unexpected modifications.
  </Accordion>

  <Accordion title="Workspace Security">
    File editing operations respect workspace boundaries. Destructive operations (`edit_file`, `write_file`) require proper workspace configuration for security.
  </Accordion>

  <Accordion title="Verification Workflow">
    After making edits, use `read_file` to verify changes were applied correctly. This catches encoding issues or unexpected results.
  </Accordion>

  <Accordion title="Atomic Operations">
    Edit operations are atomic - they either succeed completely or leave the original file unchanged. This prevents file corruption from partial writes.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Workspace" icon="folder-lock" href="/docs/features/workspace">
    How workspace containment secures file operations
  </Card>

  <Card title="Bot Default Tools" icon="toolbox" href="/docs/features/bot-default-tools">
    File tools included in default bot toolsets
  </Card>
</CardGroup>