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.

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

Requirements

Python 3.7 or higher
OpenRouter API key (get one at https://openrouter.ai)

Installation

1. Install Dependencies

Create a requirements.txt file with the following content:

typer
rich
openrouter
pyperclip
prompt_toolkit
requests

Install the dependencies:

pip install -r requirements.txt

2. Make the Script Executable

chmod +x oai.py

3. Copy to PATH

Copy the script to a directory in your $PATH environment variable. Common locations include:

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

4. Verify Installation

oai

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

Usage

Starting the Application

oai

Basic Commands

/help                     Show all available commands
/model                    Select an AI model
/config api               Set OpenRouter API key
exit                      Quit the application

Configuration

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

Common Workflows

Select a Model:

/model

Start Chatting:

You> Hello, how are you?

Attach Files:

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

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

Configuration Options

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>

File Support

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

Image Support: Any image format with proper MIME type (PNG, JPEG, GIF, etc.)

Data Storage

Configuration: ~/.config/oai/oai_config.db
Logs: ~/.config/oai/oai.log
History: ~/.config/oai/history.txt

License

MIT License

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

Author

Rune Olsen

Blog: https://blog.rune.pm

Version

1.0

Support

For issues, questions, or contributions, visit https://iurl.no/oai