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

2.1 (#2)

Browse Source 
Final release of version 2.1.

Headlights:

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

Reviewed-on: #2
Co-authored-by: Rune Olsen <rune@rune.pm>
Co-committed-by: Rune Olsen <rune@rune.pm>
This commit was merged in pull request #2.
This commit is contained in:
Rune Olsen
2026-02-03 09:02:44 +01:00
committed by rune
parent 1ef7918291
commit b0cf88704e
36 changed files with 11576 additions and 2485 deletions
Download Patch File Download Diff File Expand all files Collapse all files

411
README.md
View File

@@ -1,232 +1,301 @@
# oAI - OpenRouter AI Chat
# oAI - OpenRouter AI Chat Client
A terminal-based chat interface for OpenRouter API with conversation management, cost tracking, and rich formatting.
## Description
oAI is a command-line chat application that provides an interactive interface to OpenRouter's AI models. It features conversation persistence, file attachments, export capabilities, and detailed session metrics.
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
- Interactive chat with multiple AI models via OpenRouter
- Model selection with search functionality
- Conversation save/load/export (Markdown, JSON, HTML)
- File attachment support (code files and images)
- Session cost tracking and credit monitoring
- Rich terminal formatting with syntax highlighting
- Persistent command history
- Configurable system prompts and token limits
- SQLite-based configuration and conversation storage
### 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.7 or higher
- OpenRouter API key (get one at https://openrouter.ai)
## Screenshot (<span style="font-size:0.8em;">from version 1.0</span>)
[<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 of `/help` screen.
- Python 3.10-3.13
- OpenRouter API key ([get one here](https://openrouter.ai))
## Installation
### 1. Install Dependencies
Use the included `requirements.txt` file to install the 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 the Script Executable
### Option 2: Pre-built Binary (macOS/Linux)
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
chmod +x oai.py
```
### 3. Copy to PATH
Copy the script to a directory in your `$PATH` environment variable. Common locations include:
```bash
# Option 1: System-wide (requires sudo)
sudo cp oai.py /usr/local/bin/oai
# Option 2: User-local (recommended)
# Extract and install
unzip oai_v2.1.0_*.zip
mkdir -p ~/.local/bin
cp oai.py ~/.local/bin/oai
mv oai ~/.local/bin/
# Add to PATH if not already (add to ~/.bashrc or ~/.zshrc)
# 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"
```
### 4. Verify Installation
## Quick Start
```bash
oai
# Start the chat client
oai chat
# Or with options
oai chat --model gpt-4o --mcp
```
### 5. Alternative Installation (for *nix systems)
If you have issues with the above method you can add an alias in your `.bashrc`, `.zshrc` etc.
```bash
alias oai='python3 <path to your file>'
```
On first run, you will be prompted to enter your OpenRouter API key.
### 6. Use Binaries
You can also just download the supplied binary for either Mac wit Mx (M1, M2 etc) `oai_mac_arm64.zip` and follow [#3](https://gitlab.pm/rune/oai#3-copy-to-path). Or download for Linux (64bit) `oai_linux_x86_64.zip` and also follow [#3](https://gitlab.pm/rune/oai#3-copy-to-path).
## Usage
### Starting the Application
```bash
oai
```
On first run, you'll be prompted for your OpenRouter API key.
### Basic Commands
```
/help Show all available commands
/model Select an AI model
/config api Set OpenRouter API key
exit Quit the application
```bash
# In the chat interface:
/model # Select AI model
/help # Show all commands
/mcp on # Enable file/database access
/stats # View session statistics
exit # Quit
```
### Configuration
## MCP (Model Context Protocol)
All configuration is stored in `~/.config/oai/`:
- `oai_config.db` - SQLite database for settings and conversations
- `oai.log` - Application log file
- `history.txt` - Command history
MCP allows the AI to interact with your local files and databases.
### Common Workflows
### File Access
**Select a Model:**
```
/model
```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'"
```
**Paste from clipboard:**
Paste and send content to model
```
/paste
### 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
```
Paste with prompt and send content to model
```
/paste Analyze this text
```
### Database Mode
**Start Chatting:**
```
You> Hello, how are you?
```
```bash
/mcp add db ~/app/data.db # Add database
/mcp db 1 # Switch to database mode
**Attach Files:**
# Ask the AI:
"Show all tables"
"Find users created this month"
"What's the schema for the orders table?"
```
You> Debug this code @/path/to/script.py
You> Analyze this image @/path/to/image.png
```
**Save Conversation:**
```
/save my_conversation
```
**Export to File:**
```
/export md notes.md
/export json backup.json
/export html report.html
```
**View Session Stats:**
```
/stats
/credits
```
**Prevous commands input:**
Use the up/down arrows to see earlier `/`commands and earlier input to model and `<enter>` to execute the same command or resend the same input.
## Command Reference
Use `/help` within the application for a complete command reference organized by category:
- Session Commands
- Model Commands
- Configuration
- Token & System
- Conversation Management
- Monitoring & Stats
- File Attachments
### 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 |
## Configuration Options
### 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 |
- API Key: `/config api`
- Base URL: `/config url`
- Streaming: `/config stream on|off`
- Default Model: `/config model`
- Cost Warning: `/config costwarning <amount>`
- Max Token Limit: `/config maxtoken <value>`
### 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 |
## File Support
### 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 |
**Supported Code Extensions:**
.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, .xml, .json, .yaml, .yml, .md, .txt
## CLI Options
**Image Support:**
Any image format with proper MIME type (PNG, JPEG, GIF, etc.)
```bash
oai chat [OPTIONS]
## Data Storage
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
```
- Configuration: `~/.config/oai/oai_config.db`
- Logs: `~/.config/oai/oai.log`
- History: `~/.config/oai/history.txt`
Other commands:
```bash
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
```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
### 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
Copyright (c) 2024 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**
- Project: https://iurl.no/oai
- Repository: https://gitlab.pm/rune/oai
Blog: https://blog.rune.pm
## Contributing
## Version
1. Fork the repository
2. Create a feature branch
3. Submit a pull request
1.0
---
## Support
For issues, questions, or contributions, visit https://iurl.no/oai and create an issue.
**⭐ Star this project if you find it useful!**