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)

Installation

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

Download from Releases:

macOS (Apple Silicon): oai_v3.0.0_mac_arm64.zip
Linux (x86_64): oai_v3.0.0_linux_x86_64.zip

# 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

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

Option 2: Install from Source

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

# Install with pip
pip install -e .

Quick Start

# 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

# 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

/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

/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

/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

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:

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

# 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

# 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

# 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 for details.

Author

Rune Olsen

Project: https://iurl.no/oai
Repository: https://gitlab.pm/rune/oai

Contributing

Fork the repository
Create a feature branch
Submit a pull request

⭐ Star this project if you find it useful!