Omnigent — Repository Analysis

Generated walkthrough of omnigent-ai/omnigent — an open-source AI-agent framework and meta-harness that orchestrates Claude Code, Codex, Cursor, Kimi, Pi, Goose, Qwen, OpenCode, and custom agents under one layer. Full clone at /tmp/omnigent. Line numbers below match the tree at the time of writing.

This directory is a layered tour. Start here for the map; later docs drill into each subsystem.

1. Purpose & Problem

What it is. Omnigent is one orchestration layer that sits on top of many coding-agent harnesses. It describes itself as "the open-source AI agent framework and meta-harness for all your AI agents" (README.md:5). You point it at Claude Code, Codex, Cursor, Kimi, Pi, Goose, Qwen, OpenCode, Antigravity, Copilot, Hermes, Kiro, or an agent you wrote, and Omnigent gives all of them a common surface: one session model, one policy engine, one set of sandboxes, one web UI (README.md:7).

What it solves. The coding-agent landscape has fragmented into a dozen CLIs and SDKs, each with its own session format, permission model, credential setup, and UI. Omnigent collapses that fragmentation into four concrete wins (README.md:25-54):

Swap or combine harnesses without rewriting. An agent's YAML names a harness: (e.g. claude-sdk, codex, cursor, pi) and the same spec runs on any of them (README.md:413-415).
Cross-device session sync. Start in the terminal, continue in the browser, pick it up on your phone — messages, sub-agents, terminals, and files stay in sync (README.md:27-29).
Governance via policies. Pause for approval before risky actions, cap spend, limit which tools an agent reaches — applied server-wide, per-agent, or per-session (README.md:51-54, README.md:394-396).
Cloud sandboxes. Run sessions in disposable Modal / Daytona / Islo / E2B / CoreWeave / Kubernetes / OpenShell / Boxlite sandboxes, no laptop required (README.md:43-49).

Who it's for. Developers and teams who already use multiple coding agents and want to supervise them together — ask one agent to review another's work, split a task across vendors, or pair with teammates on a shared live session (README.md:31-41). Apache-2.0 licensed (LICENSE); the project is maintained by Databricks, Inc. (pyproject.toml:11-12) and is in alpha (pyproject.toml:16).

2. What distinguishes it from a single agent

The key inversion: Omnigent wraps Claude Code et al. — it does not replace them. Strix, OpenHands, or Hermes each are an agent loop. Omnigent is the layer above the loop. It doesn't ship its own coding intelligence; it adapts to whatever loop the underlying harness already runs.

That adaptation comes in two flavors, visible in the package layout:

SDK harnesses drive an agent through its official SDK or API surface (claude-sdk, codex, cursor, openai-agents, pi, copilot, databricks, …). Each has an executor + harness pair under omnigent/inner/ (e.g. omnigent/inner/claude_sdk_executor.py).
Native harnesses drive the real CLI of the underlying agent — Omnigent attaches to Claude Code's, Codex's, or Cursor's actual terminal process, intercepts its hooks, mirrors its session into Omnigent's own data model, and re-applies Omnigent's policies on top. These are the large *_native*.py bridge families at the top of the package (omnigent/claude_native_bridge.py, omnigent/codex_native_forwarder.py, …). On Linux these terminals are wrapped in a bwrap OS-sandbox; macOS uses seatbelt (README.md:106-111).

So a single agent like Claude Code answers "how do I solve this coding task?" Omnigent answers "how do I run, govern, sync, and combine many such agents — including Claude Code itself — as interchangeable parts?"

For Swisscheese: this is almost exactly Swisscheese's thesis. Omnigent's Polly example (README.md:218-221) is a multi-agent orchestrator that delegates to coding sub-agents in parallel git worktrees, then routes each diff to a reviewer from a different vendor than the one that wrote it — the writer→reviewer cross-vendor pipeline, already built. Study omnigent/inner/ and examples/polly/ closely.

3. Tech Stack

Language & runtime. Python ≥3.12 (pyproject.toml:10, .python-version pins 3.12), setuptools build backend (pyproject.toml:1-3), uv as the package manager. uv.toml enforces a 7-day dependency cooldown (exclude-newer = "P7D") so a compromised release has a window to surface before it's pinned — a supply-chain hardening choice worth noting.

Entry point. A single click-based CLI exposes two interchangeable names, omnigent and the short omni, both resolving to omnigent.cli:main (pyproject.toml:251-252). omnigent/cli.py is ~500KB — the command surface is large.

Runtime-critical Python deps (pyproject.toml:23-94):

Dependency	Role
openai ≥1	OpenAI client; also the shape Omnigent's own LLM layer mimics
mcp ≥1	Model Context Protocol — tools/servers plumbing
starlette + uvicorn	the async web server behind the API and web UI
httpx	HTTP client across runner/host/server transports
alembic + anyio	DB migrations + structured concurrency
prompt_toolkit / rich	terminal UI and rendering
cel-expr-python	CEL for side-effect-free, guaranteed-terminating inline policy evaluation (`pyproject.toml:46-50`)
keyring	OS keychain for model-provider credentials
psutil	host-daemon liveness checks

