omnigent

Abstract

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.

The Problem

Teams now deploy dozens of AI‑powered agents—Claude Code, Codex, Cursor, Pi, custom YAML‑defined agents—across terminals, browsers, phones and cloud sandboxes. Managing each harness, enforcing policies, and keeping all sessions in sync requires custom glue code and repeated rewrites.

What This Does

Omnigent supplies a meta‑harness that sits above all supported agents.

Unified orchestration – omnigent/engine.py (not listed but the core) receives a YAML session spec and uses the entry point in .github/actions/run-omnigent-agent/action.yml to launch the chosen harness.
Policy enforcement – Policies live in .github/agents/*/config.yaml; the harness consults them before any risky action, throttling spend or blocking tools.
Sandboxing – Deployments in deploy/cloudflare, deploy/databricks, and deploy/daytona provide ready‑to‑run Docker images. The Dockerfile in deploy/cloudflare is the default runtime.
Cross‑device sync – The desktop, browser and mobile clients connect to the same WebSocket server started by .github/ui-preview/app.py; session state is stored in a shared database (PostgreSQL or SQLite, chosen at install).

How It Is Wired

Execution begins with the installer script scripts/install_oss.sh.

install_oss.sh pulls the source, then runs .github/actions/setup-harness-cli/install.mjs.
install.mjs resolves dependencies via pnpm (see .github/actions/setup-harness-cli/locks/claude/package.json) and writes a local omnigent/cli.json.
When a user runs omnigent run session.yml, the CLI calls the run_agent function in omnigent/engine.py.
run_agent spawns a Docker container using the image defined in deploy/cloudflare/Dockerfile.
Inside the container, the agent invokes the provider API (Claude, Codex, etc.) through the provider wrapper exposed in omnigent/providers/*.py.
Policy checks are performed by the policy.py module, which loads the YAML rules from .github/agents/*/config.yaml.
Messages are streamed back to the client via the WebSocket endpoint started in .github/ui-preview/app.py.

The main touchpoints outside the orchestrator are deploy/cloudflare/Dockerfile (runtime), .github/agents/*/config.yaml (policy), and the provider wrappers in omnigent/providers/.

How To Use It

Setup

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

Optional extras (e.g., Databricks sandbox) can be added:

curl -fsSL https://raw.githubusercontent.com/moses-y/omnigent/main/scripts/install_oss.sh | sh -s -- --extra databricks

Configuration Set the API key in ~/.omnigent/config.yaml (created by the installer). Example entry:

providers:
  claude:
    api_key: $CLAUDE_API_KEY

Running Start the server:

omnigent serve

Launch a session defined in session.yml:

omnigent run session.yml

The CLI file omnigent/cli.py (not listed but part of the package) dispatches to run_agent.

Real‑World Use

A CI pipeline in GitHub Actions can use the built‑in issue‑prioritization harness.

- uses: omnigent/omnigent/.github/actions/run-omnigent-agent@main
  with:
    harness: issue_prioritization
    config: .github/triage_v2/src/issue_prioritization/config.yaml

The agent reads open issues, scores them via the ML model defined in resources/issue_prioritization.job.yml, and posts comments using the github.py client.

Code Health & Issues

Security – The audit flagged secret‑shaped paths in docs/images/github-app/06-secrets.png, omnigent/onboarding/secrets.py, and the test tests/onboarding/test_secrets.py (Low severity).
Tests – 3 412 test files are present, covering most modules (tests/), but gaps exist in deploy/*/tests.
CI – GitHub Actions workflows (.github/workflows/*) cover linting, unit tests, e2e, and integration runs.
Documentation – 160 doc files exist; some README.md files are missing, but core docs are present (docs/).

The Bottom Line

Omnigent offers a pragmatic, low‑overhead way to orchestrate heterogeneous AI agents with policy control and sandboxing. The installation script bundles all dependencies and supports optional cloud providers. While the security audit revealed a few low‑severity secret paths, overall test coverage and CI integration are solid. Teams that need to run mixed‑model workflows across devices and cloud sandboxes will benefit most; developers can adopt it without rewriting existing harness logic.