omnigent-ai/omnigent

▲ 50 stars today★ 10,622⑂ 1,698

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

Open on GitHub ↗

About omnigent-ai/omnigent

omnigent-ai/omnigent is an open-source project on GitHub, mainly written in Python. Omnigent is an open-source AI agent framework and meta-harness: orchestrate Claude Code, Codex, Cursor, Pi It currently holds 10,622 stars and 1,698 forks with 0 open issues, and was last pushed on an unknown date (repository created unknown).

Project Overview

AI Homed tracks it on the Today's Trending board, currently at rank #37 with 50 new stars today.

GitHub Repository Details

Repository omnigent-ai/omnigent · default branch - · size 0 KB · watchers 0 · source: GitHub REST API and repository README

README

https://github.com/omnigent-ai/omnigent/blob/HEAD/ Omnigent

The open-source meta-harness for all your AI agents.

Omnigent is an open-source meta-harness that gives you a common orchestration layer over Claude Code, Codex, Cursor, OpenCode, Hermes, 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 — terminal, browser, phone, or the native desktop app.

PyPI version License: Apache 2.0 Discord Status: alpha

omnigent.ai · ⬇️ Download the macOS desktop app

https://github.com/omnigent-ai/omnigent/blob/HEAD/The Omnigent desktop app: starting a new session, with pinned and project-grouped sessions in the sidebar

---

Why Omnigent?

Omnigent lets you:

follow you: start in your terminal, continue in the browser, pick it up on your phone. Messages, sub-agents, terminals, and files stay in sync. Hermes, Pi, and custom agents (defined in YAML) together in the same session. Ask one agent to review another's work, or split a task across agents that are each good at different things. or any compatible gateway. All first-class. and watch it work live, co-drive it on your machine, or fork the conversation to continue on their own. disposable Modal, Daytona, Blaxel, Islo, E2B, Gensee, CoreWeave, Kubernetes, OpenShell, Boxlite, microsandbox, or Databricks sandboxes, launched from the CLI or provisioned by the server per session (managed hosts). policies to pause for your approval before risky actions, cap spend, or limit which tools an agent reaches. They apply to the whole server, one agent, or a single chat.

---

Quick start

1. Install

One command installs Omnigent and everything it needs:

curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh
Optional integrations and extras

Need an optional integration? Pass one or more extras to the installer:

curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --extra databricks
curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --extra modal,e2b

Available user-facing extras include:

  • Model providers: databricks, bedrock, vertex
  • Sandbox providers: modal, daytona, blaxel, boxlite, microsandbox,
cwsandbox, e2b, openshell, kubernetes
  • SDK harnesses: antigravity, copilot, cursor, agents-sdk
  • Storage and memory: s3, hindsight

Prefer to install manually?

Omnigent needs Python 3.12+. Install the omnigent package:

uv tool install omnigent        # or: pip install "omnigent"

Manual installs use the same extras syntax, for example:

uv tool install "omnigent[databricks,modal]"

Or with Homebrew:

brew install omnigent-ai/tap/omnigent

For source builds on networks that require package mirrors, replace these example URLs with your mirrors:

HOMEBREW_PIP_INDEX_URL='https://pypi.example.com/simple' \
HOMEBREW_CARGO_INDEX_URL='https://cargo.example.com/index/' \
  brew install --build-from-source omnigent-ai/tap/omnigent

The PyPI setting also routes pip's isolated build dependencies through the mirror. The Cargo setting takes a sparse registry index URL ending in /, without the sparse+ prefix. Both overrides are optional and do not affect prebuilt-bottle installs.

Or install straight from the repo:

uv tool install -q --python 3.12 git+https://github.com/omnigent-ai/omnigent.git

Toolchain and prerequisites (if the installer reports a missing tool)
  • uv (required). https://docs.astral.sh/uv/getting-started/installation/
