https://github.com/oop7/OrChat
A powerful, feature-rich command-line interface for interacting with AI models through OpenRouter.
https://github.com/oop7/OrChat
ai chatbot cli llm openrouter terminal
Last synced: 3 months ago
JSON representation
A powerful, feature-rich command-line interface for interacting with AI models through OpenRouter.
- Host: GitHub
- URL: https://github.com/oop7/OrChat
- Owner: oop7
- License: mit
- Created: 2025-03-18T11:32:44.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-08-22T23:43:53.000Z (3 months ago)
- Last Synced: 2025-08-23T01:31:00.184Z (3 months ago)
- Topics: ai, chatbot, cli, llm, openrouter, terminal
- Language: Python
- Homepage:
- Size: 126 KB
- Stars: 35
- Watchers: 1
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-cli-apps-in-a-csv - OrChat - A powerful, feature-rich command-line interface for interacting with AI models through OpenRouter. (<a name="ai"></a>AI / ChatGPT)
- awesome-cli-apps - OrChat - A powerful, feature-rich command-line interface for interacting with AI models through OpenRouter. (<a name="ai"></a>AI / ChatGPT)
README
# 🤖 OrChat
[](https://badge.fury.io/py/orchat)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://pepy.tech/project/orchat)
[](https://github.com/oop7/OrChat/stargazers)
[🚀 Installation](#installation) • [✨ Features](#features) • [💬 Chat Commands](#chat-commands) • [📁 File Attachment](#file-attachment) • [🧠 Thinking Mode](#thinking-mode) • [⚙️ Configuration](#configuration) • [🔍 Troubleshooting](#troubleshooting) • [🤝 Contributing](#contributing)
A powerful CLI for chatting with AI models through OpenRouter with streaming responses, token tracking, auto-update checking, multi-line input, and extensive customization options.
🔗 Core Features
- **Universal Model Access**: Connect to any AI model available on OpenRouter with dynamic model retrieval
- **Interactive Chat**: Enjoy a smooth conversation experience with real-time streaming responses
- **Rich Markdown Rendering**: View formatted text, code blocks, tables and more directly in your terminal
- **Performance Analytics**: Track token usage, response times, and total cost for efficiency monitoring (now with accurate API-based token counting)
- **Command Auto-completion**: Enhanced user experience with intelligent command suggestions and prompt history navigation
- **Prompt History Navigation**: Use ↑/↓ arrow keys to navigate through previous prompts and Ctrl+R for history search
- **Pricing Display**: Real-time pricing information displayed during active chat sessions
- **Auto-Update System**: Automatic update checking at startup with pip integration
- **Multi-line Input Support**: Compose multi-paragraph messages with `Esc+Enter` and visual feedback
📎 File & Media Support
- **Smart File Picker**: Attach files anywhere in your message using `#` (e.g., `analyze #myfile.py`)
- **Interactive File Browser**: Browse files with icons, sizes, and directory navigation in a popup interface
- **Multimodal Support**: Share images and various file types with compatible AI models
- **Enhanced File Processing**: Improved file attachment with better error handling and path support
🧠 Advanced Features
- **Smart Thinking Mode**: See the AI's reasoning process with compatible models
- **Multiple Export Formats**: Save conversations as Markdown, HTML, JSON, TXT, or PDF
- **Smart Context Management**: Automatically manages conversation history to stay within token limits
- **Customizable Themes**: Choose from different visual themes for your terminal
⌨️ Interactive Input Features
- **Multi-line Input**: Use `Esc+Enter` to toggle multi-line mode, with status indicator and seamless toggling
- **Command History Navigation**: Press ↑/↓ arrow keys to cycle through previous prompts and commands
- **History Search**: Use Ctrl+R to search through your prompt history with keywords
- **Automatic Command Completion**: Start typing "/" and command suggestions appear instantly - no Tab key needed!
- **Auto-Suggest from History**: Previous commands and prompts appear as grey suggestions as you type
- **Intelligent File Picker**: Use `#` anywhere in your message for file selection with auto-completion and browser popup
**💡 How Auto-Completion Works:**
- Type `/` → All available commands appear automatically
- Type `/c` → Filters to commands starting with 'c' (clear, cls, clear-screen, etc.)
- Type `/temp` → Shows `/temperature` command
- Type `/think` → Shows `/thinking` and `/thinking-mode` commands
- No Tab key required - completions appear as you type!
**💡 How File Picker Works:**
- Type `#` anywhere in your message to open the file picker
- Choose files interactively (with icons for file types)
- Insert filenames naturally into your prompt, e.g., `examine #test.py and check for errors`
- File picker works anywhere in your message, not just at the beginning
📦 Installation Methods
### From PyPI (Recommended)
```bash
pip install orchat
```
```bash
# Run the application
orchat
```
### From Source
```bash
git clone https://github.com/oop7/OrChat.git
pip install -r requirements.txt
python main.py
```
📋 Prerequisites
- Python 3.7 or higher
- An OpenRouter API key (get one at [OpenRouter.ai](https://openrouter.ai))
- Required packages: in `requirements.txt`
🏁 Getting Started
1. Install OrChat using one of the methods above
2. Run the setup wizard
- if you follow from source PyPI:
```bash
orchat --setup
```
- if you follow from source method:
```bash
python main.py --setup
```
3. Enter your OpenRouter API key when prompted
4. Select your preferred AI model and configure settings
5. Start chatting!
🪛 Add-Ons
### FZF fuzzy search (Enhanced Model Selection)
1. Install fzf and pyfzf
- Install pyfzf
```bash
pip install pyfzf
```
- Fzf can be downloaded from https://github.com/junegunn/fzf?tab=readme-ov-file#installation
2. Ensure fzf is in your path
3. From now on, the model selection will use fzf for powerful fuzzy search and filtering capabilities!
**Note**: If fzf is not installed, OrChat will automatically fall back to standard model selection.
🔧 Configuration Methods
OrChat can be configured in multiple ways:
1. **Setup Wizard**: Run `python main.py --setup` for interactive configuration
2. **Config File**: Edit the `config.ini` file in the application directory
3. **Environment Variables**: Create a `.env` file with your configuration
4. **System Environment Variables**: Set environment variables directly in your system (recommended for security)
**Enhanced Environment Support**: OrChat now supports system/user environment variables, removing the strict requirement for `.env` files.
📄 Configuration Examples
Example `.env` file:
```
OPENROUTER_API_KEY=your_api_key_here
```
Example `config.ini` structure:
```ini
[API]
OPENROUTER_API_KEY = your_api_key_here
[SETTINGS]
MODEL = anthropic/claude-3-opus
TEMPERATURE = 0.7
SYSTEM_INSTRUCTIONS = You are a helpful AI assistant.
THEME = default
MAX_TOKENS = 8000
AUTOSAVE_INTERVAL = 300
STREAMING = True
THINKING_MODE = False
```
🖥️ Command-Line Options
- `--setup`: Run the setup wizard
- `--model MODEL`: Specify the model to use (e.g., `--model "anthropic/claude-3-opus"`)
- `--task {creative,coding,analysis,chat}`: Optimize for a specific task type
- `--image PATH`: Analyze an image file
| Command | Description |
| ------------------------- | ----------------------------------------------------- |
| `/help` | Show available commands |
| `/exit` | Exit the chat |
| `/quit` | Exit the chat |
| `/new` | Start a new conversation |
| `/clear` | Clear conversation history |
| `/cls` or `/clear-screen` | Clear the terminal screen |
| `/save [format]` | Save conversation (formats: md, html, json, txt, pdf) |
| `/model` | Change the AI model |
| `/temperature <0.0-2.0>` | Adjust temperature setting |
| `/system` | View or change system instructions |
| `/tokens` | Show token usage statistics (now API-accurate) |
| `/speed` | Show response time statistics |
| `/theme ` | Change the color theme (default, dark, light, hacker) |
| `/thinking` | Show last AI thinking process |
| `/thinking-mode` | Toggle thinking mode on/off |
| `/about` | Show information about OrChat |
| `/update` | Check for updates |
| `/settings` | View current settings |
📎 Basic Usage
Attach files naturally in your messages using the smart file picker:
```
analyze #path/to/your/file.ext for issues
examine #script.py and explain its logic
```
- Use `#` anywhere in your message to open the file picker popup
✨ Enhanced Features
- **Intelligent File Picker**: Auto-completion, icons, file sizes, and directory navigation
- **Quoted Path Support**: Handles file paths with spaces using quotes
- **Better Error Handling**: Improved error messages and usage examples
- **File Preview**: Shows file metadata and preview before processing
- **Security Validation**: Built-in file size and type validation (10MB limit)
📋 Supported File Types
- **Images**: JPG, PNG, GIF, WEBP, BMP (displayed visually with multimodal models)
- **Code Files**: Python, JavaScript, Java, C++, TypeScript, Swift, etc. (with syntax highlighting)
- **Text Documents**: TXT, MD, CSV (full content displayed)
- **Data Files**: JSON, XML (displayed with formatting)
- **Web Files**: HTML, CSS (formatted display)
- **Archives**: ZIP, TAR, GZ, RAR (basic metadata support)
🎯 Basic Usage
OrChat can display the AI's reasoning process with enhanced thinking mode:
```
/thinking-mode # Toggle thinking mode on/off
/thinking # Show the most recent thinking process
```
This feature allows you to see how the AI approached your question before giving its final answer. **Auto Thinking Mode** automatically enables this feature when you select models with reasoning support.
✨ Enhanced Features
- **Improved Detection**: Better extraction of thinking content from model responses
- **Model Compatibility**: Automatic handling of models that don't support thinking mode
- **Visual Indicators**: Clear status indicators showing if thinking mode is enabled
- **Flexible Setup**: Option to enable/disable during model selection
## 🎨 Themes
🎨 Available Themes
Change the visual appearance with the `/theme` command:
- **default**: Blue user, green assistant
- **dark**: Cyan user, magenta assistant
- **light**: Blue user, green assistant with lighter colors
- **hacker**: Matrix-inspired green text on black
## 📊 Token Management
📊 Smart Context Management
OrChat intelligently manages conversation context to keep within token limits:
- Automatically trims old messages when approaching limits
- Displays comprehensive token usage statistics including total tokens and cost tracking
- Shows real-time pricing information during active sessions
- Displays total cost tracking across conversations
- Allows manual clearing of context with `/clear`
## 🔄 Updates
🔄 Version Management
Check for updates with the `/update` command to see if a newer version is available.
🔍 Common Issues & Solutions
- **API Key Issues**: Ensure your OpenRouter API key is correctly set in config.ini, .env file, or system environment variables. OrChat will prompt for re-entry if an incorrect key is detected
- **Insufficient Account Credit**: If you receive a 402 error, check your OpenRouter account balance and add funds as needed
- **File Path Problems**: When using `/attach` or `/upload`, use quotes for paths with spaces and ensure correct path format for your OS
- **Model Compatibility**: Some features like thinking mode only work with specific models
- **Command Usage**: Remember that `/upload` and `/attach` can be used anywhere in your message for flexibility
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Contributions are welcome! Feel free to open issues or submit pull requests.
## 🙏 Acknowledgments
🙏 Special Thanks
- [OpenRouter](https://openrouter.ai/) for providing unified API access to AI models
- [Rich](https://github.com/Textualize/rich) for the beautiful terminal interface
- All contributors and users who provide feedback and help improve OrChat