Pi Hex Edit Extension

A robust hex stream-based edit replacement for Pi Coding Agent that provides reliable, byte-level file editing with validation and transparency.

Features

• Hex Stream Validation: Uses byte-level comparison instead of text matching for maximum reliability
• LLM-callable Tools: Tools that Pi can directly call for file operations
• Hash Verification: Shows SHA-256 hashes before and after edits for verification
• Multiple Occurrence Handling: Warns when multiple matches found and uses the first occurrence
• Detailed Output: Displays file sizes, byte changes, and exact positions
• Error Handling: Clear error messages for missing files and text not found
• Binary File Support: Perfect for both text and binary file editing
• Typebox Validation: All tools now use Typebox for robust parameter validation
• Streaming Support: Progress updates during long operations
• Enhanced Hash Verification: Both SHA-256 and simple hash for performance
• Better Context Display: ±20 byte context in validation results
• Optimized Diff Output: Shows first 50 lines for readability
• Proper Tool Labels: Clear descriptions for better LLM understanding
• Automatic Recovery: When the builtin edit tool fails, hex-edit automatically intercepts and retries with byte-level validation (enabled by default)
• Fallback for Edit Failures: Use when the built-in edit tool fails due to encoding, whitespace, or special character issues

Installation

# Install via npm
npm install @vtstech/pi-hex-edit

# Or install directly from GitHub
pi install git:github.com/VTSTech/pi-coding-agent#main --filter pi-hex-edit

Available Tools

1. hex_edit

Edit file using hex stream validation for reliable byte-level editing.

{
  "name": "hex_edit",
  "parameters": {
    "file": "string",           // Path to the file to edit
    "oldText": "string",        // Exact text to replace  
    "newText": "string"         // Replacement text
  }
}

Example Usage:

{
  "tool": "hex_edit",
  "parameters": {
    "file": "src/app.js",
    "oldText": "console.log('Hello World');",
    "newText": "console.log('Hello Universe!');"
  }
}

2. hex_edit_show

Show file content with line numbers and hex preview.

{
  "name": "hex_edit_show", 
  "parameters": {
    "file": "string"           // Path to the file to show
  }
}

Output includes:

• File size and SHA-256 hash
• Line-by-line view with text preview (60 chars)
• Hex bytes preview for each line (16 bytes)
• Line numbers for easy reference

3. hex_edit_validate

Validate that old text exists in file and show positions.

{
  "name": "hex_edit_validate",
  "parameters": {
    "file": "string",          // Path to the file to validate
    "searchText": "string"     // Text to search for in the file
  }
}

Output includes:

• Number of occurrences found
• Byte positions for each occurrence
• Context around each match (±20 bytes)
• Clear success/failure indication

4. hex_edit_diff

Show byte-level diff between two files.

{
  "name": "hex_edit_diff",
  "parameters": {
    "file1": "string",         // Path to the first file
    "file2": "string"         // Path to the second file
  }
}

Output includes:

• File sizes and hashes for both files
• "Files are identical" or detailed differences
• Line-by-line diff showing additions (+) and deletions (-)
• Truncated to 50 lines for readability

Usage Examples

Basic File Edit

# Pi can call: hex_edit(file: "config.txt", oldText: "debug=false", newText: "debug=true")

Validate Text Exists

# Pi can call: hex_edit_validate(file: "app.js", searchText: "function main")

Show File Details

# Pi can call: hex_edit_show(file: "README.md")

Compare Files

# Pi can call: hex_edit_diff(file1: "old.txt", file2: "new.txt")

Why Hex Edit?

Problems with Regular Text Editing

• Text encoding issues with different character sets
• Line ending differences between platforms (CRLF vs LF)
• Partial matches causing unintended replacements
• Binary file corruption when using text-based editors

When to Use Hex Edit

Use /hex-edit as a reliable fallback when the built-in edit tool fails:

• Encoding issues - Special characters, Unicode, non-ASCII text
• Whitespace problems - Invisible characters, different line endings
• Partial matches - When text-based matching finds wrong content
• Binary files - Images, executables, archives, and other non-text files

Automatic Recovery

When the builtin edit tool fails (returns an error), the hex-edit extension automatically intercepts the failed operation and retries it using byte-level validation. This happens seamlessly without any action required from the user. The recovery is enabled by default and can be controlled via the OVERWRITE_BUILTIN_EDIT configuration flag.

Hex Edit Solutions

• Byte-level precision - Works exactly on the bytes you specify
• Encoding agnostic - Doesn't care about text encodings
• Exact matching - Only replaces the exact byte sequence
• Binary safe - Perfect for images, executables, and other binary files

Technical Details

Hash Algorithm

• SHA-256 for file content verification
• Simple hash for quick comparison during editing

Search Algorithm

• Linear scan through file content
• All occurrences found and reported
• First occurrence used for editing

Replacement Algorithm

• Buffer manipulation for precise byte replacement
• No text parsing involved
• Position-based replacement guaranteed

Error Handling

| Error Type | Description | Solution | |------------|-------------|----------| | File not found | Specified file doesn't exist | Check file path and permissions | | Text not found | Old text not found in file | Use hex_edit_validate to verify | | Multiple matches | Multiple occurrences found | Tool will use first occurrence | | Permission denied | Insufficient file permissions | Check file permissions | | Invalid encoding | Text encoding issues | Use exact byte sequences |

Integration

The extension automatically integrates with Pi Coding Agent:

1. Tool Registration: All tools are available to Pi immediately
2. Slash Commands: User-friendly slash commands also available
3. Error Handling: Graceful error reporting and recovery
4. Validation: Built-in validation for all parameters

Development

Building

# Build the extension
npm run build

# Or build the entire project
npm run build:hex-edit

Testing

# Run tests (when implemented)
npm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE file for details.

Author

VTSTech
Website: www.vts-tech.org
GitHub: VTSTech
Repository: pi-coding-agent

Support

For issues and questions:

• GitHub Issues: pi-coding-agent/issues
• Email: [email protected]