oAI - OpenRouter CLI App

Overview

oAI is a powerful command-line interface that brings AI models directly to your terminal with advanced capabilities. Beyond simple chat, oAI now features MCP (Model Context Protocol) integration, allowing AI agents to access your local files and query SQLite databases securely - all from the comfort of your command line.

Whether you're debugging code, analyzing data, exploring databases, or just chatting with AI, oAI provides a rich, interactive experience with full conversation management, cost tracking, and intelligent file handling.

🎉 What's New in v2.1.0-RC1

Complete RC1 Feature List

• ✨ NEW: MCP (Model Context Protocol) integration
• ✨ NEW: File system access (read, search, list)
• ✨ NEW: Write mode - AI can create, edit, and delete files
• ✨ NEW: 6 write tools: write_file, edit_file, delete_file, create_directory, move_file, copy_file
• ✨ NEW: Write mode OFF by default - requires explicit /mcp write on activation
• ✨ NEW: Delete operations always require user confirmation
• ✨ NEW: Non-persistent write mode setting (resets each session for safety)
• ✨ NEW: SQLite database querying (read-only)
• ✨ NEW: Dual mode support (Files & Database)
• ✨ NEW: .gitignore filtering
• ✨ NEW: Binary data handling in databases
• ✨ NEW: Mode indicators in prompt (shows ✍️ when write mode active)
• ✨ NEW: Comprehensive /help mcp guide
• 🔧 Improved error handling for tool calls
• 🔧 Enhanced logging for MCP operations
• 🔧 Statistics tracking for tool usage

Core Features

🚀 MCP (Model Context Protocol)

MCP enables your AI to become a true agent with direct access to your local filesystem and databases. This transforms conversations from "copy-paste code to AI" into "AI directly analyzes your codebase and data."

Three Powerful Modes

You> /mcp enable
You> /mcp add ~/Projects
[🔧 MCP: Files] You> List all Python files
[🔧 MCP: Files] You> Read main.py and explain it

You> /mcp enable
You> /mcp write on
[✍️ 🔧 MCP: Files] You> Create a README.md file
[✍️ 🔧 MCP: Files] You> Fix the syntax error in app.py

