osiris-cli 5.4.4
A Sovereign AI Terminal Interface & Development Agent.
Requires Python: >=3.10
Keywords: agent, ai, anthropic, cli, deepseek, llm, openai, terminal

# OSIRIS CLI - Sovereign AGI Terminal Interface

[![Version](https://img.shields.io/badge/version-5.4.3-blue.svg)](https://github.com/The-Osiris-Labs/osiris-cli)
[![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)

A modern, interactive CLI for AI conversations with advanced tool integration, session management, and professional dashboard interface.

![Osiris CLI Demo](https://via.placeholder.com/800x400/1a1a1a/00ff88?text=Osiris+CLI+Dashboard)

## ✨ Features

### 🎨 Modern Interface
- **Dashboard UI**: Card-based, responsive design with real-time navigation
- **Multi-Column Layout**: Adapts to terminal width (1-3 columns)
- **Professional Styling**: Clean aesthetics without childish elements
- **Arrow Key Navigation**: Intuitive movement with visual feedback

### 🤖 AI Integration
- **Multi-Provider Support**: OpenAI, Anthropic (Claude), Google (Gemini), Cohere, Replicate, Groq, DeepSeek
- **Streaming Responses**: Real-time AI output with typing indicators
- **Tool Calling**: Seamless integration of AI tools in conversations
- **Model Switching**: Runtime changes between AI models
- **Direct API Integration**: Native support for Claude, Gemini, and other providers

### 🛠️ Advanced Tools
- **System Commands**: Execute shell commands safely
- **File Operations**: Read, write, and analyze files
- **Web Search**: Resilient internet research with googler plus Bing RSS/lynx fallbacks
- **Clean Output**: Automatic elimination of XML noise and internal model tags
- **Extensible Framework**: Easy to add custom tools and MCP servers

### 💾 Session Management
- **Persistent Sessions**: Save and resume conversations
- **Context Files**: Include project files in AI context
- **History Tracking**: Browse past interactions
- **Statistics**: Token usage and performance metrics

### 🔄 Auto-Updates
- **Background Checks**: Automatic update detection on startup
- **Smart Notifications**: Context-aware update suggestions
- **One-Click Updates**: Integrated update commands
- **Version Management**: Comprehensive version tracking

### 🧭 Plan & Activity
- **Plan Panel**: Osiris auto-generates plans for multi-step prompts and keeps them visible with `/plan`.
- **Activity Log**: Use `/activity` to review recent tool usage, commands, and guard decisions.
- **Safe Demo**: Hit `/demo` to run a non-destructive sequence (list, tree) that shows how tools behave without writing files.

### 🧠 Scenario Templates (v4.1)
- **Overview & Diagnostics Playbooks**: Automatically detect prompts like “comprehensive overview” or “run tests” and preload the right docs.
- **Autonomous Follow-ups**: Tool loops extend themselves for scenario work; the agent produces a final report even after long tool chains.
- **Repo Insights Tools**: New `summarize_repo_structure` and `collect_project_insights` tools expose project metadata to the model without leaving the CLI.
- **Session Summaries & History**: Every run is logged and summarized to disk, mirroring Gemini CLI’s “always end with a report” behavior.
- **Persistent Shell Tooling**: `run_shell_command` now reuses a maintained working directory so multi-step Bash workflows behave like Letta’s agents.

### 🛒 Plugin Marketplace (v5.3.0)
- **Plugin Discovery**: Browse and search community-created plugins
- **One-Click Installation**: Install plugins directly from the marketplace
- **Developer Publishing**: Submit and manage your own plugins
- **Plugin Categories**: Tools, themes, providers, workflows, and more
- **Rating & Reviews**: Community feedback and quality metrics

## 🚀 Quick Start

### Installation
```bash
# Install from PyPI (recommended)
pip install osiris-cli

# Or install from source
git clone https://github.com/The-Osiris-Labs/osiris-cli.git
cd osiris-cli
pip install -e .
```

**Auto-Updates**: Osiris CLI automatically checks for updates on startup and provides one-click upgrade commands.

Recommended (macOS/Homebrew):
```bash
brew install python@3.13
export OSIRIS_PYTHON=/opt/homebrew/opt/python@3.13/bin/python3.13
./scripts/bootstrap_venv.sh
```

### Optional: Web Search (googler + Bing RSS + lynx)
`web_search` uses `googler` and falls back to Bing RSS and `lynx` when needed. Install once:
```bash
./scripts/install_googler.sh
```
If you prefer manual install:
```bash
sudo curl -o /usr/local/bin/googler https://raw.githubusercontent.com/jarun/googler/v4.3.2/googler
sudo chmod +x /usr/local/bin/googler
```

### Configuration
```bash
# Set up API keys
export OPENAI_[REDACTED_SECRET]
export ANTHROPIC_[REDACTED_SECRET]
# ... other providers as needed
```

Tracking verbosity can be adjusted in `~/.osiris/config.toml`:
```toml
tracking_mode = "standard" # minimal | standard | verbose
tracking_min_tools = 2
tracking_min_steps = 2
```

### Launch
```bash
# Start the interactive CLI
osiris

# Or run directly
python -c "from src.osiris_cli.main import _run_interactive_mode; _run_interactive_mode()"

# One-shot prompt (print mode)
osiris -p "Summarize the repo"

# One-shot with stdin
cat README.md | osiris -p "Summarize this file"
```

### If `osiris` fails to import modules
```bash
./scripts/bootstrap_venv.sh
```
If your venv was created with an older system Python, remove it first:
```bash
rm -rf .venv
./scripts/bootstrap_venv.sh
```

## 📚 Documentation

Browse the organized docs at `docs/README.md`.

## 🎮 Usage Guide

### Navigation
```
↑↓←→  Navigate between sections and items
Enter  Select current item
1-9    Quick select first 9 options
Q      Quit or go back
?      Show help
```

### Input Shortcuts
```
!cmd         Run a shell command and keep output in context
@path        Attach a file into the next prompt context
#key:value   Remember a fact into agent memory
```

### Tracking Control
```
/tracking
/tracking minimal
/tracking standard 2 2
/tracking verbose
```

### Plan Mode Shortcuts
```
/plan                Show the current plan
/plan create Title | Description | Step1 | Step2...
/plan continue       Start the next pending step
/plan complete 2     Mark step 2 as finished
/plan list           List saved plans
/plan load plan_id   Load a saved plan
```

### Details Drawer
```
/details            Toggle the hidden details drawer (activity log + plan history)
```

### Automatic Planning
Osiris auto-detects multi-step tasks and generates a Claude-like plan (with plan_mode) before executing tools. Just describe the task; you don’t need to issue `/plan`.

### Main Dashboard

#### 🚀 Quick Actions
- **Start Chat**: Begin AI conversation
- **Command Palette**: Search commands
- **Help & Docs**: Documentation access

#### 🛠️ AI Tools
- **Tool Manager**: Browse available tools
- **Context Files**: Manage file context
- **Model Settings**: Change AI configuration

#### 💾 Session Hub
- **Load Session**: Resume conversations
- **Save Session**: Preserve chats
- **Session History**: Browse saved sessions

#### ⚙️ System
- **System Status**: Performance metrics
- **Preferences**: Customize settings
- **Exit**: Quit application

### Example Session
```bash
$ osiris
# Welcome screen appears
# Navigate with arrow keys to "Start Chat"
# Press Enter to begin conversation

You: Hello! Can you help me analyze this Python file?

# AI responds with streaming text
# Automatically uses read_file tool when relevant
# Results displayed in formatted panels
```

## 🔧 Configuration

### Environment Variables
```bash
# Required - at least one provider
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
GROQ_API_KEY=...
DEEPSEEK_API_KEY=...
```

### Settings File
Located at `~/.osiris/config.toml`:
```toml
[settings]
provider = "openai"          # openai, anthropic, google, groq
default_model = "gpt-4"      # Model name
temperature = 0.7           # Response creativity (0.0-2.0)
max_tokens = 4000           # Maximum response length
timeout = 30                # Request timeout (seconds)
theme = "default"           # UI theme
yolo_mode = false           # Enable autonomous mode
reasoning_mode = false      # Enhanced reasoning
```

## 🏗️ Architecture

```
osiris-cli/
├── src/osiris_cli/
│   ├── minimal_cli.py   # Main v4.0 interactive hub
│   ├── client.py        # Resilient AI client
│   ├── config.py        # Settings & security
│   ├── tools.py         # Autonomous tools
│   ├── enhanced_cli.py  # Dashboard interface (TUI)
│   ├── context.py       # AGI context management
│   └── main.py          # Entry point dispatcher
```

### Key Components

- **ModernMenu**: Card-based navigation system
- **EnhancedOsirisCLI**: Main application orchestrator
- **ToolRegistry**: Extensible tool framework
- **SessionManager**: Conversation persistence
- **ContextManager**: File integration system

## 🛠️ Development

### Adding Tools
```python
from .tools import tool_registry

@tool_registry.register(
    name="my_tool",
    description="Custom tool functionality",
    parameters={
        "type": "object",
        "properties": {
            "input": {"type": "string", "description": "Input parameter"}
        }
    }
)
async def my_tool(input: str) -> str:
    # Implementation
    return f"Result: {input}"
```

### Custom Menu Sections
```python
# Add to sections list in show_main_menu()
{
    "title": "My Features",
    "icon": "🎯",
    "items": [
        {"name": "My Action", "description": "Description", "action": "my_action"}
    ]
}
```

## 📊 Performance

- **Response Time**: <2s average for standard queries
- **Memory Usage**: ~50MB baseline, scales with context
- **Concurrent Sessions**: Unlimited (disk-backed)
- **Tool Execution**: Sandboxed and secure
- **Terminal Support**: 40-200+ columns, all modern terminals

## 🔒 Security

- **API Keys**: Stored locally in `~/.osiris/config.toml` for reuse across sessions
- **Tool Sandboxing**: Safe execution with user confirmation
- **HTTPS Only**: Secure communication with providers
- **Input Validation**: Comprehensive parameter checking
- **Error Isolation**: Failures contained within components

## 🤝 Contributing

We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details.

### Quick Setup for Contributors
```bash
git clone <repository>
cd osiris-cli
pip install -e ".[dev]"
pytest  # Run tests
```

### Code Style
- **Black**: Code formatting
- **isort**: Import sorting
- **mypy**: Type checking
- **ruff**: Linting

---

## 🎯 Current Status

**Version**: 5.4.3 "Zen Edition"
**Status**: Production Ready
**Last Updated**: December 18, 2025

**Key Achievements:**
- Complete UI redesign with modern dashboard interface
- Real-time navigation with professional card-based layout
- Multi-provider AI integration with tool calling
- Responsive design working across all terminal sizes
- Comprehensive session and context management
- Extensible architecture for future enhancements

**Ready to transform your AI interactions?** 🚀

```bash
# The enhanced CLI provides enterprise-grade UX
osiris
```

## Quick Tips

- Use --help for commands
- Check logs with /activity