Metadata-Version: 2.5
Name: hamster-agent
Version: 0.1.0
Summary: Hamster: a lightweight CLI software engineering agent powered by OpenRouter.
Project-URL: Homepage, https://github.com/TanushreeHarika/Hamster
Project-URL: Repository, https://github.com/TanushreeHarika/Hamster
Project-URL: Issues, https://github.com/TanushreeHarika/Hamster/issues
Author-email: Tanushree Harika Akkula <harika160406@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Tanushree Harika Akkula
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,ai,cli,coding-assistant,llm,openrouter,sandbox,software-engineering
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: duckduckgo-search>=6.3.0
Requires-Dist: requests>=2.32.0
Requires-Dist: rich>=13.9.0
Provides-Extra: auth
Requires-Dist: keyring>=25.0; extra == 'auth'
Provides-Extra: tiktoken
Requires-Dist: tiktoken>=0.7.0; extra == 'tiktoken'
Description-Content-Type: text/markdown

# 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:

| Tool | Description |
| :--- | :--- |
| `search_codebase(query)` | Conducts fast string searches across the sandbox workspace using `ripgrep` (`rg`). |
| `read_file(filepath, start_line, end_line)` | Safely reads project files by relative path with optional line-range slicing. |
| `edit_file_patch(filepath, target_text, replacement_text)` | Performs surgical replacements in file text (with exact and fuzzy whitespace-tolerant matching). |
| `write_file(filepath, content)` | Creates or overwrites a draft file, automatically scaffolding parent directories. |
| `web_search(query)` | Permission-gated DuckDuckGo search for technical documentation, APIs, and syntax lookup. |
| `run_sandbox_command(command)` | Executes pre-filtered shell commands in an isolated container or sandboxed environment. |

---

## 💻 Cross-Platform Prerequisites

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

### macOS
```bash
brew install ripgrep
```

### Linux (Ubuntu/Debian)
```bash
sudo apt update && sudo apt install ripgrep
```

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

---

## 🚀 Setup & Installation

Install Hamster globally using `uv` (recommended) or `pip`:

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

---

## ⚙️ Configuration

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

```bash
hamster set-key your_openrouter_api_key_here
```

You can optionally log in with Google to enable advanced features:
```bash
hamster login
```

---

## 🎮 Usage & Available Commands

Start the interactive CLI:
```bash
hamster
```

### Interactive CLI Commands

| Command | Description |
| :--- | :--- |
| `/help` | Show the command guide and tooling overview. |
| `/version` | Show Hamster version, model, and Python info. |
| `/files` | List files in the current draft. |
| `/search <query>` | Ask Hamster to search technical documentation. |
| `/pending` | Show pending draft changes. |
| `/apply` | Save pending draft changes to disk. |
| `/sync` | Refresh draft state from disk. |
| `/undo [N]` | Revert workspace N turns (default 1), keeps conversation log. |
| `/set-key <key>` | Set or rotate the OpenRouter API key. |
| `/login` | Log in with Google (OAuth 2.0 PKCE flow). |
| `/whoami` | Show the currently logged-in user. |
| `/logout` | Clear saved Google credentials. |
| `/clear` | Clear the terminal and redraw the splash. |
| `/exit` | Leave Hamster (prints farewell graphic). |

---

## 🛡️ 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:

```bash
uv run python -m unittest discover tests
```

---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.