ollama-remote-chat-cli 0.1.2

Remote CLI client for Ollama servers - Network-ready chat interface with history tracking and inference control

Ollama Remote Chat CLI

A network-ready command-line chat client for Ollama servers. Connect to local or remote Ollama instances from any machine on your network.

Quick Start

Installation

Install directly from PyPI:

pip install ollama-remote-chat-cli

Run the client:

orc

Or use the full command:

ollama-remote-chat-cli

First Run Setup

The first time you run orc, a setup wizard will guide you through:

1. Configuring your Ollama server URL
2. Selecting your preferred model
3. Setting up your preferences

orc
# Follow the interactive setup wizard

---

Features

• 🌐 Network-ready - Connect to local or remote Ollama servers
• 🎨 Retro terminal UI - Clean, colorful command-line interface with dynamic spinner messages
• 🧹 Smart screen clearing - /clear and /new preserve header while clearing chat history
• 🎨 Rich markdown rendering - Beautiful syntax highlighting and formatting
• 🧠 Thinking process support - See how reasoning models think (DeepSeek R1, QwQ, etc.)
• 📝 Chat history - Session management with search functionality
• ⚙️ Inference control - Configurable temperature, top_p, context window, and more
• 📊 Real-time metrics - Token usage, thinking metrics, and generation speed
• 🔄 Model management - Easy switching, pulling, and deletion of models
• 🔍 History search - Search through past conversations
• 💻 System monitoring - View running models and memory usage
• 🔒 Secure configuration - Environment-based settings with .env support

---

Requirements

• Python 3.7 or higher
• Ollama server (local or remote)
• Required packages: requests, python-dotenv, wcwidth, rich

---

Connection Methods

Method 1: Local Connection (Default)

Ollama running on the same machine:

OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama2

Setup:

1. Install Ollama from ollama.ai
2. Run: ollama serve
3. Pull a model: ollama pull llama2

---

Method 2: Hostname Connection (.local / mDNS)

Connect to another computer on your local network:

OLLAMA_HOST=http://my-computer.local:11434
OLLAMA_MODEL=llama3.3

Setup:

1. Find your server's hostname:

   • Windows: hostname in CMD
   • Mac: System Preferences → Sharing → Computer Name
   • Linux: hostname in terminal

2. Ensure mDNS/Bonjour is enabled:

   • Windows: Install Bonjour Print Services
   • Mac/Linux: Built-in support

3. Test: ping my-computer.local

4. Configure firewall to allow port 11434

---

Method 3: Static IP Address

For computers with fixed network IPs:

OLLAMA_HOST=http://192.168.1.100:11434
OLLAMA_MODEL=mistral

Setup:

1. Set static IP on your Ollama server

2. Find IP address:

   • Windows: ipconfig
   • Mac: ifconfig en0 | grep inet
   • Linux: ip addr show

3. Configure firewall to allow port 11434

---

Method 4: Docker

Ollama running in a Docker container:

OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama2

Docker setup:

docker run -d -p 11434:11434 --name ollama ollama/ollama
docker exec -it ollama ollama pull llama2

---

Method 5: WSL (Windows Subsystem for Linux)

Accessing Windows Ollama host from WSL:

OLLAMA_HOST=http://host.docker.internal:11434
OLLAMA_MODEL=llama2

Or find Windows IP from WSL:

ip route | grep default | awk '{print $3}'

---

Available Commands

Command	Description
/help	Show all available commands
/multi	Enter multi-line input mode
/clear	Clear conversation context
/new	Start a new chat session
/exit	Exit the chat
Model Management
/models	List available models
/switch	Switch to a different model
/pull	Download a new model
/delete	Delete a model
/create	Create custom model from Modelfile
/modelinfo	Show detailed model information
Generation
/generate	Generate raw completion without chat context
Configuration
/config	Show current configuration
/settings	Configure inference settings
/host	Change Ollama host URL
History
/history	View chat history
/search	Search chat history
/showthinking	View thinking from last AI response
System Monitoring
/version	Show Ollama server version
/ps	List running models (memory usage)
/ping	Test connection latency to server

---

Inference Settings

Fine-tune AI behavior with the /settings command:

Temperature (0.0-2.0) - Controls response creativity

• 0.1-0.3: Precise (coding, math, facts)
• 0.6-0.8: Balanced (general chat)
• 1.0-1.5: Creative (writing, brainstorming)

Top P (0.0-1.0) - Nucleus sampling threshold (default: 0.9)

Top K (1-100) - Limits token choices (default: 40)

Context Window (128-32768) - Conversation memory in tokens (default: 2048)

Max Output (1-4096) - Maximum response length (default: 512)

Repeat Penalty (0.0-2.0) - Reduces repetition (default: 1.1)

---

Advanced Features

Thinking Process Visualization

For reasoning models like DeepSeek R1, QwQ, and others that use chain-of-thought:

• Hidden by default: Thinking process is hidden during streaming for cleaner output
• View thinking: Use /showthinking to see the AI's reasoning after response
• Live thinking: Enable in /settings to watch the model think in real-time
• Saved in history: Thinking is automatically saved for later review

Settings control:

