Getting Started

Getting Started

Get Hamster AI running on your PC in a few minutes.

Prerequisites

RequirementVersionNotes
Windows10 or 11 (64-bit)Required
Python3.11 or newerDownload from python.org. Tick "Add to PATH" during install.
OllamaLatestDownload from ollama.com. Must be running before launching Hamster AI.
GitAnyOptional — you can also download a ZIP from GitHub.
Tip Any Ollama model works. Smaller models (3B–7B parameters) use less RAM and respond faster. llama3.2:3b is a good starting point.

Installation

  1. Clone the repository

    git clone https://github.com/Easton99/hamster-ai.git
cd hamster-ai

    Or download the ZIP from GitHub and extract it.

  2. Create a virtual environment

    python -m venv .venv
.venv\Scripts\Activate.ps1
    Note If PowerShell blocks script execution, run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser first.

  3. Install dependencies

    pip install -r requirements.txt

  4. Pull an Ollama model

    ollama pull llama3.2:3b

    You can switch models later from the Settings window.

  5. Start Ollama

    ollama serve

    Keep this running in the background. You can configure Ollama to start with Windows so you don't have to remember.

  6. Launch Hamster AI

    python app/main.py

    A hamster icon will appear in your system tray.

First Run

After launching, Hamster AI greets you and is ready to chat. Here's how to get around:

ActionHow
Open chatDouble-click the tray icon, or press Ctrl+Shift+H
Open the menuRight-click the tray icon
Open settingsRight-click tray → Settings
Enable pluginsRight-click tray → Plugins
Quick commandsType /help in chat for the full list

Optional Dependencies

Some plugins need extra packages. Install only what you need:

# Voice output (text-to-speech)
pip install pyttsx3

# Audio awareness (detects if audio is playing)
pip install pycaw

# Extended system stats (GPU, disk, network)
pip install GPUtil pywin32 wmi

# Hardware awareness (USB, battery, monitors)
pip install pywin32 wmi

Start with Windows (Optional)

To have Hamster AI launch automatically when you log in, open Settings → General and enable Start with Windows. There's a configurable delay so it waits for your desktop to settle first.

Troubleshooting

ProblemFix
"Ollama is not running"Run ollama serve in a terminal and keep it open.
No models in model switcherPull a model: ollama pull llama3.2:3b
Tray icon doesn't appearCheck data/logs/hamster_ai.log for errors. Run Diagnostics from the tray menu.
Global hotkey not workingAnother app may have registered the same shortcut. Change it in Settings → General.
Plugin shows "failed to load"Open Diagnostics for details — usually a missing optional dependency.
PowerShell execution policy errorRun Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Explore Features Diagnostics