# falcosecurity/prempti architecture

> Architecture diagram of the GitHub repository falcosecurity/prempti, 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/falcosecurity/prempti
- Repository: https://github.com/falcosecurity/prempti

## Overview

Prempti is a cross-platform Falco-based policy and visibility layer for coding-agent tool calls. The main workflow intercepts an agent action, sends it through the Falco plugin for event evaluation against YAML rules, and returns an allow, deny, or ask verdict; monitor mode logs evaluations without enforcing them. The CLI and supervisor manage operation, hooks, and logs. Plugin wiring and several CLI behaviors are represented from the README and SOURCE INDEX; unsampled details are not inferred beyond documented links.

Main entry points: [`plugins/coding-agents-plugin/src/lib.rs`](https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/lib.rs) (Falco Plugin), [`plugins/coding-agents-plugin/src/broker.rs`](https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/broker.rs) (Verdict Broker), [`tools/premptictl/src/main.rs`](https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/main.rs) (premptictl), [`plugins/coding-agents-plugin/src/socket_server.rs`](https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/socket_server.rs) (Socket Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interception["Agent Interception"]
  node_claude_hook["Claude Hook<br/>[main.rs]"]
  node_codex_hook["Codex Hook<br/>[main.rs]"]
end

subgraph group_evaluation["Falco Evaluation"]
  node_plugin["Falco Plugin<br/>[lib.rs]"]
  node_socket["Socket Server<br/>[socket_server.rs]"]
  node_http["HTTP Server<br/>[http_server.rs]"]
  node_event["Event Normalization<br/>[event.rs]"]
  node_extract["Rule Fields<br/>[extract.rs]"]
  node_patch["Patch Parsing<br/>[apply_patch.rs]"]
  node_broker["Verdict Broker<br/>[broker.rs]"]
  node_verdict["Verdict Protocol<br/>[verdict.rs]"]
end

subgraph group_operations["Runtime Operations"]
  node_cli["premptictl<br/>[main.rs]"]
  node_supervisor["Falco Supervisor<br/>[mod.rs]"]
  node_daemon_config["Daemon Config<br/>[config.rs]"]
  node_control["Control Channel<br/>[control.rs]"]
  node_pipe_drain["Log Pipe Drain<br/>[pipe_drain.rs]"]
  node_rotation["Log Rotation<br/>[rotate.rs]"]
  node_claude_registration["Claude Hook Setup<br/>[hook.rs]"]
  node_codex_registration["Codex Hook Setup<br/>[hook_codex.rs]"]
  node_log_view["Log Renderer<br/>[logs_pretty.rs]"]
end

subgraph group_policy["Policy and Audit"]
  node_rules["Falco Rules"]
  node_custom_rules["User Rules"]
  node_audit["Audit Logs"]
end

node_agent(("Coding Agent"))
node_falco["Falco Engine"]

node_agent -->|"invokes tools"| node_claude_hook
node_agent -->|"invokes tools"| node_codex_hook
node_claude_hook -->|"submits calls"| node_plugin
node_codex_hook -->|"submits calls"| node_plugin
node_plugin -->|"starts server"| node_socket
node_plugin -->|"starts server"| node_http
node_socket -->|"registers requests"| node_broker
node_socket -->|"sends events"| node_event
node_socket -->|"parses patches"| node_patch
node_http -->|"uses broker"| node_broker
node_plugin -->|"queues events"| node_event
node_plugin -->|"exposes fields"| node_extract
node_event -->|"provides events"| node_falco
node_extract -->|"provides fields"| node_falco
node_rules -->|"configures rules"| node_falco
node_custom_rules -->|"customizes policy"| node_falco
node_falco -->|"reports verdict alerts"| node_broker
node_broker -->|"resolves response"| node_verdict
node_broker -->|"returns decision"| node_claude_hook
node_broker -->|"returns decision"| node_codex_hook
node_falco -->|"records activity"| node_audit
node_cli -->|"controls daemon"| node_supervisor
node_supervisor -->|"loads settings"| node_daemon_config
node_supervisor -->|"handles control"| node_control
node_supervisor -->|"drains output"| node_pipe_drain
node_pipe_drain -->|"rotates logs"| node_rotation
node_cli -->|"manages hooks"| node_claude_registration
node_cli -->|"manages hooks"| node_codex_registration
node_cli -->|"renders logs"| node_log_view
node_audit -->|"streams logs"| node_log_view

click node_claude_hook "https://github.com/falcosecurity/prempti/blob/main/hooks/claude-code/src/main.rs"
click node_codex_hook "https://github.com/falcosecurity/prempti/blob/main/hooks/codex/src/main.rs"
click node_plugin "https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/lib.rs"
click node_socket "https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/socket_server.rs"
click node_http "https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/http_server.rs"
click node_event "https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/event.rs"
click node_extract "https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/extract.rs"
click node_patch "https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/apply_patch.rs"
click node_broker "https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/broker.rs"
click node_verdict "https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/verdict.rs"
click node_rules "https://github.com/falcosecurity/prempti/blob/main/rules/default/coding_agents_rules.yaml"
click node_custom_rules "https://github.com/falcosecurity/prempti/tree/main/rules/user"
click node_cli "https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/main.rs"
click node_supervisor "https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/daemon/mod.rs"
click node_daemon_config "https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/daemon/config.rs"
click node_control "https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/daemon/control.rs"
click node_pipe_drain "https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/daemon/pipe_drain.rs"
click node_rotation "https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/daemon/rotate.rs"
click node_claude_registration "https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/hook.rs"
click node_codex_registration "https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/hook_codex.rs"
click node_log_view "https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/logs_pretty.rs"

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_claude_hook,node_codex_hook toneBlue
class node_plugin,node_socket,node_http,node_event,node_extract,node_patch,node_broker,node_verdict toneAmber
class node_cli,node_supervisor,node_daemon_config,node_control,node_pipe_drain,node_rotation,node_claude_registration,node_codex_registration,node_log_view toneMint
class node_rules,node_custom_rules,node_audit toneRose
class node_agent,node_falco toneIndigo
```

## Components

### Agent Interception

- [Claude Hook](https://github.com/falcosecurity/prempti/blob/main/hooks/claude-code/src/main.rs): `hooks/claude-code/src/main.rs`
- [Codex Hook](https://github.com/falcosecurity/prempti/blob/main/hooks/codex/src/main.rs): `hooks/codex/src/main.rs`

### Falco Evaluation

- [Falco Plugin](https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/lib.rs): `plugins/coding-agents-plugin/src/lib.rs`
- [Socket Server](https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/socket_server.rs): `plugins/coding-agents-plugin/src/socket_server.rs`
- [HTTP Server](https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/http_server.rs): `plugins/coding-agents-plugin/src/http_server.rs`
- [Event Normalization](https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/event.rs): `plugins/coding-agents-plugin/src/event.rs`
- [Rule Fields](https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/extract.rs): `plugins/coding-agents-plugin/src/extract.rs`
- [Patch Parsing](https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/apply_patch.rs): `plugins/coding-agents-plugin/src/apply_patch.rs`
- [Verdict Broker](https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/broker.rs): `plugins/coding-agents-plugin/src/broker.rs`
- [Verdict Protocol](https://github.com/falcosecurity/prempti/blob/main/plugins/coding-agents-plugin/src/verdict.rs): `plugins/coding-agents-plugin/src/verdict.rs`

### Runtime Operations

- [premptictl](https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/main.rs): `tools/premptictl/src/main.rs`
- [Falco Supervisor](https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/daemon/mod.rs): `tools/premptictl/src/daemon/mod.rs`
- [Daemon Config](https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/daemon/config.rs): `tools/premptictl/src/daemon/config.rs`
- [Control Channel](https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/daemon/control.rs): `tools/premptictl/src/daemon/control.rs`
- [Log Pipe Drain](https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/daemon/pipe_drain.rs): `tools/premptictl/src/daemon/pipe_drain.rs`
- [Log Rotation](https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/daemon/rotate.rs): `tools/premptictl/src/daemon/rotate.rs`
- [Claude Hook Setup](https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/hook.rs): `tools/premptictl/src/hook.rs`
- [Codex Hook Setup](https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/hook_codex.rs): `tools/premptictl/src/hook_codex.rs`
- [Log Renderer](https://github.com/falcosecurity/prempti/blob/main/tools/premptictl/src/logs_pretty.rs): `tools/premptictl/src/logs_pretty.rs`

### Policy and Audit

- [Falco Rules](https://github.com/falcosecurity/prempti/blob/main/rules/default/coding_agents_rules.yaml): `rules/default/coding_agents_rules.yaml`
- [User Rules](https://github.com/falcosecurity/prempti/tree/main/rules/user): `rules/user`
- **Audit Logs**

### Other components

- **Coding Agent**
- **Falco Engine**

## Connections

- Coding Agent → Claude Hook: invokes tools (evidence: `README.md`)
- Coding Agent → Codex Hook: invokes tools (evidence: `README.md`)
- Claude Hook → Falco Plugin: submits calls (evidence: `README.md`)
- Codex Hook → Falco Plugin: submits calls (evidence: `README.md`)
- Falco Plugin → Socket Server: starts server (evidence: `plugins/coding-agents-plugin/src/lib.rs`)
- Falco Plugin → HTTP Server: starts server (evidence: `plugins/coding-agents-plugin/src/lib.rs`)
- Socket Server → Verdict Broker: registers requests (evidence: `plugins/coding-agents-plugin/src/socket_server.rs`)
- Socket Server → Event Normalization: sends events (evidence: `plugins/coding-agents-plugin/src/lib.rs`)
- Socket Server → Patch Parsing: parses patches (evidence: `plugins/coding-agents-plugin/src/socket_server.rs`)
- HTTP Server → Verdict Broker: uses broker (evidence: `plugins/coding-agents-plugin/src/http_server.rs`)
- Falco Plugin → Event Normalization: queues events (evidence: `plugins/coding-agents-plugin/src/lib.rs`)
- Falco Plugin → Rule Fields: exposes fields (evidence: `plugins/coding-agents-plugin/src/lib.rs`)
- Event Normalization → Falco Engine: provides events
- Rule Fields → Falco Engine: provides fields
- Falco Rules → Falco Engine: configures rules (evidence: `README.md`)
- User Rules → Falco Engine: customizes policy (evidence: `README.md`)
- Falco Engine → Verdict Broker: reports verdict alerts
- Verdict Broker → Verdict Protocol: resolves response (evidence: `plugins/coding-agents-plugin/src/broker.rs`)
- Verdict Broker → Claude Hook: returns decision (evidence: `README.md`)
- Verdict Broker → Codex Hook: returns decision (evidence: `README.md`)
- Falco Engine → Audit Logs: records activity (evidence: `README.md`)
- premptictl → Falco Supervisor: controls daemon (evidence: `tools/premptictl/src/main.rs`)
- Falco Supervisor → Daemon Config: loads settings (evidence: `tools/premptictl/src/daemon/mod.rs`)
- Falco Supervisor → Control Channel: handles control (evidence: `tools/premptictl/src/daemon/mod.rs`)
- Falco Supervisor → Log Pipe Drain: drains output (evidence: `tools/premptictl/src/daemon/mod.rs`)
- Log Pipe Drain → Log Rotation: rotates logs (evidence: `tools/premptictl/src/daemon/pipe_drain.rs`)
- premptictl → Claude Hook Setup: manages hooks (evidence: `tools/premptictl/src/main.rs`)
- premptictl → Codex Hook Setup: manages hooks (evidence: `tools/premptictl/src/main.rs`)
- premptictl → Log Renderer: renders logs (evidence: `tools/premptictl/src/main.rs`)
- Audit Logs → Log Renderer: streams logs (evidence: `README.md`)