• show_thinking_live - Display thinking as it happens (default: false)
• save_thinking - Save thinking to chat history (default: true)

Rich Markdown Rendering

AI responses are automatically formatted with:

• Syntax highlighting for code blocks
• Styled headers and emphasis (bold, italic)
• Formatted lists and blockquotes
• Colored output optimized for all terminals

Toggle in /settings:

• use_markdown - Enable/disable Rich rendering (default: true)

System Monitoring

/ps command shows:

• Currently loaded models in memory
• VRAM usage per model
• Model expiration times
• Total memory consumption

Useful for:

• Monitoring resource usage
• Debugging slow responses
• Managing multiple models

---

Remote Access & Performance Metrics

Optimized for remote server usage with transparent diagnostics:

• Live timing: Spinner shows elapsed time during processing (e.g., "Thinking... 4.2s")
• TTFT tracking: Measures Time To First Token for responsiveness analysis
• Connection testing: /ping command with color-coded latency status
  • 🟢 Excellent: <100ms (LAN/local)
  • 🟡 Good: 100-300ms (fast remote)
  • 🔴 Slow: >800ms (high latency)
• Detailed metrics: Two-line performance breakdown
  • Line 1: Total time, first token time, generation speed
  • Line 2: Context size, input/output tokens, thinking words

Perfect for Tailscale/VPN setups - Metrics help diagnose whether slowness is from network or model processing.

Example output:

Total: 6.3s | First token: 4.1s | Speed: 23.0 tok/s
Context: 2048 tokens | Input: 15 | Output: 118

---

Use Cases

Home Network Setup

• Powerful Desktop/Server: Runs Ollama with GPU acceleration
• Laptop/Weak PC: Runs orc client, connects remotely
• Benefit: Use AI from any device without local GPU

Development Environment

• Server: Dedicated AI inference machine
• Workstation: Lightweight client for coding assistance
• Benefit: Consistent model across team

Multi-Device Access

• Gaming PC: Hosts Ollama when not gaming
• Any Device: Connect from laptop, tablet, or work PC
• Benefit: Centralized AI without duplicate models

---

Troubleshooting

"Could not connect to Ollama"

1. Verify Ollama is running:

curl http://localhost:11434
# Should return: "Ollama is running"

2. Check firewall:

• Windows: Allow port 11434 in Windows Firewall
• Mac: System Preferences → Security → Firewall
• Linux: sudo ufw allow 11434

3. Test hostname resolution:

ping your-hostname.local
# If fails, use IP address instead

4. Check Ollama binding:

# Ensure Ollama is listening on all interfaces
OLLAMA_HOST=0.0.0.0 ollama serve

"Model not found"

# List available models on server
ollama list

# Pull a model
ollama pull llama2

"Module not found" or Import Errors

# Reinstall the package
pip install --upgrade --force-reinstall ollama-remote-chat-cli

Command not found: orc

Windows:

# Add Python Scripts to PATH
# Location: C:\Users\YourName\AppData\Local\Programs\Python\Python3XX\Scripts

Mac/Linux:

# Ensure pip install location is in PATH
export PATH="$HOME/.local/bin:$PATH"

# Add to ~/.bashrc or ~/.zshrc to make permanent

---

Configuration Files

Config location: ~/.ollama_chat_config.json

History location: ~/.ollama_chat_history.json

These are created automatically on first run.

Manual configuration: Create a .env file in your home directory:

OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama2
TEMPERATURE=0.8
TOP_P=0.9

---

Alternative Installation Methods

From Source (Development)

# Clone the repository
git clone https://github.com/Avaxerrr/ollama-remote-chat-cli.git
cd ollama-remote-chat-cli

# Install in editable mode
pip install -e .

# Run it
orc

Building Standalone Executable

# Using Nuitka build script
python nuitka_build.py

# Follow the interactive menu
# Creates portable .exe or binary

---

Updating

To get the latest version:

pip install --upgrade ollama-remote-chat-cli

Check your current version:

pip show ollama-remote-chat-cli

Or inside the app:

orc
# Then type: /version

---

Development

Running from source:

git clone https://github.com/Avaxerrr/ollama-remote-chat-cli.git
cd ollama-remote-chat-cli
pip install -e .
orc

Running tests:

# Install dev dependencies
pip install -e ".[dev]"

# Run tests (when available)
pytest

---

License

MIT License - see LICENSE file for details.

Copyright © 2026 Avaxerrr

Permission is hereby granted, free of charge, to use, modify, and distribute this software.

---

Links

• PyPI: https://pypi.org/project/ollama-remote-chat-cli/
• GitHub: https://github.com/Avaxerrr/ollama-remote-chat-cli
• Issues: https://github.com/Avaxerrr/ollama-remote-chat-cli/issues
• Changelog: CHANGELOG.md - View release history and version updates
• Ollama: https://ollama.ai

---

Acknowledgments

• Built for Ollama
• Inspired by modern CLI tools
• Community contributions welcome

---

Support

Having issues? Here's how to get help:

1. Check the Troubleshooting section
2. Search existing issues
3. Open a new issue with:
   • Your OS and Python version
   • Error messages
   • Steps to reproduce