Notably, Omnigent wrote its own multi-provider LLM client to replace litellm. omnigent/llms/ presents the OpenAI Responses API as its public surface and uses Chat Completions as a lingua franca internally; each provider adapter translates between the two (omnigent/llms/LLMCLIENT.md:1-7). Adapters exist for Anthropic, OpenAI, Bedrock, Vertex, Gemini, and Databricks (omnigent/llms/adapters/). The translation logic is ported from MLflow AI Gateway adapters.

The web app — ap-web/. A TypeScript + React + Vite single-page app (ap-web/package.json), built for mobile, that renders the same session live in a browser or phone. It ships an Electron desktop wrapper and an iOS build (ap-web/electron/, ap-web/ios/). Uses TanStack Query, Monaco/Shiki for code, TipTap for rich text, and a Mermaid renderer.

SDKs — sdks/. Two installable companion packages, version-locked to the core (pyproject.toml:27-29):

sdks/python-client/ (omnigent-client) — a typed async client for driving sessions, streaming events, and registering tools.
sdks/ui/ (omnigent-ui-sdk) — UI/terminal SDK primitives.

Deploy targets. deploy/ carries recipes for Docker, Render, Fly, Railway, Hugging Face Spaces, Cloudflare, Tailscale, Databricks, Kubernetes, and each cloud-sandbox provider (deploy/ subfolders; README.md:283-296). railway.toml, render.yaml live at the repo root.

Optional extras (pyproject.toml:95-176) gate heavy/provider-specific deps behind lazy imports: bedrock, vertex, modal, daytona, boxlite, cwsandbox, e2b, openshell, kubernetes, tracing (MLflow), agents-sdk, antigravity, copilot, cursor, databricks, s3.

4. High-Level Architecture (teaser)

The path from a user message to an underlying agent passes through five layers. Deeper docs unpack each; this is the map.

flowchart TD
    subgraph clients["Clients"]
        WEB["ap-web / desktop / iOS<br/>(TS + React)"]
        CLI["omnigent / omni CLI"]
        SDK["python-client SDK"]
    end

    SERVER["server/<br/>Starlette app: sessions, auth/OIDC,<br/>policies, managed hosts, stores"]

    HOST["host/<br/>registers a machine; daemon that<br/>accepts sessions, git worktrees"]

    RUNNER["runner/<br/>per-session engine: routing,<br/>tool dispatch, policy checks, cost"]

    RUNTIME["runtime/<br/>drives the agent's reasoning loop<br/>(inner/ harness + executor)"]

    subgraph bridges["Native + SDK bridges (per underlying agent)"]
        CC["claude_native / claude-sdk"]
        CX["codex_native / codex"]
        CU["cursor_native / cursor"]
        OT["pi · kimi · goose · qwen ·<br/>opencode · hermes · antigravity ·<br/>copilot · kiro"]
    end

    subgraph sandboxes["Execution targets"]
        LOCAL["local: bwrap (Linux) /<br/>seatbelt (macOS) / JobObject (Win)"]
        CLOUD["cloud: Modal · Daytona · Islo ·<br/>E2B · CoreWeave · K8s ·<br/>OpenShell · Boxlite"]
    end

    WEB & CLI & SDK --> SERVER
    SERVER --> HOST
    HOST --> RUNNER
    RUNNER --> RUNTIME
    RUNTIME --> bridges
    bridges --> sandboxes
    RUNNER -. "policies/ · llms/ · stores/" .- SERVER

A few load-bearing facts the diagram compresses:

