oai/README.md

# oAI - OpenRouter AI Chat Client

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 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.10-3.13
- OpenRouter API key ([get one here](https://openrouter.ai))

## Installation

### Option 1: Install from Source (Recommended)

```bash
# Clone the repository
git clone https://gitlab.pm/rune/oai.git
cd oai

# Install with pip
pip install -e .
```

### 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
# Extract and install
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"
```

### Add to PATH

```bash
# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"
```

## Quick Start

```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
# In the chat interface:
/model              # Select AI model
/help               # Show all commands
/mcp on             # Enable file/database access
/stats              # View session statistics
exit                # Quit
```

## MCP (Model Context Protocol)

MCP allows the AI to interact with your local files and databases.

### File Access

```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'"
```

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

### Database Mode

```bash
/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

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

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

## CLI Options

```bash
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
```

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 - See [LICENSE](LICENSE) for details.

## Author

**Rune Olsen**
- Project: https://iurl.no/oai
- Repository: https://gitlab.pm/rune/oai

## Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

---

**⭐ Star this project if you find it useful!**