Skip to content

maternion/MatOllama

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

30 Commits
 
 
 
 
 
 

Repository files navigation

⚑ MatOllama β€” Enhanced CLI for Local LLM

MatOllama is a powerful, feature-rich command-line interface for managing and interacting with local large language models through Ollama. Built for developers, researchers, and AI enthusiasts who demand speed, clarity, and robust functionality in their terminal workflows.

Professional terminal UX - Context-aware switching - Session persistence

image

✨ Key Features

🎯 Professional Terminal Experience

  • Rich UI Components: Beautiful tables, panels, progress bars, and color-coded output
  • Concurrent Operations: Multi-layer progress bars for model downloads/uploads with real-time speed & ETA
  • Adaptive Layouts: Dynamic table widths that adjust to terminal size and content length
  • Real-time Feedback: Streaming chat responses with first-token responsiveness
  • Intelligent Display: Handles "thinking" models with dimmed reasoning steps

πŸ”„ Advanced Model Management

  • Context-Aware Switching: Seamlessly switch between models while preserving conversation history
  • Comprehensive Operations: Pull, run, copy, rename, create, push, and remove models with confirmation prompts
  • Smart Selection: Interactive model picker with arrow key navigation
  • Resource Control: Unload models, monitor running processes, and manage GPU/CPU usage
  • Intelligent Deletion: Auto-refresh model list after deletions to prevent index confusion
  • Native Pass-through: Automatically passes unknown commands (like signin) to the official Ollama binary

πŸ’Ύ Session & Data Management

  • Persistent Sessions: Save/load conversations with metadata and version tracking
  • Export Capabilities: Export chats in JSON (for datasets) or text formats
  • Organized Storage: Automatic directory structure (Sessions/, Exports/, config.json)
  • Theme Persistence: Customizable color themes that survive restarts

πŸ›‘οΈ Robust Error Handling

  • Auto-Bootstrapping: Automatically manages virtual environments and installs dependencies
  • Graceful Interruption: Ctrl+C handling with context-aware responses
  • Input Blocking: Prevents commands during long operations (model copying/renaming)
  • Confirmation Dialogs: Safety prompts for destructive actions
  • Memory Management: Automatic model unloading before deletion to prevent failures

πŸ“¦ Installation

Prerequisites

  • Python 3.9+ (Check with python3 --version)
  • Ollama installed and running (Download Ollama)

Quick Install

  1. Clone the repository:

    git clone https://github.com/maternion/MatOllama.git
    cd MatOllama
  2. Run MatOllama:

    # The script is a self-contained installer. 
    # It will automatically create a venv, install dependencies, and run.
    ./MatOllama.py

    Note: Ensure the script is executable (chmod +x MatOllama.py)


πŸš€ Quick Start

1. Launch Ollama Server

ollama serve

2. Start MatOllama

./MatOllama.py

3. Pull and Run Your First Model

# Pull a model (now with concurrent download bars!)
pull qwen3

# Run by name or index
run qwen3
# or
run 1

# One-shot prompt
run qwen3 "Explain quantum computing in simple terms"

4. Interactive Chat

Once a model is loaded:

  • Type messages directly
  • Use /switch 2 to change models while preserving context
  • Use /unload to unload current model and exit chat mode
  • Use /exit to leave chat mode
  • Use stop or Ctrl+C to halt generation

🧰 Command Reference

Core Model Operations

Command Description Examples
list, ls Display all models with index, name, size, and modified date list, ls
select Interactive model picker with arrow keys select
pull <model> Download model from Ollama registry (multi-layer progress) pull codellama:7b
run <model|#> [prompt] Start chat session or execute single prompt run 2, run gpt-oss:20b "Hello"
show <model> Display detailed model information show qwen3:4b

Model Management

Command Description Examples
rm <model|#> Remove model (shows updated list after deletion) rm 3, rm old-model
copy <src> <dest> Duplicate model with new name copy llama3.1 my-llama
rename <old> <new> Rename model (copy + delete original) rename 1 better-name
create <name> [file] Create custom model from Modelfile create my-bot ./Modelfile
push <model|#> Upload model to registry (multi-layer progress) push my-model

System & Control

