oai/README.md

oAI - OpenRouter AI Chat

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.

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)

Screenshot

Screenshot of /help screen.

Installation

1. Install Dependencies

Use the included requirements.txt file to 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

5. Alternative Installation (for *nix systems)

If you have issues with the above method you can add an alias in your .bashrc, .zshrc etc.

alias oai='python3 <path to your file>'

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

Paste from clipboard: Paste and send content to model

/paste 

Paste with prompt and send content to model

/paste Analyze this text

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

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

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

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

Author

Rune Olsen

Blog: https://blog.rune.pm

Version

1.0

Support

For issues, questions, or contributions, visit https://iurl.no/oai and create an issue.