# perplexityai/numbat architecture

> Architecture diagram of the GitHub repository perplexityai/numbat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/perplexityai/numbat
- Repository: https://github.com/perplexityai/numbat

## Overview

Numbat is an endpoint-local AI-agent activity monitor and forensic investigation CLI. Its main workflow captures live hook or OTLP events, or reconstructs events from discovered session artifacts; normalized events enter a shared evaluation path for CEL and sequence detections, then selected records are emitted locally or over HTTP. Separate CLI capabilities cover agent inventory, policy and hook management, timelines, and portable case bundles. The README and pipeline excerpt document shared processing; several sensor-to-pipeline and CLI-to-subsystem connections are not visible in the sampled callers and are marked unverified.

Main entry points: [`internal/pipeline/pipeline.go`](https://github.com/perplexityai/numbat/blob/main/internal/pipeline/pipeline.go) (Event Pipeline), [`cmd/numbat/main.go`](https://github.com/perplexityai/numbat/blob/main/cmd/numbat/main.go) (Numbat CLI), [`internal/hook/hook.go`](https://github.com/perplexityai/numbat/blob/main/internal/hook/hook.go) (Live Hooks), [`internal/otel/otel.go`](https://github.com/perplexityai/numbat/blob/main/internal/otel/otel.go) (OTLP Receiver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Setup"]
  node_cli["Numbat CLI<br/>[main.go]"]
  node_inventory["Agent Inventory<br/>[agents.go]"]
  node_hooksetup["Hook Management<br/>[hook_install.go]"]
  node_policy["Rule Commands<br/>[rules.go]"]
  node_artifactscan["Artifact Scan<br/>[scan.go]"]
end

subgraph group_sensors["Activity Sources"]
  node_livehook["Live Hooks<br/>[hook.go]"]
  node_otel["OTLP Receiver<br/>[otel.go]"]
  node_discover["Artifact Discovery<br/>[discover.go]"]
  node_extract["Session Extractors"]
end

subgraph group_detection["Normalization and Detection"]
  node_pipeline["Event Pipeline<br/>[pipeline.go]"]
  node_eventmodel["Normalized Events<br/>[event.go]"]
  node_rules["CEL Rule Engine<br/>[engine.go]"]
  node_sequence["Sequence Tracker<br/>[sequence.go]"]
  node_builtinrules["Built-in Rules<br/>[builtin.go]"]
end

subgraph group_investigation["Records and Investigation"]
  node_finding["Finding Renderer<br/>[finding.go]"]
  node_emitter["Record Emitter<br/>[output.go]"]
  node_sinks["File and HTTP Sinks"]
  node_indicators["Indicator Analysis<br/>[indicators.go]"]
  node_casebundle["Case Bundles<br/>[build.go]"]
  node_bundleverify["Bundle Verification<br/>[verify.go]"]
  node_timeline["Session Timelines<br/>[timeline.go]"]
end

node_operator(("Operator"))
node_httpservice(("HTTP Collector"))

node_operator -->|"invokes"| node_cli
node_cli -.->|"lists agents"| node_inventory
node_cli -.->|"installs hooks"| node_hooksetup
node_cli -.->|"manages rules"| node_policy
node_cli -.->|"scans artifacts"| node_artifactscan
node_cli -.->|"builds timelines"| node_timeline
node_operator -->|"enables capture"| node_livehook
node_operator -->|"exports logs"| node_otel
node_operator -->|"requests scan"| node_artifactscan
node_artifactscan -.->|"finds artifacts"| node_discover
node_discover -->|"classifies for parsing"| node_extract
node_livehook -->|"normalizes payload"| node_eventmodel
node_otel -->|"maps log records"| node_eventmodel
node_extract -->|"reconstructs events"| node_eventmodel
node_livehook -.->|"feeds events"| node_pipeline
node_otel -.->|"feeds events"| node_pipeline
node_extract -.->|"feeds events"| node_pipeline
node_pipeline -->|"evaluates events"| node_rules
node_pipeline -->|"tracks sequences"| node_sequence
node_rules -.->|"loads policy"| node_builtinrules
node_pipeline -->|"renders matches"| node_finding
node_pipeline -->|"emits records"| node_emitter
node_pipeline -->|"accumulates indicators"| node_indicators
node_emitter -.->|"routes records"| node_sinks
node_sinks -->|"delivers records"| node_httpservice
node_operator -->|"creates bundle"| node_casebundle
node_casebundle -.->|"supports verification"| node_bundleverify
node_operator -->|"investigates session"| node_timeline

click node_cli "https://github.com/perplexityai/numbat/blob/main/cmd/numbat/main.go"
click node_inventory "https://github.com/perplexityai/numbat/blob/main/cmd/numbat/agents.go"
click node_hooksetup "https://github.com/perplexityai/numbat/blob/main/cmd/numbat/hook_install.go"
click node_policy "https://github.com/perplexityai/numbat/blob/main/cmd/numbat/rules.go"
click node_artifactscan "https://github.com/perplexityai/numbat/blob/main/cmd/numbat/scan.go"
click node_livehook "https://github.com/perplexityai/numbat/blob/main/internal/hook/hook.go"
click node_otel "https://github.com/perplexityai/numbat/blob/main/internal/otel/otel.go"
click node_discover "https://github.com/perplexityai/numbat/blob/main/internal/discover/discover.go"
click node_extract "https://github.com/perplexityai/numbat/tree/main/internal/extract"
click node_pipeline "https://github.com/perplexityai/numbat/blob/main/internal/pipeline/pipeline.go"
click node_eventmodel "https://github.com/perplexityai/numbat/blob/main/internal/model/event.go"
click node_rules "https://github.com/perplexityai/numbat/blob/main/internal/rule/engine.go"
click node_sequence "https://github.com/perplexityai/numbat/blob/main/internal/sequence/sequence.go"
click node_builtinrules "https://github.com/perplexityai/numbat/blob/main/rules/builtin.go"
click node_finding "https://github.com/perplexityai/numbat/blob/main/internal/finding/finding.go"
click node_emitter "https://github.com/perplexityai/numbat/blob/main/internal/output/output.go"
click node_sinks "https://github.com/perplexityai/numbat/tree/main/internal/output"
click node_indicators "https://github.com/perplexityai/numbat/blob/main/internal/output/indicators.go"
click node_casebundle "https://github.com/perplexityai/numbat/blob/main/internal/casebundle/build.go"
click node_bundleverify "https://github.com/perplexityai/numbat/blob/main/internal/casebundle/verify.go"
click node_timeline "https://github.com/perplexityai/numbat/blob/main/cmd/numbat/timeline.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_inventory,node_hooksetup,node_policy,node_artifactscan toneBlue
class node_livehook,node_otel,node_discover,node_extract toneAmber
class node_pipeline,node_eventmodel,node_rules,node_sequence,node_builtinrules toneMint
class node_finding,node_emitter,node_sinks,node_indicators,node_casebundle,node_bundleverify,node_timeline toneRose
class node_operator,node_httpservice toneIndigo
```

## Components

### CLI and Setup

- [Numbat CLI](https://github.com/perplexityai/numbat/blob/main/cmd/numbat/main.go): `cmd/numbat/main.go`
- [Agent Inventory](https://github.com/perplexityai/numbat/blob/main/cmd/numbat/agents.go): `cmd/numbat/agents.go`
- [Hook Management](https://github.com/perplexityai/numbat/blob/main/cmd/numbat/hook_install.go): `cmd/numbat/hook_install.go`
- [Rule Commands](https://github.com/perplexityai/numbat/blob/main/cmd/numbat/rules.go): `cmd/numbat/rules.go`
- [Artifact Scan](https://github.com/perplexityai/numbat/blob/main/cmd/numbat/scan.go): `cmd/numbat/scan.go`

### Activity Sources

- [Live Hooks](https://github.com/perplexityai/numbat/blob/main/internal/hook/hook.go): `internal/hook/hook.go`
- [OTLP Receiver](https://github.com/perplexityai/numbat/blob/main/internal/otel/otel.go): `internal/otel/otel.go`
- [Artifact Discovery](https://github.com/perplexityai/numbat/blob/main/internal/discover/discover.go): `internal/discover/discover.go`
- [Session Extractors](https://github.com/perplexityai/numbat/tree/main/internal/extract): `internal/extract`

### Normalization and Detection

- [Event Pipeline](https://github.com/perplexityai/numbat/blob/main/internal/pipeline/pipeline.go): `internal/pipeline/pipeline.go`
- [Normalized Events](https://github.com/perplexityai/numbat/blob/main/internal/model/event.go): `internal/model/event.go`
- [CEL Rule Engine](https://github.com/perplexityai/numbat/blob/main/internal/rule/engine.go): `internal/rule/engine.go`
- [Sequence Tracker](https://github.com/perplexityai/numbat/blob/main/internal/sequence/sequence.go): `internal/sequence/sequence.go`
- [Built-in Rules](https://github.com/perplexityai/numbat/blob/main/rules/builtin.go): `rules/builtin.go`

### Records and Investigation

- [Finding Renderer](https://github.com/perplexityai/numbat/blob/main/internal/finding/finding.go): `internal/finding/finding.go`
- [Record Emitter](https://github.com/perplexityai/numbat/blob/main/internal/output/output.go): `internal/output/output.go`
- [File and HTTP Sinks](https://github.com/perplexityai/numbat/tree/main/internal/output): `internal/output`
- [Indicator Analysis](https://github.com/perplexityai/numbat/blob/main/internal/output/indicators.go): `internal/output/indicators.go`
- [Case Bundles](https://github.com/perplexityai/numbat/blob/main/internal/casebundle/build.go): `internal/casebundle/build.go`
- [Bundle Verification](https://github.com/perplexityai/numbat/blob/main/internal/casebundle/verify.go): `internal/casebundle/verify.go`
- [Session Timelines](https://github.com/perplexityai/numbat/blob/main/cmd/numbat/timeline.go): `cmd/numbat/timeline.go`

### Other components

- **Operator**
- **HTTP Collector**

## Connections

- Operator → Numbat CLI: invokes (evidence: `README.md`)
- Numbat CLI → Agent Inventory: lists agents
- Numbat CLI → Hook Management: installs hooks
- Numbat CLI → Rule Commands: manages rules
- Numbat CLI → Artifact Scan: scans artifacts
- Numbat CLI → Session Timelines: builds timelines
- Operator → Live Hooks: enables capture (evidence: `README.md`)
- Operator → OTLP Receiver: exports logs (evidence: `README.md`)
- Operator → Artifact Scan: requests scan (evidence: `README.md`)
- Artifact Scan → Artifact Discovery: finds artifacts
- Artifact Discovery → Session Extractors: classifies for parsing (evidence: `internal/discover/discover.go`)
- Live Hooks → Normalized Events: normalizes payload (evidence: `internal/hook/hook.go`)
- OTLP Receiver → Normalized Events: maps log records
- Session Extractors → Normalized Events: reconstructs events (evidence: `internal/extract/gemini_session.go`)
- Live Hooks → Event Pipeline: feeds events
- OTLP Receiver → Event Pipeline: feeds events
- Session Extractors → Event Pipeline: feeds events
- Event Pipeline → CEL Rule Engine: evaluates events (evidence: `internal/pipeline/pipeline.go`)
- Event Pipeline → Sequence Tracker: tracks sequences (evidence: `internal/pipeline/pipeline.go`)
- CEL Rule Engine → Built-in Rules: loads policy
- Event Pipeline → Finding Renderer: renders matches (evidence: `internal/pipeline/pipeline.go`)
- Event Pipeline → Record Emitter: emits records (evidence: `internal/pipeline/pipeline.go`)
- Event Pipeline → Indicator Analysis: accumulates indicators (evidence: `internal/pipeline/pipeline.go`)
- Record Emitter → File and HTTP Sinks: routes records
- File and HTTP Sinks → HTTP Collector: delivers records (evidence: `README.md`)
- Operator → Case Bundles: creates bundle (evidence: `README.md`)
- Case Bundles → Bundle Verification: supports verification
- Operator → Session Timelines: investigates session (evidence: `README.md`)
