Skip to content

develop-linux.md

Latest commit

 

History

History
116 lines (76 loc) · 3.92 KB

develop-linux.md

File metadata and controls

116 lines (76 loc) · 3.92 KB
Raw

Developing on Linux

Pre-requisites

You need Python 3.11.7 and some system dependencies to run Wingman AI Core. We recommend using pyenv to manage Python versions.

Debian / Ubuntu

sudo apt-get update
sudo apt-get install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
  libreadline-dev libsqlite3-dev wget curl llvm libncurses-dev \
  libffi-dev liblzma-dev tk-dev portaudio19-dev libsdl2-dev

Arch

sudo pacman -Syu --noconfirm base-devel openssl zlib bzip2 readline sqlite \
  wget curl llvm ncurses libffi xz tk portaudio sdl2

Fedora

sudo dnf install -y gcc make openssl-devel zlib-devel bzip2-devel \
  readline-devel sqlite-devel wget curl llvm ncurses-devel \
  libffi-devel xz-devel tk-devel portaudio-devel SDL2-devel

Install Python 3.11.7 with pyenv

curl https://pyenv.run | bash

Add the following to your ~/.bashrc or ~/.zshrc:

export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Restart the terminal, then:

pyenv install 3.11.7
pyenv global 3.11.7

Test with python --version.

Keyboard and mouse access

Wingman AI needs access to keyboard and mouse input events. Add your user to the input group:

sudo usermod -aG input $USER

Log out and back in for the group change to take effect.

Install dependencies

Fork and clone the repository, then start a terminal in the root folder.

python -m venv venv                 # create a virtual environment
source venv/bin/activate            # activate the virtual environment
pip install -r requirements.txt     # install dependencies

requirements.txt installs one package (pocket-tts) from GitHub, so Git must be installed.

Models

Models (Parakeet, Pocket TTS, Silero VAD and others) are downloaded by Core on first use into the models/ folder of the Wingman user data directory (~/.local/share/WingmanAI/models on Linux). If you already have a Wingman AI installation, the dev environment uses the same folder, so there is nothing to copy.

torch: CPU build (recommended)

On Linux, torch from PyPI is the CUDA build and pulls in about 4 GB of NVIDIA libraries. Wingman only needs torch for Pocket TTS, which runs on the CPU. The release build installs the CPU wheel before the requirements, and you can do the same:

pip install torch==2.8.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt

GPU speech recognition (Parakeet) does not use torch. It runs on onnxruntime-gpu with the CUDA 13 packages from requirements.txt.

Setup Visual Studio Code

Open the root folder in Visual Studio Code. It should automatically detect the virtual environment and suggest the correct Python interpreter. If not, open the command palette (Ctrl+Shift+P), run Python: Select Interpreter, and select the venv you created.

The repo includes recommended extensions in .vscode/extensions.json — install them when prompted.

Press F5 to launch main.py via the preconfigured debugger. The Wingman AI Core API server will start on 127.0.0.1:49111. Connect the Wingman AI client to use it.

If it doesn't start, verify that:

  • The virtual environment is selected as the Python interpreter
  • All dependencies are installed (pip install -r requirements.txt)
  • The integrated terminal is running from the repository root directory

Run the tests

pip install -r requirements-dev.txt
python -m pytest

Developing Skills

See the full Skills Developer Documentation for everything you need to know about creating skills — discovery metadata, the @tool decorator, hooks, custom properties, bundling dependencies, and distribution.

If you're building a major skill or integration, please reach out on Discord first to make sure it aligns with the project's direction.