The installer offers to set this up for you.
  • git (required).
  • Node.js 22 LTS or newer with npm (for the coding-harness CLIs
installed by omnigent run) and pnpm (for the web UI). You can get both from a single Node install; pnpm is available via corepack enable or npm install -g pnpm.
  • Devin CLI (optional), for omnigent devin: install with
curl -fsSL https://cli.devin.ai/install.sh | bash, then sign in with devin auth login. Devin tool approvals appear as Chat approval cards (its PermissionRequest hook is mirrored to the web UI) and stay answerable in the embedded Terminal. See docs/devin-native.md.
  • Kiro CLI (optional), for omnigent kiro: install with
curl -fsSL https://cli.kiro.dev/install | bash, then sign in with Kiro. Kiro tool approvals stay answerable in the embedded Terminal; supported one-time approvals also appear as Chat cards. See docs/kiro-native-elicitation.md.
  • tmux, required by the native omnigent terminal wrappers
(claude, codex, cursor, devin, hermes, kiro, pi) (brew install tmux / apt install tmux; the installer offers to install it for you).
  • bubblewrap (bwrap), Linux only. The native omnigent
terminal wrappers and the pi harness wrap each agent terminal in a bwrap OS-sandbox; on Linux that isolation is mandatory, so a missing bwrap binary makes those terminals fail to start (apt install bubblewrap; the installer offers to install it for you). macOS uses the built-in seatbelt sandbox and needs nothing extra.
  • Databricks (optional). To use a Databricks workspace as your model
provider, install Omnigent with the databricks extra: uv tool install "omnigent[databricks]" — or pass it to the bootstrap installer with ... | sh -s -- --extra databricks. Signing in to the workspace also uses the Databricks CLI.

Windows (native)

Omnigent runs natively on Windows in a degraded mode. The install_oss.sh bootstrap is POSIX-only, so install with uv directly:

uv tool install --python 3.12 omnigent

or from the repo:

uv tool install --python 3.12 git+https://github.com/omnigent-ai/omnigent.git

What works on Windows: omnigent server, the web UI, and the SDK-based harnesses (omnigent run with the claude-sdk / cursor / codex harnesses). Agents run under a Windows Job Object for process-tree containment.

What is not available on Windows (use Linux/macOS, or WSL, for these):

  • the native omnigent claude / omnigent codex / omnigent cursor
tmux/PTY terminal wrappers (run an SDK harness or the web UI instead);
  • bwrap/seatbelt filesystem & network sandboxing and the L7 egress proxy
— the Job Object backend contains the process tree and enforces resource limits but does not isolate the filesystem or network.

Updating to a new release

When a newer release is on PyPI, Omnigent shows a one-line notice (once per release) pointing here. To update:

omni upgrade            # detects how you installed, drains & stops the local
                        # server, then runs the matching upgrade command
omni upgrade --check    # just report whether a newer release is available

omni upgrade waits for in-flight agent sessions to finish before stopping the local server (pass --force to stop them immediately); the next omni command brings the server back up on the new version. Source checkouts update with git pull instead. Silence the notice with OMNIGENT_NO_UPDATE_CHECK=1.

The check queries your configured package index — honoring UV_INDEX_URL / PIP_INDEX_URL and your uv.toml / pip.conf (default PyPI), so private mirrors work out of the box; override with OMNIGENT_INDEX_URL if needed.

Uninstalling Omnigent

Preview the CLI/profile cleanup that would run by default:

omnigent uninstall

Remove the CLI and installer-managed PATH entries while keeping your local history, credentials, and projects:

omnigent uninstall --yes

To also remove Omnigent state under ~/.omnigent, pass --purge; Omnigent backs it up outside the target before deletion. Your ~/omnigent workspace is kept unless you explicitly add --purge-workspace.

omnigent uninstall --purge --yes

If the installed wheel is broken or omnigent is not on PATH, run the standalone script instead:

curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/uninstall_oss.sh | sh

Add --yes to the standalone script to perform the previewed CLI cleanup.

