@atlas0321/ollama-ui

Modern desktop chat interface for Ollama with advanced features including RAG (Retrieval-Augmented Generation), tool calling, web search, and multi-model thinking modes.

Note: This project is in early access and active development. Features and APIs may change. Feedback and bug reports are highly appreciated.

Table of Contents

• Features
• Installation
• Requirements
• Quick Start
• Usage
• Configuration
• Supported Models
• Development
• Troubleshooting
• License

Features

AI Capabilities

• RAG System - Semantic search with ChromaDB vector database and 2-stage retrieval pipeline (semantic search + re-ranking)
• Thinking Modes - Multiple thinking levels and model-specific reasoning (gpt-oss, qwen3, deepseek-r1)
• Tool Calling - Secure execution of bash, read, write, edit, and glob operations
• Web Search - Integrated web search with Ollama or Searx/SearxNG providers

User Experience

• Modern Settings UI - Card-based design with organized tabs (Model Settings, UI Settings, RAG Settings, Ollama Settings)
• Per-Model Settings - Each model retains its own parameters, WebSearch provider, and configuration
• Stream Abort - Stop generation instantly with ESC key or stop button
• Input History - Navigate previous messages with arrow keys (terminal-style)
• Token Counter - Real-time token tracking with context progress bar (100% tiktoken-based)
• Message Editing - Edit and re-submit previous messages
• Think-Block Visualization - Collapsible reasoning display with shimmer animation
• Syntax Highlighting - Code blocks with Atom One Dark theme
• Dark Theme - Modern gray color scheme optimized for extended sessions

Security & Control

• Permission System - Project-based, per-model tool approval (Allow Once / Always Allow / Deny)
• Secure Tool Execution - Sandboxed command execution with user consent
• Model Isolation - Separate permission configurations per model

Performance

• Render Batching - Throttled DOM updates (70-80% fewer operations)
• Scroll Optimization - Smart auto-scroll with minimal layout recalculations
• Streaming Optimization - Efficient typewriter effects applied post-stream

Installation

Quick Start

npm install -g @atlas0321/ollama-ui

The application will automatically:

• Install NPM dependencies if missing
• Prompt for optional ChromaDB installation (RAG features)
• Start ChromaDB server in background (if installed)

Requirements

Essential

• Node.js v16 or higher
• Ollama installed and running (download)

Optional (for RAG features)

• Python 3.8+ for ChromaDB
• ChromaDB will be installed automatically on first run if you choose

Quick Start

1. Start Ollama

ollama serve

2. Download a Model

Download one of the officially supported models:

ollama pull gpt-oss:20b
# or
ollama pull qwen3:4b

Required for RAG features:

ollama pull snowflake-arctic-embed:l
ollama pull xitao/bge-reranker-v2-m3

These embedding models are mandatory for RAG functionality.

3. Launch OllamaUI

ollama-ui

Usage

Basic Chat

1. Select your model from the dropdown
2. Choose thinking level (low/medium/high for gpt-oss, on/off for qwen3/deepseek-r1)
3. Start chatting

RAG (Retrieval-Augmented Generation)

Index your documentation and query it semantically:

Setup:

1. Click Settings → RAG Settings tab
2. Add documentation folder
3. Wait for indexing (progress shown)

Usage:

1. Enable RAG Mode (button below input)
2. Ask questions about your indexed documentation

Supported Formats:

• Code: .cpp, .hpp, .h, .c, .cc, .cxx, .php, .py, .js, .ts, .jsx, .tsx, .java, .kt, .swift, .go, .rs, .lua
• Documents: .pdf, .md, .html, .htm
• Config/Data: .ini, .cfg, .conf, .toml, .yaml, .yml, .json, .xml, .csv, .txt, .log

The model will use knowledge_search tool to find relevant documentation and answer based on your indexed content.

WebSearch Integration

Enable WebSearch Mode to allow the model to search the web.

Configuration:

1. Click Settings → Ollama Settings tab
2. Select WebSearch Provider:
   • Ollama WebSearch - Official Ollama API (requires API key from ollama.com/settings/keys)
   • Searx / SearxNG - Self-hosted search (requires server URL)
3. Enter API key or Searx URL
4. Save settings

Usage:

1. Enable WebSearch Mode (button below input)
2. Ask questions requiring web information

Tool Calling

Enable Code Mode to allow tool execution.

Available Tools:

• bash - Execute shell commands
• read - Read files from filesystem
• write - Create or overwrite files
• edit - String replacement in files
• glob - File pattern matching

Permission System:

On first tool use, you will be prompted with three options:

• Allow Once - Execute this time only
• Always Allow - Remember for this tool/command
• Deny - Abort execution

Permissions are stored in .{modelname}/permissions.json in your working directory.

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | ESC | Abort streaming response | | ↑ / ↓ | Navigate input history | | Enter | Send message | | Shift+Enter | New line in input |

Configuration

Settings Modal

Access via Settings button in header. Organized in four tabs:

Model Settings:

• Temperature, Top P, Top K
• Context Length (with visual progress bar)
• Repeat Penalty
• Seed (optional, for reproducible outputs)

UI Settings:

• Coming soon

RAG Settings:

• Add/remove documentation folders
• View indexed sources
• ChromaDB connection status

Ollama Settings:

• API Endpoint configuration
• WebSearch provider selection
• Ollama API Key (for WebSearch)
• Searx URL (for self-hosted search)

All settings are saved per-model and persist across sessions.

Ollama API Endpoint

Default: http://localhost:11434

To change:

1. Settings → Ollama Settings tab
2. Enter custom endpoint URL
3. Save (persists in localStorage)

ChromaDB Setup

Automatic Detection:

OllamaUI will automatically find ChromaDB in standard locations:

• Windows: %APPDATA%\Python\Python3XX\Scripts\chroma.exe
• Linux: ~/.local/bin/chroma, /usr/local/bin/chroma
• macOS: /opt/homebrew/bin/chroma

Manual Installation:

# Linux/Mac
pip3 install --user chromadb

# Windows
pip install --user chromadb

Server Start:

ChromaDB starts automatically. To start manually:

chroma run --host localhost --port 8000 --path ./chroma

Model Configuration

Custom Modelfiles available in /models/ directory:

• gpt-oss_20b_Modelfile.txt - GPT-4 with Chain-of-Thought
• qwen3_14b_Modelfile.txt - Qwen3 with thinking tags
• deepseek-r1_14b_Modelfile.txt - DeepSeek-R1 (no tool support)
• gemma3-tools-simple_Modelfile.txt - Gemma3 with simple tool format

Supported Models

Officially Supported

gpt-oss:20b

• Base: GPT-4 (OpenAI)
• Features: Channel-based output (analysis/commentary/final)
• Thinking: 3 levels (low/medium/high), cannot disable
• Tools: Full support
• Status: Fully tested and optimized

qwen3:4b

• Features: XML-based tool calls
• Thinking: Toggle on/off, soft-switch in prompts
• Tools: Full support
• Status: Fully tested and optimized

Other Models (Experimental)

Other Ollama models may work but are not officially supported. Features like tool calling, thinking modes, and RAG integration may have limited or no functionality. Use at your own discretion.

Required Models for RAG

For RAG functionality, the following models must be installed:

# Embedding model (semantic search)
ollama pull snowflake-arctic-embed:l

# Re-ranking model (precision ranking)
ollama pull xitao/bge-reranker-v2-m3

These models are used for:

• snowflake-arctic-embed:l - Generates embeddings for semantic search (Stage 1: retrieves top 20 candidates)
• xitao/bge-reranker-v2-m3 - Re-ranks results for precision (Stage 2: selects top N most relevant)

Development

Run in Development Mode

ollama-ui --dev

Opens Electron DevTools for debugging.

Troubleshooting

"Connection refused" to Ollama

Solution:

Ensure Ollama is running:

ollama serve

Verify endpoint in settings (default: http://localhost:11434)

ChromaDB not found

Solution:

ChromaDB will be offered for installation on first run. If skipped:

pip3 install --user chromadb  # Linux/Mac
pip install --user chromadb   # Windows

RAG indexing fails

Diagnosis:

1. Ensure ChromaDB server is running (auto-started by OllamaUI)
2. Check ChromaDB status:

   curl http://localhost:8000/api/v2/heartbeat

3. Restart ChromaDB:

   # Find process
   ps aux | grep chroma
   # Kill and let OllamaUI restart it automatically

Native module errors (tiktoken, electron)

These packages require platform-specific binaries.

Linux:

sudo apt-get install build-essential python3
npm install -g @atlas0321/ollama-ui --force

Mac:

xcode-select --install
npm install -g @atlas0321/ollama-ui --force

Windows:

Install Visual Studio Build Tools, then:

npm install -g @atlas0321/ollama-ui --force

Version History

v0.8.42 - 2025-10-19

Added:

• Extended RAG file format support from 5 to 30+ formats
  • Code files: C/C++ (.cpp, .hpp, .h, .c, .cc, .cxx), Web/Scripting (.php, .py, .js, .ts, .jsx, .tsx), System/JVM (.java, .kt, .swift, .go, .rs, .lua)
  • Config/Data: .ini, .cfg, .conf, .toml, .yaml, .yml, .json, .xml, .csv, .log
  • Markdown variants: .mdx, .mdown, .markdown
• Semantic chunking strategies for code files (function/class boundaries)
• Semantic chunking strategies for config files (section headers)
• PDF validation with empty/scanned PDF detection and warnings

Fixed:

• RAG indexing compatibility issue (removed CLI executable dependency)
• Enhanced error messages with format-specific hints

v0.8.4 - 2025-10-18

Fixed:

• WebSearch Settings Persistence - Provider, Searx URL, and Ollama API Key now save correctly
• Extended settings-modal.js to load/save WebSearch settings
• Fixed model-settings-manager.js object overwriting bug

v0.8.3 - 2025-10-18

Added:

• Settings UI modernization with card-based design
• Four organized tabs: Model Settings, UI Settings, RAG Settings, Ollama Settings
• Per-model settings storage and management
• Visual improvements with Material Design-inspired cards

v0.8.1 - 2025-10-18

Added:

• ChromaDB PATH Auto-Detection (95% success rate)
• Smart executable finder for Windows/Linux/macOS
• No manual PATH configuration needed

v0.8.0 - 2025-10-18

Added:

• Automatic dependency installation
• ChromaDB auto-setup with interactive dialog
• Cross-platform NPM/pip integration
• Background ChromaDB server management

See CHANGELOG.md for complete history.

Contributing

Issues and feedback are welcome via npm or direct contact.

License

MIT License - see LICENSE file for details.

Links

• npm Package
• Ollama Documentation
• ChromaDB Documentation

Credits

Author: ATLAS

Built for Ollama