diff --git a/README.md b/README.md index 2dd455f..1a0b3d3 100644 --- a/README.md +++ b/README.md @@ -2,31 +2,14 @@ An AI-powered coding assistant built as a .NET 10.0 console application, featuring the **Hashline** technique for safe, precise file editing. -## What is Hashline? - -AnchorCli's unique approach to file editing. Every line returned by file tools is prefixed with a content-derived hash anchor: - -``` -1:a3| function hello() { -2:f1| return "world"; -3:0e| } -``` - -When editing, you reference these `line:hash` anchors instead of reproducing old content. Before any mutation, both the line number **and** hash are validated — stale anchors are rejected immediately. - -This eliminates: -- Whitespace/indentation reproduction errors -- Silent edits to the wrong line in large files -- Entire-file rewrites just to change one line - ## Features - **Batch Editing**: Apply multiple replace/delete operations atomically in a single pass without line drift - **Interactive REPL**: Chat with an AI model to edit files, manage directories, and execute commands -- **Slash Commands**: `/setup`, `/help`, `/exit`, `/clear`, `/status`, `/compact`, `/reset` +- **Slash Commands**: `/setup`, `/help`, `/exit`, `/clear`, `/status`, `/compact`, `/reset`, `/load`, `/save` - **Token Tracking**: Real-time token usage and cost per response, plus session totals - **Model Pricing Display**: Shows current model pricing from OpenRouter in the header -- **Context Compaction**: Automatic conversation history compression when approaching context limits, including stale tool result compaction +- **Context Compaction**: Automatic conversation history compression when approaching context limits - **Comprehensive Toolset**: 15 tools for file operations, editing, directory management, and command execution - **AOT-Ready**: Native AOT compilation for ~12 MB binaries with no .NET runtime dependency - **Rich CLI**: Beautiful terminal output using Spectre.Console with tables, rules, and colored text @@ -34,12 +17,14 @@ This eliminates: - **OpenAI-Compatible**: Works with any OpenAI-compatible API (OpenAI, Ollama, Cerebras, Groq, OpenRouter, etc.) - **Ctrl+C Support**: Cancel in-progress responses without exiting -## Requirements +## Installation + +### Requirements - .NET 10 SDK - `clang` (for native AOT publish on Linux) -## Quick Start +### Quick Start ```bash # Run the application @@ -47,11 +32,10 @@ dotnet run --project AnchorCli # First time? The app will prompt you to run /setup # Or run it explicitly: -dotnet run --project AnchorCli /setup ``` -## Native AOT Build +### Native AOT Build ```bash dotnet publish AnchorCli -r linux-x64 -c Release @@ -60,94 +44,17 @@ dotnet publish AnchorCli -r linux-x64 -c Release The resulting binary is ~12 MB, has no .NET runtime dependency, and starts instantly. -## Slash Commands - -| Command | Description | -|---|---| -| `/setup` | Run interactive TUI to configure API key and model (also accessible via `anchor setup` subcommand) | -| `/help` | Show available tools and commands | -| `/exit` | Exit the application | -| `/clear` | Clear the conversation history | -| `/status` | Show session token usage and cost | -| `/compact` | Manually trigger context compaction | -| `/reset` | Clear session and reset token tracker | -| `/load` | Load a previous session from disk | -| `/save` | Save current session to disk | -## Available Tools - -**File Operations:** -- `read_file` - Read a file (or a window) with Hashline-tagged lines -- `grep_file` - Search a file by regex — results are pre-tagged for immediate editing -- `grep_recursive` - Search for a regex pattern across all files in a directory tree -- `find_files` - Search for files matching glob patterns -- `get_file_info` - Get detailed file information (size, permissions, etc.) - -**Edit Operations:** -- `replace_lines` - Replace a range identified by `line:hash` anchors -- `insert_after` - Insert lines after an anchor -- `delete_range` - Delete a range between two anchors -- `create_file` - Create a new file with optional initial content -- `delete_file` - Delete a file permanently -- `rename_file` - Rename or move a file -- `copy_file` - Copy a file to a new location -- `append_to_file` - Append lines to the end of a file -- `batch_edit` - Apply multiple replace/delete operations atomically in a single call - -**Directory Operations:** -- `list_dir` - List directory contents -- `create_dir` - Create a new directory (with parent directories) -- `rename_dir` - Rename or move a directory -- `delete_dir` - Delete a directory and all its contents - -**Command Execution:** -- `execute_command` - Run shell commands (with user approval) - -``` -AnchorCli/ -├── Program.cs # Entry point + CLI parsing -├── ReplLoop.cs # Main REPL loop with streaming, spinners, and cancellation -├── ChatSession.cs # AI chat client wrapper with message history -├── ToolRegistry.cs # Centralized tool registration and dispatch -├── AnchorConfig.cs # JSON file-based configuration (~APPDATA~/anchor/config.json) -├── ContextCompactor.cs # Conversation history compression -├── AppJsonContext.cs # Source-generated JSON context (AOT) -├── SetupTui.cs # Interactive setup TUI -├── Hashline/ -│ ├── HashlineEncoder.cs # Adler-8 + position-seed hashing -│ └── HashlineValidator.cs # Anchor resolution + validation -├── Tools/ -│ ├── FileTools.cs # read_file, grep_file, grep_recursive, find_files, get_file_info -│ ├── EditTools.cs # replace_lines, insert_after, delete_range, create/delete/rename/copy/append -│ ├── DirTools.cs # list_dir, create_dir, rename_dir, delete_dir -│ └── CommandTool.cs # execute_command -├── Commands/ -│ ├── ICommand.cs # Command interface -│ ├── CommandRegistry.cs # Command registration -│ ├── CommandDispatcher.cs # Command dispatch logic -│ ├── ExitCommand.cs # /exit command -│ ├── HelpCommand.cs # /help command -│ ├── ClearCommand.cs # /clear command -│ ├── StatusCommand.cs # /status command -│ ├── CompactCommand.cs # /compact command -│ ├── ResetCommand.cs # /reset command -│ ├── SetupCommand.cs # /setup command -└── OpenRouter/ - └── PricingProvider.cs # Fetch model pricing from OpenRouter -``` - -## How It Works +## Usage 1. **Setup**: Configure API credentials via the `/setup` command (or `anchor setup` subcommand) -2. **REPL Loop**: You interact with the AI through a conversational interface -3. **Tool Calling**: The AI can call any of the available tools to read/edit files, manage directories, or execute commands -4. **Hashline Validation**: All file edits are validated using the Hashline technique to ensure precision -5. **Token Tracking**: Responses show token usage and cost; session totals are maintained -6. **Context Compaction**: When approaching context limits, conversation history is automatically compressed -7. **Safe Execution**: Commands require explicit user approval before running +2. **REPL Loop**: Interact with the AI through a conversational interface +3. **Tool Calling**: The AI can call tools to read/edit files, manage directories, or execute commands +4. **Safe Execution**: Commands require explicit user approval before running -## Supported Models +### Supported Models + +AnchorCli works with any OpenAI-compatible API endpoint: -AnchorCli works with any OpenAI-compatible API endpoint, including: - OpenAI (gpt-4o, gpt-4.1, etc.) - Ollama (local models) - Cerebras @@ -155,6 +62,22 @@ AnchorCli works with any OpenAI-compatible API endpoint, including: - OpenRouter (qwen3.5-27b, etc.) - Any custom OpenAI-compatible server +## Configuration + +Configuration is stored in `~APPDATA~/anchor/config.json` on Windows or `~/.anchor/config.json` on Linux/macOS. + +Use the `/setup` command or run `anchor setup` from the command line to configure: + +- API Key +- API Endpoint (default: OpenRouter) +- Model selection + +## Documentation + +- [**Available Tools**](docs/TOOLS.md) - Complete list of all tools organized by category +- [**Hashline Technique**](docs/HASHLINE.md) - Detailed explanation of Hashline editing with examples +- [**Slash Commands**](docs/COMMANDS.md) - All available slash commands with descriptions + ## License MIT License - See LICENSE file for details.