2. Start your first agent

omnigent picks a model with you and starts a session in your terminal. It also launches a local web UI at http://localhost:6767 that shows the same session in the browser, or on a phone on your network (step 4). The desktop app wraps that same UI in a native window and adds OS notifications (with a configurable sound) and a dock badge — download it for macOS.

[!NOTE]
The install puts two names for the same CLI on your PATH: omnigent and
the shorter omni. They're interchangeable.
[!TIP]
On first run, Omnigent picks up model credentials already in your
environment (an ANTHROPIC_API_KEY / OPENAI_API_KEY, or a claude /
codex CLI you're logged into) and offers one as the default.
omnigent

Or launch a specific agent runtime:

omnigent claude                      # Claude Code, in a session your team can join
omnigent codex                       # Codex
omnigent cursor                      # Cursor
omnigent agy                         # Antigravity
omnigent opencode                    # OpenCode
omnigent hermes                      # Hermes Agent (Nous Research)
omnigent pi                          # Pi
omnigent copilot                     # GitHub Copilot (SDK harness, via omnigent run)

omnigent agy requires agy 1.1.13 or newer. When GEMINI_API_KEY is set, direct Gemini API authentication takes precedence over agy's saved OAuth login.

Using OpenClaw? See the OpenClaw integration guide to import its coding agents or drive a live OpenClaw Gateway session over ACP.

Grok Build and Devin

Two more coding agents are built in but have no omnigent launcher of their own, because each ships a CLI that holds its own login. Install the vendor CLI, log in with it, then name the harness:

# Grok Build (xAI)
curl -fsSL https://x.ai/cli/install.sh | bash
grok login --device-auth              # xAI OAuth
omnigent run --harness grok           # 'grok-build' also works

Devin (Cognition)

curl -fsSL https://cli.devin.ai/install.sh | bash
devin auth login
omnigent run --harness devin

Both speak the Agent Client Protocol over stdio, and Omnigent stores no credential for either — each CLI reads back the login it wrote to disk. That also means --model is refused rather than silently dropped: both run their account-default model. To pin one, configure an acp: agent whose command passes the vendor's own model flag.

Use the vendor login rather than an API key. A builtin ACP row has no env_passthrough of its own, and XAI_API_KEY is not in the host-to-runner credential allowlist, so exporting it in your shell does not reach the agent. If you need the key route, pass it explicitly with OMNIGENT_RUNNER_ENV_PASSTHROUGH=XAI_API_KEY, or configure an acp: agent that declares the passthrough.

🐙 Polly and 🟠🔵 Debby

Two example agents ship with the repo, and they make good first sessions:

omnigent run examples/polly/
omnigent run examples/debby/
omnigent run examples/deep-research/

...or on a different harness (sub-agents keep their own):

omnigent run examples/polly/ --harness 
omnigent run examples/debby/ --harness

🐙 Polly is a multi-agent coding orchestrator who writes no code herself. She's the tech lead: she plans, delegates the work to coding sub-agents (Claude Code, Codex, or Pi) in parallel git worktrees, then routes each diff to a reviewer from a different vendor than the one that wrote it. You merge.

🟠🔵 Debby is a brainstorming partner with two heads, one Claude and one GPT. Every question you ask goes to both heads, and she lays the two answers out side by side. Type /debate and the heads critique each other for a few rounds before converging. (She needs both a Claude and an OpenAI credential; see step 3.)

🔎 Deep Research is a single agent that answers a question with a cited, cross-checked report. It plans sub-queries, searches the live web and reads full pages through an MCP search server, and verifies each claim across independent sources. It's also the simplest example to copy from: one agent plus one tools/mcp/*.yaml server, no sub-agents.

Prefer the browser? One command starts the local server and registers this machine as a host:

omnigent start   # starts the local server and registers this machine as a host

Open the server URL it prints, hit New Chat, pick your machine, and go. Check status with omnigent server status; stop everything with omnigent stop.

To suppress the automatic browser tab, use omni host --no-open or set OMNIGENT_HOST_NO_OPEN=1 in your shell. Both also apply to `omni host --background and omni start`. Sign-in may still open a browser; use --non-interactive in scripts to fail if sign-in is required.

A session can also start itself: the Automations page runs an agent on a recurring schedule. See the automations guide for the schedule format, the REST API, and the current limits.

Customize automatic session titles

Set additional natural-language requirements for the isolated title generator:

omnigent config set --global \
  'session_title_instructions=Prefix titles with the current date as lowercase mon-dd. Use PR-number-short-name for pull requests, issue-number-short-description for issues, and a short snake_case activity otherwise.'

The title generator receives the current date as YYYY-MM-DD, then applies these requirements to the first user message. The setting is server-owned and does not alter an agent's portable instructions. Default generated titles are limited to 100 characters; custom title requirements may use up to 200. Default titles over 100 characters are rejected, leaving the first-message fallback title in place. Custom titles over 200 characters are truncated with a trailing ellipsis. Manually assigned titles are also limited to 200 characters. The setting applies after the local Omnigent server restarts, both to new sessions and to later agent-initiated renames through sys_session_rename. Agent proposals are formatted using the same title requirements; if formatting fails, the existing title is preserved. Manual renames remain unchanged. For longer instructions, edit ~/.omnigent/config.yaml directly and use a YAML block scalar:

session_title_instructions: |
  Prefix every title with the current date as lowercase mon-dd.
  For pull requests use mon-dd-PR-number-short-name.
  For issues use mon-dd-issue-number-short-description.
  For other work use mon-dd-short_snake_case_activity.

Server operators can set the same key in the YAML passed to omnigent server --config.

3. Choose & switch models

omnigent setup

Add a credential, set a default, or remove one, grouped by agent. Omnigent works with four kinds of credentials:

| | Kind | What it is | |---|---|---| | 🔑 | API key | A first-party vendor key for Anthropic, OpenAI, and similar providers | | 🎟️ | Subscription | A Claude Pro/Max or ChatGPT plan, via the official claude / codex CLIs | | 🌐 | Gateway | Any OpenAI- or Anthropic-compatible base_url and key (OpenRouter, LiteLLM, Ollama, vLLM, Azure) | | 🧱 | Databricks | A Databricks workspace profile (requires the databricks extra) |

Defaults are per agent, so a Claude default and a Codex default coexist. You can also switch models in the middle of a session with the /model command.

Gateway base URLs (OpenRouter, Ollama)

When you add a Gateway credential, omnigent setup asks for a base URL and a key. The base URL depends on which agent you point it at:

| Provider | For | Base URL | Key | |---|---|---|---| | OpenRouter | Claude Code | https://openrouter.ai/api | your OpenRouter key (sk-or-…) | | OpenRouter | Codex / OpenAI agents | https://openrouter.ai/api/v1 | your OpenRouter key (sk-or-…) | | Ollama (local) | Codex / OpenAI agents | http://localhost:11434/v1 | any value (Ollama ignores it) |

For Claude Code, point at OpenRouter's Anthropic-compatible endpoint (…/api, not …/api/v1). For Codex and the OpenAI-agents harness, use the OpenAI-compatible …/api/v1.

4. Deploy a server (and use it from your phone📱)

Run Omnigent on a server with a stable URL (deploy/README.md is the full guide) and your sessions become reachable from anywhere, including your phone. The web UI is built for mobile, so you get the same chat, sub-agents, terminals, and files, in sync with your laptop.

One docker compose up runs the server on any host you have (a VPS, a home server); Render and Railway deploy with one click; Fly.io, Hugging Face Spaces, Modal, Cloudflare (serverless, scale-to-zero), and Databricks Apps (backed by Lakebase Postgres and Unity Catalog Volumes) are covered too — and a Cloudflare quick tunnel (public) or Tailscale (private) reaches a server running on your own laptop without a deploy. The server can also provision a cloud sandbox per session (managed hosts), so no laptop has to stay online. The full menu of targets, the database options, the sandbox setup, and branding/white-labeling live in deploy/README.md.

Once the server is up, sign in and register your laptop as a host:

omnigent login https://your-host    # sign in once; run / attach / host reuse the token
omnigent host  https://your-host    # new sessions can now run on this machine
[!TIP]
On your own network you don't need a deploy. Open your machine's LAN
address on your phone (e.g. http://192.168.x.x:6767).

5. Collaborate with your team

Omnigent supports multi-user accounts, controlled by one environment variable:

OMNIGENT_AUTH_ENABLED=1 omnigent server --background

The Docker deploy in step 4 turns it on for you (OMNIGENT_AUTH_ENABLED defaults to 1 there).

Invite your teammates

Open the web UI (http://localhost:6767 locally, or your host's URL) and sign in as admin; first run prints the password and saves it locally. Then open Admin → Members → Invite to create a single-use invite link, no email server needed. Send it over; your teammate opens it, sets a password, and they're in. Signup is invite-only.

[!NOTE]
Teammates need to be able to reach the server. A local server is only
reachable on your network; for anyone off it, deploy an always-on host
(see step 4).

Code together

teammates watch your agent work and chat with it in real time. Pick Leave session from its sidebar row menu to drop it from your sidebar. Nothing is deleted — the owner keeps it and can share it again. messages execute on your machine. Great for pairing or handing the keyboard to a domain expert mid-investigation. 
  omnigent attach <session_id>
independently from the fork point. 
  omnigent run --fork <session_id>
[!TIP]
Want your team to sign in with the logins they already have (Google,
GitHub, Okta, Microsoft)? Set OMNIGENT_OIDC_ISSUER plus a client ID
and secret on your deployed server and restart. The full walkthrough,
domain allowlists, and the proxy-only header auth mode are covered in
deploy/README.md#auth.

6. Govern your agents with policies

Policies decide what an agent may do: run shell commands, edit files, spend tokens. They check every action and either allow it, block it, or pause to ask you first.

policies and toggle them on or off. commands."* The agent sets it up for you.

Want defaults that apply to everyone, or to a specific agent? Define them in your server config or an agent's YAML:

policies:
  approve_shell:
    type: function
    handler: omnigent.policies.builtins.safety.ask_on_os_tools   # ask before shell / file writes
  cap_calls:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 50                    # cap how many tools one session can call
  budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00           # hard spend cap...
      ask_thresholds_usd: [3.00]   # ...with a soft warning on the way

Policies stack across three levels, server-wide (admin), per-agent (developer), and per-session (you), with the stricter session rules checked first. Spend caps and access limits ship as builtins.

See the

GitHub Stars & Activity

10,622Stars
1,698Forks
0Open issues
PythonLanguage

GitHub Popularity

GitHub stars10,622
Forks1,698
Open issues0
Primary languagePython
License-
Stars gained today50
Created-
Last pushed-

Trending History

Daily boardrank #37 · ▲ 50 stars

Related AI Projects

1

NousResearch / hermes-agent

Python★ 251,657⑂ 0
→
2

Significant-Gravitas / AutoGPT

Python★ 187,666⑂ 0
→
3

anthropics / skills

Python★ 179,889⑂ 0
→
4

Panniantong / Agent-Reach

Python★ 92,553⑂ 8,116▲ 977 stars
→
5

rohitg00 / ai-engineering-from-scratch

Python★ 65,238⑂ 11,243▲ 783 stars
→
6

calesthio / OpenMontage

Python★ 64,626⑂ 8,192▲ 973 stars
→
7

ayghri / i-have-adhd

Python★ 54,298⑂ 3,120▲ 318 stars
→
8

topoteretes / cognee

Python★ 31,481⑂ 3,227▲ 73 stars
→

More AI Rankings