omnara 1.4.13

Omnara Agent Dashboard - MCP Server and Python SDK

Omnara - Mission Control for Your AI Agents 🚀

Your AI workforce, in your pocket.

📱 Download iOS App • 🌐 Try Web Dashboard • 🎥 See a Demo • ⭐ Star on GitHub

---

🚀 What is Omnara?

Omnara transforms your AI agents (Claude Code, Cursor, GitHub Copilot, and more) from silent workers into communicative teammates. Get real-time visibility into what your agents are doing, respond to their questions instantly, and guide them to success - all from your phone.

✨ Key Features

Feature	Description
📊 Real-Time Monitoring	See every step your AI agents take as they work
💬 Interactive Q&A	Respond instantly when agents need guidance
📱 Mobile-First Design	Full control from your phone, tablet, or desktop
🔔 Smart Notifications	Get alerted only when your input is needed
🎯 Universal Dashboard	All your AI agents in one unified interface

🎬 See It In Action

The moment your agent needs help, you're there. No more returning to failed jobs hours later.

💡 Why Omnara?

We built Omnara because we were tired of:

• ❌ Starting long agent jobs and finding them stuck hours later
• ❌ Missing critical questions that blocked progress
• ❌ Having no visibility into what our AI was actually doing
• ❌ Being tied to our desks while agents worked

Now you can:

• ✅ Launch agents and monitor them from anywhere
• ✅ Get push notifications when input is needed
• ✅ Send real-time feedback to guide your agents
• ✅ Have confidence your AI workforce is productive

🎯 Real-World Use Cases

🔍 Code Review Assistant

Launch Claude to review PRs while you're at lunch. Get notified only if it needs clarification on architectural decisions.

🚨 Production Firefighter

Debug production issues from your phone at 2am. See exactly what your agent is investigating and guide it to the right logs.

📊 Data Pipeline Guardian

Start a 6-hour data migration before leaving work. Get alerts if anything looks suspicious, approve schema changes on the go.

🏗️ Refactoring Copilot

Let Claude refactor that legacy module while you're in meetings. Answer its questions about business logic without context switching.

🧪 Test Suite Doctor

Have Claude fix failing tests overnight. Wake up to either green builds or specific questions about expected behavior.

🏗️ Architecture Overview

Omnara provides a unified platform for monitoring and controlling your AI agents:

graph TB
    subgraph "Your AI Agents"
        A[🤖 AI Agents<br/>Claude Code, Cursor, etc.]
    end

    subgraph "Omnara Platform"
        API[🌐 API Server]
        DB[(📊 PostgreSQL)]
        NOTIFY[🔔 Notification Service<br/>Push/Email/SMS]
    end

    subgraph "Your Devices"
        M[📱 Mobile App]
        W[💻 Web Dashboard]
    end

    A -->|Send updates| API
    API -->|Store data| DB
    API -->|Trigger notifications| NOTIFY
    NOTIFY -->|Alert users| M
    DB -->|Real-time sync| M
    DB -->|Real-time sync| W
    M -->|User responses| API
    W -->|User responses| API
    API -->|Deliver feedback| A

    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:3px
    style API fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
    style DB fill:#ffccbc,stroke:#d84315,stroke-width:2px
    style NOTIFY fill:#fff59d,stroke:#f57f17,stroke-width:2px
    style M fill:#f8bbd0,stroke:#c2185b,stroke-width:3px
    style W fill:#f8bbd0,stroke:#c2185b,stroke-width:3px

🚀 How It Works

1. Connect Your Agent → Install Omnara SDK or wrapper
2. Get Real-Time Updates → See every step your agent takes
3. Respond Instantly → Answer questions from anywhere

🔄 Two Ways to Use Omnara

Mode	Setup	How It Works
Real-Time Monitoring	omnara or uv run omnara	Monitor your Claude session, forwards to Omnara
Remote Launch	omnara serve or uv run omnara serve	Launch agents from phone, communicate via MCP

🔧 Technical Stack

• Backend: FastAPI with separate read/write servers for optimal performance
• Frontend: React (Web) + React Native (Mobile)
• Protocol: Model Context Protocol (MCP) + REST API
• Database: PostgreSQL with SQLAlchemy ORM
• Auth: Dual JWT system (Supabase for users, custom for agents)

