# fajarhide/omni architecture

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

- Interactive diagram: https://gitdiagram.com/fajarhide/omni
- Repository: https://github.com/fajarhide/omni

## Overview

1. **What Omni is**
   - Omni is a Rust-based terminal interceptor for AI agents. It sits between the agent and command execution/output, reducing noisy terminal logs before they are fed back into the model.
   - The core architectural goal is not just “truncation,” but semantic filtering: preserve error signal, drop repetitive success/output noise.

2. **Primary execution surfaces**
   - The repository builds a single CLI binary (`src/main.rs`, `src/cli/*`) that exposes user-facing commands like `init`, `exec`, `rewrite`, `session`, `stats`, `doctor`, `diff`, `learn`, and maintenance commands such as `reset`, `update`, and `rewind`.
   - The CLI is the control plane for installation, configuration, diagnostics, and interacting with persisted session/history data.

3. **Hook-driven integration boundary**
   - Omni integrates through hook stages rather than embedding into a specific agent runtime. The `src/hooks/*` layer contains handlers for `pre_tool`, `post_tool`, `session_start`, `pre_compact`, and a dispatcher/pipe abstraction.
   - These hooks form the boundary between the AI agent/terminal environment and Omni’s internal filtering engine.

4. **Command execution and interception flow**
   - `src/cli/exec.rs` and the hook pipeline suggest the main data path is: agent triggers a tool/command → Omni captures raw terminal output → output is distilled → cleaned result is returned to the agent.
   - `rewrite` and `rewind` indicate Omni can also alter or recover command history/output, not just passively filter it.

5. **Semantic filtering pipeline**
   - The central “signal engine” lives in `src/pipeline/*`: `classifier`, `scorer`, `composer`, `collapse`, and `toml_filter`.
   - This pipeline likely classifies output type, scores relevance, collapses verbose sections, and composes a final concise response. The design is explicitly multi-stage, which is important for diagramming internal data flow.

6. **Domain-specific distillers**
   - `src/distillers/*` contains specialized parsers/normalizers for common command families: build tools, cloud/Kubernetes/Terraform, JavaScript/TypeScript, logs, git, system ops, and tabular output.
   - The `filters/*.toml` files map command patterns to these distillers/rules, so the repo mixes hardcoded distillation logic with user-extensible TOML-driven filter definitions.

7. **Persistence and rewind archive**
   - `src/store/*` provides durable storage backed by SQLite (`sqlite.rs`) plus transcript handling (`transcript.rs`).
   - The README’s “zero information loss” claim maps to this store: Omni keeps raw outputs in a local archive so filtered results can be traced back or recovered later via rewind/session workflows.

8. **Session intelligence and learning**
   - `src/session/*` tracks active context and user behavior: `tracker`, `learn`, and `correction` imply the system learns what files/commands are relevant during a session.
   - Session state is persisted and reused by hooks like `session_start` and `pre_compact`, which helps Omni avoid re-sending context the agent already knows.

9. **Safety, trust, and limits**
   - `src/guard/*` is a separate boundary for operational safety: environment handling, trust policy, limits, and update-related checks.
   - This indicates Omni is not only a filter but also a policy-enforcing tool that constrains what can run or be trusted in intercepted environments.

10. **MCP integration**
   - `src/mcp/*` provides a Model Context Protocol server, making Omni compatible with MCP-capable clients in addition to hook-based terminal workflows.
   - This is a second integration surface alongside native hooks, and it likely exposes some of the same session/history capabilities over a protocol boundary.

11. **Configuration and extensibility**
   - The repository centers configuration around TOML filters plus top-level config artifacts like `omni_config.json` and `omni.rb`.
   - The filter directory and the snapshot tests show the system is meant to be extended by adding new command-specific rules without changing the core engine.

12. **Testing and validation strategy**
   - The test suite is heavy on fixture-based golden/snapshot validation: many command-output fixtures under `tests/fixtures` and snapshot files under `src/distillers/snapshots`.
   - This is a strong signal that the architecture depends on deterministic output transformation, with regressions caught by comparing distilled output against known command transcripts.

13. **Distribution and deployment**
   - Build and release are standard Rust CLI workflows, but the repo also includes installer scripts for shell, PowerShell, Homebrew, and CI/release automation in GitHub Actions.
   - Architecturally, that means Omni is designed as a locally installed agent-side tool rather than a hosted service.

