How Driga observes sessions

Driga does not run inside your agents and does not proxy their traffic. It reads what agents already leave on disk, watches the process table, and accepts events from hooks you choose to install.

Evidence sources

• Session files. Claude Code and Codex histories and Gemini CLI chat transcripts. The Codex catalog is opened read-only. Copilot session-state files are not read.
• Hooks. Optional commands the agent runs on lifecycle events. They append events to a spool directory and exit immediately; only the collector writes the database. Claude’s permission hook talks to the collector’s in-memory broker instead, so a prompt can be answered. See the hooks reference.
• Processes. The process table attributes processes to sessions by parent chain and working directory, matched against signatures. Antigravity (agy) is observed this way only, because its storage format is closed.
• Git. Local git commands for branches, worktrees, dirty state and overlaps. They never fetch.
• OTLP (optional). A loopback OTLP/HTTP JSON receiver that enriches existing Claude sessions with metadata. Content attributes are discarded before storage, and it never creates sessions.

Unknown or incomplete evidence is shown as such: stalled? is a suspicion, unknown means the evidence cannot decide, and unknown agent versions are parsed tolerantly and reported by driga doctor.

Collector and snapshots

Without a collector, every read command takes a one-shot snapshot that writes no database and is labelled snapshot · no history.

The collector (driga service install, or driga collect in the foreground) keeps a local SQLite database. Only one collector can hold a data directory. Idle, it samples processes and machine health every 60 seconds and Git every five minutes; while a viewer is open those speed up to 5, 10 and 30 seconds.

Families

Related sessions form a family, such as a lead session and the workers it spawned. Spawn links come only from a recorded parent; Flow never infers them from timing. Selecting one session never selects its whole family.

Interfaces share one read path

The CLI’s --json, the terminal UI, the web dashboard, the MCP server and paired viewers read the same schema-2 views. JSON envelopes carry the observation time, collection mode, source freshness and coverage gaps, so a consumer can tell how current an answer is.

OTLP intake

[intake]
otlp = true
listen = "127.0.0.1:7418"

Then configure the exporters, previewing first:

driga hooks install --otlp claude --dry-run
driga hooks install --otlp claude
driga hooks status --otlp

For Claude this sets logs to OTLP with metrics and traces off (add --traces for Claude’s beta spans) and does not enable prompt or tool-content logging. Installation refuses to replace telemetry you have already configured.