Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/omnigent-ai/omnigent/llms.txt

Use this file to discover all available pages before exploring further.

Harnesses are adapters that connect Omnigent’s runner to a specific agent runtime or SDK. When a session starts, the runner loads the harness declared in the agent spec (or passed on the CLI), hands it the model credentials from the user’s machine, and delegates the entire LLM loop to it. Swapping harnesses is a one-line change in YAML or a single CLI flag — no rewriting of agent logic.

​
Supported Harnesses

HarnessDescriptionCredential typeNotes
claude-sdkClaude Code via the claude-agent-sdk Python packageAnthropic API key, Claude subscription, or compatible gatewayDefault alias: claude
openai-agentsOpenAI Agents SDKOpenAI API key or compatible gatewayAlias: openai-agents-sdk
codexOpenAI Codex CLI via the @openai/codex npm packageOpenAI API key or ChatGPT subscriptionRequires Node.js 22 LTS+
piPi harness (Anthropic Pi)Claude subscription or API keyRequires Node.js 22 LTS+
claude-nativeNative Claude Code CLI, tmux-basedClaude subscriptionBoots from Claude Code’s own on-disk transcript
codex-nativeNative Codex CLI, tmux-basedOpenAI/ChatGPT subscriptionBoots from Codex’s own on-disk transcript
The native harnesses (claude-native, codex-native) require tmux and launch the underlying CLI in a managed terminal pane. The SDK harnesses (claude-sdk, openai-agents, codex, pi) run as Python or Node subprocesses and do not require tmux.

​
Selecting a Harness

The harness for an agent is set in two places: In the agent YAML (executor.harness): 
name: my_agent
prompt: You are a helpful coding assistant.

executor:
  harness: claude-sdk        # or: codex, openai-agents, pi, claude-native, codex-native
On the CLI with the --harness flag: 
omnigent run --harness codex
omnigent run --harness openai-agents
omnigent run examples/my_agent.yaml --harness pi
When both are present, --harness takes precedence over the YAML declaration for the top-level agent (sub-agents keep their own harness as declared in their spec).

​
Switching Harnesses at Runtime

You can override the harness for any agent — including the bundled example agents — without editing their YAML files. For example, to run the Polly multi-agent orchestrator using the pi harness instead of its default: 
omnigent run examples/polly/ --harness pi
omnigent run examples/debby/ --harness openai-agents
Sub-agents declared inside the orchestrator YAML retain their own harness settings; only the top-level supervisor’s harness is overridden.

​
Model Selection Within a Harness

You can choose which model a harness uses in three ways, from highest to lowest precedence: CLI flag — applies to the current run only: 
omnigent run examples/my_agent.yaml --harness claude-sdk --model claude-opus-4-7
In-session /model command — switches the model mid-conversation in the REPL: 
/model claude-sonnet-4-6
executor.model in the agent YAML — sets the default model for an agent: 
executor:
  harness: openai-agents
  model: gpt-4o

​
Gateways

Instead of a first-party API key, you can point any harness at an OpenAI- or Anthropic-compatible gateway — OpenRouter, Ollama, LiteLLM, vLLM, Azure, or any other compatible backend. Gateways are configured via omnigent setup and stored as named credential entries. The base URL depends on which harness family the gateway serves:
ProviderFor harnessBase URLKey
OpenRouterclaude-sdkhttps://openrouter.ai/apiYour OpenRouter key (sk-or-…)
OpenRoutercodex / openai-agentshttps://openrouter.ai/api/v1Your OpenRouter key (sk-or-…)
Ollama (local)codex / openai-agentshttp://localhost:11434/v1Any value (Ollama ignores it)
For the claude-sdk harness, point at OpenRouter’s Anthropic-compatible endpoint (…/api, not …/api/v1). For codex and openai-agents, use the OpenAI-compatible …/api/v1 endpoint.
Other compatible backends (LiteLLM, vLLM, Azure OpenAI) follow the same pattern: provide a base URL and an API key when prompted by omnigent setup. The gateway entry becomes selectable as a credential for any harness in the same family.

​
Configuring Credentials

Run omnigent setup to add, switch, or remove credentials for any harness interactively. Credentials are stored per harness, so a Claude default and a Codex default coexist without conflict. Run omnigent config list to see what is currently configured.
Omnigent works with four kinds of credentials:

API Key

A first-party vendor key for Anthropic, OpenAI, and similar providers. Stored in the system keychain or referenced via an environment variable.

Subscription

A Claude Pro/Max or ChatGPT plan, via the official claude or codex CLIs. omnigent setup drives the harness’s own login flow.

Gateway

Any OpenAI- or Anthropic-compatible base_url and key (OpenRouter, LiteLLM, Ollama, vLLM, Azure). Configured with a name, URL, and key in omnigent setup.

Databricks

A Databricks workspace profile that routes model calls through Unity AI Gateway. Requires the databricks extra (uv tool install "omnigent[databricks]").

Build docs developers (and LLMs) love

Get started for freeTalk to us