diff --git a/README.md b/README.md index d2507aa..3f1c086 100644 --- a/README.md +++ b/README.md @@ -1,300 +1,245 @@ -# Omnara - Native Mission Control for Your AI Agents 🚀 +# Omnara - Your AI Agent Command Center 🎯 -**Your AI workforce launchpad, in your pocket.** +**Monitor and control your AI workforce from anywhere. Never miss an agent question again.** -![Omnara Demo](./docs/assets/Mobile-app-showcase.gif) +![Omnara Mobile Experience](./docs/assets/three-panel.png) -• Launch & monitor Claude Code + Custom Agents \ -• Real-time logs & activity feed \ -• Interactive Q&A from your phone \ -• Push notifications for every critical moment +
-[📱 Download on App Store](https://apps.apple.com/us/app/omnara-ai-command-center/id6748426727) • [🌐 Try Web Version](https://omnara.ai) • [⭐ Star on GitHub](https://github.com/omnara-ai/omnara) +[📱 **Download iOS App**](https://apps.apple.com/us/app/omnara-ai-command-center/id6748426727) • [🌐 **Try Web Dashboard**](https://omnara.ai) • [⭐ **Star on GitHub**](https://github.com/omnara-ai/omnara) -## Why We Built This +
-We were tired of kicking off long agent jobs, leaving our desks, and returning hours later to find them stuck on a simple question or failing silently. +--- -We wanted peace of mind and the power to intervene from anywhere. So we built Omnara. +## 🚀 What is Omnara? -## 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. -Omnara is an open-source platform that lets you communicate with all your AI agents - Claude Code, Cursor, GitHub Copilot, and more - through one simple dashboard. No more wondering what your AI is up to or missing its questions! +### ✨ Key Features -### The Magic ✨ +| 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 Everything**: Watch your AI agents work in real-time, like having a window into their minds -- **Jump In Anytime**: When your agent asks "Should I refactor this?" or "Which approach do you prefer?", you'll see it instantly and can respond -- **Guide Your AI**: Send feedback and corrections while your agent is working - it'll see your messages and adjust course -- **Works Everywhere**: Whether you're on your phone, tablet, or another computer, you can check in on your agents -- **One Dashboard, All Agents**: Stop juggling between different tools - see all your AI assistants in one place +### 🎬 See It In Action -### Built on MCP (Model Context Protocol) +![Mobile Notifications](./docs/assets/iNotifications-Stack.gif) -We use the Model Context Protocol to make this all work seamlessly. Your agents can talk to Omnara, and Omnara talks to you. +> *The moment your agent needs help, you're there. No more returning to failed jobs hours later.* -## See It In Action +![Agent Activity Feed](./docs/assets/Mobile-app-showcase.gif) -![Notification Magic](./docs/assets/iNotifications-Stack.gif) +## 💡 Why Omnara? -The real magic is the feedback loop. Your agents don't have to fail silently anymore. +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 -When they need guidance → you get notified → you respond → the work continues. +**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 -It's the difference between a prototype and a production-ready AI workforce. +## 🏗️ Architecture Overview -## How It Works +Omnara uses the **Model Context Protocol (MCP)** to enable seamless communication between your agents and the dashboard. -A lightweight protocol wraps your agent with simple decorators (`log_step`, `ask_question`). We open a secure tunnel to your machine to stream its state in real-time. +```mermaid +graph TB + subgraph "Your AI Agents" + A[🤖 AI Agents
Claude, Cursor, Copilot] + end -```python -api_key = os.getenv("OMNARA_API_KEY") -agent_instance_id = os.getenv("AGENT_INSTANCE_ID") + subgraph "Omnara Platform" + S[🔄 MCP Server] + DB[(📊 Database)] + API[🌐 API Server] + end -client = OmnaraClient(api_key=api_key) + subgraph "Your Devices" + M[📱 Mobile App] + W[💻 Web Dashboard] + end -response = client.log_step( - agent_type="claude-code", - agent_instance_id=agent_instance_id, - step_description="Analyzing the current website structure", -) + A -->|Log activities| S + S -->|Store data| DB + DB -->|Real-time sync| API + API -->|Push updates| M + API -->|Push updates| W + M -->|Send feedback| API + W -->|Send feedback| API + API -->|Store feedback| DB + S <-->|Agent queries| DB + + style A fill:#e3f2fd,stroke:#1976d2,stroke-width:3px + style S fill:#c8e6c9,stroke:#388e3c,stroke-width:2px + style DB fill:#ffccbc,stroke:#d84315,stroke-width:2px + style API fill:#c8e6c9,stroke:#388e3c,stroke-width:2px + style M fill:#f8bbd0,stroke:#c2185b,stroke-width:3px + style W fill:#f8bbd0,stroke:#c2185b,stroke-width:3px ``` -And we're completely open source. Check out the repo and monitor your first agent in minutes. +### 🔧 Technical Stack -## Project Architecture +- **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) -### Core Components +## 🚀 Quick Start -``` -omnara/ -├── backend/ # Web dashboard API (FastAPI) -├── servers/ # Agent write operations server (MCP + REST) -├── shared/ # Database models and shared infrastructure -├── omnara/ # Python package directory -│ └── sdk/ # Python SDK for agent integration -├── cli/ # Node.js CLI tool for MCP configuration -├── scripts/ # Development and utility scripts -└── webhooks/ # Webhook handlers -``` +### For Users -### System Architecture +1. **Download the app** or visit [omnara.ai](https://omnara.ai) +2. **Create an account** and generate an API key +3. **Configure your agent** with the API key +4. **Start monitoring** your AI workforce! -1. **Backend API** (`backend/`) - - FastAPI application serving the web dashboard - - Handles read operations and user authentication via Supabase - - Manages API key generation and user sessions +### For Developers -2. **Servers** (`servers/`) - - Unified server supporting both MCP and REST protocols - - Processes all write operations from AI agents - - Implements JWT authentication with optimized token length - -3. **Shared Infrastructure** (`shared/`) - - Database models and migration management - - Common utilities and configuration - - Ensures consistency across all services - - -### Data Flow - -``` -AI Agents → MCP/REST Server (Write) → PostgreSQL ← Backend API (Read) ← Web Dashboard -``` - -### Billing & Monetization (Optional) - -Omnara includes optional Stripe integration for SaaS deployments: - -- **Free Tier**: 20 agents per month -- **Pro Tier ($9/mo)**: Unlimited agents -- **Enterprise Tier ([Schedule a Call](https://cal.com/ishaan-sehgal-8kc22w/omnara-demo))**: Unlimited agents + Teams, dedicated support, custom integrations+notifications and more - -Billing is only enforced when explicitly configured with Stripe keys. - -## Development Setup - -### Prerequisites +
+🛠️ Development Setup +#### Prerequisites - Python 3.10+ - PostgreSQL -- Make (for development commands) +- Node.js (for CLI tools) -### Quick Start +#### Setup Steps -1. **Clone the repository** +1. **Clone and enter the repository** ```bash - git clone + git clone https://github.com/omnara-ai/omnara cd omnara ``` 2. **Set up Python environment** ```bash python -m venv .venv - source .venv/bin/activate # On Windows: .venv\Scripts\activate + source .venv/bin/activate # Windows: .venv\Scripts\activate + make dev-install ``` -3. **Install dependencies and development tools** - ```bash - make dev-install # Install all Python dependencies - make pre-commit-install # Set up code quality hooks - ``` - -4. **Generate JWT keys for agent authentication** +3. **Generate JWT keys** ```bash python scripts/generate_jwt_keys.py ``` -5. **Configure environment variables** - Create `.env` file in the root directory (see Environment Variables section) +4. **Configure environment** (create `.env` file) + ```env + 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...' + ``` -6. **Initialize database** +5. **Initialize database** ```bash cd shared/ alembic upgrade head cd .. ``` -7. **Run the services** +6. **Run services** ```bash - # Terminal 1: Unified server (MCP + REST) + # Terminal 1: MCP + REST Server python -m servers.app # Terminal 2: Backend API cd backend && python -m main ``` +
+ +## 📚 Integration Guide + +### Method 1: MCP Configuration +```json +{ + "mcpServers": { + "omnara": { + "url": "https://api.omnara.ai/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` + +### Method 2: Python SDK +```python +from omnara import OmnaraClient + +client = OmnaraClient(api_key="your-api-key") + +# Log progress and check for user feedback +response = client.log_step( + agent_type="claude-code", + step_description="Analyzing codebase structure" +) + +# Ask for user input when needed +answer = client.ask_question( + question="Should I refactor this legacy module?" +) +``` + +### Method 3: REST API +```bash +curl -X POST https://api.omnara.ai/api/v1/steps \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"step_description": "Starting deployment process"}' +``` + +## 🤝 Contributing + +We love contributions! Check out our [Contributing Guide](CONTRIBUTING.md) to get started. + ### Development Commands - ```bash -# Code quality -make lint # Run all linting and type checking -make format # Auto-format code -make pre-commit-run # Run pre-commit on all files - -# Testing -make test # Run all tests -make test-sdk # Test Python SDK -make test-integration # Run integration tests (requires Docker) - -# Database migrations -cd shared/ -alembic revision --autogenerate -m "Description" # Create migration -alembic upgrade head # Apply migrations +make lint # Run code quality checks +make format # Auto-format code +make test # Run test suite +make dev-serve # Start development servers ``` -### Code Quality +## 📊 Pricing -The project maintains high code quality standards through automated tooling: -- **Ruff** for Python linting and formatting -- **Pyright** for type checking -- **Pre-commit hooks** for automatic validation -- **Python 3.12** as the standard version +| Plan | Price | Features | +|------|-------|----------| +| **Free** | $0/mo | 20 agents/month, Core features | +| **Pro** | $9/mo | Unlimited agents, Priority support | +| **Enterprise** | [Contact Us](https://cal.com/ishaan-sehgal-8kc22w/omnara-demo) | Teams, SSO, Custom integrations | -## Environment Variables +## 🆘 Support -### Required Configuration +- 📖 [Documentation](https://docs.omnara.ai) +- 💬 [GitHub Discussions](https://github.com/omnara-ai/omnara/discussions) +- 🐛 [Report Issues](https://github.com/omnara-ai/omnara/issues) +- 📧 [Email Support](mailto:support@omnara.ai) -```bash -# Database -DATABASE_URL=postgresql://user:password@localhost:5432/omnara +## 📜 License -# Supabase (for web authentication) -SUPABASE_URL=https://your-project.supabase.co -SUPABASE_ANON_KEY=your-anon-key +Omnara is open source software licensed under the [MIT License](LICENSE). -# JWT Keys (from generate_jwt_keys.py) -JWT_PRIVATE_KEY='-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----' -JWT_PUBLIC_KEY='-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----' +--- -# Optional -ENVIRONMENT=development -API_PORT=8000 -MCP_SERVER_PORT=8080 -``` +
-## For AI Agent Developers +**Built with ❤️ by the Omnara team** -### Getting Started +[Website](https://omnara.ai) • [Twitter](https://twitter.com/omnara_ai) • [LinkedIn](https://linkedin.com/company/omnara) -1. Sign up at the Omnara dashboard -2. Generate an API key from the dashboard -3. Configure your agent with the API key -4. Use either MCP protocol or REST API to interact - -### Available Tools/Endpoints - -- **log_step**: Log progress and receive user feedback -- **ask_question**: Request user input (non-blocking) -- **end_session**: Mark agent session as completed - -### Integration Options - -1. **MCP Protocol** (for compatible agents) - ```json - { - "mcpServers": { - "omnara": { - "url": "http://localhost:8080/mcp", - "headers": { - "Authorization": "Bearer YOUR_API_KEY" - } - } - } - } - ``` - -2. **REST API** (for direct integration) - - POST `/api/v1/steps` - - POST `/api/v1/questions` - - POST `/api/v1/sessions/end` - -3. **Python SDK** (available on PyPI) - ```bash - pip install omnara - ``` - -## Database Management - -### Working with Migrations - -```bash -cd shared/ - -# Check current migration -alembic current - -# Create new migration after model changes -alembic revision --autogenerate -m "Add new feature" - -# Apply pending migrations -alembic upgrade head - -# Rollback one migration -alembic downgrade -1 -``` - -**Important**: Always create migrations when modifying database models. Pre-commit hooks enforce this requirement. - -## Contributing - -We welcome contributions to this open-source project. Here's how you can help: - -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Make your changes -4. Run tests and ensure code quality checks pass -5. Commit your changes (`git commit -m 'Add amazing feature'`) -6. Push to your branch (`git push origin feature/amazing-feature`) -7. Open a Pull Request - - -## Support - -- **Issues**: Report bugs or request features via GitHub Issues -- **Discussions**: Join the conversation in GitHub Discussions -- **Documentation**: Check the project documentation for detailed guides - -## License - -Open source and free to use! Check the LICENSE file for details. +
\ No newline at end of file diff --git a/docs/architecture-diagram.md b/docs/architecture-diagram.md new file mode 100644 index 0000000..2aabb48 --- /dev/null +++ b/docs/architecture-diagram.md @@ -0,0 +1,148 @@ +# Omnara Architecture Diagram + +```mermaid +graph TB + subgraph "AI Agents" + A1[Claude Code] + A2[Cursor] + A3[GitHub Copilot] + A4[Custom Agents] + end + + subgraph "Client Applications" + C1[iOS App] + C2[Web Dashboard] + C3[Android App] + end + + subgraph "Omnara Platform" + subgraph "API Layer" + API1[Backend API
FastAPI - Read Ops] + API2[Servers API
FastAPI + MCP - Write Ops] + end + + subgraph "Authentication" + AUTH1[Supabase Auth
Web Users] + AUTH2[Custom JWT
Agent Auth] + end + + subgraph "Data Layer" + DB[(PostgreSQL
Database)] + CACHE[Redis Cache
Optional] + end + + subgraph "Integration Layer" + SDK[Python SDK] + CLI[Node.js CLI] + MCP[MCP Protocol] + REST[REST API] + end + end + + subgraph "External Services" + SUP[Supabase] + STRIPE[Stripe
Optional] + PUSH[Push Notifications
APNs/FCM] + end + + %% Agent connections + A1 --> MCP + A2 --> MCP + A3 --> REST + A4 --> SDK + + %% Integration to Servers + MCP --> API2 + REST --> API2 + SDK --> API2 + CLI --> API2 + + %% Client connections + C1 --> API1 + C2 --> API1 + C3 --> API1 + + %% API to Database + API1 --> DB + API2 --> DB + API1 -.-> CACHE + API2 -.-> CACHE + + %% Authentication flows + API1 --> AUTH1 + API2 --> AUTH2 + AUTH1 --> SUP + + %% External services + API1 --> STRIPE + API1 --> PUSH + + %% Styling + classDef agents fill:#e1f5fe,stroke:#01579b,stroke-width:2px + classDef clients fill:#f3e5f5,stroke:#4a148c,stroke-width:2px + classDef api fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px + classDef auth fill:#fff3e0,stroke:#e65100,stroke-width:2px + classDef data fill:#fce4ec,stroke:#880e4f,stroke-width:2px + classDef external fill:#f5f5f5,stroke:#424242,stroke-width:2px + + class A1,A2,A3,A4 agents + class C1,C2,C3 clients + class API1,API2 api + class AUTH1,AUTH2 auth + class DB,CACHE data + class SUP,STRIPE,PUSH external +``` + +## Data Flow Diagram + +```mermaid +sequenceDiagram + participant Agent as AI Agent + participant MCP as MCP Server + participant DB as Database + participant API as Backend API + participant App as Mobile App + participant User as User + + Agent->>MCP: log_step("Analyzing code") + MCP->>DB: Store step + DB->>API: Real-time update + API->>App: Push notification + App->>User: "Agent needs input" + + User->>App: Provides feedback + App->>API: Send feedback + API->>DB: Store feedback + + Agent->>MCP: Check for feedback + MCP->>DB: Query feedback + DB->>MCP: Return feedback + MCP->>Agent: User feedback + + Agent->>Agent: Adjust approach + Agent->>MCP: log_step("Implementing changes") +``` + +## Component Interaction Diagram + +```mermaid +graph LR + subgraph "Write Path" + A[Agents] -->|log_step| S[Servers
:8080] + A -->|ask_question| S + S -->|Write| D[(Database)] + end + + subgraph "Read Path" + D -->|Query| B[Backend
:8000] + B -->|WebSocket/REST| W[Web/Mobile] + W -->|Feedback| B + B -->|Store| D + end + + style A fill:#e3f2fd + style S fill:#c8e6c9 + style D fill:#ffccbc + style B fill:#c8e6c9 + style W fill:#f8bbd0 +``` \ No newline at end of file diff --git a/docs/assets/three-panel.png b/docs/assets/three-panel.png new file mode 100644 index 0000000..2dfb390 Binary files /dev/null and b/docs/assets/three-panel.png differ