omnigent-ai/omnigent

Omnigent lets you:

• 📱 Work with agents from any device, including your phone. Sessions 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.

• 🤖 Supervise multiple agents. Mix Claude Code, Codex, Cursor, OpenCode, 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.

• 🔌 Use any model. A first-party API key, a Claude/ChatGPT subscription, or any compatible gateway. All first-class.

• 🤝 Collaborate. Share a session so teammates can chat with your agent and watch it work live, co-drive it on your machine, or fork the conversation to continue on their own.

• ☁️ Run agents in cloud sandboxes. No laptop required: run sessions in 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).

• 🛡️ Govern your agents. Create 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.

One command installs Omnigent and everything it needs:

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

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

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

uv tool install "omnigent[databricks,modal]"

brew install omnigent-ai/tap/omnigent

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

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

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

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

omnigent uninstall

omnigent uninstall --yes

omnigent uninstall --purge --yes

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

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.

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

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 <harness>
omnigent run examples/debby/ --harness <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.

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.'

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.

omnigent setup

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

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.

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

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).

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.

• Share a live session. Hit Share in the web UI and send the link; teammates watch your agent work and chat with it in real time.

• Share with everyone who can sign in. Admins can allow public Edit in Settings > Sharing > Maximum public permission. Owners then choose Share > General access > Edit. The default stays Read.

• Leave a shared session. Done with a session someone shared with you? 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.

• Co-drive. A teammate co-attaches to your running session; their messages execute on your machine. Great for pairing or handing the keyboard to a domain expert mid-investigation.

  omnigent attach <session_id>

• Fork. Clone a conversation onto your own machine and continue independently from the fork point.

  omnigent run --fork <session_id>

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.

• In the web UI: open a session's info panel to browse the available policies and toggle them on or off.
• In chat: ask. "Add a policy that asks me before running shell 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 policy guide for the full catalog and trust model.

An agent is a short YAML file: your prompt, your tools — local Python functions, MCP servers, and sub-agents a supervisor can delegate to. You don't have to write it by hand: agents can build agents, so describe the agent you want in any Omnigent chat and it authors the file for you.

name: my_agent
prompt: You are a helpful data analyst.

executor:
  harness: claude-sdk          # or: claude-native, codex, codex-native, cursor,
                               # cursor-native, hermes, hermes-native, opencode,
                               # pi, pi-native, openai-agents

tools:
  # A local Python function (schema auto-generated from the signature)
  word_count:
    type: function
    callable: mypackage.mymodule.word_count

  # Tools from an MCP server (a local command, or a remote URL)
  docs:
    type: mcp
    url: https://example.com/mcp

  # A sub-agent the supervisor can delegate to
  researcher:
    type: agent
    prompt: Search for relevant information and summarize it.
    tools:
      word_count: inherit

Run it with:

omnigent run path/to/my_agent.yaml

The same file can declare sub-agents and reviewers. For a fuller example, see Polly at examples/polly/, and the Agent YAML spec for the full schema.

Omnigent collects anonymized usage data (telemetry) by default. This data contains no sensitive or personally identifiable information. If you're using Omnigent through a managed service or distribution, please consult your managed service agreement to determine any data collection that may impact your use of the service. To opt out, follow our instructions in Usage Telemetry.

Contributions are welcome. See CONTRIBUTING.md for how to set up your environment, run the checks, and open a pull request.

Adding or changing support for a harness (Claude, Codex, Cursor, OpenCode, Hermes, Pi, ...)? Run the harness test bench to check its capability matrix against observed behavior.

Thanks to all of our amazing contributors!