OSIRIS CLI - Sovereign AGI Terminal Interface

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

✨ 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

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

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:

./scripts/install_googler.sh

If you prefer manual install:

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

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

tracking_mode = "standard" # minimal | standard | verbose
tracking_min_tools = 2
tracking_min_steps = 2

Launch

# 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

./scripts/bootstrap_venv.sh

If your venv was created with an older system Python, remove it first:

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

$ 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

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

[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

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

# 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 for details.

Quick Setup for Contributors

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? 🚀

# The enhanced CLI provides enterprise-grade UX
osiris

Quick Tips

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