Hamster

Hamster is a lightweight, high-performance Command Line Interface (CLI) software engineering agent. Utilizing the OpenRouter API framework, Hamster drafts changes in an isolated temporary sandbox, presenting rich terminal previews and allowing you to accept or discard all changes at the end of each task.

🌟 Key Features

• Isolated Draft Workspace: All reads, writes, and command executions target a temporary sandbox (/tmp/hamster-sandbox-<uuid>/). The real project directory is touched only when you explicitly approve changes at task completion.
• Cross-Platform Compatibility: Fully compatible with macOS, Linux, and Windows (CMD, PowerShell, Git Bash, WSL2).
• APFS Fast-Cloning: On macOS, utilizes APFS copy-on-write (cp -c) for instant (<10ms) sandbox instantiation without physically duplicating file contents.
• Ephemeral Docker Sandbox Backend: Command execution delegates to an ephemeral, network-isolated Docker container (--network=none, --memory=256m, --cpus=1) when Docker is present, falling back seamlessly to host process execution.
• Two-Stage Planning → Execution Engine: Automatically detects structured planning responses from the model and injects an execution prompt before invoking tools.
• Persistent LSP Integration: Integrates a persistent JSON-RPC 2.0 language server daemon (pyright-langserver) for real-time code diagnostics and definition resolution.
• Windowed File Reading & Fuzzy Patching: Supports line-range slicing (start_line, end_line) for reading large files, and trailing-whitespace-tolerant fuzzy diff matching for edits.
• Token Budget Context Compactor: Built-in context compaction using tiktoken BPE token estimation (cl100k_base) to maximize context retention without overflowing model limits.
• Strict Security Policy: Path containment checks prevent sandbox escaping, combined with regex command filtering and strict binary allowlists (git, python, pytest, npm, etc.).

🛠️ Tooling Overview

Hamster exposes six permission-gated tools to the AI model:

💻 Cross-Platform Prerequisites

Hamster requires Python 3.11+ and ripgrep (rg) on system PATH.

macOS

brew install ripgrep

Linux (Ubuntu/Debian)

sudo apt update && sudo apt install ripgrep

Windows

winget install BurntSushi.ripgrep.MSVC
# Or via Chocolatey: choco install ripgrep

🚀 Setup & Installation

Install Hamster globally using uv (recommended) or pip:

uv tool install hamster-agent
# OR
pip install hamster-agent

⚙️ Configuration

Set up your OpenRouter API key using the built-in command:

hamster set-key your_openrouter_api_key_here

You can optionally log in with Google to enable advanced features:

hamster login

🎮 Usage & Available Commands

Start the interactive CLI:

hamster

Interactive CLI Commands

🛡️ Security Measures

Hamster implements strict defense-in-depth security:

• Path Canonicalization: Resolves relative paths against the active sandbox root using os.path.realpath, rejecting any breakout attempts (../../.env).
• Binary Allowlisting & Command Filtering: Blocks dangerous commands (sudo, rm, chmod, chown, curl-to-shell pipes) while validating commands against an allowed binary matrix.
• 3-Way Conflict Detection: Prevents overwriting external host edits when applying drafted changes.

🧪 Running Tests

Hamster includes a full unit test suite covering sandbox lifecycle, isolation, fuzzy patching, and policy analysis:

uv run python -m unittest discover tests

📄 License

MIT License. See LICENSE for details.