server / host / runner / runtime are distinct layers, each with its own README. The spec defines what an agent is (portable contract); the runtime is how it runs (a library, not a service); the server is one way to deploy (managed, multi-tenant, always-on) (omnigent/spec/README.md:1-5, omnigent/runtime/README.md:1-5, omnigent/server/README.md:1-5).
The inner loop (omnigent/inner/) is where Omnigent meets each underlying agent. There are 22 executor/harness pairs (omnigent/inner/*_executor.py) and ~60 top-level bridge files in the *_native* families.
An egress proxy (omnigent/inner/egress/) with its own CA can intercept and rule-filter the underlying agent's network traffic — relevant to policy enforcement and audit.

5. Repository Layout

Top level

omnigent/
├── omnigent/         # the Python package (see below)
├── ap-web/           # TS + React + Vite web app; Electron + iOS wrappers
├── sdks/             # omnigent-client + omnigent-ui-sdk companion packages
├── deploy/           # per-target deploy recipes (docker, render, fly, k8s, …)
├── docs/             # docs site (docs/POLICIES.md, docs/AGENT_YAML_SPEC.md, …)
├── examples/         # polly, debby, scribe — shippable example agents
├── designs/          # design notes (e.g. UNIFICATION.md, referenced in scripts)
├── dev/ · scripts/   # dev tooling and the scripts/install_oss.sh bootstrap
├── tests/            # large test tree (mirrors the package)
├── pyproject.toml    # metadata, deps, extras, entry points
├── setup.py          # build hook that stamps _build_info.py into the wheel
├── uv.toml           # uv config: 7-day supply-chain cooldown
├── openapi.json      # generated server API schema (~371KB)
└── README.md

The `omnigent/` package

omnigent/
├── omnigent/cli.py                     # the click CLI (huge; omni/omnigent → main)
├── omnigent/chat.py                    # session/chat orchestration
├── omnigent/model_catalog.py           # known models, costs, capabilities
│
├── *_native*.py  ────────────  # NATIVE BRIDGE FAMILIES (~60 files):
│     claude_native*           #   drive the real underlying-agent CLI,
│     codex_native*            #   intercept its hooks, mirror its session
│     cursor_native*           #   into Omnigent's data model, re-apply
│     goose_native*            #   policies. Each family typically has
│     hermes_native*           #   _bridge / _forwarder / _hook / _state /
│     kimi_native*             #   _permissions modules.
│     kiro_native*
│     opencode_native*
│     pi_native*
│     qwen_native*
│     antigravity_native*
│     native_* (policy_hook, cost_popup, server_harness, terminal, …)
│
├── spec/            # what an agent IS — YAML schema, parser, validator
├── runtime/         # how an agent RUNS — reasoning loop, compaction, retries
├── inner/           # the inner loop: 22 executor/harness pairs + egress proxy,
│                    #   sandbox wrappers (bwrap/seatbelt/JobObject), nessie
├── runner/          # per-session engine: routing, tool_dispatch, policy, cost
├── host/            # register a machine as a host; daemon; git worktrees
├── server/          # Starlette app: auth/OIDC, accounts, managed_hosts, routes
├── llms/            # own multi-provider LLM client (Responses API surface)
│                    #   adapters/: anthropic, openai, bedrock, vertex, gemini,
│                    #   databricks
├── policies/        # governance engine: base, registry, CEL, builtins/
│                    #   (safety, cost, github, google, risk_score, routing, …)
├── sandbox/         # local OS sandboxes: omnigent/sandbox/bwrap.py, omnigent/sandbox/seatbelt.py
├── tools/           # tool model: builtins, MCP, local callables, client tools
├── stores/          # persistence: agent / conversation / file / policy / …
├── terminals/       # terminal registry + websocket bridge
├── environments/    # execution-environment abstraction
├── onboarding/      # setup wizard, provider/credential config,
│                    #   sandboxes/ (modal, daytona, e2b, islo, cwsandbox,
│                    #   boxlite, kubernetes, openshell)
├── db/ · entities/  # database + domain entities
├── repl/ · resources/ · testing/   # REPL, static resources, test helpers
└── omnigent/update_check.py · omnigent/cost_plan.py · omnigent/model_override.py · omnigent/errors.py

The repeated *_native* pattern is the heart of the meta-harness: each underlying agent gets a dedicated bridge family that translates its quirks into Omnigent's uniform session, policy, and cost model.

6. The "19th-project" context

This is project #19 in a corpus studying agent / LLM tools (Claude Code, Strix, OpenHands, Hermes, Mistral Vibe, Comp AI, Kimi Code, …). Where most of those are single agents — one loop, one harness — Omnigent is the rare meta-harness: it consumes the others as interchangeable backends.

Standout traits worth carrying into later docs:

Meta-harness, not an agent. It wraps Claude Code, Codex, Cursor, Pi, Kimi, Goose, Qwen, OpenCode, Hermes, Antigravity, Copilot, and Kiro rather than competing with them. The corpus already analyzes Hermes and Kimi Code as standalone tools — here you can watch them be driven by a harness above them.
Policy governance as a first-class subsystem. omnigent/policies/ with a CEL evaluator, a builtins catalog, and three-level stacking (server / agent / session) is unusual depth for an open-source agent runtime.
Many sandbox providers. Eight cloud-sandbox backends plus three local OS sandboxes (bwrap / seatbelt / Windows Job Object) — a breadth no other corpus project matches.
Its own LLM client. Most corpus projects lean on litellm; Omnigent built a replacement around the Responses API with Chat Completions as an internal interchange.

For the EU AI Act platform: Omnigent's three-level policy stack, the CEL evaluator (side-effect-free, guaranteed-terminating — pyproject.toml:46-48), the egress proxy that can log every network call, and the per-session stores together form the skeleton of an audit-traceable-by-construction runtime — directly relevant to Articles 12 (record-keeping) and 14 (human oversight, via the approval-pause policies). Worth a dedicated read of omnigent/policies/ and omnigent/inner/egress/.

Next: 01_architecture.md (server ↔ host ↔ runner ↔ runtime data flow), then the inner-loop bridges, the policy engine, the LLM client, and the sandbox providers.