Skip to content

Installation

Jump to bottom
Chris Schroedinger edited this page Jul 3, 2026 · 2 revisions

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

Alternative: .deb package

Prefer a system-wide install? Build and install the Debian package instead of running install.sh:

./build-deb.sh
sudo apt install ./dist/agentwhisper_*.deb

Python dependencies are installed into a private virtualenv during package configuration (one-time ~200 MB download). Remove with sudo apt remove agentwhisper. Use either the .deb or install.sh, not both.

Start at login

Once installed, enable autostart from the tray menu (Start at login) or:

agentwhisper autostart on    # or: off

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.

AgentWhisper

Repository · Changelog

Clone this wiki locally