Catch

Catch is a local Windows voice assistant built as a personal beta/testing project. It is not intended for public deployment or production use. The repository is public and open: clone it, fork it, modify it, and build on it for your own experiments.

Status and important quirks

• The working wake phrase is “Hey Jarvis.” The original idea was “Hey Catch” to match Catch/CatchAI, but the model actually trained and working in this beta is Jarvis.
• Catch uses local speech recognition and a local Ollama model for planning, with deterministic fast routes for common commands.
• Spotify playback control is experimental. Catalog search and desktop URI fallback work, while SpotAPI login/playback can depend on the Spotify account, client state, CAPTCHA, or upstream compatibility.
• Start-with-Windows exists in the tray menu, but its reliability still needs a final verification pass (including whether Ollama is already running or should be started at login).

What Catch can do

Applications, files, folders, and web

• Open and close applications discovered from configured executables, Start Menu entries, and packaged-app identifiers.
• Resolve fuzzy or ambiguous application names with numbered choices and remember confirmed aliases.
• Open allowlisted folders, validated direct URLs, Windows Search, and Google searches.
• Search configured Desktop, Documents, and Downloads folders by filename and open validated files.
• Answer application-inventory questions such as whether an app is installed and what browsers/apps are available.

Windows controls

• Lock the computer and put it to sleep.
• Restart or shut down the computer through a required confirmation flow.
• Open allowlisted Windows Settings pages.
• Enable/disable Wi-Fi and Bluetooth and toggle battery saver.
• Set or adjust display brightness where supported.
• Read and control master volume by default, or per-application volume when an application is named (for example, “turn up Spotify”).
• Play, pause, toggle, stop, skip, and go back in the active Windows media session.

Media and information

• Search and play Spotify tracks, including numbered disambiguation and follow-up selection by number, ordinal, or title.
• Search YouTube with Data API v3 and open results, including numbered disambiguation when multiple results are returned.
• Look up current weather for a spoken city or the saved profile location.
• Answer common “who/what is …?” factual requests with a fast Wikipedia lookup before falling back to the Ollama assistant.
• Report current CPU and RAM usage.
• Fetch cat or dog images and display them briefly in the floating UI.
• Return local time and date and support the configured profile name.

Voice experience

• Stream microphone audio, detect the wake word, and transcribe commands.
• Keep listening for follow-up commands for the configured timeout and interrupt an in-progress response when a new wake event is detected.
• Show idle/ready, listening, transcribing/thinking, executing, responding, and error states in the floating UI.
• Play one sound when entering ready-for-wake-word and another when entering listening; sounds are edge-triggered rather than repeated on UI refreshes.
• Review temporary files before deletion: show the discovered list, require confirmation, skip locked/undeletable files, and report what was skipped.

All LLM tool calls pass through the validated registry and Pydantic argument schemas. The model is not given arbitrary shell execution access.

Requirements

• Windows 10/11.
• Python 3.14 (the development environment currently uses Python 3.14).
• A working microphone and audio output.
• Ollama installed and running at the configured host, normally http://localhost:11434.
• The configured Ollama model, normally qwen3.5:0.8b.
• Git and a PowerShell or Command Prompt.

What is not stored in GitHub

These files are intentionally excluded by .gitignore and must be supplied or generated locally:

