Skip to content
BranchesTags

Repository files navigation

LLMTerm v2.0 — Local AI Terminal Assistant 🚀

Zero cloud · Zero telemetry · Runs 100% on your machine via Ollama

  ██╗     ██╗     ███╗   ███╗████████╗███████╗██████╗ ███╗   ███╗
  ██║     ██║     ████╗ ████║╚══██╔══╝██╔════╝██╔══██╗████╗ ████║
  ██║     ██║     ██╔████╔██║   ██║   █████╗  ██████╔╝██╔████╔██║
  ██║     ██║     ██║╚██╔╝██║   ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║
  ███████╗███████╗██║ ╚═╝ ██║   ██║   ███████╗██║  ██║██║ ╚═╝ ██║
  ╚══════╝╚══════╝╚═╝     ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝

LLMTerm is a privacy-first, offline-capable AI terminal assistant with voice support. Talk to your computer, get AI-powered code help, and manage your system — all without sending data to the cloud.

✨ Features

🎯 Core Features

  • 100% Local — All AI runs on your machine via Ollama
  • Zero Telemetry — No data leaves your computer
  • Voice Interface — Speak to your AI and hear responses
  • Web Search — AI searches the web when knowledge is outdated
  • Smart Command Execution — AI suggests and runs shell commands with your permission
  • Code Assistant — Write, fix, review, and explain code files
  • Session Management — Multiple chat sessions with history
  • Package Management — Install/update packages with AI help
  • Auto Error Fixing — AI diagnoses and fixes errors automatically

🔍 Web Search Features (NEW!)

  • Auto-Detection — LLMTerm suggests web search for current events, recent news, and live data
  • Smart Summarization — AI searches web and summarizes findings
  • DuckDuckGo Integration — Privacy-first search (no API key needed)
  • Raw Results — Option to view raw search results without AI summary

🎤 Voice Features (NEW!)

  • Text-to-Speech (TTS)

    • 🇮🇳 Indian English Neural Voices (Microsoft Edge TTS)
    • 🇺🇸 American & 🇬🇧 British English voices
    • 🔊 Multiple voice options with adjustable speed
    • 🔄 Automatic fallback: Edge-TTS → Google TTS → Offline

  • Speech-to-Text (STT)

    • 🎙️ Press Enter to activate voice input
    • 🧠 Offline AI (Faster Whisper) or Online (Google)
    • 🔇 VAD (Voice Activity Detection) for smart recording
    • 🎯 Indian English optimized

📦 Installation

Prerequisites

  1. Ollama — Install from ollama.com

    # Linux
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama
ollama serve

# Pull a model
ollama pull llama3.2

  2. Python 3.10+

    python3 --version  # Should be 3.10 or higher

Method 1: Arch Linux (Recommended)

# 1. Clone the repository
git clone https://github.com/yourusername/llmterm
cd llmterm

# 2. Install system dependencies
sudo pacman -S python python-pip ffmpeg mpv

# 3. Install Python packages
pip install -r requirements.txt --break-system-packages

# 4. Install LLMTerm
bash scripts/install-arch.sh

Method 2: Debian/Ubuntu

# 1. Clone the repository
git clone https://github.com/yourusername/llmterm
cd llmterm

# 2. Install system dependencies
sudo apt update
sudo apt install -y python3 python3-pip ffmpeg mpv

# 3. Install Python packages
pip install -r requirements.txt --break-system-packages

# 4. Manual install
mkdir -p ~/.local/lib ~/.local/bin ~/.config/llmterm/sessions
cp -r llmterm ~/.local/lib/
cat > ~/.local/bin/llmterm << 'EOF'
#!/usr/bin/env bash
export PYTHONPATH="$HOME/.local/lib:$PYTHONPATH"
exec python3 -m llmterm "$@"
EOF
chmod +x ~/.local/bin/llmterm
export PATH="$HOME/.local/bin:$PATH"

Method 3: Termux (Android)

# 1. Update Termux
pkg update && pkg upgrade

# 2. Clone repository
git clone https://github.com/yourusername/llmterm
cd llmterm

# 3. Install dependencies
pkg install -y python ffmpeg mpv

# 4. Install Python packages
pip install -r requirements.txt

# 5. Install LLMTerm
bash scripts/install-termux.sh

Method 4: macOS

# 1. Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Clone repository
git clone https://github.com/yourusername/llmterm
cd llmterm

# 3. Install dependencies
brew install python ffmpeg mpv

# 4. Install Python packages
pip install -r requirements.txt

# 5. Manual install (same as Debian/Ubuntu method above)

🎤 Voice Setup

Step 1: Enable Voice Features

# Start LLMTerm
llmterm

# Inside LLMTerm:
voice setup    # Shows installation commands
voice on       # Enable TTS (AI speaks)
mic on         # Enable STT (voice input)

Step 2: Test Voice

# Test text-to-speech
voice test

# Test microphone (press Enter, then speak)
mic test

