rune/oai
1
0
Fork 0
Code Issues Pull Requests Releases 9 Activity

Final release of 2.1

Browse Source
This commit is contained in:
Rune Olsen
2026-02-03 08:57:16 +01:00
parent a0ed0eaaf0
commit 2ffed27ab6
35 changed files with 11494 additions and 6462 deletions
Download Patch File Download Diff File Expand all files Collapse all files

667
README.md
View File

@@ -1,584 +1,301 @@
# oAI - OpenRouter AI Chat
# oAI - OpenRouter AI Chat Client
A powerful terminal-based chat interface for OpenRouter API with **MCP (Model Context Protocol)** support, enabling AI agents to access local files and query SQLite databases directly.
## Description
oAI is a feature-rich command-line chat application that provides an interactive interface to OpenRouter's AI models. It now includes **MCP integration** for local file system access and read-only database querying, allowing AI to help with code analysis, data exploration, and more.
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 capability filtering
- 🔍 Model selection with search and filtering
- 💾 Conversation save/load/export (Markdown, JSON, HTML)
- 📎 File attachment support (images, PDFs, code files)
- 💰 Session cost tracking and credit monitoring
- 🎨 Rich terminal formatting with syntax highlighting
- 📎 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)
- ⚙️ Configurable system prompts and token limits
- 🗄️ SQLite-based configuration and conversation storage
- 🌐 Online mode (web search capabilities)
- 🧠 Conversation memory toggle (save costs with stateless mode)
- 🧠 Conversation memory toggle
### NEW: MCP (Model Context Protocol) v2.1.0-beta
- 🔧 **File Mode**: AI can read, search, and list your local files
### MCP Integration
- 🔧 **File Mode**: AI can read, search, and list local files
- Automatic .gitignore filtering
- Virtual environment exclusion (venv, node_modules, etc.)
- Supports code files, text, JSON, YAML, and more
- Virtual environment exclusion
- Large file handling (auto-truncates >50KB)
- ✍️ **Write Mode** (NEW!): AI can modify files with your permission
- Create and edit files within allowed folders
- Delete files (always requires confirmation)
- Move, copy, and organize files
- Create directories
- Ignores .gitignore for write operations
- OFF by default - explicit opt-in required
- 🗄️ **Database Mode**: AI can query your SQLite databases
- Read-only access (no data modification possible)
- Schema inspection (tables, columns, indexes)
- Full-text search across all tables
- SQL query execution (SELECT, JOINs, CTEs, subqueries)
- Query validation and timeout protection
- Result limiting (max 1000 rows)
- 🔒 **Security Features**:
- Explicit folder/database approval required
- System directory blocking
- Write mode OFF by default (non-persistent)
- Delete operations always require user confirmation
- Read-only database access
- SQL injection protection
- Query timeout (5 seconds)
- ✍️ **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 (3.14 not supported yet)
- OpenRouter API key (get one at https://openrouter.ai)
- Function-calling model required for MCP features (GPT-4, Claude, etc.)
## Screenshot
[<img src="https://gitlab.pm/rune/oai/raw/branch/main/images/screenshot_01.png">](https://gitlab.pm/rune/oai/src/branch/main/README.md)
*Screenshot from version 1.0 - MCP interface shows mode indicators like `[🔧 MCP: Files]` or `[🗄️ MCP: DB #1]`*
- Python 3.10-3.13
- OpenRouter API key ([get one here](https://openrouter.ai))
## Installation
### Option 1: From Source (Recommended for Development)
#### 1. Install Dependencies
### Option 1: Install from Source (Recommended)
```bash
pip install -r requirements.txt
# Clone the repository
git clone https://gitlab.pm/rune/oai.git
cd oai
# Install with pip
pip install -e .
```
#### 2. Make Executable
### Option 2: Pre-built Binary (macOS/Linux)
```bash
chmod +x oai.py
```
#### 3. Copy to PATH
```bash
# 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 needed (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"
```
#### 4. Verify Installation
```bash
oai --version
```
### Option 2: Pre-built Binaries
Download platform-specific binaries:
- **macOS (Apple Silicon)**: `oai_vx.x.x_mac_arm64.zip`
- **Linux (x86_64)**: `oai_vx.x.x-linux-x86_64.zip`
Download from [Releases](https://gitlab.pm/rune/oai/releases):
- **macOS (Apple Silicon)**: `oai_v2.1.0_mac_arm64.zip`
- **Linux (x86_64)**: `oai_v2.1.0_linux_x86_64.zip`
```bash
# Extract and install
unzip oai_vx.x.x_mac_arm64.zip # or `oai_vx.x.x-linux-x86_64.zip`
chmod +x oai
mkdir -p ~/.local/bin # Remember to add this to your path. Or just move to folder already in your $PATH
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"
```
### Alternative: Shell Alias
### Add to PATH
```bash
# Add to ~/.bashrc or ~/.zshrc
alias oai='python3 /path/to/oai.py'
# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"
```
## Quick Start
### First Run Setup
```bash
# 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
```bash
oai
# In the chat interface:
/model # Select AI model
/help # Show all commands
/mcp on # Enable file/database access
/stats # View session statistics
exit # Quit
```
On first run, you'll be prompted to enter your OpenRouter API key.
## MCP (Model Context Protocol)
### Basic Usage
MCP allows the AI to interact with your local files and databases.
### File Access
```bash
# Start chatting
oai
/mcp on # Enable MCP
/mcp add ~/Projects # Grant access to folder
/mcp list # View allowed folders
# Select a model
You> /model
# Enable MCP for file access
You> /mcp on
You> /mcp add ~/Documents
# Ask AI to help with files (read-only)
[🔧 MCP: Files] You> List all Python files in Documents
[🔧 MCP: Files] You> Read and explain main.py
# Enable write mode to let AI modify files
You> /mcp write on
[🔧✍️ MCP: Files+Write] You> Create a new Python file with helper functions
[🔧✍️ MCP: Files+Write] You> Refactor main.py to use async/await
# Switch to database mode
You> /mcp add db ~/myapp/data.db
You> /mcp db 1
[🗄️ MCP: DB #1] You> Show me all tables
[🗄️ MCP: DB #1] You> Find all users created this month
```
## MCP Guide
### File Mode (Default)
**Setup:**
```bash
/mcp on # Start MCP server
/mcp add ~/Projects # Grant access to folder
/mcp add ~/Documents # Add another folder
/mcp list # View all allowed folders
```
**Natural Language Usage:**
```
# Now ask the AI:
"List all Python files in Projects"
"Read and explain config.yaml"
"Read and explain main.py"
"Search for files containing 'TODO'"
"What's in my Documents folder?"
```
**Available Tools (Read-Only):**
- `read_file` - Read complete file contents
- `list_directory` - List files/folders (recursive optional)
- `search_files` - Search by name or content
**Available Tools (Write Mode - requires `/mcp write on`):**
- `write_file` - Create new files or overwrite existing ones
- `edit_file` - Find and replace text in existing files
- `delete_file` - Delete files (always requires confirmation)
- `create_directory` - Create directories
- `move_file` - Move or rename files
- `copy_file` - Copy files to new locations
**Features:**
- ✅ Automatic .gitignore filtering (read operations only)
- ✅ Skips virtual environments (venv, node_modules)
- ✅ Handles large files (auto-truncates >50KB)
- ✅ Cross-platform (macOS, Linux, Windows via WSL)
- ✅ Write mode OFF by default for safety
- ✅ Delete operations require user confirmation with LLM's reason
### Database Mode
**Setup:**
```bash
/mcp add db ~/app/database.db # Add SQLite database
/mcp db list # View all databases
/mcp db 1 # Switch to database #1
```
**Natural Language Usage:**
```
"Show me all tables in this database"
"Find records mentioning 'error'"
"How many users registered last week?"
"Get the schema for the orders table"
"Show me the 10 most recent transactions"
```
**Available Tools:**
- `inspect_database` - View schema, tables, columns, indexes
- `search_database` - Full-text search across tables
- `query_database` - Execute read-only SQL queries
**Supported Queries:**
- ✅ SELECT statements
- ✅ JOINs (INNER, LEFT, RIGHT, FULL)
- ✅ Subqueries
- ✅ CTEs (Common Table Expressions)
- ✅ Aggregations (COUNT, SUM, AVG, etc.)
- ✅ WHERE, GROUP BY, HAVING, ORDER BY, LIMIT
- ❌ INSERT/UPDATE/DELETE (blocked for safety)
### Write Mode
**Enable Write Mode:**
```bash
/mcp write on # Enable write mode (shows warning, requires confirmation)
/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
```
**Natural Language Usage:**
```
"Create a new Python file called utils.py with helper functions"
"Edit main.py and replace the old API endpoint with the new one"
"Delete the backup.old file" (will prompt for confirmation)
"Create a directory called tests"
"Move config.json to the config folder"
```
**Important:**
- ⚠️ Write mode is **OFF by default** and resets each session
- ⚠️ Delete operations **always** require user confirmation
- ⚠️ All operations are limited to allowed MCP folders
- ✅ Write operations ignore .gitignore (can write to any file in allowed folders)
**Disable Write Mode:**
```bash
/mcp write off # Disable write mode (back to read-only)
```
### Mode Management
### Database Mode
```bash
/mcp status # Show current mode, write mode, stats, folders/databases
/mcp files # Switch to file mode
/mcp db <number> # Switch to database mode
/mcp gitignore on # Enable .gitignore filtering (default)
/mcp write on|off # Enable/disable write mode
/mcp remove 2 # Remove folder/database by number
/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
### Session Commands
```
/help [command] Show help menu or detailed command help
/help mcp Comprehensive MCP guide
/clear or /cl Clear terminal screen (or Ctrl+L)
/memory on|off Toggle conversation memory (save costs)
/online on|off Enable/disable web search
/paste [prompt] Paste clipboard content
/retry Resend last prompt
/reset Clear history and system prompt
/prev View previous response
/next View next response
```
### 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
```
/mcp on Start MCP server
/mcp off Stop MCP server
/mcp status Show comprehensive status (includes write mode)
/mcp add <folder> Add folder for file access
/mcp add db <path> Add SQLite database
/mcp list List all folders
/mcp db list List all databases
/mcp db <number> Switch to database mode
/mcp files Switch to file mode
/mcp remove <num> Remove folder/database
/mcp gitignore on Enable .gitignore filtering
/mcp write on Enable write mode (create/edit/delete files)
/mcp write off Disable write mode (read-only)
```
| 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 |
### Model Commands
```
/model [search] Select/change AI model
/info [model_id] Show model details (pricing, capabilities)
```
### 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
```
/config View all settings
/config api Set API key
/config model Set default model
/config online Set default online mode (on|off)
/config stream Enable/disable streaming (on|off)
/config maxtoken Set max token limit
/config costwarning Set cost warning threshold ($)
/config loglevel Set log level (debug/info/warning/error)
/config log Set log file size (MB)
```
| 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 |
### Conversation Management
```
/save <name> Save conversation
/load <name|num> Load saved conversation
/delete <name|num> Delete conversation
/list List saved conversations
/export md|json|html <file> Export conversation
```
## CLI Options
### Token & System
```
/maxtoken [value] Set session token limit
/system [prompt] Set system prompt (use 'clear' to reset)
/middleout on|off Enable prompt compression
```
### Monitoring
```
/stats View session statistics
/credits Check OpenRouter credits
```
### File Attachments
```
@/path/to/file Attach file (images, PDFs, code)
Examples:
Debug @script.py
Analyze @data.json
Review @screenshot.png
```
## Configuration Options
All configuration stored in `~/.config/oai/`:
### Files
- `oai_config.db` - SQLite database (settings, conversations, MCP config)
- `oai.log` - Application logs (rotating, configurable size)
- `history.txt` - Command history (searchable with Ctrl+R)
### Key Settings
- **API Key**: OpenRouter authentication
- **Default Model**: Auto-select on startup
- **Streaming**: Real-time response display
- **Max Tokens**: Global and session limits
- **Cost Warning**: Alert threshold for expensive requests
- **Online Mode**: Default web search setting
- **Log Level**: debug/info/warning/error/critical
- **Log Size**: Rotating file size in MB
## Supported File Types
### Code Files
`.py, .js, .ts, .cs, .java, .c, .cpp, .h, .hpp, .rb, .ruby, .php, .swift, .kt, .kts, .go, .sh, .bat, .ps1, .R, .scala, .pl, .lua, .dart, .elm`
### Data Files
`.json, .yaml, .yml, .xml, .csv, .txt, .md`
### Images
All standard formats: PNG, JPEG, JPG, GIF, WEBP, BMP
### Documents
PDF (models with document support)
### Size Limits
- Images: 10 MB max
- Code/Text: Auto-truncates files >50KB
- Binary data: Displayed as `<binary: X bytes>`
## MCP Security
### Access Control
- ✅ Explicit folder/database approval required
- ✅ System directories blocked automatically
- ✅ User confirmation for each addition
- ✅ .gitignore patterns respected (file mode)
### Database Safety
- ✅ Read-only mode (cannot modify data)
- ✅ SQL query validation (blocks INSERT/UPDATE/DELETE)
- ✅ Query timeout (5 seconds max)
- ✅ Result limits (1000 rows max)
- ✅ Database opened in `mode=ro`
### File System Safety
- ✅ Read-only by default (write mode requires explicit opt-in)
- ✅ Write mode OFF by default each session (non-persistent)
- ✅ Delete operations always require user confirmation
- ✅ Write operations limited to allowed folders only
- ✅ System directories blocked
- ✅ Virtual environment exclusion
- ✅ Build artifact filtering
- ✅ Maximum file size (10 MB)
## Tips & Tricks
### Command History
- **↑/↓ arrows**: Navigate previous commands
- **Ctrl+R**: Search command history
- **Auto-complete**: Start typing `/` for command suggestions
### Cost Optimization
```bash
/memory off # Disable context (stateless mode)
/maxtoken 1000 # Limit response length
/config costwarning 0.01 # Set alert threshold
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
```
### MCP Best Practices
Other commands:
```bash
# Check status frequently
/mcp status
# Use specific paths to reduce search time
"List Python files in Projects/app/" # Better than
"List all Python files" # Slower
# Database queries - be specific
"SELECT * FROM users LIMIT 10" # Good
"SELECT * FROM users" # May hit row limit
oai config [setting] [value] # Configure settings
oai version # Show version
oai credits # Check credits
```
### Debugging
```bash
# Enable debug logging
/config loglevel debug
## Configuration
# Check log file
tail -f ~/.config/oai/oai.log
Configuration is stored in `~/.config/oai/`:
# View MCP statistics
/mcp status # Shows tool call counts
| 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
### MCP Not Working
```bash
# 1. Check if MCP is installed
python3 -c "import mcp; print('MCP OK')"
### macOS Binary Issues
# 2. Verify model supports function calling
```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
# 3. Check MCP status
# Check MCP status
/mcp status
# 4. Review logs
tail ~/.config/oai/oai.log
# View logs
tail -f ~/.config/oai/oai.log
```
### Import Errors
```bash
# Reinstall dependencies
pip install --force-reinstall -r requirements.txt
```
### Binary Issues (macOS)
```bash
# Remove quarantine
xattr -cr ~/.local/bin/oai
# Check security settings
# System Settings > Privacy & Security > "Allow Anyway"
```
### Database Errors
```bash
# Verify it's a valid SQLite database
sqlite3 database.db ".tables"
# Check file permissions
ls -la database.db
# Reinstall package
pip install -e . --force-reinstall
```
## Version History
### v2.1.0-RC1 (Current)
- ✨ **NEW**: MCP (Model Context Protocol) integration
- ✨ **NEW**: File system access (read, search, list)
- ✨ **NEW**: Write mode - AI can create, edit, and delete files
- 6 write tools: write_file, edit_file, delete_file, create_directory, move_file, copy_file
- OFF by default - requires explicit `/mcp write on` activation
- Delete operations always require user confirmation
- Non-persistent setting (resets each session)
- ✨ **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
### 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.6
- Base version with core chat functionality
- Conversation management
### v1.9.x
- Single-file implementation
- Core chat functionality
- File attachments
- Cost tracking
- Export capabilities
- Conversation management
## License
MIT License
Copyright (c) 2024-2025 Rune Olsen
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Full license: https://opensource.org/licenses/MIT
MIT License - See [LICENSE](LICENSE) for details.
## Author
**Rune Olsen**
- Homepage: https://ai.fubar.pm/
- Blog: https://blog.rune.pm
- Project: https://iurl.no/oai
- Repository: https://gitlab.pm/rune/oai
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Submit a pull request with detailed description
## Acknowledgments
- OpenRouter team for the unified AI API
- Rich library for beautiful terminal output
- MCP community for the protocol specification
3. Submit a pull request
---
**Star ⭐ this project if you find it useful!**
---
Did you really read all the way down here? WOW! You deserve a 🍾 🥂!
**⭐ Star this project if you find it useful!**