🚀 Quick Start

Option 1: Monitor Your Claude Sessions

See what Claude is doing in real-time:

1. Install Omnara:

   # Using pip
   pip install omnara
   
   # Using uv (faster)
   uv pip install omnara
   

2. Start monitoring:

   # If installed with pip
   omnara
   
   # If installed with uv
   uv run omnara
   

3. Authenticate in your browser (opens automatically)
4. See everything your agent does in the Omnara dashboard!

Option 2: Launch Agents Remotely

Trigger Claude from your phone:

1. Start the server on your computer:

   # Using pip
   pip install omnara
   omnara serve
   
   # Using uv (faster)
   uv pip install omnara
   uv run omnara serve
   

2. Set up your agent in the mobile app with the webhook URL shown
3. Launch agents from anywhere - beach, coffee shop, bed!

For Developers

🛠️ Development Setup

Prerequisites

• Python 3.10+
• PostgreSQL
• Node.js (for CLI tools)

Setup Steps

1. Clone and enter the repository

   git clone https://github.com/omnara-ai/omnara
   cd omnara
   

2. Set up Python environment

   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   make dev-install
   

3. Generate JWT keys

   python scripts/generate_jwt_keys.py
   

4. Configure environment (create .env file)

   DATABASE_URL=postgresql://user:password@localhost:5432/omnara
   SUPABASE_URL=https://your-project.supabase.co
   SUPABASE_ANON_KEY=your-anon-key
   JWT_PRIVATE_KEY='-----BEGIN RSA PRIVATE KEY-----\n...'
   JWT_PUBLIC_KEY='-----BEGIN PUBLIC KEY-----\n...'
   

5. Initialize database

   cd shared/
   alembic upgrade head
   cd ..
   

6. Run services

   # Terminal 1: MCP + REST Server
   python -m servers.app
   
   # Terminal 2: Backend API
   cd backend && python -m main
   

🔧 Advanced Usage (Without CLI)

Note: Most users should use the simple omnara or omnara serve commands shown above. These methods are for advanced users who need custom integrations or want to run the underlying scripts directly.

Method 1: Direct Wrapper Script

Run the monitoring wrapper directly (what omnara does under the hood):

# Basic usage
python -m webhooks.claude_wrapper_v3 --api-key YOUR_API_KEY

# With git diff tracking
python -m webhooks.claude_wrapper_v3 --api-key YOUR_API_KEY --git-diff

# Custom API endpoint (for self-hosted)
python -m webhooks.claude_wrapper_v3 --api-key YOUR_API_KEY --base-url https://your-server.com

Method 2: Manual MCP Configuration

For custom MCP setups, you can configure manually:

{
  "mcpServers": {
    "omnara": {
      "command": "pipx",
      "args": ["run", "--no-cache", "omnara", "mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

Method 3: Python SDK

from omnara import OmnaraClient
import uuid

client = OmnaraClient(api_key="your-api-key")
instance_id = str(uuid.uuid4())

# Log progress and check for user feedback
response = client.send_message(
    agent_type="claude-code",
    content="Analyzing codebase structure",
    agent_instance_id=instance_id,
    requires_user_input=False
)

# Ask for user input when needed
answer = client.send_message(
    content="Should I refactor this legacy module?",
    agent_instance_id=instance_id,
    requires_user_input=True
)

Method 4: REST API

curl -X POST https://api.omnara.ai/api/v1/messages/agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Starting deployment process", "agent_type": "claude-code", "requires_user_input": false}'

🤝 Contributing

We love contributions! Check out our Contributing Guide to get started.

Development Commands

make lint       # Run code quality checks
make format     # Auto-format code
make test       # Run test suite
make dev-serve  # Start development servers

📊 Pricing

Plan	Price	Features
Free	$0/mo	10 agents/month, Core features
Pro	$9/mo	Unlimited agents, Priority support
Enterprise	Contact Us	Teams, SSO, Custom integrations

🆘 Support

• 💬 GitHub Discussions
• 🐛 Report Issues
• 📧 Email Support
• 📖 Documentation (coming soon)

📜 License

Omnara is open source software licensed under the Apache 2.0 License.

---

Built with ❤️ by the Omnara team

Website • Twitter • LinkedIn