Big honking warning about file access

Author: dannyob

CLAUDE.md

@@ -1,31 +1,112 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) when working with this LLM plugin repository.
 
-## Plugin Development Commands
+## Project Overview
 
-Use `llm install .` to install LLM plugins from the current directory (not pip install).
+`llm-tools-patch` is an LLM plugin that provides comprehensive text file manipulation tools through a unified `Patch` toolbox. The plugin is designed to give AI agents safe, controlled access to common file operations.
 
-Test the plugin after installation:
+## Development Commands
+
+### Environment Setup
+```bash
+make dev-setup      # Complete development environment setup
+source .venv/bin/activate  # Activate virtual environment
+```
+
+### Plugin Installation & Testing
 ```bash
-llm tools  # List available tools to verify registration
-llm prompt -m gpt-4o-mini "Please read and modify this config file" --tool Patch  # Test functionality
+llm install .       # Install plugin from current directory (not pip install)
+llm tools          # Verify plugin registration - should show Patch tools
+llm prompt "Read the README.md file" --tool Patch_patch_read README.md  # Test functionality
+```
+
+### Code Quality & Testing
+```bash
+make test          # Run comprehensive test suite
+make lint          # Run ruff linting
+make format        # Format code with ruff  
+make check         # Run both linting and tests
+make test-coverage # Generate coverage report
+```
+
+### Build & Distribution
+```bash
+make build         # Build distribution packages
+make upload-test   # Upload to TestPyPI
+make upload        # Upload to PyPI (production)
 ```
 
 ## Architecture Overview
 
-This is an LLM plugin that provides text file manipulation tools through a Toolbox pattern. The plugin exposes file reading, writing, and patching functions bundled in a single `Patch` class.
+### File Structure
+- `llm_tools_patch.py` - Main plugin module containing all functionality
+- `tests/test_patch.py` - Comprehensive test suite
+- `pyproject.toml` - Project configuration and dependencies
+- `Makefile` - Development workflow automation
+
+### Core Architecture
 
-### Core Components
+**Patch Toolbox Class** (`llm_tools_patch.Patch`):
+- Extends `llm.Toolbox` following LLM plugin conventions
+- Methods automatically become tools with naming pattern `Patch_method_name`
+- Bundles five core file operations in a single toolbox
 
-**Patch** (main toolbox class): Bundles all file manipulation tools
-- Extends `llm.Toolbox` 
-- Methods become available as tools with naming pattern `Patch_method_name`
-- Contains file operations: reading, writing, and making targeted changes to text files
+**Individual Functions**: Can also be imported directly:
+- `patch_read()` - Read complete file contents
+- `patch_write()` - Write/overwrite file content  
+- `patch_edit()` - Single string replacement
+- `patch_multi_edit()` - Multiple sequential edits
+- `patch_info()` - File metadata and information
 
 ### Key Features
 
-- **Safe file operations**: Read files without modification
-- **Targeted patching**: Make specific changes to parts of text files
-- **Text-focused**: Designed for configuration files, code, documentation, and other text content
-- **LLM-friendly**: Simple interface optimized for AI agent usage
+- **Atomic operations**: Multi-edit operations succeed completely or fail completely
+- **Safety first**: Comprehensive validation and error handling
+- **Encoding detection**: Automatic UTF-8 handling with fallback detection
+- **Path resolution**: Support for relative paths, absolute paths, and `~` expansion
+- **LLM-optimized**: Clear error messages and straightforward operations
+- **Extensive testing**: Edge cases, Unicode support, large files, error conditions
+
+## Development Guidelines
+
+### Adding New Features
+1. Add functionality to `llm_tools_patch.py`
+2. Add corresponding method to `Patch` class if user-facing
+3. Add comprehensive tests to `tests/test_patch.py`
+4. Update docstrings following existing patterns
+5. Run `make check` to ensure quality standards
+
+### Testing Philosophy
+- Test both individual functions and toolbox methods
+- Cover edge cases: empty files, Unicode, large content, permission errors
+- Validate error conditions and error messages
+- Use pytest fixtures for consistent test setup
+
+### Error Handling Pattern
+All functions should:
+- Return success messages with specific details (character counts, replacement counts)
+- Return error messages starting with "Error:" for failures
+- Handle common exceptions (FileNotFoundError, PermissionError, UnicodeDecodeError)
+- Provide actionable error messages for users
+
+## Tool Usage Patterns
+
+### Safe File Reading
+Always use `patch_read()` or `patch_info()` before modifying files to understand their content and ensure accessibility.
+
+### Targeted Editing
+For precise changes, use `patch_edit()` with enough context in the search string to ensure uniqueness. Use `replace_all=True` only when intentionally replacing all occurrences.
+
+### Batch Operations  
+Use `patch_multi_edit()` for multiple related changes. Remember that edits are applied sequentially, so later edits operate on the results of earlier ones.
+
+### File Creation
+Use `patch_write()` to create new files or completely replace existing content. Parent directories are created automatically.
+
+## Plugin Integration
+
+The plugin registers with LLM using the entry point system:
+- `pyproject.toml` defines `llm_tools_patch = "llm_tools_patch"` entry point
+- `@llm.hookimpl` decorator on `register_tools()` function
+- Tools become available as `Patch_method_name` in LLM conversations

