File-to-Responsibility Map

A navigable map of the Omnigent repo. Omnigent is a meta-harness: a common orchestration layer (sessions, policies, sandboxing, real-time multi-device UI) that wraps many third-party coding agents (Claude Code, Codex, Cursor, …) plus agents you write yourself in YAML.

Rough size: ~290k LOC Python in omnigent/ (499 files), ~437k LOC in tests/, ~134k LOC TypeScript in ap-web/src/ (483 .ts(x) files). 11 native agents are wrapped (claude, codex, cursor, goose, kimi, pi, qwen, opencode, antigravity, kiro, hermes).

Skip the obvious (omnigent/__init__.py re-exports, _*.py private helpers) unless noted.

Repo Top Level

Path	Responsibility
`omnigent/`	The Python package — CLI, server, runner, runtime, native wrappers, tools. The whole product backend.
`ap-web/`	The web/desktop UI: a Vite + React/TypeScript SPA (`src/`), an Electron wrapper (`electron/`), and an iOS shell (`ios/`). ~134k LOC.
`sdks/`	Client SDKs: `python-client/` (programmatic `OmnigentClient`), plus a `ui/` embed and shared `README.md`.
`deploy/`	One subdir per sandbox/host target (modal, daytona, e2b, islo, kubernetes, fly, railway, render, docker, hf-spaces, cloudflare, boxlite, cwsandbox, openshell, databricks, tailscale).
`designs/`	Architecture proposals: `designs/CLI_CONTRACT.md`, `designs/SANDBOX_CREDENTIAL_PROXY.md`, CI/contributor-review proposals.
`docs/`	User + design docs: `docs/AGENT_YAML_SPEC.md`, `docs/POLICIES.md`, per-agent native design notes (cursor, qwen, antigravity), bot setup.
`examples/`	Sample agents: `examples/kimi_hello.yaml` (single-file launcher), `debby/` `polly/` `scribe/` (multi-agent bundle layout with `agents/` + `skills/` + `config.yaml`).
`tests/`	~437k LOC, mirrors the package layout (server/ runner/ runtime/ inner/ spec/ stores/ …) plus `e2e/`, `e2e_ui/`, `codex_parity/`, per-native-agent `test__native_.py`.
`scripts/`	Dev/release helpers: `scripts/dump_openapi.py`, `scripts/gen_cursor_models.py`, `scripts/install_oss.sh`, `scripts/update_versions.py`, `scripts/normalize_uv_lock_registry.py`.
`dev/`	Lint/dev tooling (`dev/lint`).

Key root files