# Or just press Enter to activate voice input anytime

Step 3: Customize Voice

# List available voices
voice

# Change voice (Indian female by default)
voice voice in_female     # Indian female — warm, clear
voice voice in_male       # Indian male — clear
voice voice us_female     # US female — warm
voice voice uk_male       # British male

# Adjust speaking speed
voice speed +20    # 20% faster
voice speed -15    # 15% slower
voice speed 0      # Normal speed

🚀 Usage

Basic Chat

# Start LLMTerm
llmterm

# Ask anything
What's the difference between TCP and UDP?

# Voice input: Just press Enter and speak!
<press Enter>
🎤 Listening... (speak: "How do I check disk space?")

Package Management

install neofetch          # Smart install (auto-detects pacman/apt/pip/npm)
update                    # Update all packages
search docker             # Search for packages

Web Search

# Smart search: AI searches web and summarizes
search web latest AI developments
search web current weather in Pune
search web who won yesterday's cricket match

# Raw search results (no AI summary)
/web Arch Linux news

# Auto-detection: LLMTerm suggests web search
What's the latest Python version?
💡 This might need web search. Try: search web What's the latest Python version?

Code & File Tools

/write calculator.py      # AI writes a calculator script
/fixfile mycode.py        # AI fixes all errors in a file
/runfile script.sh        # Run file, auto-fix if errors occur
/explain complex.cpp      # AI explains what the code does
/review api.js            # Full code review (bugs, security, performance)
/edit config.json         # Describe changes, AI edits the file
/diff oldfile.py          # AI suggests improvements as colored diff

Error Debugging

# Paste an error message
/fix
# Then paste error → AI diagnoses and provides fix

# Run command and auto-analyze failures
/run python3 broken.py

Chat Sessions

/new project-x            # Start new chat with name
/chats                    # List all sessions
/chat switch 2            # Switch to session 2
/chat clear               # Clear current chat
/chat delete 3            # Delete session 3
/chat copy 1              # Duplicate session 1
/chat export              # Export chat to .txt
/chat rename 2 debugging  # Rename session 2

Settings & Configuration

model                     # List installed models
model llama3.2:1b         # Switch to faster model
ctx 1024                  # Set context window (smaller = faster)
safe on                   # Require confirmation before running commands
safe off                  # Auto-run commands (use carefully!)
config                    # Show all settings
sysinfo                   # Display system info (CPU, RAM, GPU, disk)
theme dark                # Change theme

⚡ Speed Optimization

Model speed depends on hardware and context window:

# Inside llmterm — adjust context window
ctx 512      # Fastest (mobile/weak CPU)
ctx 1024     # Fast (Termux default)
ctx 2048     # Balanced (desktop default)
ctx 4096     # Smarter but slower

Recommended Models by Hardware

Model Size Speed Best For
qwen2:0.5b 300MB ⚡⚡⚡ Basic tasks, Termux
llama3.2:1b 700MB ⚡⚡⚡ General use, mobile
phi3:mini 2GB ⚡⚡ Smarter reasoning
llama3.2 2GB ⚡⚡ Recommended desktop
qwen2.5-coder 4GB ⚡ Coding tasks 
# Pull and switch to faster model
ollama pull llama3.2:1b
model llama3.2:1b

🔧 Troubleshooting

Voice Not Working?

  1. TTS (Speaking) Issues

    # Check if voice is enabled
voice

# Test audio playback
mpv /path/to/test.mp3

# Re-install TTS backend
pip install edge-tts --break-system-packages --force-reinstall

# Check ffmpeg
ffmpeg -version

  2. STT (Microphone) Issues

    # Test microphone access
arecord -l  # Linux: list audio devices

# Check sounddevice
python3 -c "import sounddevice; print(sounddevice.query_devices())"

# Re-install STT backend
pip install faster-whisper sounddevice --break-system-packages --force-reinstall

# Check mic permissions (Linux)
groups | grep audio  # Should show 'audio' group

# Add yourself to audio group if missing
sudo usermod -aG audio $USER
# Then logout and login again

  3. No Audio Output?

    # Install missing audio player
sudo pacman -S mpv ffmpeg  # Arch
sudo apt install mpv ffmpeg  # Debian/Ubuntu

# Test speaker
speaker-test -t wav -c 2

Ollama Connection Issues

# Check if Ollama is running
curl http://localhost:11434/api/version

# Start Ollama
ollama serve

# Check models
ollama list

Python Package Issues

# Clear pip cache and reinstall
pip cache purge
pip install -r requirements.txt --break-system-packages --force-reinstall

Permission Denied Errors

# Make sure llmterm is executable
chmod +x ~/.local/bin/llmterm

# Add to PATH if needed
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

📁 Project Structure

