Installation

Installation

Requirements

• Linux with X11 (not Wayland) — built and tested on Debian/Ubuntu with XFCE; any Debian-family desktop should work
• Python 3.11+ (your distro's regular Python)
• A microphone
• System packages for the tray icon, typing, clipboard, and notifications:

sudo apt install python3-gi python3-gi-cairo gir1.2-ayatanaappindicator3-0.1 \
                 xclip xdotool libnotify-bin

Not sure whether you're on X11? echo $XDG_SESSION_TYPE must print x11.

Install

Everything installs into your home directory — no root needed beyond the apt line above.

git clone https://github.com/ChrisSchroedinger/agentwhisper.git
cd agentwhisper

# uv (fast Python package manager) — once, if you don't have it:
curl -LsSf https://astral.sh/uv/install.sh | sh

./install.sh

The installer:

1. creates a private Python environment (based on your system Python, so the tray's GTK bindings work),
2. installs the Python dependencies,
3. adds AgentWhisper to your applications menu (Utility category),
4. puts the agentwhisper and agentwhisperd commands on your PATH,
5. warns you clearly if any system tool is missing.

It is safe to re-run at any time.

First run

Start AgentWhisper from the menu. The speech model (~140 MB for the default base.en) downloads automatically in the background — once, into the shared cache at ~/.cache/huggingface/. Until it finishes, dictations wait. Check progress:

agentwhisper status     # engine: loading  →  engine: ready

Updating

cd agentwhisper
git pull
./install.sh            # re-run; picks up new dependencies if any
agentwhisper quit       # then start it again from the menu

Uninstall

./uninstall.sh          # removes app, menu entry, launchers, environment
./uninstall.sh --purge  # additionally removes your settings and logs

The downloaded speech models in ~/.cache/huggingface/ are left alone (other tools may share them); delete them manually if you want the disk space back.