Metadata-Version: 2.4
Name: ollama-remote-chat-cli
Version: 0.1.2
Summary: Remote CLI client for Ollama servers - Network-ready chat interface with history tracking and inference control
Home-page: https://github.com/Avaxerrr/ollama-remote-chat-cli
Author: Avaxerrr
Author-email: Avaxerrr@users.noreply.github.com
License: MIT
Project-URL: Bug Tracker, https://github.com/Avaxerrr/ollama-remote-chat-cli/issues
Project-URL: Source Code, https://github.com/Avaxerrr/ollama-remote-chat-cli
Project-URL: Documentation, https://github.com/Avaxerrr/ollama-remote-chat-cli#readme
Keywords: ollama,chat,cli,remote,llm,ai,terminal,client,network
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: wcwidth>=0.2.5
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Ollama Remote Chat CLI

[![PyPI version](https://img.shields.io/pypi/v/ollama-remote-chat-cli.svg)](https://pypi.org/project/ollama-remote-chat-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)

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

<img width="1180" height="845" alt="ollama-cli" src="https://github.com/user-attachments/assets/875d3ab0-a030-4c23-b7c0-6d7023bb4808" />

## Quick Start

### Installation

Install directly from PyPI:

```bash
pip install ollama-remote-chat-cli
```

Run the client:

```bash
orc
```

Or use the full command:

```bash
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

```bash
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:

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

**Setup:**
1. Install Ollama from [ollama.ai](https://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:

```env
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](https://support.apple.com/kb/DL999)
   - **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:

```env
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:

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

**Docker setup:**
```bash
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:

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

Or find Windows IP from WSL:
```bash
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:**
```bash
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:**
```bash
ping your-hostname.local
# If fails, use IP address instead
```

**4. Check Ollama binding:**
```bash
# Ensure Ollama is listening on all interfaces
OLLAMA_HOST=0.0.0.0 ollama serve
```

### "Model not found"

```bash
# List available models on server
ollama list

# Pull a model
ollama pull llama2
```

### "Module not found" or Import Errors

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

### Command not found: `orc`

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

**Mac/Linux:**
```bash
# 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:

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

---

## Alternative Installation Methods

### From Source (Development)

```bash
# 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

```bash
# Using Nuitka build script
python nuitka_build.py

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

---

## Updating

To get the latest version:

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

Check your current version:

```bash
pip show ollama-remote-chat-cli
```

Or inside the app:
```bash
orc
# Then type: /version
```

---

## Development

### Running from source:
```bash
git clone https://github.com/Avaxerrr/ollama-remote-chat-cli.git
cd ollama-remote-chat-cli
pip install -e .
orc
```

### Running tests:
```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests (when available)
pytest
```

---

## License

MIT License - see [LICENSE](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/](https://pypi.org/project/ollama-remote-chat-cli/)
- **GitHub**: [https://github.com/Avaxerrr/ollama-remote-chat-cli](https://github.com/Avaxerrr/ollama-remote-chat-cli)
- **Issues**: [https://github.com/Avaxerrr/ollama-remote-chat-cli/issues](https://github.com/Avaxerrr/ollama-remote-chat-cli/issues)
- **Changelog**: [CHANGELOG.md](CHANGELOG.md) - View release history and version updates
- **Ollama**: [https://ollama.ai](https://ollama.ai)

---

## Acknowledgments

- Built for [Ollama](https://ollama.ai)
- Inspired by modern CLI tools
- Community contributions welcome

---

## Support

Having issues? Here's how to get help:

1. Check the [Troubleshooting](#troubleshooting) section
2. Search [existing issues](https://github.com/Avaxerrr/ollama-remote-chat-cli/issues)
3. Open a [new issue](https://github.com/Avaxerrr/ollama-remote-chat-cli/issues/new) with:
   - Your OS and Python version
   - Error messages
   - Steps to reproduce