llmterm/
├── llmterm/
│   ├── __init__.py        # Package metadata
│   ├── __main__.py        # Entry point (python3 -m llmterm)
│   ├── app.py             # Main REPL + command router
│   ├── colors.py          # ANSI colors and theme system
│   ├── config.py          # Config load/save/detect
│   ├── file_tools.py      # File operations: /write /fix /explain etc.
│   ├── ollama_client.py   # Ollama HTTP API client
│   ├── packages.py        # Package manager (pacman/apt/pip/npm)
│   ├── prompt.py          # System prompt builder
│   ├── renderer.py        # Stream renderer + spinner
│   ├── session.py         # Chat history + session manager
│   ├── ui.py              # Banner, help, model list, sysinfo
│   ├── voice.py           # TTS/STT voice manager
│   └── web_search.py      # Web search integration (NEW!)
├── scripts/
│   ├── install-arch.sh    # Arch Linux installer
│   └── install-termux.sh  # Termux (Android) installer
├── requirements.txt       # Python dependencies
└── README.md              # This file

🎯 Command Reference

Voice Commands

Command Description
voice Show voice status and available voices
voice on Enable text-to-speech
voice off Disable text-to-speech
voice test Test TTS with sample text
voice setup Show installation instructions
voice voice <n> Change voice (e.g., voice voice in_male)
voice speed <±n> Adjust speed (e.g., voice speed +15)
mic on Enable speech-to-text
mic off Disable speech-to-text
mic test Test microphone input
<Enter> Activate voice input (when STT enabled)

Package Management

Command Description
install <pkg> Smart install — auto-detects pacman/yay/pip/npm
update Update all system packages
search <pkg> Search package repositories

Web Search (NEW!)

Command Description
search web <query> Search web + AI summarizes results
/web <query> Show raw web search results (no AI)
Auto-detect LLMTerm suggests web search for current events

Code & File Tools

Command Description
/write <file> AI writes a new file from your description
/fixfile <file> AI reads, diagnoses, and fixes all errors
/runfile <file> Run file — auto-fix errors with AI
/explain <file> AI explains what a file does
/review <file> Full code review: bugs, security, performance
/edit <file> Describe a change — AI edits the file
/diff <file> AI suggests improvements as a colored diff

Error & Debug

Command Description
/fix Paste an error → AI diagnoses and fixes
/run <cmd> Run command — AI analyzes failure if it occurs

Chat Sessions

Command Description
/new [name] Start a fresh chat session
/chats List all saved sessions
/chat switch <n> Switch to session n
/chat clear Wipe messages in current session
/chat delete <n> Delete session n
/chat copy <n> Duplicate session n
/chat export [n] Export session to .txt
/chat rename <n> name Rename session n
/clear Clear current chat
history Show recent chat history

Settings

Command Description
model List installed models
model <n> Switch active model
ctx <n> Set context window (smaller = faster)
safe on|off Toggle command confirmation
config Show current configuration
sysinfo Display system info (CPU, RAM, GPU, disk)
theme List available themes
theme <n> Change theme (dark/light/ocean/forest)
help Show help message
exit Quit LLMTerm

🔐 Privacy & Data Storage

All data stays on your machine:

  • Config: ~/.config/llmterm/config.json
  • Sessions: ~/.config/llmterm/sessions/*.jsonl
  • Voice models: ~/.config/llmterm/vosk-model/ (if using Vosk)
  • No network calls except to:
    • localhost:11434 (Ollama)
    • Optional: Edge TTS / Google TTS (only when voice is enabled)
    • Optional: Google STT (only when using Google backend)

Note: Voice features can work 100% offline if you use:

  • TTS: pyttsx3 or kokoro (offline backends)
  • STT: faster-whisper or vosk (offline backends)

🛠️ Requirements

System Requirements

  • OS: Linux (Arch, Debian, Ubuntu, Termux), macOS
  • Python: 3.10 or higher
  • Ollama: Latest version running locally
  • Audio: ffmpeg, mpv (for voice features)

Python Dependencies

See requirements.txt for complete list. Key packages:

  • Voice (TTS): edge-tts, gTTS, pyttsx3
  • Voice (STT): faster-whisper, SpeechRecognition, vosk
  • Audio: sounddevice, soundfile, numpy

Note: Core LLMTerm functionality works with zero pip dependencies (pure stdlib), but voice features require additional packages.

🤝 Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

📜 License

MIT License — See LICENSE file for details

🙏 Acknowledgments

  • Ollama — Local LLM runtime
  • Edge TTS — Microsoft Neural voices
  • Faster Whisper — Accurate offline STT
  • LLMTerm Community — For feedback and contributions

📞 Support

  • Issues: GitHub Issues
  • Documentation: This README
  • In-app help: Type help inside LLMTerm

👨‍💻 Creator

Pratik Khumkar

Computer Science Engineer

Passionate about AI, Web Development, Cybersecurity, and building privacy-first developer tools.

Made with ❤️ for the command line

About

Privacy-first local AI terminal assistant with voice support, web search, smart coding tools, and Ollama integration.

Topics

aiautomationchatbotclidevelolinuxllmoffline-aiollamapythonterminalvoice-assistantweb-search

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages