oai/README.md

# oAI - Open AI Chat Client

A powerful, modern **Textual TUI** chat client with **multi-provider support** (OpenRouter, Anthropic, OpenAI, Ollama) and **MCP (Model Context Protocol)** integration, enabling AI to access local files and query SQLite databases.

## Features

### Core Features
- 🖥️ **Modern Textual TUI** with async streaming and beautiful interface
- 🔄 **Multi-Provider Support** - OpenRouter, Anthropic (Claude), OpenAI (ChatGPT), Ollama (local)
- 🤖 Interactive chat with 300+ AI models across providers
- 🔍 Model selection with search, filtering, and capability icons
- 💾 Conversation save/load/export (Markdown, JSON, HTML)
- 📎 File attachments (images, PDFs, code files)
- 💰 Real-time cost tracking and credit monitoring (OpenRouter)
- 🎨 Dark theme with syntax highlighting and Markdown rendering
- 📝 Command history navigation (Up/Down arrows)
- 🌐 **Universal Online Mode** - Web search for ALL providers:
  - **Anthropic Native** - Built-in search with automatic citations ($0.01/search)
  - **DuckDuckGo** - Free web scraping (all providers)
  - **Google Custom Search** - Premium search option
- 🧠 Conversation memory toggle
- ⌨️ Keyboard shortcuts (F1=Help, F2=Models, Ctrl+S=Stats)

### MCP Integration
- 🔧 **File Mode**: AI can read, search, and list local files
  - Automatic .gitignore filtering
  - Virtual environment exclusion
  - Large file handling (auto-truncates >50KB)

- ✍️ **Write Mode**: AI can modify files with permission
  - Create, edit, delete files
  - Move, copy, organize files
  - Always requires explicit opt-in

- 🗄️ **Database Mode**: AI can query SQLite databases
  - Read-only access (safe)
  - Schema inspection
  - Full SQL query support

## Requirements

