File Manipulation Tools
Relevant source files
The following files were used as context for generating this wiki page:
File Manipulation Tools are a core component of the QQcode system, providing structured and safe mechanisms for an AI agent to interact with a local filesystem. These tools replace standard shell-based file operations (like cat, echo, or sed) with specialized Python-based implementations that enforce size limits, path validation, and human-in-the-loop approval workflows.
The primary objective of these tools is to allow the agent to read, create, and modify source code within a project's boundaries while maintaining security through allowlists and denylists. By using structured data models (Pydantic), these tools ensure that all filesystem changes are predictable and revertible.
Sources: CLAUDE.md:1-50, vibe/core/tools/builtins/prompts/bash.md:1-15
Architecture and Core Components
The file manipulation system is built on top of a base tool architecture that uses asynchronous I/O (aiofiles) and Pydantic for validation. Each tool consists of an argument model, a result model, and a logic class that inherits from BaseTool.
Tool Execution Flow
When the agent requests a file operation, the system follows a strict validation and execution pipeline:
The diagram shows the sequential validation and safety checks performed before any filesystem write occurs.
Sources: vibe/core/tools/builtins/write_file.py:84-135, vibe/core/tools/builtins/edit.py:75-125
Core Components Table
| Component | Description | Reference |
|---|---|---|
WriteFile | Creates or overwrites UTF-8 files with size and path enforcement. | write_file.py |
Edit | Performs targeted string replacements; requires uniqueness for safety. | edit.py |
ToolUIData | Interface for generating rich UI displays for tool calls and results. | tool_widgets.py |
BaseToolConfig | Defines safety parameters like max_write_bytes and denylist. | write_file.py:32 |
Detailed Tool Specifications
WriteFile Tool
The WriteFile tool is used to create new files or completely replace existing ones. It includes a safety flag overwrite which must be explicitly set to True if the target file already exists.
Configuration & Limits:
- Max Write Bytes: Defaults to 64,000 bytes.
- Parent Directory Creation: Automatically creates missing parent directories if enabled in config.
- Project Boundary: Prevents writing outside the project root using path resolution and comparison.
Sources: vibe/core/tools/builtins/write_file.py:15-45, vibe/core/tools/builtins/write_file.py:108-120
Edit Tool
The Edit tool provides a safer alternative to full-file writes by allowing exact text replacements. This tool is specifically recommended over sed or awk for code modifications.
Operational Logic:
- Uniqueness Check: By default, the tool fails if
old_stringappears multiple times, preventing accidental broad changes. - Replace All: A boolean flag that can override the uniqueness requirement.
- Validation: Ensures the file exists and does not exceed the
max_file_size(default 100,000 bytes).
Sources: vibe/core/tools/builtins/edit.py:14-45, vibe/core/tools/builtins/edit.py:84-105
User Interface and Feedback
QQcode uses the Textual-based TUI to provide visual feedback for file operations. Every tool implements methods to render "Approval" and "Result" widgets.
The sequence shows how user interaction is integrated into the tool execution lifecycle.
Sources: vibe/cli/textual_ui/widgets/tool_widgets.py:100-150, vibe/core/tools/builtins/edit.py:46-70
UI Components for Files
| Widget | Purpose | Data Displayed |
|---|---|---|
WriteFileApprovalWidget | Pre-write review | Path, file extension, and code block of content. |
EditApprovalWidget | Change review | Path and line-by-line diff (+/- formatting). |
ReadFileResultWidget | Content display | File path, warnings (if any), and truncated content. |
Sources: vibe/cli/textual_ui/widgets/tool_widgets.py:80-95, vibe/cli/textual_ui/widgets/tool_widgets.py:134-160
Usage Best Practices
The system instructions explicitly define when to use these tools versus standard bash commands to ensure safety and state management.
- Prohibited Bash Commands:
cat,echo >,sed -i, andfindshould be avoided in favor ofread_file,write_file,edit, andgrep. - Statelessness: Note that while the
bashtool is stateless (runs in fresh environments), file manipulation tools directly alter the persistent filesystem state. - Safety: Always utilize the
edittool for targeted changes to large files to avoid hitting token limits or accidentally wiping content.
Sources: vibe/core/tools/builtins/prompts/bash.md:10-35, vibe/core/tools/builtins/edit.py:40-44
Summary
File Manipulation Tools in QQcode provide a hardened layer for filesystem interactions. By combining Pydantic validation, asynchronous file I/O, and specialized TUI widgets, the system ensures that AI-driven code changes are transparent, bounded within the project directory, and subject to user oversight. These tools serve as the primary interface for the agent to implement features and fix bugs.