omnara

Name	omnara JSON
Version	1.2.0 JSON
	download
home_page	None
Summary	Omnara Agent Dashboard - MCP Server and Python SDK
upload_time	2025-07-09 21:34:51
maintainer	None
docs_url	None
author	None
requires_python	>=3.11
license	MIT License Copyright 2025 Omnara Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords	mcp ai agents dashboard human-in-the-loop claude-code
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Omnara - Talk to Your AI Agents from Anywhere! 🚀

Ever wished you could peek into what your AI coding assistants are doing? Or help them when they get stuck? That's exactly what Omnara does!

## What is Omnara?

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!

### The Magic ✨

- **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

### Built on MCP (Model Context Protocol)

We use the Model Context Protocol to make this all work seamlessly. Your agents can talk to Omnara, and Omnara talks to you.

## Project Architecture

### Core Components

```
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
```

### System Architecture

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

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
```

## Development Setup

### Prerequisites

- Python 3.12
- PostgreSQL
- Make (for development commands)

### Quick Start

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd omnara
   ```

2. **Set up Python environment**
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

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**
   ```bash
   python scripts/generate_jwt_keys.py
   ```

5. **Configure environment variables**
   Create `.env` file in the root directory (see Environment Variables section)

6. **Initialize database**
   ```bash
   cd shared/
   alembic upgrade head
   cd ..
   ```

7. **Run the services**
   ```bash
   # Terminal 1: Unified server (MCP + REST)
   python -m servers.app
   
   # Terminal 2: Backend API
   cd backend && python -m main
   ```

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

### Code Quality

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

## Environment Variables

### Required Configuration

