---
title: "How Driga observes sessions"
summary: "Evidence sources per agent, the collector and hook spool, snapshot mode, collection cadence, session families and how uncertain evidence is shown."
description: "Where Driga's evidence comes from - session files, hooks, the process table, Git and optional OTLP - and how the collector, spool and snapshots fit together."
read_when:
  - "You want to know why a session shows a particular label."
  - "You are deciding whether to install hooks, the service or OTLP intake."
---
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](/reference/hooks).
- **Processes.** The process table attributes processes to sessions by parent
  chain and working directory, matched against
  [signatures](/guides/projects-and-machines#orphans). 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

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

Then configure the exporters, previewing first:

```sh
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.