diff --git a/README.md b/README.md index 39f80b3..a928d81 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,23 @@ We built Omnara because we were tired of: - โœ… 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: @@ -98,123 +115,18 @@ graph TB style W fill:#f8bbd0,stroke:#c2185b,stroke-width:3px ``` -Omnara supports two distinct modes of operation: +### ๐Ÿš€ How It Works -### Mode 1: Real-Time Claude Code Monitoring +**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 -When you run Claude Code locally with the Omnara wrapper, it monitors your agent's activity in real-time: +### ๐Ÿ”„ Two Ways to Use Omnara -```mermaid -graph TB - subgraph "Your Local Machine" - CC[๐Ÿค– Claude Code] - CW[๐Ÿ“Š Claude Wrapper
claude_wrapper_v3.py] - LOG[๐Ÿ“„ JSONL Logs
~/.claude/projects/] - TERM[๐Ÿ–ฅ๏ธ Terminal Output] - end - - subgraph "Omnara Platform" - API[๐ŸŒ REST API Server] - DB[(๐Ÿ“Š PostgreSQL)] - SSE[๐Ÿ“ก SSE Endpoint] - NOTIFY[๐Ÿ”” Notification Service
Push/Email/SMS] - end - - subgraph "Your Devices" - M[๐Ÿ“ฑ Mobile App] - W[๐Ÿ’ป Web Dashboard] - end - - CC -->|Writes logs| LOG - CC -->|Displays output| TERM - CW -->|Monitors| LOG - CW -->|Watches| TERM - CW -->|Sends messages via REST| API - API -->|Stores messages| DB - API -->|Triggers notifications| NOTIFY - DB -->|NOTIFY triggers| SSE - SSE -->|Real-time updates| M - SSE -->|Real-time updates| W - NOTIFY -->|Push/Email/SMS| M - M -->|User responses| API - W -->|User responses| API - API -->|Queued messages| CW - CW -->|Types into| CC - - style CC fill:#e3f2fd,stroke:#1976d2,stroke-width:3px - style CW fill:#fff59d,stroke:#f57f17,stroke-width:2px - style API fill:#c8e6c9,stroke:#388e3c,stroke-width:2px - style DB fill:#ffccbc,stroke:#d84315,stroke-width:2px - style NOTIFY fill:#ffe082,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:** -- The wrapper monitors Claude's JSONL log files and terminal output -- It identifies questions by detecting idle states and parsing terminal prompts -- Messages are sent to Omnara via REST API with `requires_user_input` flag -- PostgreSQL triggers send real-time notifications via SSE -- Users receive push/email/SMS notifications for questions -- Responses are injected back into Claude's terminal - -### Mode 2: Remote Agent Launch via Webhook - -When you trigger an agent remotely from Omnara, it uses the Model Context Protocol (MCP): - -```mermaid -graph TB - subgraph "Omnara Platform" - UI[๐ŸŒ Web/Mobile UI] - API[๐ŸŒ API Server
+ MCP Endpoint] - DB[(๐Ÿ“Š PostgreSQL)] - SSE[๐Ÿ“ก SSE Endpoint] - end - - subgraph "Your Computer" - WH[๐Ÿ”— Webhook Server
claude_code.py] - CT[โ˜๏ธ Cloudflare Tunnel
optional] - CC[๐Ÿค– Claude Code
w/ MCP Config] - end - - UI -->|Trigger agent| API - API -->|POST webhook| CT - CT -->|Forward request| WH - WH -->|Launch Claude| CC - CC -->|log_step/ask_question
via MCP| API - API -->|Store messages| DB - DB -->|Real-time updates| SSE - SSE -->|Push updates| UI - UI -->|User responses| API - API -->|Return answers
via MCP| CC - - style UI fill:#f8bbd0,stroke:#c2185b,stroke-width:3px - style WH fill:#fff59d,stroke:#f57f17,stroke-width:2px - style CC 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 SSE fill:#dcedc8,stroke:#689f38,stroke-width:2px -``` - -**How it works:** -- User triggers an agent from the Omnara interface -- Webhook server receives the request (optionally via Cloudflare tunnel) -- Claude is launched with MCP configuration pointing to Omnara -- The system prompt enforces Omnara-only communication (no terminal output) -- All communication flows through `log_step` and `ask_question` MCP tools -- Questions are explicitly marked with `requires_user_input=true` - -### ๐Ÿ”„ Mode Comparison - -| Feature | Real-Time Monitoring | Remote Launch | -|---------|---------------------|---------------| -| **Best for** | Local development | Remote automation | -| **Setup complexity** | Simple (just run wrapper) | Moderate (webhook + tunnel) | -| **Claude output visible** | Yes (in terminal) | No (MCP only) | -| **Question detection** | Automatic (terminal parsing) | Explicit (ask_question) | -| **Git isolation** | Uses current directory | Creates worktrees | -| **Parallel sessions** | Not recommended | Fully supported | -| **Network requirements** | API access only | Webhook endpoint | +| 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 @@ -226,34 +138,45 @@ graph TB ## ๐Ÿš€ Quick Start -### Option 1: Real-Time Monitoring (Recommended for local development) +### Option 1: Monitor Your Claude Sessions -Monitor your Claude Code sessions in real-time: +See what Claude is doing in real-time: -1. **Download the app** or visit [omnara.ai](https://omnara.ai) -2. **Get your API key** from the dashboard -3. **Run Claude with the wrapper**: +1. **Install Omnara**: ```bash - python -m webhooks.claude_wrapper_v3 --api-key YOUR_API_KEY + # Using pip + pip install omnara + + # Using uv (faster) + uv pip install omnara ``` +2. **Start monitoring**: + ```bash + # 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: Remote Agent Launch (For triggering agents from anywhere) +### Option 2: Launch Agents Remotely -Launch Claude Code remotely from your phone or web browser: +Trigger Claude from your phone: -1. **Download the app** or visit [omnara.ai](https://omnara.ai) -2. **Install Omnara CLI**: +1. **Start the server** on your computer: ```bash + # Using pip pip install omnara - # or with uv: uv pip install omnara - ``` -3. **Start the webhook server** on your computer: - ```bash omnara serve + + # Using uv (faster) + uv pip install omnara + uv run omnara serve ``` -4. **Create your agent** with the webhook URL and API key shown -5. **Trigger agents remotely** from anywhere! +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 @@ -312,11 +235,13 @@ Launch Claude Code remotely from your phone or web browser: -## ๐Ÿ“š Integration Guide +## ๐Ÿ”ง Advanced Usage (Without CLI) -### Method 1: Real-Time Monitoring with Wrapper +> **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. -Run Claude Code with the Omnara wrapper for automatic monitoring: +### Method 1: Direct Wrapper Script + +Run the monitoring wrapper directly (what `omnara` does under the hood): ```bash # Basic usage @@ -329,9 +254,9 @@ python -m webhooks.claude_wrapper_v3 --api-key YOUR_API_KEY --git-diff python -m webhooks.claude_wrapper_v3 --api-key YOUR_API_KEY --base-url https://your-server.com ``` -### Method 2: Remote Launch with MCP +### Method 2: Manual MCP Configuration -For remote agent launching, the webhook automatically configures MCP: +For custom MCP setups, you can configure manually: ```json {