Events and Traces

Everything Omnodex captures is a trace event. Detection, the dashboards, and reports are all built on the event stream.

Event structure

Every event has:

Field	Description
event_id	Unique identifier for this event
session_id	The agent session that produced it
occurred_at	When it happened (ISO 8601)
interceptor	What captured it, for example claude-code-hook, codex-hook, or mcp-proxy
event_type	What kind of event it is, for example tool.invoked

The remaining fields depend on the event type.

Event types

Type	Description
session.started	An agent session, or a proxy session, began
session.ended	The session ended
tool.invoked	The agent called a tool. Includes the tool name, owning server, and parameters
tool.completed	The tool call finished. Includes duration, status, and response size
file.read	The agent read files
file.written	The agent wrote a file
risk.detected	A detection rule matched

tool.invoked and tool.completed share a tool_call_id, so each call can be followed from start to finish. Tool output is never stored, only its size.

See the Event Schema for every field.

Sessions

Events are grouped into sessions. A hook session covers one agent session, from start to finish. A proxy session covers one run of the MCP proxy, which a desktop app may keep open across several conversations.

Sessions give analysis context: a tool call that looks suspicious in isolation can be normal for what the agent was asked to do.

The event log

Events are stored as JSON Lines (one JSON object per line), in one append-only file per session under event-log/sessions/ in the Omnodex home.

{"schema_version":1,"event_id":"a1b2c3d4-0000-4000-8000-000000000001","session_id":"sess-example","occurred_at":"2026-09-16T10:00:01Z","recorded_at":"2026-09-16T10:00:01Z","interceptor":"claude-code-hook","event_type":"tool.invoked","tool_call_id":"call-1","tool_name":"Read","mcp_server":"builtin","parameters":{"file_path":"/home/case/project/src/index.ts"}}

This format is:

• Human-readable - inspect it with cat, grep, or jq
• Append-only - new events are added to the end; existing lines are not rewritten
• Streamable - the dashboard tails the files for real-time updates
• Portable - plain JSON, readable by any tool

The SQLite database (traces.db) is built from these files and can be deleted and rebuilt with omnodex replay at any time.

Next steps

• How Omnodex Works - The full pipeline
• Event Schema Reference - Complete field reference