Item	Current measured size/nature	How to obtain it
dist/Catch.exe	163,456,867 bytes (generated executable)	Run build.bat after setup
build/	Generated PyInstaller analysis/package files; build/Catch/Catch.pkg was 163,111,267 bytes	Generated by build.bat
models/moonshine-tiny-en-int8/*.onnx	Four ONNX speech files totaling about 117 MB (encode, preprocess, cached_decode, uncached_decode)	Run download_moonshine.py; it downloads the official Sherpa/Moonshine archive
models/**/test_wavs/*.wav	Local test recordings, 212,044–534,924 bytes each	Optional; obtain the test fixtures separately if running those manual tests
.venv/, .venv-1/	Local Python virtual environments	Create locally with Python
__pycache__/, .pytest_cache/, coverage output	Generated interpreter/test files	Generated automatically
logs/*.log, data/*	Local logs, profile/history, and user data	Generated by Catch

The wake-word ONNX model is not stored in this repository either. The openwakeword package downloads/ships hey_jarvis_v0.1.onnx in the Python environment. Ollama models are stored and managed by Ollama itself, not in this project; install Ollama and run ollama pull qwen3.5:0.8b.

Small UI assets such as the WebM animations, MP3 transition sounds, and CatchAI_app_logo.png are kept in the repository.

Secrets

Catch reads secrets first from environment variables and then from:

%LOCALAPPDATA%\Catch\secrets.json

Copy secrets.example.json to that location and fill in only the values you need. The real secrets.json is ignored and must never be committed.

Name	Used for	Where to obtain it
SPOTIFY_TEST_EMAIL	Experimental SpotAPI login	Your Spotify account email
SPOTIFY_TEST_PASSWORD	Experimental SpotAPI login	Your Spotify account password
YOUTUBE_API_KEY	YouTube Data API v3 search	Google Cloud Console; enable YouTube Data API v3
OPENWEATHER_API_KEY	Current weather	OpenWeather account/API dashboard
CAT_API_KEY	Cat image requests	TheCatAPI account/API key

These are the complete get_secret() names currently used by the source. Never paste real credentials into source files, commits, issues, or logs.

Setup from source

1. Clone the repository:

   git clone https://github.com/putbullet/CatchAI.git
   cd CatchAI

2. Create and activate a Python 3.14 virtual environment:

   py -3.14 -m venv .venv
   .\.venv\Scripts\Activate.ps1

3. Install dependencies:

   python -m pip install --upgrade pip
   python -m pip install -r requirements.txt

4. Download the speech model:

   python download_moonshine.py

   The downloaded files are intentionally local and ignored by Git.

5. Install/start Ollama and pull the configured model Download Ollama from here:

   ollama pull qwen3.5:0.8b

   See other models supported by Ollama:

6. Copy secrets.example.json to %LOCALAPPDATA%\Catch\secrets.json and configure the required services.

7. Run from source:

   python main.py --tray

   Other useful modes are python main.py --listen, python main.py --voice, and python main.py --text "Hello Catch". Tray and packaged runs write diagnostics to %LOCALAPPDATA%\Catch\logs\catch.log.

Building the executable

build.bat uses the existing Catch.spec PyInstaller configuration. It requires .venv\Scripts\python.exe and the dependencies from requirements.txt. Run it from a Command Prompt, PowerShell, or by double-clicking it:

.\build.bat

The script removes the previous build/Catch and dist/Catch.exe, runs python -m PyInstaller --noconfirm --clean Catch.spec, and verifies that dist/Catch.exe exists. The spec bundles the YAML configuration, WebM animations, MP3 transition sounds, and openWakeWord package data. It does not embed the Moonshine weights; the frozen application expects them under %LOCALAPPDATA%\Catch\models and download_moonshine.py should be run before launching the executable. The script intentionally does not create a desktop shortcut.

Configuration and user data

Edit config.yaml to change the Ollama host/model, speech settings, wake-word threshold, listening timeouts, search roots, volume step, and image display duration. Catch stores profile, preferences, aliases, history, and logs below %LOCALAPPDATA%\Catch. User-specific data is ignored by Git.

Development and tests

Run the test suite with:

python -m pytest

Useful diagnostics and benchmarks include:

python diagnostics.py
python benchmark_runtime.py
python benchmark_latency.py --runs 10

Planned follow-up items

The executable now uses the bundled CatchAI_app_logo.ico, generated from CatchAI_app_logo.png, as its Windows application icon.

The Start-with-Windows flow still needs a final end-to-end verification, including reliably starting the executable and ensuring Ollama is already running or is started so Catch is ready immediately after login.

Contributing

Catch is an open-source beta project, and contributions are very welcome. If you clone or fork this repository and discover bugs, broken features, performance issues, or anything that can be improved, feel free to fix them and make Catch better for everyone.

You are also completely free to customize Catch for your own needs and use cases. Modify the interface, add new commands, improve existing features, experiment with different models, or adapt the assistant however you like.

If you find a problem, have an idea, or want to contribute directly, feel free to contact me at soulaimanettabaas@gmail.com.

A Note About Development

Catch is still actively under development and testing. This repository should be considered a beta, not a production-ready application intended for general users. Some features may be experimental, unstable, or require additional configuration, and breaking changes may happen as development continues.

The project was developed and delivered in a relatively short period of time, so GitHub Copilot in VS Code was used as part of the development process. For a project of this size and scope, using AI-assisted development tools is a normal part of the workflow and helped accelerate implementation, debugging, and iteration. The project was not produced through 100% manual typing, and that is intentional.

The goal is not to present Catch as a finished or perfect piece of software, but to share a working foundation that can be tested, improved, customized, and built upon by anyone interested in it.