Command Description Examples
ps Show currently running models with resource usage ps
unload [model|#] Free model from memory unload, unload 2
stop Halt active generation stop
version Display CLI and Ollama version info version
* Unknown commands passed to Ollama binary signin, cp

Session & Configuration

Command Description Examples
save [filename] Save current session to Sessions/ save, save my-session
load <filename> Load session from Sessions/ load session_20250101.json
export [format] [file] Export conversation to Exports/ export json, export text chat.txt
theme [color] Set persistent theme color theme blue, theme
temp [0.0-2.0] Show/set temperature (persistent) temp 0.8, temp
system [prompt] Set system prompt for current session system "You are a helpful coding assistant"

Chat & History

Command Description Examples
history Display conversation with timestamps history
clear Clear conversation history (with confirmation) clear
help Show comprehensive command help help
exit, quit Exit application (prompts to save) exit

πŸ’¬ In-Chat Commands

When in chat mode (after running a model):

Command Description Examples
/switch <model|#> Switch models preserving context /switch 2, /switch gpt-4o
/unload Unload current model and exit chat mode /unload
/set verbose <true|false> Toggle detailed API debugging /set verbose true
/set think <true|false> Toggle thinking mode for reasoning models /set think false
/exit Exit chat mode, return to command mode /exit
/help Show in-chat help /help

🎨 Advanced Features

Context-Aware Model Switching

# Start conversation with one model
run qwen3:30b
> "Let's discuss machine learning basics"

# Switch to specialized model while keeping context
/switch qwen3-coder:30b
# Conversation history is preserved and transferred

Intelligent Model Deletion

# Remove models with automatic list refresh
rm 1
# βœ“ Model deleted
# Updated model list automatically displayed
# No more index confusion!

# Also works with model names
rm old-experimental-model

Enhanced Chat Mode Control

# In chat mode, cleanly exit and unload
/unload
# βœ“ Model unloaded, exited chat mode
# Memory freed, ready for next model

# Quick model switching with context
/switch 3
# βœ“ Previous conversation transferred to new model

Persistent Themes & Settings

# Set theme (survives restarts)
theme magenta

# Configure temperature (persistent)
temp 0.9

# Settings stored in config.json

Batch Operations & Automation

# Rename models efficiently
rename 1 production-model
rename 2 dev-model

# Export conversations in different formats
export json training-data.json
export text readable-chat.txt

Session Management Workflow

# Save current work
save important-research

# Load previous session
load important-research.json
# Restores: model, history, settings, theme

# Export for sharing
export text research-summary.txt

βš™οΈ Configuration

Command Line Options

./MatOllama.py --help

Options:
  --host TEXT          Ollama server URL (default: http://localhost:11434)
  --timeout FLOAT      Request timeout in seconds (default: 300.0)
  --version           Show version and exit

Configuration Files

MatOllama creates organized directories:

MatOllama/
β”œβ”€β”€ MatOllama.py          # Main script (Self-contained installer)
β”œβ”€β”€ config.json          # Persistent settings
β”œβ”€β”€ Sessions/            # Saved chat sessions
β”œβ”€β”€ Exports/             # Exported conversations
└── .ollama_history      # Command history

Environment Variables

# Custom Ollama host
export OLLAMA_HOST=http://192.168.1.100:11434

# Run with custom settings
./MatOllama.py --host $OLLAMA_HOST --timeout 600

🎯 Usage Examples

Research Workflow

# Pull research-focused model
pull deepseek-coder:33b

# Start research session
run deepseek-coder:33b

# Chat about complex topics, then switch for different perspective
/switch llama3.1:70b

# Save valuable conversation
save research-session-$(date +%Y%m%d)

# Export for sharing
export text research-summary.txt

Development Workflow

# Interactive model selection
select
# Use arrow keys to choose

# Quick code generation
run codellama "Write a Python function for binary search"

# Switch to general model for documentation
/switch llama3.1 
"Now write documentation for that function"

# Export as training data
export json code-examples.json

Model Management

# List all models with clear formatting
list
# or use shorthand
ls

# Clean up old models (with auto-refresh)
rm old-model-v1
rm 3  # Remove by index, shows updated list

# Create production copies
copy experimental-model production-v1
rename development-model staging-v2

# Monitor system resources
ps

# Clean unload when switching contexts
/unload  # In chat mode
unload unused-model  # In command mode

πŸ”§ Troubleshooting

Connection Issues

# Check Ollama server status
curl http://localhost:11434/api/version

# Test with custom host
./MatOllama.py --host http://localhost:11434

# Verify Ollama is running
ollama serve

Performance Issues

# Check running models
ps

# Unload unused models
unload old-model

# Clean exit from chat with unload
/unload  # Frees memory and exits chat

# Monitor during operations
run llama3 --verbose

Model Deletion Issues

# Models not deleting? They might be loaded
ps  # Check what's running
unload problematic-model  # Unload first
rm problematic-model     # Then delete

# Use the auto-refresh feature
rm 1  # Automatically shows updated list after deletion

Display Problems

# Terminal too narrow?
# Resize terminal - tables auto-adjust to width

# Color issues?
theme cyan  # Try different theme

# Text corruption?
clear  # Clear terminal buffer

# Table formatting issues?
ls  # New responsive tables adapt to terminal size

Model Issues

# Model not found?
pull missing-model

# Corrupted model?
rm problematic-model
pull problematic-model  # Re-download

# Out of memory?
/unload  # In chat mode - frees memory and exits
unload   # In command mode
ps       # Check what's running

🎯 Tips & Best Practices

Performance

  • Use /unload in chat mode to cleanly free memory and exit
  • Use unload command to free specific models from memory
  • Monitor with ps to track resource usage
  • Set appropriate temp values (0.7 default, 0.3 for factual, 1.2 for creative)

Workflow

  • Use select for visual model picking
  • Use ls as shorthand for list command
  • Save important sessions before switching models
  • Use /unload instead of /exit when you want to free model memory
  • Export conversations regularly for backup
  • Use /switch to compare model responses on same topic

Model Management

  • The rm command now shows updated model list automatically
  • Delete by name to avoid index confusion: rm old-model-name
  • Always check ps to see what's actually running
  • Use /unload in chat mode for clean memory management

Organization

  • Use descriptive names when saving sessions
  • Export training conversations as JSON
  • Keep Sessions/ organized by date or topic
  • Regular cleanup of old exports and models using improved rm command

πŸ™ Acknowledgments

Built with love for the Ollama community. MatOllama leverages:

MatOllama - Professional CLI for Local LLMs

⭐ Star this repo if MatOllama enhances your AI workflow!