oai/README.md

oAI - OpenRouter AI Chat Client

A powerful, extensible terminal-based chat client for OpenRouter API with MCP (Model Context Protocol) support, enabling AI to access local files and query SQLite databases.

Features

Core Features

• 🤖 Interactive chat with 300+ AI models via OpenRouter
• 🔍 Model selection with search and filtering
• 💾 Conversation save/load/export (Markdown, JSON, HTML)
• 📎 File attachments (images, PDFs, code files)
• 💰 Real-time cost tracking and credit monitoring
• 🎨 Rich terminal UI with syntax highlighting
• 📝 Persistent command history with search (Ctrl+R)
• 🌐 Online mode (web search capabilities)
• 🧠 Conversation memory toggle

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: Install from Source (Recommended)

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

# Install with pip
pip install -e .

Option 2: Pre-built Binary (macOS/Linux)

Download from Releases:

• macOS (Apple Silicon): oai_v2.1.0_mac_arm64.zip
• Linux (x86_64): oai_v2.1.0_linux_x86_64.zip

# Extract and install
unzip oai_v2.1.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"

Quick Start

# Start the chat client
oai chat

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

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

Basic Commands

# In the chat interface:
/model              # Select AI model
/help               # Show all commands
/mcp on             # Enable file/database access
/stats              # View session statistics
exit                # 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 chat [OPTIONS]

Options:
  -m, --model TEXT    Model ID to use
  -s, --system TEXT   System prompt
  -o, --online        Enable online mode
  --mcp               Enable MCP server
  --help              Show help

Other commands:

oai config [setting] [value]  # Configure settings
oai version                   # Show version
oai credits                   # Check credits

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 interface
│   ├── 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
│   ├── ui/                # Terminal UI utilities
│   └── 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

v2.1.0 (Current)

• 🏗️ 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

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

---

⭐ Star this project if you find it useful!