- Python 3.10-3.13
- API key for your chosen provider:
  - **OpenRouter**: [openrouter.ai](https://openrouter.ai)
  - **Anthropic**: [console.anthropic.com](https://console.anthropic.com)
  - **OpenAI**: [platform.openai.com](https://platform.openai.com)
  - **Ollama**: No API key needed (local server)

## Installation

### Option 1: Pre-built Binary (macOS/Linux) (Recommended)

Download from [Releases](https://gitlab.pm/rune/oai/releases):
- **macOS (Apple Silicon)**: `oai_v3.0.0_mac_arm64.zip`
- **Linux (x86_64)**: `oai_v3.0.0_linux_x86_64.zip`

```bash
# Extract and install
unzip oai_v3.0.0_*.zip
mkdir -p ~/.local/bin
mv oai ~/.local/bin/

# macOS only: Remove quarantine and approve
xattr -cr ~/.local/bin/oai
# Then right-click oai in Finder → Open With → Terminal → Click "Open"
```

### Add to PATH

```bash
# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"
```


### Option 2: Install from Source

```bash
# Clone the repository
git clone https://gitlab.pm/rune/oai.git
cd oai

# Install with pip
pip install -e .
```


## Quick Start

```bash
# Start oAI (launches TUI)
oai

# Start with specific provider
oai --provider anthropic
oai --provider openai
oai --provider ollama

# Or with options
oai --provider openrouter --model gpt-4o --online --mcp

# Show version
oai version
```

On first run, you'll be prompted for your API key. Configure additional providers anytime with `/config`.

### Enable Web Search (All Providers)

```bash
# Using Anthropic native search (best quality, automatic citations)
/config search_provider anthropic_native
/online on

# Using free DuckDuckGo (works with all providers)
/config search_provider duckduckgo
/online on

# Using Google Custom Search (requires API key)
/config search_provider google
/config google_api_key YOUR_KEY
/config google_search_engine_id YOUR_ID
/online on
```

### Basic Commands

```bash
# In the TUI interface:
/provider           # Show current provider or switch
/provider anthropic # Switch to Anthropic (Claude)
/provider openai    # Switch to OpenAI (ChatGPT)
/provider ollama    # Switch to Ollama (local)
/model              # Select AI model (or press F2)
/online on          # Enable web search
/help               # Show all commands (or press F1)
/mcp on             # Enable file/database access
/stats              # View session statistics (or press Ctrl+S)
/config             # View configuration settings
/credits            # Check account credits (shows API balance or console link)
Ctrl+Q              # Quit
```

## Web Search

oAI provides universal web search capabilities for all AI providers with three options:

### Anthropic Native Search (Recommended for Anthropic)

Anthropic's built-in web search API with automatic citations:

```bash
/config search_provider anthropic_native
/online on

# Now ask questions requiring current information
What are the latest developments in quantum computing?
```

**Features:**
- ✅ **Automatic citations** - Claude cites its sources
- ✅ **Smart searching** - Claude decides when to search
- ✅ **Progressive searches** - Multiple searches for complex queries
- ✅ **Best quality** - Professional-grade results

**Pricing:** $10 per 1,000 searches ($0.01 per search) + token costs

**Note:** Only works with Anthropic provider (Claude models)

### DuckDuckGo Search (Default - Free)

Free web scraping that works with ALL providers:

```bash
/config search_provider duckduckgo  # Default
/online on

# Works with Anthropic, OpenAI, Ollama, and OpenRouter
```

**Features:**
- ✅ **Free** - No API key or costs
- ✅ **Universal** - Works with all providers
- ✅ **Privacy-friendly** - Uses DuckDuckGo

### Google Custom Search (Premium Option)

Google's Custom Search API for high-quality results:

```bash
/config search_provider google
/config google_api_key YOUR_GOOGLE_API_KEY
/config google_search_engine_id YOUR_SEARCH_ENGINE_ID
/online on
```

Get your API key: [Google Custom Search API](https://developers.google.com/custom-search/v1/overview)

## MCP (Model Context Protocol)

MCP allows the AI to interact with your local files and databases.

### File Access

```bash
/mcp on                    # Enable MCP
/mcp add ~/Projects        # Grant access to folder
/mcp list                  # View allowed folders

# Now ask the AI:
"List all Python files in Projects"
"Read and explain main.py"
"Search for files containing 'TODO'"
```

### Write Mode

```bash
/mcp write on              # Enable file modifications

# AI can now:
"Create a new file called utils.py"
"Edit config.json and update the API URL"
"Delete the old backup files"  # Always asks for confirmation
```

### Database Mode

```bash
/mcp add db ~/app/data.db  # Add database
/mcp db 1                  # Switch to database mode

# Ask the AI:
"Show all tables"
"Find users created this month"
"What's the schema for the orders table?"
```

## Command Reference

### Chat Commands
| Command | Description |
|---------|-------------|
| `/help [cmd]` | Show help |
| `/model [search]` | Select model |
| `/info [model]` | Model details |
| `/memory on\|off` | Toggle context |
| `/online on\|off` | Toggle web search |
| `/retry` | Resend last message |
| `/clear` | Clear screen |

### MCP Commands
| Command | Description |
|---------|-------------|
| `/mcp on\|off` | Enable/disable MCP |
| `/mcp status` | Show MCP status |
| `/mcp add <path>` | Add folder |
| `/mcp add db <path>` | Add database |
| `/mcp list` | List folders |
| `/mcp db list` | List databases |
| `/mcp db <n>` | Switch to database |
| `/mcp files` | Switch to file mode |
| `/mcp write on\|off` | Toggle write mode |

### Conversation Commands
| Command | Description |
|---------|-------------|
| `/save <name>` | Save conversation |
| `/load <name>` | Load conversation |
| `/list` | List saved conversations |
| `/delete <name>` | Delete conversation |
| `/export md\|json\|html <file>` | Export |

### Configuration
| Command | Description |
|---------|-------------|
| `/config` | View settings |
| `/config provider <name>` | Set default provider |
| `/config openrouter_api_key` | Set OpenRouter API key |
| `/config anthropic_api_key` | Set Anthropic API key |
| `/config openai_api_key` | Set OpenAI API key |
| `/config ollama_base_url` | Set Ollama server URL |
| `/config search_provider <provider>` | Set search provider (anthropic_native/duckduckgo/google) |
| `/config google_api_key` | Set Google API key (for Google search) |
| `/config online on\|off` | Set default online mode |
| `/config model <id>` | Set default model |
| `/config stream on\|off` | Toggle streaming |
| `/stats` | Session statistics |
| `/credits` | Check credits (OpenRouter) |

## CLI Options

```bash
oai [OPTIONS]

Options:
  -p, --provider TEXT Provider to use (openrouter/anthropic/openai/ollama)
  -m, --model TEXT    Model ID to use
  -s, --system TEXT   System prompt
  -o, --online        Enable online mode (OpenRouter only)
  --mcp               Enable MCP server
  -v, --version       Show version
  --help              Show help
```

Commands:
```bash
oai              # Launch TUI (default)
oai version      # Show version information
oai --help       # Show help message
```

## Configuration

Configuration is stored in `~/.config/oai/`:

| File | Purpose |
|------|---------|
| `oai_config.db` | Settings, conversations, MCP config |
| `oai.log` | Application logs |
| `history.txt` | Command history |

## Project Structure

```
oai/
├── oai/
│   ├── __init__.py
│   ├── __main__.py        # Entry point for python -m oai
│   ├── cli.py             # Main CLI entry point
│   ├── constants.py       # Configuration constants
│   ├── commands/          # Slash command handlers
│   ├── config/            # Settings and database
│   ├── core/              # Chat client and session
│   ├── mcp/               # MCP server and tools
│   ├── providers/         # AI provider abstraction
│   ├── tui/               # Textual TUI interface
│   │   ├── app.py         # Main TUI application
│   │   ├── widgets/       # Custom widgets
│   │   ├── screens/       # Modal screens
│   │   └── styles.tcss    # TUI styling
│   └── utils/             # Logging, export, etc.
├── pyproject.toml         # Package configuration
├── build.sh               # Binary build script
└── README.md
```

## Troubleshooting

### macOS Binary Issues

```bash
# Remove quarantine attribute
xattr -cr ~/.local/bin/oai

# Then in Finder: right-click oai → Open With → Terminal → Click "Open"
# After this, oai works from any terminal
```

### MCP Not Working

```bash
# Check if model supports function calling
/info  # Look for "tools" in supported parameters

# Check MCP status
/mcp status

# View logs
tail -f ~/.config/oai/oai.log
```

### Import Errors

```bash
# Reinstall package
pip install -e . --force-reinstall
```

## Version History

### v3.0.0-b3 (Current - Beta 3)
- 🔄 **Multi-Provider Support** - OpenRouter, Anthropic (Claude), OpenAI (ChatGPT), Ollama (local)
- 🔌 **Provider Switching** - Switch between providers mid-session with `/provider`
- 🧠 **Provider Model Memory** - Remembers last used model per provider
- ⚙️ **Provider Configuration** - Separate API keys for each provider
- 🌐 **Universal Web Search** - Three search options for all providers:
  - **Anthropic Native** - Built-in search with citations ($0.01/search)
  - **DuckDuckGo** - Free web scraping (default)
  - **Google Custom Search** - Premium option
- 🎨 **Enhanced Header** - Shows current provider and model
- 📊 **Updated Config Screen** - Shows provider-specific settings
- 🔧 **Command Dropdown** - Added `/provider` commands for discoverability
- 🎯 **Auto-Scrolling** - Chat window auto-scrolls during streaming responses
- 🎨 **Refined UI** - Thinner scrollbar, cleaner styling
- 🔧 **Updated Models** - Claude 4.5 (Sonnet, Haiku, Opus)

### v3.0.0 (Beta)
- 🎨 **Complete migration to Textual TUI** - Modern async terminal interface
- 🗑️ **Removed CLI interface** - TUI-only for cleaner codebase (11.6% smaller)
- 🖱️ **Modal screens** - Help, stats, config, credits, model selector
- ⌨️ **Keyboard shortcuts** - F1 (help), F2 (models), Ctrl+S (stats), etc.
- 🎯 **Capability indicators** - Visual icons for model features (vision, tools, online)
- 🎨 **Consistent dark theme** - Professional styling throughout
- 📊 **Enhanced model selector** - Search, filter, capability columns
- 🚀 **Default command** - Just run `oai` to launch TUI
- 🧹 **Code cleanup** - Removed 1,300+ lines of CLI code

### v2.1.0
- 🏗️ Complete codebase refactoring to modular package structure
- 🔌 Extensible provider architecture for adding new AI providers
- 📦 Proper Python packaging with pyproject.toml
- ✨ MCP integration (file access, write mode, database queries)
- 🔧 Command registry pattern for slash commands
- 📊 Improved cost tracking and session statistics

### v1.9.x
- Single-file implementation
- Core chat functionality
- File attachments
- Conversation management

## License

MIT License - See [LICENSE](LICENSE) for details.

## Author

**Rune Olsen**
- Project: https://iurl.no/oai
- Repository: https://gitlab.pm/rune/oai

## Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

---

**⭐ Star this project if you find it useful!**