How Omnodex Works

Omnodex operates as a passive observer of AI agent execution. It hooks into the agent runtime, captures a complete record of activity, and analyzes it for risk - all without interfering with the agent itself.

The Pipeline

Agent executes -> Hook fires -> Event captured -> Log appended -> Analysis runs -> Dashboard updates

Each stage is independent and asynchronous. A failure at any stage does not affect the agent or earlier stages.

1. Interception

Omnodex registers as a hook in the agent’s runtime (Claude Code, OpenAI Codex, and Google Antigravity hooks). Where hooks are not available, such as Cowork, or for MCP servers you want to route explicitly, it intercepts at the MCP protocol layer with the Omnodex MCP proxy. When the agent invokes a tool, the runtime fires the hook, or the call passes through the proxy, with the event details.

The hook is:

• Async - It does not block the agent’s execution
• External - It runs outside the agent’s context window (the agent cannot see it)
• Passive - It observes only; it cannot modify the agent’s behavior

2. Event Capture

The hook captures structured event data:

• What tool was called
• What parameters were passed
• What result was returned
• When it happened
• Which session it belongs to

Events are normalized into a consistent schema regardless of which agent or interceptor produced them.

3. Event Log

Events are appended to append-only JSONL files, one per session. This is the source of truth. Properties:

• Append-only - Events can never be modified or deleted once written
• Tamper-evident - The sequential structure makes gaps or modifications detectable
• Replayable - Any derived view (database, dashboard) can be rebuilt from the log

4. Analysis

The rule engine scans events and applies detection rules. Each rule defines a pattern to match and a risk level to assign. Analysis produces findings that are attached to the events that triggered them.

5. Reporting

Results are available via:

• A local web dashboard with real-time SSE updates
• CLI reports
• (Hosted tier) A cloud dashboard with team access

Design Principles

Event-log-first: The JSONL event log is the source of truth. The SQLite database is a derived read model that can be rebuilt by replaying the log at any time.

Interceptor-agnostic: The system is designed to support multiple agent runtimes through a common interface. Adding a new agent only requires implementing the interceptor interface - everything downstream works unchanged.

Local-first: The free tier is a complete, fully-functional product that runs entirely on your machine. Cloud features are additive, not required.