How fajarhide/omni works
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: toml_filter.rs TOML Filters · dispatcher.rs Hook Dispatch · mod.rs Commands · classifier.rs Classifier
Components 29
CLI Control Plane
User-facing commands for setup, diagnostics, history, and maintenance.
- Omni CLI · Single Rust command-line entrypoint and command dispatcher.
src/main.rs - Commands · Init, exec, rewrite, session, stats, doctor, diff, learn, reset, update, rewind.
src/cli/mod.rs - Exec Flow · Primary path for capturing, filtering, and returning command output.
src/cli/exec.rs - History Ops · Session, diff, rewind, and transcript-oriented maintenance commands.
src/cli/session.rs
Hook Boundary
Entry points that intercept agent and terminal events.
- Hook Dispatch · Routes hook events to the right interception handler.
src/hooks/dispatcher.rs - Hook Pipe · Pipe abstraction for moving intercepted terminal data through Omni.
src/hooks/pipe.rs - Pre Tool · Intercepts tool execution before the command runs.
src/hooks/pre_tool.rs - Post Tool · Captures and processes command output after execution.
src/hooks/post_tool.rs - Session Start · Loads or primes session state at the beginning of an agent session.
src/hooks/session_start.rs - Pre Compact · Prepares summarized context before model compaction.
src/hooks/pre_compact.rs
Filtering Engine
Semantic pipeline that classifies, scores, collapses, and composes terminal output.
- Classifier · Identifies the kind of output and likely command family.
src/pipeline/classifier.rs - Scorer · Ranks which lines or sections carry useful signal.
src/pipeline/scorer.rs - Collapse · Removes repetitive success noise and compresses verbose sections.
src/pipeline/collapse.rs - Composer · Builds the final concise response returned to the agent.
src/pipeline/composer.rs - TOML Filters · Loads command-pattern rules that steer distillation behavior.
src/pipeline/toml_filter.rs
Distillers
Command-family specific output normalizers and parsers.
- Build · Build and compile output normalization for tools like cargo, make, and tsc.
src/distillers/build.rs - Cloud · Docker, kubectl, Terraform, and infrastructure command distillation.
src/distillers/cloud.rs - JS/TS · JavaScript and TypeScript tool output normalization.
src/distillers/jsts.rs - Git · Git status, diff, and log output distillation.
src/distillers/git.rs - Logs · Structured and text log extraction and summarization.
src/distillers/log.rs - System Ops · Generic shell and filesystem output handling.
src/distillers/system_ops.rs - Tabular · Table-like output normalization for list and query results.
src/distillers/tabular.rs
Persistence & Session
Durable transcript storage and session learning state.
- SQLite Store · Local durable store for transcripts, sessions, and recovered history.
src/store/sqlite.rs - Transcript · Raw command output archive used for rewind and traceability.
src/store/transcript.rs - Tracker · Tracks active session context and relevant files or commands.
src/session/tracker.rs - Learn · Learns command and context patterns from session behavior.
src/session/learn.rs - Correction · Applies user corrections to session relevance and output choices.
src/session/correction.rs
External Surfaces
Secondary runtime integrations and policy boundaries.
- Guard · Environment, trust, limits, and update safety checks.
src/guard/mod.rs - MCP Server · Exposes Omni capabilities to MCP-compatible clients.
src/mcp/server.rs
Connections 32
- 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.