Skip to main content

​
Quick diagnostic

Run these three commands to diagnose most issues: 
# 1. Is Augent installed?
augent --version

# 2. Is the MCP server working?
augent-mcp <<< '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# 3. Is FFmpeg available?
ffmpeg -version
If step 1 fails, see command not found. If step 2 fails, see MCP not connecting. If step 3 fails, see FFmpeg missing.

​
Install issues

​
Command not found after install

Symptom: augent: command not found or augent-mcp: command not found Fix: The installer adds ~/.local/bin to your PATH via your shell rc file. Either restart your terminal or run: 
source ~/.zshrc    # macOS
source ~/.bashrc   # Linux
If it still fails, check that the binary exists: 
ls ~/.local/bin/augent
If it doesn’t exist, reinstall: 
curl -fsSL https://augent.app/install.sh | bash

​
pip installed to wrong Python

Symptom: augent runs but imports fail, or ModuleNotFoundError for faster_whisper, sentence_transformers, etc. Fix: This happens when python3 resolves to a different version than the one pip installed to. Check which Python is being used: 
which python3
python3 -c "import augent; print(augent.__file__)"
If they point to different Python installations, reinstall to the correct one: 
python3 -m pip install augent[all]

​
MCP issues

​
MCP server not connecting

Symptom: /mcp in Claude Code doesn’t show Augent, or shows it as disconnected. Fix: Check the MCP registration: 
claude mcp list
If Augent isn’t listed, register it: 
claude mcp add augent -s user -- augent-mcp
Then restart Claude Code. If it’s listed but disconnected, test the server directly: 
augent-mcp <<< '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
You should see a JSON response with protocolVersion. If you get an error, check the install issues section.

​
Transcription issues

​
Transcription fails

Symptom: Error mentioning FFmpeg, or transcription hangs/crashes. Fix: Augent requires FFmpeg for audio processing: 
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Fedora
sudo dnf install ffmpeg

​
Model download slow on first run

Symptom: First transcription takes a long time before producing output. This is normal. The Whisper model downloads on first use (~75MB for tiny, larger for other sizes). Subsequent runs use the cached model. The sentence-transformer model (~80MB) also downloads on first semantic search.

​
Download issues

​
Download fails or hangs

Symptom: download_audio returns an error or hangs indefinitely. Fix: Check that yt-dlp is installed and up to date: 
yt-dlp --version
brew upgrade yt-dlp    # macOS
pip install -U yt-dlp  # or via pip
Some sites require authentication or have rate limits. If a specific URL fails, try it directly: 
yt-dlp --print filename "URL"

​
aria2c not found (slower downloads)

Symptom: Downloads work but are slow. Fix: aria2c enables 16 parallel connections. Install it: 
# macOS
brew install aria2

# Ubuntu/Debian
sudo apt install aria2

​
Feature-specific issues

​
Speaker identification fails

Symptom: identify_speakers returns an import error. Fix: Speaker diarization requires pyannote-audio and pre-downloaded models: 
pip install augent[speakers]
The models (~29MB) should have been downloaded by the installer. If they’re missing, reinstall: 
curl -fsSL https://augent.app/install.sh | bash

​
Text-to-speech fails

Symptom: text_to_speech returns an import error or fails silently. Fix: 
pip install augent[tts]
brew install espeak-ng    # macOS — required by Kokoro

​
Source separation fails

Symptom: separate_audio returns an import error. Fix: 
pip install augent[separator]
This installs Demucs and PyTorch. It’s a large download (~2GB for PyTorch).

​
Deep search / chapters not working

Symptom: deep_search or chapters returns an import error. Fix: 
pip install augent[semantic]
This installs sentence-transformers (~80MB model downloaded on first use).

​
Still stuck?

  1. Check GitHub Issues for known problems
  2. Ask in Discord
  3. Enterprise support: support@augent.app