14. **How to draw the architecture**
   - A useful diagram would show four main layers: agent/hook entrypoints, the semantic pipeline/distillers, persistence/session state, and external integration surfaces (CLI + MCP).
   - The key data flow is: raw terminal output in → classification/distillation/scoring/composition → filtered response out, with raw transcripts and session state written to SQLite for rewind, stats, and learning.

Main entry points: [`src/pipeline/toml_filter.rs`](https://github.com/fajarhide/omni/blob/main/src/pipeline/toml_filter.rs) (TOML Filters), [`src/hooks/dispatcher.rs`](https://github.com/fajarhide/omni/blob/main/src/hooks/dispatcher.rs) (Hook Dispatch), [`src/cli/mod.rs`](https://github.com/fajarhide/omni/blob/main/src/cli/mod.rs) (Commands), [`src/pipeline/classifier.rs`](https://github.com/fajarhide/omni/blob/main/src/pipeline/classifier.rs) (Classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI Control Plane"]
  node_main_cli["Omni CLI<br/>binary<br/>[main.rs]"]
  node_cli_commands["Commands<br/>[mod.rs]"]
  node_cli_exec["Exec Flow<br/>command flow<br/>[exec.rs]"]
  node_cli_history["History Ops<br/>command flow<br/>[session.rs]"]
end

subgraph group_hooks["Hook Boundary"]
  node_hook_dispatch["Hook Dispatch<br/>dispatcher<br/>[dispatcher.rs]"]
  node_hook_pipe["Hook Pipe<br/>adapter<br/>[pipe.rs]"]
  node_pre_tool["Pre Tool<br/>hook handler<br/>[pre_tool.rs]"]
  node_post_tool["Post Tool<br/>hook handler<br/>[post_tool.rs]"]
  node_session_start["Session Start<br/>hook handler<br/>[session_start.rs]"]
  node_pre_compact["Pre Compact<br/>hook handler<br/>[pre_compact.rs]"]
end

subgraph group_engine["Filtering Engine"]
  node_classifier["Classifier<br/>pipeline stage<br/>[classifier.rs]"]
  node_scorer["Scorer<br/>pipeline stage<br/>[scorer.rs]"]
  node_collapse["Collapse<br/>pipeline stage<br/>[collapse.rs]"]
  node_composer["Composer<br/>pipeline stage<br/>[composer.rs]"]
  node_toml_filter["TOML Filters<br/>rule loader<br/>[toml_filter.rs]"]
end

subgraph group_distillers["Distillers"]
  node_build_distiller["Build<br/>distiller<br/>[build.rs]"]
  node_cloud_distiller["Cloud<br/>distiller<br/>[cloud.rs]"]
  node_jsts_distiller["JS/TS<br/>distiller<br/>[jsts.rs]"]
  node_git_distiller["Git<br/>distiller<br/>[git.rs]"]
  node_log_distiller["Logs<br/>distiller<br/>[log.rs]"]
  node_system_ops["System Ops<br/>distiller<br/>[system_ops.rs]"]
  node_tabular["Tabular<br/>distiller<br/>[tabular.rs]"]
end

subgraph group_state["Persistence & Session"]
  node_sqlite_store[("SQLite Store<br/>database<br/>[sqlite.rs]")]
  node_transcript["Transcript<br/>archive<br/>[transcript.rs]"]
  node_tracker["Tracker<br/>session state<br/>[tracker.rs]"]
  node_learn["Learn<br/>session model<br/>[learn.rs]"]
  node_correction["Correction<br/>session feedback<br/>[correction.rs]"]
end

subgraph group_integrations["External Surfaces"]
  node_guard{{"Guard<br/>policy boundary<br/>[mod.rs]"}}
  node_mcp_server["MCP Server<br/>protocol server<br/>[server.rs]"]
end

node_main_cli -->|"dispatches"| node_cli_commands
node_cli_commands -->|"exec"| node_cli_exec
node_cli_commands -->|"history"| node_cli_history
node_cli_exec -->|"invokes"| node_hook_dispatch
node_hook_dispatch -->|"routes"| node_hook_pipe
node_hook_dispatch -->|"pre"| node_pre_tool
node_hook_dispatch -->|"post"| node_post_tool
node_hook_dispatch -->|"session"| node_session_start
node_hook_dispatch -->|"compact"| node_pre_compact
node_pre_tool -->|"analyzes"| node_classifier
node_post_tool -->|"captures"| node_classifier
node_classifier -->|"ranks"| node_scorer
node_scorer -->|"compresses"| node_collapse
node_collapse -->|"formats"| node_composer
node_toml_filter -->|"guides"| node_classifier
node_toml_filter -->|"maps"| node_build_distiller
node_toml_filter -->|"maps"| node_cloud_distiller
node_toml_filter -->|"maps"| node_jsts_distiller
node_toml_filter -->|"maps"| node_git_distiller
node_toml_filter -->|"maps"| node_log_distiller
node_toml_filter -->|"maps"| node_system_ops
node_toml_filter -->|"maps"| node_tabular
node_cli_history -->|"reads/writes"| node_sqlite_store
node_post_tool -->|"archives"| node_transcript
node_session_start -->|"loads"| node_tracker
node_pre_compact -->|"uses"| node_tracker
node_tracker -->|"updates"| node_learn
node_learn -->|"refines"| node_correction
node_guard -->|"constrains"| node_cli_commands
node_guard -->|"protects"| node_mcp_server
node_mcp_server -->|"queries"| node_sqlite_store
node_mcp_server -->|"exposes"| node_tracker

click node_main_cli "https://github.com/fajarhide/omni/blob/main/src/main.rs"
click node_cli_commands "https://github.com/fajarhide/omni/blob/main/src/cli/mod.rs"
click node_cli_exec "https://github.com/fajarhide/omni/blob/main/src/cli/exec.rs"
click node_cli_history "https://github.com/fajarhide/omni/blob/main/src/cli/session.rs"
click node_hook_dispatch "https://github.com/fajarhide/omni/blob/main/src/hooks/dispatcher.rs"
click node_hook_pipe "https://github.com/fajarhide/omni/blob/main/src/hooks/pipe.rs"
click node_pre_tool "https://github.com/fajarhide/omni/blob/main/src/hooks/pre_tool.rs"
click node_post_tool "https://github.com/fajarhide/omni/blob/main/src/hooks/post_tool.rs"
click node_session_start "https://github.com/fajarhide/omni/blob/main/src/hooks/session_start.rs"
click node_pre_compact "https://github.com/fajarhide/omni/blob/main/src/hooks/pre_compact.rs"
click node_classifier "https://github.com/fajarhide/omni/blob/main/src/pipeline/classifier.rs"
click node_scorer "https://github.com/fajarhide/omni/blob/main/src/pipeline/scorer.rs"
click node_collapse "https://github.com/fajarhide/omni/blob/main/src/pipeline/collapse.rs"
click node_composer "https://github.com/fajarhide/omni/blob/main/src/pipeline/composer.rs"
click node_toml_filter "https://github.com/fajarhide/omni/blob/main/src/pipeline/toml_filter.rs"
click node_build_distiller "https://github.com/fajarhide/omni/blob/main/src/distillers/build.rs"
click node_cloud_distiller "https://github.com/fajarhide/omni/blob/main/src/distillers/cloud.rs"
click node_jsts_distiller "https://github.com/fajarhide/omni/blob/main/src/distillers/jsts.rs"
click node_git_distiller "https://github.com/fajarhide/omni/blob/main/src/distillers/git.rs"
click node_log_distiller "https://github.com/fajarhide/omni/blob/main/src/distillers/log.rs"
click node_system_ops "https://github.com/fajarhide/omni/blob/main/src/distillers/system_ops.rs"
click node_tabular "https://github.com/fajarhide/omni/blob/main/src/distillers/tabular.rs"
click node_sqlite_store "https://github.com/fajarhide/omni/blob/main/src/store/sqlite.rs"
click node_transcript "https://github.com/fajarhide/omni/blob/main/src/store/transcript.rs"
click node_tracker "https://github.com/fajarhide/omni/blob/main/src/session/tracker.rs"
click node_learn "https://github.com/fajarhide/omni/blob/main/src/session/learn.rs"
click node_correction "https://github.com/fajarhide/omni/blob/main/src/session/correction.rs"
click node_guard "https://github.com/fajarhide/omni/blob/main/src/guard/mod.rs"
click node_mcp_server "https://github.com/fajarhide/omni/blob/main/src/mcp/server.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_main_cli,node_cli_commands,node_cli_exec,node_cli_history toneBlue
class node_hook_dispatch,node_hook_pipe,node_pre_tool,node_post_tool,node_session_start,node_pre_compact toneAmber
class node_classifier,node_scorer,node_collapse,node_composer,node_toml_filter toneMint
class node_build_distiller,node_cloud_distiller,node_jsts_distiller,node_git_distiller,node_log_distiller,node_system_ops,node_tabular toneRose
class node_sqlite_store,node_transcript,node_tracker,node_learn,node_correction toneIndigo
class node_guard,node_mcp_server toneTeal
```

## Components

### CLI Control Plane

User-facing commands for setup, diagnostics, history, and maintenance.

- [Omni CLI](https://github.com/fajarhide/omni/blob/main/src/main.rs): binary · Single Rust command-line entrypoint and command dispatcher. · `src/main.rs`
- [Commands](https://github.com/fajarhide/omni/blob/main/src/cli/mod.rs): subcommands · Init, exec, rewrite, session, stats, doctor, diff, learn, reset, update, rewind. · `src/cli/mod.rs`
- [Exec Flow](https://github.com/fajarhide/omni/blob/main/src/cli/exec.rs): command flow · Primary path for capturing, filtering, and returning command output. · `src/cli/exec.rs`
- [History Ops](https://github.com/fajarhide/omni/blob/main/src/cli/session.rs): command flow · Session, diff, rewind, and transcript-oriented maintenance commands. · `src/cli/session.rs`

### Hook Boundary

Entry points that intercept agent and terminal events.

- [Hook Dispatch](https://github.com/fajarhide/omni/blob/main/src/hooks/dispatcher.rs): dispatcher · Routes hook events to the right interception handler. · `src/hooks/dispatcher.rs`
- [Hook Pipe](https://github.com/fajarhide/omni/blob/main/src/hooks/pipe.rs): adapter · Pipe abstraction for moving intercepted terminal data through Omni. · `src/hooks/pipe.rs`
- [Pre Tool](https://github.com/fajarhide/omni/blob/main/src/hooks/pre_tool.rs): hook handler · Intercepts tool execution before the command runs. · `src/hooks/pre_tool.rs`
- [Post Tool](https://github.com/fajarhide/omni/blob/main/src/hooks/post_tool.rs): hook handler · Captures and processes command output after execution. · `src/hooks/post_tool.rs`
- [Session Start](https://github.com/fajarhide/omni/blob/main/src/hooks/session_start.rs): hook handler · Loads or primes session state at the beginning of an agent session. · `src/hooks/session_start.rs`
- [Pre Compact](https://github.com/fajarhide/omni/blob/main/src/hooks/pre_compact.rs): hook handler · Prepares summarized context before model compaction. · `src/hooks/pre_compact.rs`

### Filtering Engine

Semantic pipeline that classifies, scores, collapses, and composes terminal output.

- [Classifier](https://github.com/fajarhide/omni/blob/main/src/pipeline/classifier.rs): pipeline stage · Identifies the kind of output and likely command family. · `src/pipeline/classifier.rs`
- [Scorer](https://github.com/fajarhide/omni/blob/main/src/pipeline/scorer.rs): pipeline stage · Ranks which lines or sections carry useful signal. · `src/pipeline/scorer.rs`
- [Collapse](https://github.com/fajarhide/omni/blob/main/src/pipeline/collapse.rs): pipeline stage · Removes repetitive success noise and compresses verbose sections. · `src/pipeline/collapse.rs`
- [Composer](https://github.com/fajarhide/omni/blob/main/src/pipeline/composer.rs): pipeline stage · Builds the final concise response returned to the agent. · `src/pipeline/composer.rs`
- [TOML Filters](https://github.com/fajarhide/omni/blob/main/src/pipeline/toml_filter.rs): rule loader · Loads command-pattern rules that steer distillation behavior. · `src/pipeline/toml_filter.rs`

### Distillers

Command-family specific output normalizers and parsers.

- [Build](https://github.com/fajarhide/omni/blob/main/src/distillers/build.rs): distiller · Build and compile output normalization for tools like cargo, make, and tsc. · `src/distillers/build.rs`
- [Cloud](https://github.com/fajarhide/omni/blob/main/src/distillers/cloud.rs): distiller · Docker, kubectl, Terraform, and infrastructure command distillation. · `src/distillers/cloud.rs`
- [JS/TS](https://github.com/fajarhide/omni/blob/main/src/distillers/jsts.rs): distiller · JavaScript and TypeScript tool output normalization. · `src/distillers/jsts.rs`
- [Git](https://github.com/fajarhide/omni/blob/main/src/distillers/git.rs): distiller · Git status, diff, and log output distillation. · `src/distillers/git.rs`
- [Logs](https://github.com/fajarhide/omni/blob/main/src/distillers/log.rs): distiller · Structured and text log extraction and summarization. · `src/distillers/log.rs`
- [System Ops](https://github.com/fajarhide/omni/blob/main/src/distillers/system_ops.rs): distiller · Generic shell and filesystem output handling. · `src/distillers/system_ops.rs`
- [Tabular](https://github.com/fajarhide/omni/blob/main/src/distillers/tabular.rs): distiller · Table-like output normalization for list and query results. · `src/distillers/tabular.rs`

### Persistence & Session

Durable transcript storage and session learning state.

- [SQLite Store](https://github.com/fajarhide/omni/blob/main/src/store/sqlite.rs): database · Local durable store for transcripts, sessions, and recovered history. · `src/store/sqlite.rs`
- [Transcript](https://github.com/fajarhide/omni/blob/main/src/store/transcript.rs): archive · Raw command output archive used for rewind and traceability. · `src/store/transcript.rs`
- [Tracker](https://github.com/fajarhide/omni/blob/main/src/session/tracker.rs): session state · Tracks active session context and relevant files or commands. · `src/session/tracker.rs`
- [Learn](https://github.com/fajarhide/omni/blob/main/src/session/learn.rs): session model · Learns command and context patterns from session behavior. · `src/session/learn.rs`
- [Correction](https://github.com/fajarhide/omni/blob/main/src/session/correction.rs): session feedback · Applies user corrections to session relevance and output choices. · `src/session/correction.rs`

### External Surfaces

Secondary runtime integrations and policy boundaries.

- [Guard](https://github.com/fajarhide/omni/blob/main/src/guard/mod.rs): policy boundary · Environment, trust, limits, and update safety checks. · `src/guard/mod.rs`
- [MCP Server](https://github.com/fajarhide/omni/blob/main/src/mcp/server.rs): protocol server · Exposes Omni capabilities to MCP-compatible clients. · `src/mcp/server.rs`

## Connections

- Omni CLI → Commands: dispatches · CLI entrypoint routes to subcommands.
- Commands → Exec Flow: exec · Command path for interception and output filtering.
- Commands → History Ops: history · Session, diff, rewind, and related workflows.
- Exec Flow → Hook Dispatch: invokes · Exec flow uses hook boundaries for interception.
- Hook Dispatch → Hook Pipe: routes · Dispatcher sends event data through the hook pipe.
- Hook Dispatch → Pre Tool: pre · Before-command interception.
- Hook Dispatch → Post Tool: post · After-command interception.
- Hook Dispatch → Session Start: session · Session initialization hook.
- Hook Dispatch → Pre Compact: compact · Hook before context compaction.
- Pre Tool → Classifier: analyzes · Captures raw command intent and output shape.
- Post Tool → Classifier: captures · Feeds raw terminal output into the semantic pipeline.
- Classifier → Scorer: ranks · Pipeline assigns relevance to detected sections.
- Scorer → Collapse: compresses · Low-signal repetition is collapsed away.
- Collapse → Composer: formats · Compressed signal is turned into the final reply.
- TOML Filters → Classifier: guides · Pattern rules select appropriate distillation behavior.
- TOML Filters → Build: maps · Command families are matched to specialized distillers.
- TOML Filters → Cloud: maps · Command families are matched to specialized distillers.
- TOML Filters → JS/TS: maps · Command families are matched to specialized distillers.
- TOML Filters → Git: maps · Command families are matched to specialized distillers.
- TOML Filters → Logs: maps · Command families are matched to specialized distillers.
- TOML Filters → System Ops: maps · Command families are matched to specialized distillers.
- TOML Filters → Tabular: maps · Command families are matched to specialized distillers.
- History Ops → SQLite Store: reads/writes · History commands query durable local state.
- Post Tool → Transcript: archives · Raw command outputs are preserved for rewind and traceability.
- Session Start → Tracker: loads · Session startup restores active context.
- Pre Compact → Tracker: uses · Compaction consults current session relevance.
- Tracker → Learn: updates · Observed behavior feeds session learning.
- Learn → Correction: refines · Corrections adjust the learned model of relevance.
- Guard → Commands: constrains · Policy checks limit or validate operational commands.
- Guard → MCP Server: protects · Safety and trust boundaries apply to protocol exposure.
- MCP Server → SQLite Store: queries · MCP surface can serve stored session and transcript data.
- MCP Server → Tracker: exposes · Protocol clients can access session-aware capabilities.