```bash
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/omnara

# Supabase (for web authentication)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key

# 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

### Getting Started

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.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "omnara",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.11",
    "maintainer_email": null,
    "keywords": "mcp, ai, agents, dashboard, human-in-the-loop, claude-code",
    "author": null,
    "author_email": "Omnara <ishaan@omnara.com>",
    "download_url": "https://files.pythonhosted.org/packages/42/d6/f40ac2c6ade2521697b4cb890f94ed7358b27618d78bcff3d27cc55204a1/omnara-1.2.0.tar.gz",
    "platform": null,
    "description": "# Omnara - Talk to Your AI Agents from Anywhere! \ud83d\ude80\n\nEver wished you could peek into what your AI coding assistants are doing? Or help them when they get stuck? That's exactly what Omnara does!\n\n## What is Omnara?\n\nOmnara 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!\n\n### The Magic \u2728\n\n- **See Everything**: Watch your AI agents work in real-time, like having a window into their minds\n- **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\n- **Guide Your AI**: Send feedback and corrections while your agent is working - it'll see your messages and adjust course\n- **Works Everywhere**: Whether you're on your phone, tablet, or another computer, you can check in on your agents\n- **One Dashboard, All Agents**: Stop juggling between different tools - see all your AI assistants in one place\n\n### Built on MCP (Model Context Protocol)\n\nWe use the Model Context Protocol to make this all work seamlessly. Your agents can talk to Omnara, and Omnara talks to you.\n\n## Project Architecture\n\n### Core Components\n\n```\nomnara/\n\u251c\u2500\u2500 backend/          # Web dashboard API (FastAPI)\n\u251c\u2500\u2500 servers/          # Agent write operations server (MCP + REST)\n\u251c\u2500\u2500 shared/           # Database models and shared infrastructure\n\u251c\u2500\u2500 omnara/           # Python package directory\n\u2502   \u2514\u2500\u2500 sdk/          # Python SDK for agent integration\n\u251c\u2500\u2500 cli/              # Node.js CLI tool for MCP configuration\n\u251c\u2500\u2500 scripts/          # Development and utility scripts\n\u2514\u2500\u2500 webhooks/         # Webhook handlers\n```\n\n### System Architecture\n\n1. **Backend API** (`backend/`)\n   - FastAPI application serving the web dashboard\n   - Handles read operations and user authentication via Supabase\n   - Manages API key generation and user sessions\n\n2. **Servers** (`servers/`)\n   - Unified server supporting both MCP and REST protocols\n   - Processes all write operations from AI agents\n   - Implements JWT authentication with optimized token length\n\n3. **Shared Infrastructure** (`shared/`)\n   - Database models and migration management\n   - Common utilities and configuration\n   - Ensures consistency across all services\n\n\n### Data Flow\n\n```\nAI Agents \u2192 MCP/REST Server (Write) \u2192 PostgreSQL \u2190 Backend API (Read) \u2190 Web Dashboard\n```\n\n## Development Setup\n\n### Prerequisites\n\n- Python 3.12\n- PostgreSQL\n- Make (for development commands)\n\n### Quick Start\n\n1. **Clone the repository**\n   ```bash\n   git clone <repository-url>\n   cd omnara\n   ```\n\n2. **Set up Python environment**\n   ```bash\n   python -m venv .venv\n   source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n   ```\n\n3. **Install dependencies and development tools**\n   ```bash\n   make dev-install          # Install all Python dependencies\n   make pre-commit-install   # Set up code quality hooks\n   ```\n\n4. **Generate JWT keys for agent authentication**\n   ```bash\n   python scripts/generate_jwt_keys.py\n   ```\n\n5. **Configure environment variables**\n   Create `.env` file in the root directory (see Environment Variables section)\n\n6. **Initialize database**\n   ```bash\n   cd shared/\n   alembic upgrade head\n   cd ..\n   ```\n\n7. **Run the services**\n   ```bash\n   # Terminal 1: Unified server (MCP + REST)\n   python -m servers.app\n   \n   # Terminal 2: Backend API\n   cd backend && python -m main\n   ```\n\n### Development Commands\n\n```bash\n# Code quality\nmake lint              # Run all linting and type checking\nmake format            # Auto-format code\nmake pre-commit-run    # Run pre-commit on all files\n\n# Testing\nmake test              # Run all tests\nmake test-sdk          # Test Python SDK\nmake test-integration  # Run integration tests (requires Docker)\n\n# Database migrations\ncd shared/\nalembic revision --autogenerate -m \"Description\"  # Create migration\nalembic upgrade head                              # Apply migrations\n```\n\n### Code Quality\n\nThe project maintains high code quality standards through automated tooling:\n- **Ruff** for Python linting and formatting\n- **Pyright** for type checking\n- **Pre-commit hooks** for automatic validation\n- **Python 3.12** as the standard version\n\n## Environment Variables\n\n### Required Configuration\n\n```bash\n# Database\nDATABASE_URL=postgresql://user:password@localhost:5432/omnara\n\n# Supabase (for web authentication)\nSUPABASE_URL=https://your-project.supabase.co\nSUPABASE_ANON_KEY=your-anon-key\n\n# JWT Keys (from generate_jwt_keys.py)\nJWT_PRIVATE_KEY='-----BEGIN RSA PRIVATE KEY-----\\n...\\n-----END RSA PRIVATE KEY-----'\nJWT_PUBLIC_KEY='-----BEGIN PUBLIC KEY-----\\n...\\n-----END PUBLIC KEY-----'\n\n# Optional\nENVIRONMENT=development\nAPI_PORT=8000\nMCP_SERVER_PORT=8080\n```\n\n## For AI Agent Developers\n\n### Getting Started\n\n1. Sign up at the Omnara dashboard\n2. Generate an API key from the dashboard\n3. Configure your agent with the API key\n4. Use either MCP protocol or REST API to interact\n\n### Available Tools/Endpoints\n\n- **log_step**: Log progress and receive user feedback\n- **ask_question**: Request user input (non-blocking)\n- **end_session**: Mark agent session as completed\n\n### Integration Options\n\n1. **MCP Protocol** (for compatible agents)\n   ```json\n   {\n     \"mcpServers\": {\n       \"omnara\": {\n         \"url\": \"http://localhost:8080/mcp\",\n         \"headers\": {\n           \"Authorization\": \"Bearer YOUR_API_KEY\"\n         }\n       }\n     }\n   }\n   ```\n\n2. **REST API** (for direct integration)\n   - POST `/api/v1/steps`\n   - POST `/api/v1/questions`\n   - POST `/api/v1/sessions/end`\n\n3. **Python SDK** (available on PyPI)\n   ```bash\n   pip install omnara\n   ```\n\n## Database Management\n\n### Working with Migrations\n\n```bash\ncd shared/\n\n# Check current migration\nalembic current\n\n# Create new migration after model changes\nalembic revision --autogenerate -m \"Add new feature\"\n\n# Apply pending migrations\nalembic upgrade head\n\n# Rollback one migration\nalembic downgrade -1\n```\n\n**Important**: Always create migrations when modifying database models. Pre-commit hooks enforce this requirement.\n\n## Contributing\n\nWe welcome contributions to this open-source project. Here's how you can help:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests and ensure code quality checks pass\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to your branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n\n## Support\n\n- **Issues**: Report bugs or request features via GitHub Issues\n- **Discussions**: Join the conversation in GitHub Discussions\n- **Documentation**: Check the project documentation for detailed guides\n\n## License\n\nOpen source and free to use! Check the LICENSE file for details.\n",
    "bugtrack_url": null,
    "license": "MIT License\n        \n        Copyright 2025 Omnara Contributors\n        \n        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \u201cSoftware\u201d), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n        \n        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n        \n        THE SOFTWARE IS PROVIDED \u201cAS IS\u201d, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
    "summary": "Omnara Agent Dashboard - MCP Server and Python SDK",
    "version": "1.2.0",
    "project_urls": {
        "Homepage": "https://github.com/omnara-ai/omnara",
        "Issues": "https://github.com/omnara-ai/omnara/issues",
        "Repository": "https://github.com/omnara-ai/omnara"
    },
    "split_keywords": [
        "mcp",
        " ai",
        " agents",
        " dashboard",
        " human-in-the-loop",
        " claude-code"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "70239371b9235dd3aae07c43f3df0a1eec71b3b41b2f51e62c3a1af9a7a57d0c",
                "md5": "407ac6ae792e6c0db3e478cafcea63bd",
                "sha256": "b42835b5b8de0d90daca3286728e8876b2c7bd4f6064823444fb0702f28611bf"
            },
            "downloads": -1,
            "filename": "omnara-1.2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "407ac6ae792e6c0db3e478cafcea63bd",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.11",
            "size": 28391,
            "upload_time": "2025-07-09T21:34:50",
            "upload_time_iso_8601": "2025-07-09T21:34:50.019601Z",
            "url": "https://files.pythonhosted.org/packages/70/23/9371b9235dd3aae07c43f3df0a1eec71b3b41b2f51e62c3a1af9a7a57d0c/omnara-1.2.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "42d6f40ac2c6ade2521697b4cb890f94ed7358b27618d78bcff3d27cc55204a1",
                "md5": "26dc748d066048c57e06413722c5d147",
                "sha256": "47b137728dfb32c36b82e3e8ec83deed64db8563eeb70ac41a762003e246f18f"
            },
            "downloads": -1,
            "filename": "omnara-1.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "26dc748d066048c57e06413722c5d147",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.11",
            "size": 23874,
            "upload_time": "2025-07-09T21:34:51",
            "upload_time_iso_8601": "2025-07-09T21:34:51.257201Z",
            "url": "https://files.pythonhosted.org/packages/42/d6/f40ac2c6ade2521697b4cb890f94ed7358b27618d78bcff3d27cc55204a1/omnara-1.2.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-09 21:34:51",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "omnara-ai",
    "github_project": "omnara",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "omnara"
}