File	Responsibility
`pyproject.toml`	Deps, tool config, entry points (~30k bytes).
`setup.py`	Packaging shim alongside `pyproject.toml`.
`openapi.json`	Generated OpenAPI spec for the server (~371 KB); regenerate via `scripts/dump_openapi.py`.
`config.yaml`	Default LLM profile (`databricks-claude-haiku-4-5`, profile `oss`).
`railway.toml` / `render.yaml`	PaaS deploy blueprints — both pull the prebuilt CI image (a source build can't produce the gitignored web bundle); pair with managed Postgres.
`uv.lock` / `uv.toml`	uv dependency lock + config.
`pyrefly.toml`	Type-checker config.
`README.md`, `CONTRIBUTING.md`, `RELEASING.md`, `SECURITY.md`, `NOTICE`, `LICENSE`	Docs/legal (Apache 2.0).

`omnigent/` package — by subsystem

Top-level orchestration files (package root)

File	LOC	Responsibility
`omnigent/cli.py`	12.5k	Main CLI surface — all subcommands (`chat`, `run`, native-wrapper launches, auth, sandbox).
`omnigent/chat.py`	4.1k	The `omnigent chat` flow — load a spec/YAML, start a session, drive the REPL.
`omnigent/native_coding_agents.py`	190	`NativeCodingAgent` metadata registry — stable wire labels + harness mapping for each wrapped TUI.
`omnigent/native_server_harness.py` / `omnigent/native_server_transport.py` / `omnigent/native_terminal.py`	—	Shared scaffolding all native wrappers reuse (server harness, transport, TTY attach).
`omnigent/native_policy_hook.py`	382	Common policy-enforcement hook shared across native agents.
`omnigent/model_catalog.py` / `omnigent/model_override.py` / `omnigent/reasoning_effort.py` / `omnigent/cost_plan.py`	—	Model metadata, per-invocation overrides, reasoning-effort + cost plumbing.
`omnigent/session_lifecycle.py` / `omnigent/resume_dispatch.py` / `omnigent/update_check.py`	—	Session bind/create/resume dispatch, update checks.
`omnigent/harness_aliases.py`	—	Canonicalizes harness names (e.g. aliases → canonical key).
`omnigent/cli_auth.py` / `omnigent/cli_sandbox.py` / `omnigent/cli_diagnostics.py`	—	Auth, sandbox-launch, and diagnostics CLI helpers.
`omnigent/_wrapper_labels.py` / `omnigent/_platform.py` / `omnigent/_env_compat.py` / `omnigent/_runner_startup.py`	—	Private constants & startup glue.

Native-agent wrappers (one family per agent, package root)

Each wrapped agent has a base module (<agent>_native.py) that launches the third-party TUI terminal-first inside an Omnigent session, plus a suffix family. Suffix meanings: bridge = MCP/filesystem rendezvous between the live TUI and Omnigent turns; forwarder = background transcript/event forwarding to the session stream; hook = lifecycle/policy hook into the agent; permissions = permission-prompt mapping; state = wrapper-side session state; credentials = auth/key plumbing.

Agent	Base	Suffix modules present	Notes
claude	`omnigent/claude_native.py` (4.4k)	bridge (4.8k), forwarder (4.0k), hook, message_display_hook, state, status	Most fleshed-out wrapper.
codex	`omnigent/codex_native.py` (2.5k)	app_server, bridge, elicitation, forwarder (5.4k), hook, state	App-server transport + elicitation.
cursor	`omnigent/cursor_native.py`	bridge, forwarder, permissions, usage	Usage/cost tracking.
goose	`omnigent/goose_native.py`	bridge, forwarder, permissions
kimi	`omnigent/kimi_native.py`	bridge, credentials, forwarder, hook
pi	`omnigent/pi_native.py`	bridge, credentials	Thinnest family.
qwen	`omnigent/qwen_native.py`	bridge, forwarder, permissions
opencode	`omnigent/opencode_native.py`	app_server, bridge, client, forwarder, permissions, provider, state (+ `omnigent/opencode_http_transport.py`)	HTTP-transport based.
antigravity	`omnigent/antigravity_native.py` (1.7k)	audit, bridge, interactions, launch, reader (2.6k), rpc (1.6k), steps	RPC-driven; richest non-claude family.
kiro	`omnigent/kiro_native.py`	bridge, session_forwarder
hermes	`omnigent/hermes_native.py`	bridge, forwarder, permissions

`server/` — control-plane API (~42k LOC)

FastAPI app that owns accounts/auth/identity, host registry, presence, and the session REST/WS surface. Multi-user, IdP-optional.

File	Responsibility
`app.py` (2.2k)	FastAPI app assembly, middleware, static mount — server entry point.
`omnigent/server/routes/sessions.py` (19.7k)	The big one — all session create/resume/message/stream/terminal routes.
`routes/` (others)	hosts, host_tunnel, runner_tunnel, comments, policies, accounts_auth, terminal_attach, session_mcp_servers, builtin_agents, default_policies.
`omnigent/server/schemas.py` (3.6k)	Pydantic wire schemas for the API.
`auth.py` / `omnigent/server/oidc.py` / `omnigent/server/oidc_access.py` / `accounts_*.py` / `omnigent/server/passwords.py`	Auth: OIDC + built-in `accounts` multi-user store.
`omnigent/server/managed_hosts.py` / `omnigent/server/host_registry.py` / `omnigent/server/presence.py`	Managed-host provisioning, host registry, live presence.

`runner/` — harness process manager (~32k LOC)

Owns harness subprocesses; resolves harness type + spawn-env from the agent spec and dispatches tool calls. (See designs/RUNNER.md.)

File	Responsibility
`app.py` (17k)	Runner FastAPI app — spawn harness subprocesses, dispatch to them.
`omnigent/runner/tool_dispatch.py` (5.7k)	Routes tool calls to the right handler.
`policy.py` / `omnigent/runner/pending_approvals.py`	Policy gating + human-in-the-loop approvals.
`omnigent/runner/cost_advisor.py` / `omnigent/runner/cost_judge.py` / `routing.py`	Cost-aware model routing.
`omnigent/runner/mcp_manager.py` / `omnigent/runner/proxy_mcp_manager.py` / `omnigent/runner/resource_registry.py`	MCP server pools, resource registry.

`runtime/` — turn/agent execution core (~18k LOC)

File	Responsibility
`omnigent/runtime/workflow.py` (2.5k)	The agent turn/workflow loop.
`omnigent/runtime/harnesses/_executor_adapter.py` (1.8k) / `omnigent/runtime/harnesses/_scaffold.py` (1.7k) / `omnigent/runtime/harnesses/process_manager.py` (1.2k)	Generic harness scaffold + executor adapter + subprocess lifecycle.
`omnigent/runtime/policies/engine.py` (1.2k)	Runtime policy evaluation engine.
`omnigent/runtime/compaction.py` / `prompt.py` / `omnigent/runtime/content_resolver.py`	History compaction, prompt assembly, content resolution.
`omnigent/runtime/session_stream.py` / `omnigent/runtime/user_session_stream.py` / `omnigent/runtime/pending_elicitations.py` / `omnigent/runtime/pending_inputs.py`	Live session event streams + pending UI prompts.
`credentials/`	Per-session credential resolution.

`inner/` — per-harness executors & sandbox runtime (~40k LOC)

The "inner" process: the actual integration code for each backend, plus the sandbox jails. Each agent has an <agent>_executor.py + <agent>_harness.py pair (SDK-mode), and native agents add <agent>_native_executor.py + <agent>_native_harness.py (terminal-mode).

File	Responsibility
`omnigent/inner/claude_sdk_executor.py` (2.6k) / `omnigent/inner/codex_executor.py` (2.3k) / `omnigent/inner/pi_executor.py` (2.3k) / `omnigent/inner/openai_agents_sdk_executor.py` (1.8k)	Largest executors — drive each backend's SDK/CLI.
`_executor.py` / `_harness.py` (per agent)	Executor = runs turns against a backend; harness = process/lifecycle wrapper. Backends: claude_sdk, codex, cursor, goose, hermes, kimi, pi, qwen, copilot, databricks, antigravity, openai_agents_sdk + native variants.
`omnigent/inner/seatbelt_sandbox.py` (2.0k) / `omnigent/inner/bwrap_sandbox.py` / `omnigent/inner/windows_jobobject_sandbox.py`	OS-level sandboxes (macOS Seatbelt, Linux bubblewrap, Windows job objects).
`omnigent/inner/credential_proxy.py` / `omnigent/inner/claude_gateway_shim.py`	Credential proxying + Claude gateway shim.
`policies.py` / `omnigent/inner/cursor_policy_hook.py` / `omnigent/inner/hermes_policy_hook.py`	Inner-side policy hooks.

`policies/` — policy framework (~7k LOC)

File	Responsibility
`base.py` / `omnigent/policies/function.py` (646) / `registry.py` / `omnigent/policies/schema.py` / `types.py`	Policy model, function-policy support, registry, schemas.
`omnigent/policies/builtins/github.py` (1.1k) / `omnigent/policies/builtins/google.py` / `omnigent/policies/builtins/cost.py` / `omnigent/policies/builtins/safety.py`	Built-in policy bundles.

`tools/` — tool system (~11k LOC)

File	Responsibility
`omnigent/tools/manager.py` (924)	Tool registry / resolution.
`omnigent/tools/mcp.py` (1.3k)	MCP client integration.
`local.py` / `omnigent/tools/local_callable.py` / `base.py` / `_runner.py`	Local Python-callable tools + base types.
`omnigent/tools/builtins/spawn.py` (1.6k) / `omnigent/tools/builtins/sys_terminal.py` (1.1k) / `omnigent/tools/builtins/agents.py` / `omnigent/tools/builtins/load_skill.py` / `omnigent/tools/builtins/list_files.py`	Built-in tools (spawn sub-agents, terminal, skills, FS).
`client_specified/`	Tools defined by the connected client.

`client_tools/` — tools the client-side runs (~0.5k LOC)

omnigent/client_tools/coding.py, omnigent/client_tools/async_demo.py — reference client-executed tools.

`spec/` — Agent YAML spec & translation (~9k LOC)

File	Responsibility
`omnigent/spec/parser.py` (3.3k)	Parse Agent YAML → spec objects.
`omnigent/spec/omnigent.py` (2.0k)	Bidirectional translator `AgentSpec` ↔ `AgentDef` (round-trip invariant tested).
`types.py` (1.5k) / `omnigent/spec/validator.py` (628)	Spec types + validation.

`stores/` — persistence repositories (~7k LOC)

One subdir per aggregate: conversation_store/ (sqlalchemy_store.py 2.6k — the largest), agent_store/, artifact_store/, comment_store/, file_store/, permission_store/, policy_store/, plus omnigent/stores/host_store.py.

`db/` — schema & migrations (~4k LOC)

omnigent/db/db_models.py (789) SQLAlchemy models, omnigent/db/converters.py, omnigent/db/utils.py (902), migrations/versions/* (Alembic).

`entities/` — domain models (~2k LOC)

Plain dataclasses/pydantic: omnigent/entities/account.py, omnigent/entities/agent.py, omnigent/entities/conversation.py, omnigent/entities/comment.py, omnigent/entities/file.py, omnigent/entities/permission.py, policy.py, omnigent/entities/session_resources.py, environment_filesystem.py, omnigent/entities/pagination.py.

`environments/` — (~45 LOC) thin namespace/init for environment types.

`terminals/` — terminal multiplexing (~1.2k LOC)

registry.py (terminal resource registry), omnigent/terminals/ws_bridge.py (WebSocket TTY bridge).

`onboarding/` — first-run setup wizard (~17k LOC)

File	Responsibility
`omnigent/onboarding/wizard.py` (1.5k) / `omnigent/onboarding/interactive.py` / `setup.py`	The interactive onboarding flow.
`omnigent/onboarding/provider_config.py` (1.4k) / `omnigent/onboarding/configure_models.py` (938) / `omnigent/onboarding/provider_selection.py`	Model/provider config.
`*_auth.py` (antigravity, copilot, cursor, gemini, goose, opencode)	Per-backend auth flows.
`omnigent/onboarding/sandboxes/kubernetes.py` (1.5k) / `omnigent/onboarding/sandboxes/e2b.py` (782) / …	Sandbox provider setup.

Path	Responsibility
`src/main.tsx` / `App.tsx` / `embed.tsx`	SPA + embeddable entry points.
`src/pages/`	Route-level views — `ChatPage.tsx` (the core session view), `ApprovePage.tsx`, etc.
`src/components/`	Reusable components: `AgentCard`, `PermissionsModal`, `CostRoutingControl`, `ai-elements/`, `blocks/`, `icons/`.
`src/store/`, `src/hooks/`, `src/lib/`, `src/shell/`	State, hooks, utilities, app shell.
`electron/`, `ios/`, `platform-assets/`	Desktop (Electron) + iOS shells.
`ap-web/vite.config.ts` / `ap-web/vite.embed.config.ts`	Build configs (app + embed).

Where to Start Reading

To understand Omnigent end-to-end, read in this order:

README.md — 5 min — the product thesis: a meta-harness over many agents, multi-device sync, YAML-defined agents.
docs/AGENT_YAML_SPEC.md + examples/kimi_hello.yaml — 5 min — the user-facing contract: how an agent is declared.
omnigent/spec/omnigent.py + omnigent/spec/parser.py — 10 min — how YAML becomes an executable spec (the AgentSpec↔AgentDef translation).
omnigent/runner/app.py (header + spawn path) — 10 min — how a spec resolves to a harness subprocess; the heart of the meta-harness.
omnigent/runtime/workflow.py — 10 min — the actual turn loop once a harness is running.
omnigent/inner/claude_sdk_executor.py — 10 min — one concrete backend integration (Claude), the template for all *_executor.py.
omnigent/claude_native.py + omnigent/claude_native_bridge.py (headers) — 10 min — the native (terminal-first) wrapper pattern that all 11 wrapped TUIs follow.
omnigent/server/routes/sessions.py (skim) — 10 min — the API surface that the web/mobile/desktop clients drive.

The three subsystems to study first, in priority order:

runner/ + runtime/ — the orchestration core: how any harness is spawned and a turn is executed.
inner/ (the *_executor.py/*_harness.py pairs) + the root *_native*.py wrapper families — how each real agent is actually integrated, in two flavors (SDK vs native terminal).
spec/ — the YAML contract that ties user intent to executor selection.

Navigating By Concern

"How is a third-party agent wrapped as a terminal?" → omnigent/<agent>_native.py + <agent>_native_bridge.py (MCP/FS rendezvous) + <agent>_native_forwarder.py (transcript → stream).
"How does a YAML agent get executed?" → omnigent/spec/parser.py → omnigent/spec/omnigent.py → omnigent/runner/app.py (spawn) → omnigent/runtime/workflow.py (turn loop).
"How is a backend (Claude/Codex/…) driven?" → inner/<backend>_executor.py + inner/<backend>_harness.py.
"How are policies enforced?" → policies/ (definitions) + omnigent/runner/policy.py + omnigent/runtime/policies/engine.py + omnigent/native_policy_hook.py.
"How does sandboxing work?" → omnigent/inner/seatbelt_sandbox.py / omnigent/inner/bwrap_sandbox.py / omnigent/inner/windows_jobobject_sandbox.py, selected via sandbox/.
"How does the server expose sessions to clients?" → omnigent/server/app.py + omnigent/server/routes/sessions.py; client side in ap-web/src/pages/ChatPage.tsx.
"How are conversations persisted?" → omnigent/stores/conversation_store/sqlalchemy_store.py + omnigent/db/db_models.py.
"How does cost-aware model routing decide?" → omnigent/runner/cost_advisor.py + omnigent/runner/cost_judge.py + routing.py; omnigent/llms/routing.py.
"Where is the interactive terminal UI?" → omnigent/repl/_repl.py.