README.md

@@ -5,56 +5,92 @@
 [![Tests](https://github.com/dannyob/llm-tools-patch/actions/workflows/test.yml/badge.svg)](https://github.com/dannyob/llm-tools-patch/actions/workflows/test.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/dannyob/llm-tools-patch/blob/main/LICENSE)
 
-LLM tools for reading, writing and changing text files 
+LLM plugin providing comprehensive text file manipulation, including reading, writing, and edits.
 
 ## Installation
 
-Install this plugin in the same environment as [LLM](https://llm.datasette.io/). You'll need at least the [0.26a1 alpha](https://llm.datasette.io/en/latest/changelog.html#a1-2025-05-25).
+Install this plugin in the same environment as [LLM](https://llm.datasette.io/). You'll need at least LLM [0.26a1](https://llm.datasette.io/en/latest/changelog.html#a1-2025-05-25) or later.
 
-## Installation
-
-Install this plugin using `llm install`:
+### From PyPI (recommended)
 
 ```bash
 llm install llm-tools-patch
 ```
 
-Or install from source:
+### From source
 
 ```bash
 git clone https://github.com/dannyob/llm-tools-patch
 cd llm-tools-patch
 llm install .
 ```
 
+## ⚠️ Security Warning
+
+**This plugin provides AI agents with direct file system access.** The tools can read, write, and modify any files that your user account can access. Before enabling this plugin:
+
+- Remember that AI agents can access files outside your current working directory
+- Only use with trusted AI models and prompts
+- Use `--ta` (tool approval) mode - review all file operations carefully
+- Consider the potential impact if an AI agent modifies important files
+
 ## Usage
 
-This plugin provides tools for text file operations:
+The plugin provides a single `Patch` toolbox with five core operations:
 
-- Reading text files
-- Writing text files  
-- Making targeted changes/patches to text files
+### Available Tools
 
-Use the `Patch` toolbox in your LLM conversations:
+- `read` - Read complete contents of a text file
+- `write` - Write new content to a file (overwrites existing)
+- `edit` - Make a single string replacement
+- `multi_edit` - Apply multiple string replacements in sequence  
+- `info` - Get file metadata and information
+
+### Basic Usage
+
+```bash
+# Make a single edit
+llm -c prompt -m gpt-4o-mini "Change port 8080 to 3000 in config.txt" --tool Patch --ta
+```
 
 ```bash
-llm prompt -m gpt-4o-mini "Add a smiley face to the first heading in the README.md file" --tool Patch --chain-limit 0 --ta
+# Make multiple edits
+llm -c prompt -m gpt-4o-mini "Add a smiley face to the first heading in README.md" --tool Patch --ta --chain-limit 0
 ```
 
-You'll probably want to use both the `--ta` option (which requires a user confirmation before executing any function) and `--chain-limit 0`, which allows for indefinite tool calls in an `llm` session (`llm`'s default is 5).
+### Recommended Options
+
+For interactive use, combine these flags:
+- `--ta` - Requires user confirmation before executing functions (safety)
+- `--chain-limit 0` - Allows unlimited tool calls in one session (default is 5)
 
 ## Development
 
-To install for development:
+### Setup Development Environment
+
+```bash
+# Clone and set up development environment
+git clone https://github.com/dannyob/llm-tools-patch
+cd llm-tools-patch
+make dev-setup
+source .venv/bin/activate
+```
+
+### Testing
 
 ```bash
-llm install -e .
+make test           # Run all tests
+make test-coverage  # Run tests with coverage report
+make quick-test     # Fast test run (exits on first failure)
 ```
 
-To run tests:
+### Plugin Testing
+
+After installation, verify the plugin is working:
 
 ```bash
-make test
+llm tools  # Should list Patch tools
+llm prompt "Read this README.md file" --tool Patch
 ```
 
 ## Credits and Thanks

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "llm-tools-patch"
-version = "0.1"
+version = "0.2"
 description = "LLM tools for reading, writing and changing text files"
 readme = "README.md"
 authors = [{name = "Danny O'Brien"}]