You> /mcp add db ~/app/data.db
You> /mcp db 1
[🗄️ MCP: DB #1] You> Show all tables
[🗄️ MCP: DB #1] You> Find users created this month

Quick Start with MCP

1. Enable MCP

   You> /mcp enable
   ✓ MCP Filesystem Server started successfully

2. Add Resources (Files or Databases)

   # For file access
   You> /mcp add ~/Documents
   
   # For database querying
   You> /mcp add db ~/myapp/database.db

3. Switch Modes as Needed

   # Use files (default)
   You> /mcp files
   
   # Switch to database
   You> /mcp db 1

4. Ask Natural Questions

   # In file mode
   [🔧 MCP: Files] You> What Python files are in my project?
   
   # In database mode
   [🗄️ MCP: DB #1] You> How many users signed up last week?

Requirements

All other dependencies are automatically installed from the included requirements.txt file.

Installation

Download binary for your system from the release page.
Move to path (e.g. /usr/local/bin).
Run chmod +x your-path-here/oai
Run from anywhere with just oai
                        

Follow these steps to install oAI v2.1.0-RC1 on your system (if you are going to develop on the project):

1. Clone the Repository

   git clone https://gitlab.pm/rune/oai.git
   # Or download the latest zip file from the release page
   cd oai

2. Install Dependencies

   Use the included requirements.txt file (now with MCP support):

   pip install -r requirements.txt

3. Make the Script Executable

   chmod +x oai.py

4. Copy to PATH

   Copy the script to a directory in your $PATH environment variable:

   Option 1: System-wide (requires sudo)

   sudo cp oai.py /usr/local/bin/oai

   Option 2: User-local (recommended)

   mkdir -p ~/.local/bin
   cp oai.py ~/.local/bin/oai
   
   # Add to PATH if not already (add to ~/.bashrc or ~/.zshrc)
   export PATH="$HOME/.local/bin:$PATH"

On first run, you will be prompted to enter your OpenRouter API key.

alias oai='python3 /path/to/oai/oai.py'

How to Use

Quick Start

After installation, simply run:

oai

This starts an interactive chat session. If no API key is configured, you'll be prompted to enter one.

Selecting a Model

You> /model

Browse and select from 300+ available models. You can search by name:

You> /model gpt
You> /model claude

Using MCP for File Access

# Enable MCP and add your project folder
You> /mcp enable
You> /mcp add ~/Projects/myapp

# AI can now access your files
[🔧 MCP: Files] You> List all Python files in this project
🔧 AI requesting 1 tool call(s)...
  → Calling: search_files(pattern="*.py")
  ✓ Found 24 file(s)

AI Response: I found 24 Python files in your project:
- src/main.py
- src/utils.py
- tests/test_main.py
...

[🔧 MCP: Files] You> Read main.py and explain what it does
🔧 AI requesting 1 tool call(s)...
  → Calling: read_file(file_path="~/Projects/myapp/src/main.py")
  ✓ Read file (8192 bytes)

AI Response: This is the main entry point for your application...

Using MCP for Database Queries

# Add a database
You> /mcp add db ~/myapp/users.db
✓ Added database #1: users.db

# Switch to database mode
You> /mcp db 1

# Ask natural language questions
[🗄️ MCP: DB #1] You> What tables are in this database?
🔧 AI requesting 1 tool call(s)...
  → Calling: inspect_database()
  ✓ Inspected database (5 tables)

AI Response: This database contains 5 tables:
1. users (1,234 rows)
2. posts (5,678 rows)
3. comments (12,345 rows)
...

[🗄️ MCP: DB #1] You> How many users signed up in December 2024?
🔧 AI requesting 1 tool call(s)...
  → Calling: query_database(query="SELECT COUNT(*) FROM users WHERE created_at >= '2024-12-01'")
  ✓ Query returned 1 row(s)

AI Response: There were 47 users who signed up in December 2024.

Chatting with AI

Simply type your question or prompt:

You> Explain quantum computing in simple terms

Attaching Files

Attach images, PDFs, or code files using the @ symbol:

You> Analyze this code @script.py
You> Summarize this document @report.pdf
You> What's in this image? @photo.jpg

Using Web Search

Enable online mode for models that support it:

You> /online on
Online mode enabled. Model will use web search capabilities.

You> What are the latest developments in AI?
🌐 Online mode active - model has web search access

Managing Conversations

# Save current conversation
You> /save my_project_discussion

# List saved conversations
You> /list

# Load a conversation by name or number
You> /load my_project_discussion
You> /load 3

# Export to file
You> /export md conversation.md
You> /export html report.html

Using Clipboard

# Paste code from clipboard
You> /paste

# Paste with additional prompt
You> /paste Explain this code and suggest improvements

Command Reference

Usage Examples

🆕 MCP File Access Example

You> /mcp enable
✓ MCP Filesystem Server started successfully

You> /mcp add ~/Projects/webapp
⚠️  Security Check:
You are granting MCP access to: /Users/you/Projects/webapp
This folder contains: 156 files (2.3 MB)

MCP will be able to:
  ✓ Read files in this folder
  ✓ List and search files
  ✓ Access subfolders recursively
  ✓ Automatically respect .gitignore patterns
  ✗ Delete or modify files (read-only)

Proceed? [Y/n]: y

✓ Added /Users/you/Projects/webapp to MCP allowed folders

[🔧 MCP: Files] You> What Python files are in the src/ directory?
🔧 AI requesting 1 tool call(s)...
  → Calling: search_files(pattern="*.py", search_path="~/Projects/webapp/src")
  ✓ Found 12 file(s)

AI Response: I found 12 Python files in src/:
- main.py (entry point)
- config.py (configuration)
- models.py (database models)
...

[🔧 MCP: Files] You> Read models.py and explain the User model
🔧 AI requesting 1 tool call(s)...
  → Calling: read_file(file_path="~/Projects/webapp/src/models.py")
  ✓ Read file (4096 bytes)

AI Response: The User model in models.py is a SQLAlchemy ORM class...

🆕 MCP Database Query Example

You> /mcp add db ~/webapp/production.db
⚠️  Database Check:
Adding: production.db
Size: 45.3 MB
Tables: users, orders, products, sessions (4 total)

Proceed? [Y/n]: y

✓ Added database #1: production.db

You> /mcp db 1
✓ Switched to database #1: production.db
Tables: users, orders, products, sessions

[🗄️ MCP: DB #1] You> Show me the schema for the users table
🔧 AI requesting 1 tool call(s)...
  → Calling: inspect_database(table_name="users")
  ✓ Inspected table: users (1,234 rows)

AI Response: The users table has the following schema:
- id (INTEGER, PRIMARY KEY)
- email (TEXT, NOT NULL)
- created_at (TIMESTAMP)
- last_login (TIMESTAMP)
...

[🗄️ MCP: DB #1] You> How many orders were placed in December 2024?
🔧 AI requesting 1 tool call(s)...
  → Calling: query_database(query="SELECT COUNT(*) as order_count FROM orders WHERE created_at >= '2024-12-01' AND created_at < '2025-01-01'")
  ✓ Query returned 1 row(s)

AI Response: There were 347 orders placed in December 2024.

Basic Chat

You> /model gpt-4o
Selected: GPT-4o (openai/gpt-4o)

You> Write a Python function to calculate fibonacci numbers
AI Response: Here's an efficient implementation...

Code Analysis with File Attachment

You> Review this code for potential bugs @app.py
✓ Code file attached: app.py (12.3 KB)

AI Response: I've analyzed your code. Here are some observations...

Web Search with Online Mode

You> /online on
Online mode enabled. Model will use web search capabilities.

You> What are the latest features in Python 3.13?
🌐 Online mode active - model has web search access

AI Response: Based on recent information, Python 3.13 introduces...

Multi-modal with Images

You> What's in this screenshot? @error.png
✓ Image attached: error.png (245.8 KB)

AI Response: This screenshot shows a Python traceback error...

Cost-Conscious Mode

You> /memory off
Conversation memory disabled. API calls will not include history (lower cost)

You> Quick question: What is 2+2?
📊 Metrics: 142 tokens | $0.0002 | 0.85s, Memory: OFF

Configuration Guide

Setting Up Your Environment

All configuration is stored in ~/.config/oai/:

• oai_config.db - Settings, conversations, and MCP configuration
• history.txt - Command history for auto-completion
• oai.log - Application logs for debugging (rotating, configurable size)

First-Time Setup

1. Enter Your API Key

   On first run, you'll be prompted to enter your OpenRouter API key. Alternatively:

   You> /config api
   Enter new API key: sk-or-v1-...

2. Select a Default Model

   You> /config model
   # Choose your preferred model from the list
   # Models with function calling support will work with MCP

3. Configure Preferences

   # Enable streaming for real-time responses
   You> /config stream on
   
   # Set token limit
   You> /config maxtoken 50000
   
   # Set cost alert threshold
   You> /config costwarning 0.10
   
   # Set default online mode
   You> /config online on

4. 🆕 Set Up MCP (Optional)

   # Enable MCP
   You> /mcp enable
   
   # Add folders for file access
   You> /mcp add ~/Documents
   You> /mcp add ~/Projects
   
   # Add databases for querying
   You> /mcp add db ~/app/data.db
   
   # View status
   You> /mcp status

Advanced Configuration

You> /system You are a Python expert specialized in data science
Session system prompt set to: You are a Python expert...

Support & Contributing

Frequently Asked Questions

# Default: File mode
You> /mcp enable
You> /mcp add ~/Projects
[🔧 MCP: Files] You> List Python files

# Switch to database
You> /mcp db 1
[🗄️ MCP: DB #1] You> Show tables

# Switch back to files
You> /mcp files
[🔧 MCP: Files] You> Search for config files

You> /online on
You> What happened in the news today?
🌐 Online mode active - model has web search access

cd /path/to/oai
git pull origin main
pip install -r requirements.txt --upgrade

# Set a system prompt
You> /system You are a helpful Python expert specialized in web development

# View current system prompt
You> /system

# Clear system prompt
You> /system clear