{"id":51041253,"url":"https://github.com/omnigent-ai/omnigent","last_synced_at":"2026-06-23T23:01:07.423Z","repository":{"id":364464566,"uuid":"1266212515","full_name":"omnigent-ai/omnigent","owner":"omnigent-ai","description":"Omnigent is an open-source AI agent framework and meta-harness: orchestrate Claude Code, Codex, Cursor, Pi, and custom agents — swap harnesses without rewriting, enforce policies and sandboxing, and collaborate in real time from any device.","archived":false,"fork":false,"pushed_at":"2026-06-20T08:19:24.000Z","size":46075,"stargazers_count":4108,"open_issues_count":215,"forks_count":463,"subscribers_count":17,"default_branch":"main","last_synced_at":"2026-06-20T09:22:31.009Z","etag":null,"topics":["agent-framework","agent-governance","agent-orchestration","agents","ai","ai-agent","ai-agents","claude-code","codex","coding-agents","developer-tools","llm","ml","multi-agent","python","sandbox"],"latest_commit_sha":null,"homepage":"https://omnigent.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/omnigent-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-11T12:18:13.000Z","updated_at":"2026-06-20T09:16:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/omnigent-ai/omnigent","commit_stats":null,"previous_names":["omnigent-ai/omnigent"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/omnigent-ai/omnigent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omnigent-ai%2Fomnigent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omnigent-ai%2Fomnigent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omnigent-ai%2Fomnigent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omnigent-ai%2Fomnigent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omnigent-ai","download_url":"https://codeload.github.com/omnigent-ai/omnigent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omnigent-ai%2Fomnigent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34709804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","agent-governance","agent-orchestration","agents","ai","ai-agent","ai-agents","claude-code","codex","coding-agents","developer-tools","llm","ml","multi-agent","python","sandbox"],"created_at":"2026-06-22T11:00:25.787Z","updated_at":"2026-06-23T23:01:07.416Z","avatar_url":"https://github.com/omnigent-ai.png","language":"Python","funding_links":[],"categories":["Python","Reference Implementations","Catalog"],"sub_categories":["Generators \u0026 Meta-Harnesses","Harness Architecture \u0026 Orchestration"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# \u003cimg src=\"https://raw.githubusercontent.com/omnigent-ai/omnigent/main/docs/images/omnigent-logo.svg\" alt=\"\" height=\"38\" valign=\"middle\" /\u003e Omnigent\n\n### The open-source AI agent framework and meta-harness for all your AI agents.\n\nOmnigent is an open-source **AI agent framework** and meta-harness that gives you a common orchestration layer over Claude Code, Codex, Cursor, Pi, and the agents you write yourself: swap or combine harnesses without rewriting, enforce policies and sandboxing, and collaborate in real time from any device.\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/omnigent-ai/omnigent/blob/main/LICENSE)\n![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](#1-install)\n\n[omnigent.ai](https://omnigent.ai) · **[⬇️ Download the macOS desktop app](https://omnigent.ai/download/mac)**\n\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/omnigent-ai/omnigent/main/docs/images/omnigent-hero.png\" alt=\"An Omnigent orchestrator and its sub-agents in one shared session\" width=\"520\" /\u003e\n\u003c/p\u003e\n\n---\n\n## Why Omnigent?\n\nOmnigent lets you:\n\n- **📱 Work with agents from any device, including your phone.** Sessions\n  follow you: start in your terminal, continue in the browser, pick it up on\n  your phone. Messages, sub-agents, terminals, and files stay in sync.\n\n- **🤖 Supervise multiple agents.** Use Claude Code, Codex, Pi, and custom\n  agents (defined in YAML) together in the same session. Ask one agent to\n  review another's work, or split a task across agents that are each good at\n  different things.\n\n- **🔌 Use any model.** A first-party API key, a Claude/ChatGPT subscription,\n  or any compatible gateway. All first-class.\n\n- **🤝 Collaborate.** Share a session so teammates can chat with your agent\n  and watch it work live, co-drive it on your machine, or fork the\n  conversation to continue on their own.\n\n- **☁️ Run agents in cloud sandboxes.** No laptop required: run sessions in\n  disposable [Modal](https://modal.com), [Daytona](https://www.daytona.io), or\n  [Islo](https://islo.dev) sandboxes, launched from the CLI or provisioned by\n  the server per session (*managed hosts*).\n\n- **🛡️ Govern your agents.** Create\n  [policies](#6-govern-your-agents-with-policies) to pause for your approval\n  before risky actions, cap spend, or limit which tools an agent reaches.\n  They apply to the whole server, one agent, or a single chat.\n\n---\n\n## Quick start\n\n### 1. Install\n\nOne command installs Omnigent and everything it needs:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh\n```\n\n\u003cdetails\u003e\n\u003csummary\u003ePrefer to install manually?\u003c/summary\u003e\n\nOmnigent needs **Python 3.12+**. Install the `omnigent` package:\n\n```bash\nuv tool install omnigent        # or: pip install \"omnigent\"\n```\n\nOr with [Homebrew](https://github.com/omnigent-ai/homebrew-tap):\n\n```bash\nbrew install omnigent-ai/tap/omnigent\n```\n\nOr install straight from the repo:\n\n```bash\nuv tool install -q --python 3.12 git+https://github.com/omnigent-ai/omnigent.git\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eToolchain and prerequisites (if the installer reports a missing tool)\u003c/summary\u003e\n\n- **`uv`** (required). https://docs.astral.sh/uv/getting-started/installation/\n  The installer offers to set this up for you.\n- **`git`** (required).\n- **Node.js 22 LTS or newer** with **`npm`**, for the Claude, Codex, and Pi\n  coding harnesses. `omnigent run` installs the harness CLI you pick.\n  https://docs.npmjs.com/downloading-and-installing-node-js-and-npm\n- **`tmux`**, required by the native `omnigent claude` / `omnigent codex`\n  wrappers (`brew install tmux` / `apt install tmux`; the installer offers\n  to install it for you).\n- **`bubblewrap`** (`bwrap`), **Linux only**. The native `omnigent claude` /\n  `omnigent codex` and `pi` harnesses wrap each agent terminal in a `bwrap`\n  OS-sandbox; on Linux that isolation is mandatory, so a missing `bwrap`\n  binary makes those terminals fail to start (`apt install bubblewrap`; the\n  installer offers to install it for you). macOS uses the built-in `seatbelt`\n  sandbox and needs nothing extra.\n- **Databricks** (optional). To use a Databricks workspace as your model\n  provider, install Omnigent with the `databricks` extra:\n  `uv tool install \"omnigent[databricks]\"` — or pass it to the bootstrap\n  installer with `... | sh -s -- --extra databricks`. Signing in to the\n  workspace also uses the [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/install).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eUpdating to a new release\u003c/summary\u003e\n\nWhen a newer release is on PyPI, Omnigent shows a one-line notice (once per\nrelease) pointing here. To update:\n\n```bash\nomni upgrade            # detects how you installed, drains \u0026 stops the local\n                        # server, then runs the matching upgrade command\nomni upgrade --check    # just report whether a newer release is available\n```\n\n`omni upgrade` waits for in-flight agent sessions to finish before stopping the\nlocal server (pass `--force` to stop them immediately); the next `omni` command\nbrings the server back up on the new version. Source checkouts update with\n`git pull` instead. Silence the notice with `OMNIGENT_NO_UPDATE_CHECK=1`.\n\nThe check queries your configured package index — honoring `UV_INDEX_URL` /\n`PIP_INDEX_URL` and your `uv.toml` / `pip.conf` (default PyPI), so private\nmirrors work out of the box; override with `OMNIGENT_INDEX_URL` if needed.\n\n\u003c/details\u003e\n\n### 2. Start your first agent\n\n`omnigent` picks a model with you and starts a session in your terminal. It\nalso launches a local web UI at `http://localhost:6767` that shows the same\nsession in the browser, or on a phone on your network (step 4). The\n[desktop app](https://omnigent.ai/docs/interact/desktop) wraps that same UI\nin a native window and adds OS notifications and a dock badge —\n[download it for macOS](https://omnigent.ai/download/mac).\n\n\u003e [!NOTE]\n\u003e The install puts two names for the same CLI on your PATH: `omnigent` and\n\u003e the shorter `omni`. They're interchangeable.\n\n\u003e [!TIP]\n\u003e On first run, Omnigent picks up model credentials already in your\n\u003e environment (an `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or a `claude` /\n\u003e `codex` CLI you're logged into) and offers one as the default.\n\n```bash\nomnigent\n```\n\nOr launch a specific agent runtime, or your own agent:\n\n```bash\nomnigent claude                      # Claude Code, in a session your team can join\nomnigent codex                       # Codex\nomnigent run path/to/agent.yaml      # your own agent (see \"Write your own agent\")\n```\n\n#### 🐙 Polly and 🟠🔵 Debby\n\nTwo example agents ship with the repo, and they make good first sessions:\n\n```bash\nomnigent run examples/polly/\nomnigent run examples/debby/\n\n# Run an orchestrator on a different harness (sub-agents keep their own):\nomnigent run examples/polly/ --harness pi\nomnigent run examples/debby/ --harness openai-agents\nomnigent run examples/polly/ --harness cursor  # Cursor CLI (needs cursor-agent + CURSOR_API_KEY)\n```\n\n**🐙 Polly** is a multi-agent coding orchestrator who writes no code herself.\nShe's the tech lead: she plans, delegates the work to coding sub-agents\n(Claude Code, Codex, or Pi) in parallel git worktrees, then routes each diff\nto a reviewer from a different vendor than the one that wrote it. You merge.\n\n**🟠🔵 Debby** is a brainstorming partner with two heads, one Claude and one GPT.\nEvery question you ask goes to both heads, and she lays the two answers out\nside by side. Type `/debate` and the heads critique each other for a few\nrounds before converging. (She needs both a Claude and an OpenAI credential;\nsee step 3.)\n\n**Prefer the browser?** Start a server and register your machine as a host:\n\n```bash\nomnigent server start   # start the local server and web UI in the background\nomnigent host           # (separate terminal) register this machine as a host\n```\n\nIn the web UI, hit **New Chat**, pick your machine, and go. Check status with\n`omnigent server status`; stop everything with `omnigent stop`.\n\n### 3. Choose \u0026 switch models\n\n```bash\nomnigent setup\n```\n\nAdd a credential, set a default, or remove one, grouped by agent. Omnigent\nworks with four kinds of credentials:\n\n| | Kind | What it is |\n|---|---|---|\n| 🔑 | **API key** | A first-party vendor key for Anthropic, OpenAI, and similar providers |\n| 🎟️ | **Subscription** | A Claude Pro/Max or ChatGPT plan, via the official `claude` / `codex` CLIs |\n| 🌐 | **Gateway** | Any OpenAI- or Anthropic-compatible `base_url` and key (OpenRouter, LiteLLM, Ollama, vLLM, Azure) |\n| 🧱 | **Databricks** | A Databricks workspace profile (requires the `databricks` extra) |\n\nDefaults are per agent, so a Claude default and a Codex default coexist. You\ncan also switch models in the middle of a session with the `/model` command.\n\n\u003cdetails\u003e\n\u003csummary\u003eGateway base URLs (OpenRouter, Ollama)\u003c/summary\u003e\n\nWhen you add a **Gateway** credential, `omnigent setup` asks for a base URL\nand a key. The base URL depends on which agent you point it at:\n\n| Provider | For | Base URL | Key |\n|---|---|---|---|\n| **OpenRouter** | Claude Code | `https://openrouter.ai/api` | your OpenRouter key (`sk-or-…`) |\n| **OpenRouter** | Codex / OpenAI agents | `https://openrouter.ai/api/v1` | your OpenRouter key (`sk-or-…`) |\n| **Ollama** (local) | Codex / OpenAI agents | `http://localhost:11434/v1` | any value (Ollama ignores it) |\n\nFor Claude Code, point at OpenRouter's Anthropic-compatible endpoint\n(`…/api`, **not** `…/api/v1`). For Codex and the OpenAI-agents harness, use\nthe OpenAI-compatible `…/api/v1`.\n\n\u003c/details\u003e\n\n### 4. Deploy a server (and use it from your phone📱)\n\nRun Omnigent on a server with a stable URL\n([`deploy/README.md`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md) is the full guide) and your sessions\nbecome reachable from anywhere, including your phone. The web UI is built for\nmobile, so you get the same chat, sub-agents, terminals, and files, in sync\nwith your laptop.\n\nOne `docker compose up` runs the server on any host you have (a VPS, a home\nserver); Render deploys with one click; Fly.io, Railway, Hugging Face Spaces,\nand Modal are covered too. The server can also provision a cloud sandbox per\nsession (*managed hosts*), so no laptop has to stay online. The full menu of\ntargets, the database options, and the sandbox setup live in\n[`deploy/README.md`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md).\n\nOnce the server is up, sign in and register your laptop as a host:\n\n```bash\nomnigent login https://your-host    # sign in once; run / attach / host reuse the token\nomnigent host  https://your-host    # new sessions can now run on this machine\n```\n\n\u003e [!TIP]\n\u003e On your own network you don't need a deploy. Open your machine's LAN\n\u003e address on your phone (e.g. `http://192.168.x.x:6767`).\n\n### 5. Collaborate with your team\n\nOmnigent supports **multi-user accounts**, controlled by one environment\nvariable:\n\n```bash\nOMNIGENT_AUTH_ENABLED=1 omnigent server start\n```\n\nThe **Docker deploy in [step 4](#4-deploy-a-server-and-use-it-from-your-phone)\nturns it on for you** (`OMNIGENT_AUTH_ENABLED` defaults to `1` there).\n\n#### Invite your teammates\n\nOpen the web UI (`http://localhost:6767` locally, or your host's URL) and\nsign in as `admin`; first run prints the password and saves it locally. Then\nopen **Admin → Members → Invite** to create a single-use invite link, no\nemail server needed. Send it over; your teammate opens it, sets a password,\nand they're in. Signup is invite-only.\n\n\u003c!-- TODO: screenshot of Admin → Members → Invite. --\u003e\n\n\u003e [!NOTE]\n\u003e Teammates need to be able to reach the server. A local server is only\n\u003e reachable on your network; for anyone off it, deploy an always-on host\n\u003e (see [step 4](#4-deploy-a-server-and-use-it-from-your-phone)).\n\n#### Code together\n\n- **Share a live session.** Hit **Share** in the web UI and send the link;\n  teammates watch your agent work and chat with it in real time.\n- **Co-drive.** A teammate co-attaches to your running session; their\n  messages execute on **your** machine. Great for pairing or handing the\n  keyboard to a domain expert mid-investigation.\n\n  ```bash\n  omnigent attach \u003csession_id\u003e\n  ```\n\n- **Fork.** Clone a conversation onto your own machine and continue\n  independently from the fork point.\n\n  ```bash\n  omnigent run --fork \u003csession_id\u003e\n  ```\n\n\u003e [!TIP]\n\u003e Want your team to sign in with the logins they already have (**Google,\n\u003e GitHub, Okta, Microsoft**)? Set `OMNIGENT_OIDC_ISSUER` plus a client ID\n\u003e and secret on your deployed server and restart. The full walkthrough,\n\u003e domain allowlists, and the proxy-only `header` auth mode are covered in\n\u003e [`deploy/README.md#auth`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md#auth).\n\n### 6. Govern your agents with policies\n\n**Policies** decide what an agent may do: run shell commands, edit files,\nspend tokens. They check every action and either allow it, block it, or pause\nto ask you first.\n\n- **In the web UI**: open a session's info panel to browse the available\n  policies and toggle them on or off.\n- **In chat**: ask. *\"Add a policy that asks me before running shell\n  commands.\"* The agent sets it up for you.\n\nWant defaults that apply to everyone, or to a specific agent? Define them in\nyour server config or an agent's YAML:\n\n```yaml\npolicies:\n  approve_shell:\n    type: function\n    handler: omnigent.policies.builtins.safety.ask_on_os_tools   # ask before shell / file writes\n  cap_calls:\n    type: function\n    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session\n    factory_params:\n      limit: 50                    # cap how many tools one session can call\n  budget:\n    type: function\n    handler: omnigent.policies.builtins.cost.cost_budget\n    factory_params:\n      max_cost_usd: 5.00           # hard spend cap...\n      ask_thresholds_usd: [3.00]   # ...with a soft warning on the way\n```\n\nPolicies stack across three levels, **server-wide** (admin), **per-agent**\n(developer), and **per-session** (you), with the stricter session rules\nchecked first. Spend caps and access limits ship as builtins.\n\nSee the [policy guide](https://github.com/omnigent-ai/omnigent/blob/main/docs/POLICIES.md) for the full catalog and trust model.\n\n---\n\n## Write your own agent\n\nAn agent is a short YAML file: your prompt, your tools, and optional helper\nsub-agents a supervisor can delegate to. You don't have to write it by hand:\nagents can build agents, so describe the agent you want in any Omnigent chat\nand it authors the file for you.\n\n```yaml\nname: my_agent\nprompt: You are a helpful data analyst.\n\nexecutor:\n  harness: claude-sdk          # or: claude-native, codex, codex-native, cursor, cursor-native, openai-agents, pi, pi-native, antigravity, qwen\n\ntools:\n  # A local Python function (schema auto-generated from the signature)\n  word_count:\n    type: function\n    callable: mypackage.mymodule.word_count\n\n  # A sub-agent the supervisor can delegate to\n  researcher:\n    type: agent\n    prompt: Search for relevant information and summarize it.\n    tools:\n      word_count: inherit\n```\n\nRun it with:\n\n```bash\nomnigent run path/to/my_agent.yaml\n```\n\nThe same file can declare sub-agents and reviewers. For a fuller example, see\nPolly at [`examples/polly/`](https://github.com/omnigent-ai/omnigent/tree/main/examples/polly/), and the\n[Agent YAML spec](https://github.com/omnigent-ai/omnigent/blob/main/docs/AGENT_YAML_SPEC.md) for the full schema.\n\n---\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](https://github.com/omnigent-ai/omnigent/blob/main/CONTRIBUTING.md) for how to set up your environment, run the checks, and open a pull request.\n\n\n### Contributors\n\nThanks to all of our amazing contributors!\n\n\u003ca href=\"https://github.com/omnigent-ai/omnigent/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=omnigent-ai/omnigent\" /\u003e\n\u003c/a\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomnigent-ai%2Fomnigent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomnigent-ai%2Fomnigent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomnigent-ai%2Fomnigent/lists"}