oai/README.md

# oAI - OpenRouter AI Chat Client

A powerful, modern **Textual TUI** chat client for OpenRouter API with **MCP (Model Context Protocol)** support, enabling AI to access local files and query SQLite databases.

## Features

### Core Features
- 🖥️ **Modern Textual TUI** with async streaming and beautiful interface
- 🤖 Interactive chat with 300+ AI models via OpenRouter
- 🔍 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
- 🎨 Dark theme with syntax highlighting and Markdown rendering
- 📝 Command history navigation (Up/Down arrows)
- 🌐 Online mode (web search capabilities)
- 🧠 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
- OpenRouter API key ([get one here](https://openrouter.ai))

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

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

# Show version
oai version
```

On first run, you'll be prompted for your OpenRouter API key.

### Basic Commands

```bash
# In the TUI interface:
/model              # Select AI model (or press F2)
/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
Ctrl+Q              # Quit
```

## 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 api` | Set API key |
| `/config model <id>` | Set default model |
| `/config stream on\|off` | Toggle streaming |
| `/stats` | Session statistics |
| `/credits` | Check credits |

## CLI Options

```bash
oai [OPTIONS]

Options:
  -m, --model TEXT    Model ID to use
  -s, --system TEXT   System prompt
  -o, --online        Enable online mode
  --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 (Current)
- 🎨 **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!**