Skip to content
Omnodex Omnodex Omnodex Docs

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

Section titled “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

Section titled “1. Interception”

Omnodex registers as a hook in the agent’s runtime (Claude Code hooks, OpenAI Codex hooks). For desktop agents like Cowork, it intercepts at the MCP proxy layer instead. When the agent invokes a tool, the runtime fires the hook 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

Section titled “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

Section titled “3. Event Log”

Events are appended to an immutable, append-only JSONL file. 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

Section titled “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

Section titled “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

Section titled “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.