### First-Time OMNI Setup Checklist

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Follow this checklist for initial OMNI installation and configuration to ensure all components are set up correctly.

```bash
# Install OMNI (`brew install fajarhide/tap/omni` or script)
# Run `omni init` for your chosen agent
# Run `omni doctor` — all checks should be green
# If any checks fail, run `omni doctor --fix`
# Use Claude Code normally for one session
# Run `omni stats` to confirm savings are being tracked
```

--------------------------------

### Initialize Omni with Antigravity

Source: https://context7.com/fajarhide/omni/llms.txt

Use this command to initialize Omni with Antigravity support. No specific setup is required beyond having Omni installed.

```bash
omni init --antigravity
```

--------------------------------

### Install Omni via Homebrew or Script

Source: https://context7.com/fajarhide/omni/llms.txt

Recommended installation for macOS and Linux using Homebrew. Alternatively, use the universal installer script.

```bash
# macOS / Linux via Homebrew (recommended)
brew install fajarhide/tap/omni
```

```bash
# Universal installer script (macOS / Linux / WSL)
curl -fsSL omni.weekndlabs.com/install | bash
```

```powershell
# Windows PowerShell
irm omni.weekndlabs.com/install.ps1 | iex
```

--------------------------------

### Install Omni via Homebrew

Source: https://github.com/fajarhide/omni/blob/main/README.md

Installs Omni using the Homebrew package manager on macOS or Linux. Follow this with `omni init` for setup.

```bash
# 1. Install via Homebrew
brew install fajarhide/tap/omni
```

--------------------------------

### Manual OMNI Upgrade and Installation

Source: https://github.com/fajarhide/omni/blob/main/docs/MIGRATION.md

Steps for manually downloading, installing, and initializing OMNI. This includes moving the binary and reinitializing hooks.

```bash
# Download for your platform
curl -LO https://github.com/fajarhide/omni/releases/download/v0.5.0/omni-v0.5.0-aarch64-apple-darwin.tar.gz
tar xzf omni-v0.5.0-aarch64-apple-darwin.tar.gz
mv omni ~/.local/bin/
omni init           # Reinitialize hooks via interactive menu
omni doctor
```

--------------------------------

### Install cargo-insta

Source: https://github.com/fajarhide/omni/blob/main/CONTRIBUTING.md

Installs cargo-insta, a tool used for snapshot testing. This is a prerequisite for running snapshot tests.

```bash
cargo install cargo-insta
```

--------------------------------

### Automatic OMNI Plugin Installation

Source: https://github.com/fajarhide/omni/blob/main/integrations/openclaw/README.md

Run this command for automatic installation, which securely fetches integration files directly from GitHub without requiring a local clone.

```bash
omni doctor --fix
```

--------------------------------

### Install OMNI Signal Engine Plugin via ClawHub

Source: https://github.com/fajarhide/omni/blob/main/integrations/openclaw/README.md

Use this command to install the OMNI Signal Engine plugin using ClawHub for a recommended setup.

```bash
openclaw plugins install clawhub:@fajarhide/omni-signal-engine
```

--------------------------------

### Install OMNI via Homebrew

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Use this command to install the OMNI binary on macOS or Linux systems that use Homebrew.

```bash
brew install fajarhide/tap/omni
```

--------------------------------

### Windows Omni Installer

Source: https://github.com/fajarhide/omni/blob/main/README.md

Installs Omni on Windows using PowerShell. This script fetches and executes the installer.

```powershell
irm omni.weekndlabs.com/install.ps1 | iex
```

--------------------------------

### Build and Run Project

Source: https://github.com/fajarhide/omni/blob/main/README.md

Commands to build the Omni project from source. Ensure you have Rust and Cargo installed.

```bash
make ci

```

```bash
cargo build
```

--------------------------------

### Initialize Omni Setup

Source: https://github.com/fajarhide/omni/blob/main/README.md

Sets up Omni interactively for various AI environments like Claude, VS Code, and others. Use `omni doctor` to verify.

```bash
# 2. Setup Omni (Interactive Menu for Claude, VS Code, OpenCode, Codex, Antigravity)
omni init
```

--------------------------------

### Start MCP Server Manually

Source: https://context7.com/fajarhide/omni/llms.txt

To manually start the Omni MCP (Machine Communication Protocol) server, use the `omni --mcp` command. This is typically launched automatically by the agent framework during `omni init` but can be started independently if needed.

```bash
# Start MCP server manually (normally launched by the agent framework)
omni --mcp
```

--------------------------------

### Add Project-Local Filter Configuration

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Example TOML file for a project-local filter. This filter is named 'setup-backend' and is configured to strip specific lines.

```toml
schema_version = 1
[filters.setup-backend]
match_command = "^./scripts/setup-db"
strip_lines_matching = ["^Connecting", "^Checking versions"]
on_empty = "db: setup complete"

```

--------------------------------

### Universal Omni Installer

Source: https://github.com/fajarhide/omni/blob/main/README.md

Installs Omni using a curl script, compatible with macOS, Linux, and WSL. This is an alternative to Homebrew.

```bash
curl -fsSL omni.weekndlabs.com/install | bash
```

--------------------------------

### Omni Pipe Mode Examples

Source: https://context7.com/fajarhide/omni/llms.txt

Demonstrates Omni's pipe mode for direct integration into shell pipelines. Examples include basic distillation, dry-run mode, suppressing stderr output with `OMNI_QUIET`, and specifying a custom database path.

```bash
cargo test 2>&1 | omni
```

```bash
git diff HEAD~3 | omni --dry-run
```

```bash
OMNI_QUIET=1 npm install 2>&1 | omni
```

```bash
OMNI_DB_PATH=/tmp/ci-omni.db cargo build 2>&1 | omni
```

--------------------------------

### Docker Build Steps

Source: https://github.com/fajarhide/omni/blob/main/tests/fixtures/docker_build.txt

Illustrates the sequence of commands executed during a Docker image build. This includes pulling a base image, installing a package, copying application code, and setting the working directory.

```dockerfile
FROM alpine:latest
RUN apk add --no-cache zig
COPY . /app
WORKDIR /app
```

--------------------------------

### Upgrade OMNI using Homebrew or Manual Install

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Use 'brew upgrade omni' for Homebrew users, followed by 'omni init' to reinstall hooks. For manual installation, run the provided script and then 'omni init'.

```bash
# Homebrew
brew upgrade omni
omni init    # Reinstall hooks after upgrade

# Manual
curl -fsSL https://raw.githubusercontent.com/fajarhide/omni/main/scripts/install.sh | sh
omni init
```

--------------------------------

### Verify OMNI Installation

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Check if OMNI is installed correctly and all hooks are properly configured.

```bash
omni doctor
```

--------------------------------

### Upgrade OMNI via Install Script

Source: https://github.com/fajarhide/omni/blob/main/docs/MIGRATION.md

Upgrade OMNI using the provided installation script. Follow up with `omni init` and `omni doctor`.

```bash
curl -fsSL https://raw.githubusercontent.com/fajarhide/omni/main/scripts/install.sh | sh
omni init
omni doctor
```

--------------------------------

### Omni Learn Command Examples

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Commands for learning and applying filter patterns from log output. Use these for verifying, discovering, previewing, and applying filters.

```bash
# Verify all loaded filters pass inline tests
omni learn --verify

# Discovery: search for patterns in a log file
omni learn --discover < output.log

# Preview: show generated TOML
omni learn --dry-run < output.log

# Action: apply patterns to learned.toml
omni learn --apply < output.log

```

--------------------------------

### Initialize OMNI Hooks

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Sets up OMNI hooks in various code editors and AI agents. Use the interactive menu for general setup or specify an agent to bypass the menu.

```bash
omni init              # Interactive Menu for any AI Agent
```

```bash
omni init --claude     # Full Setup for Claude Code (Hooks + MCP)
```

```bash
omni init --cursor     # Setup for Cursor AI
```

```bash
omni init --zed        # Setup for Zed Editor
```

```bash
omni init --cline      # Setup for Cline
```

```bash
omni init --roo        # Setup for Roo Code
```

```bash
omni init --copilot    # Setup for GitHub Copilot CLI
```

```bash
omni init --gemini     # Setup for Gemini CLI
```

```bash
omni init --opencode   # Setup for OpenCode plugin
```

```bash
omni init --codex      # Setup for Codex CLI
```

```bash
omni init --openclaw   # Setup for OpenClaw plugin
```

```bash
omni init --antigravity# Setup for Antigravity IDE
```

```bash
omni init --mcp        # Setup Claude MCP Server only
```

```bash
omni init --hook       # Setup Claude hooks only
```

```bash
omni init --status     # Check Claude installation status
```

```bash
omni init --uninstall  # Remove all OMNI components from Claude
```

--------------------------------

### Install Rust

Source: https://github.com/fajarhide/omni/blob/main/CONTRIBUTING.md

Installs the Rust programming language and its package manager, Cargo. Ensure you are using the stable 2024 edition.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Verify Omni Installation

Source: https://github.com/fajarhide/omni/blob/main/README.md

Checks the current installation of Omni for any issues. Use the `--fix` flag to attempt automatic resolution.

```bash
# 3. Verify it's working
omni doctor
```

```bash
# 4. Or auto-fix any issues
omni doctor --fix
```

--------------------------------

### Configure OMNI Session TTL and Fresh Start

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Environment variables to control the session Time-To-Live (TTL) and force a new session.

```bash
export OMNI_SESSION_TTL=480   # Extend to 8 hours (in minutes)
```

```bash
export OMNI_FRESH=1           # Force a brand-new session right now
```

```bash
export OMNI_CONTINUE=1        # Always continue the last session, regardless of TTL
```

--------------------------------

### OMNI Stats Example Output

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

An example of the detailed statistics provided by 'omni stats', showing command processing, byte reduction, signal ratio, estimated cost savings, breakdown by filter, and route distribution.

```text
─────────────────────────────────────────────────
 OMNI Stats — last 30 days
─────────────────────────────────────────────────
 Commands processed:   1,247
 Input bytes:          48.3 MB
 Output bytes:         5.1 MB
 Signal ratio:         89.4% reduction
 Est. cost savings:    $0.43 / session

 By Filter:
   cargo      ████████████  847 calls  91% reduction
   npm        ████████      203 calls  84% reduction
   pytest     ██████        112 calls  79% reduction
   docker     █████          67 calls  73% reduction

 Route Distribution:
   Keep:        743 (59%)   ← clean distillation
   Soft:        312 (25%)   ← partial distillation
   Passthrough:  147 (12%)  ← unknown tool (sent to learning queue)
   Rewind:        45 (4%)   ← archived (too large)
─────────────────────────────────────────────────
```

--------------------------------

### Local Developer Install for OMNI Plugin

Source: https://github.com/fajarhide/omni/blob/main/integrations/openclaw/README.md

Install the OMNI Signal Engine plugin locally if you have cloned the repository. This is useful for development purposes.

```bash
openclaw plugins install ./integrations/openclaw
```

--------------------------------

### Multi-Agent Awareness Example

Source: https://context7.com/fajarhide/omni/llms.txt

Example output from the `omni_agents` MCP tool, showing how different agents (like Claude Code and Cursor) can discover each other's presence, tasks, and errors to prevent conflicts. This is automatically called by agents.

```json
{
  "agents": [
    { "id": "claude", "task": "fixing auth module", "domain": "src/auth/", "errors": ["E0432"] },
    { "id": "cursor", "task": "adding tests",        "domain": "tests/",    "errors": [] }
  ]
}
```

--------------------------------

### OpenClaw Integration with Omni

Source: https://context7.com/fajarhide/omni/llms.txt

Instructions for installing Omni as an OpenClaw plugin and configuring its path. Once installed, agents can use `omni_cmd` to run Omni commands.

```bash
# Install via ClawHub
openclaw plugins install clawhub:@fajarhide/omni-signal-engine

# Or auto-install via Omni's doctor
omni doctor --fix
```

```yaml
plugins:
  omni-signal-engine:
    omniPath: "/usr/local/bin/omni"   # default: auto-detected from PATH
```

--------------------------------

### Omni Hook Examples

Source: https://context7.com/fajarhide/omni/llms.txt

These examples demonstrate how to use the `omni --hook` command to process JSON events from stdin for different hook types like PostToolUse, SessionStart, and PreCompact. The output is always distilled to stdout and the command exits with 0.

```bash
echo '{ "hook_event_name": "PostToolUse", "tool_name": "Bash", "tool_input": {"command": "cargo test"}, "tool_response": {"output": "   Compiling serde v1.0...\nerror[E0308]: mismatched types\n..."} }' | omni --hook
```

```bash
echo '{"hook_event_name": "SessionStart", "session_id": "abc123"}' | omni --hook
```

```bash
echo '{"hook_event_name": "PreCompact", "session_id": "abc123"}' | omni --hook
```

--------------------------------

### Compare Cargo Test Output With and Without OMNI

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Demonstrates how OMNI significantly reduces noise in 'cargo test' output, making it easier to identify test failures. The 'Before' example shows verbose compilation and test output, while the 'After' example presents a concise summary.

```text
   Compiling proc-macro2 v1.0.78
   Compiling quote v1.0.35
   Compiling unicode-ident v1.0.12
   Compiling syn v2.0.48
   ... (200 more Compiling lines)
   Compiling myapp v0.1.0
    Finished test profile in 12.34s
     Running tests/integration_test.rs
running 5 tests
test auth::test_login ... ok
test auth::test_logout ... ok
test auth::test_invalid_token ... FAILED

failures:

---- auth::test_invalid_token stdout ----
thread 'auth::test_invalid_token' panicked at 'assertion failed: `(left == right)`
  left: `401`,
 right: `403`',
 tests/auth_test.rs:45

test result: FAILED. 2 passed; 1 failed
```

```text
Tests: 2 passed, 1 failed

---- auth::test_invalid_token stdout ----
thread 'auth::test_invalid_token' panicked at 'assertion failed: `(left == right)`
  left: `401`,
 right: `403`',
 tests/auth_test.rs:45

test result: FAILED. 2 passed; 1 failed
```

--------------------------------

### Remove Old OMNI Installation (npm)

Source: https://github.com/fajarhide/omni/blob/main/docs/MIGRATION.md

Instructions for removing a previous OMNI installation managed by npm and removing the old Zig binary.

```bash
npm uninstall -g omni    # Remove old npm package
rm -f ~/.omni/omni.wasm  # Remove old Zig binary
```

--------------------------------

### Configure Omni with MCP or Hooks Only

Source: https://context7.com/fajarhide/omni/llms.txt

Allows selective setup of Omni, either only the MCP server or only the hooks.

```bash
# Set up only the MCP server (no hooks)
omni init --mcp
```

```bash
# Set up only hooks (no MCP)
omni init --hook
```

--------------------------------

### Get OMNI Help Information

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Displays usage information for the OMNI CLI. Shorthand options `-h` and `--help` are also available.

```bash
omni help       # Show usage information
```

```bash
omni --help     # Same as above
```

```bash
omni -h         # Same as above
```

--------------------------------

### Verify Omni Installation Health

Source: https://context7.com/fajarhide/omni/llms.txt

Runs a diagnostic check on the Omni installation. Use `--fix` to attempt automatic repairs.

```bash
# Verify installation health
omni doctor
```

```bash
# Auto-fix any detected issues
omni doctor --fix
```

--------------------------------

### Check Antigravity Integration Status

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

This is an example of the expected output from `omni doctor` when the Antigravity IDE integration is correctly configured.

```bash
  Antigravity IDE:
   Config:         ~/.gemini/antigravity/mcp_config.json [OK]
```

--------------------------------

### Get OMNI Version

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Prints the current version of the OMNI CLI.

```bash
omni version    # Prints current version
```

--------------------------------

### Force Fresh Session

Source: https://github.com/fajarhide/omni/blob/main/docs/SESSION.md

Start a new, clean session by setting the OMNI_FRESH environment variable to 1. This ignores any previously saved session state.

```bash
export OMNI_FRESH=1  # Start with a clean session
```

--------------------------------

### Diagnose Omni Installation Issues

Source: https://context7.com/fajarhide/omni/llms.txt

Performs comprehensive diagnostics on Omni's components, including binary version, config, database, hooks, and RewindStore.

```bash
# Run full diagnostics
omni doctor
```

--------------------------------

### OMNI Hook Mode Example

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Demonstrates how to pipe JSON data to `omni --hook` for automatic event handling, typically used by Claude Code.

```bash
# Called automatically by Claude Code
echo '{"hook_event_name": "PostToolUse", ...}' | omni --hook
```

--------------------------------

### Configure Omni Pricing

Source: https://context7.com/fajarhide/omni/llms.txt

Custom pricing for AI models can be set in the ~/.omni/config.toml file. This example shows pricing for Claude 3.5 Sonnet.

```toml
[pricing]
# Claude 3.5 Sonnet pricing
input_price_per_1m = 3.0
output_price_per_1m = 15.0
```

--------------------------------

### Custom TOML Filter for Deploy Tool

Source: https://context7.com/fajarhide/omni/llms.txt

Define a custom TOML filter to process the output of a specific command, such as a deploy tool. This example shows how to match commands, strip ANSI codes, define output patterns with substitutions, and set inline tests.

```toml
schema_version = 1

[filters.deploy]
description = "Internal deploy pipeline — keep only final status"
match_command = "^deploy\b"
strip_ansi = true
confidence = 0.90

# Output pattern matching — first match wins, supports $1 capture groups
[[filters.deploy.match_output]]
pattern = "Successfully deployed to (\w+)"
message = "deploy: ✓ $1"

[[filters.deploy.match_output]]
pattern = "ROLLBACK"
message = "deploy: ✗ ROLLBACK triggered"
unless = "dry-run"           # Skip this match if "dry-run" also appears in output

# Line-level stripping (mutually exclusive with keep_lines_matching)
strip_lines_matching = [
    "^\\\[DEBUG\\\",
    "^Uploading artifact",
    "^Waiting for health check",
    "^\\s*\\d+%",
]

max_lines = 20
on_empty = "deploy: completed (no notable output)"

# Inline tests — run via `omni learn --verify`
[[tests.deploy]]
name = "success case"
input = """
[DEBUG] Connecting to prod-cluster
Uploading artifact...
  45%
  90%
  100%
Successfully deployed to production
Health check passed
"""
expected = "deploy: ✓ production"

[[tests.deploy]]
name = "rollback case"
input = """
[DEBUG] Deploying v2.0
Health check FAILED
ROLLBACK initiated
"""
expected = "deploy: ✗ ROLLBACK triggered"

```

--------------------------------

### Configure Log Aggregator Filter

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Define filters for log aggregation to process and distill log output. This example configures a filter to only keep error and warning messages.

```toml
schema_version = 1

[filters.logquery]
description = "Log aggregator query results"
match_command = "^logq\b"
strip_ansi = true

strip_lines_matching = [
    "^Querying",
    "^Scanning \d+ shards",
    "^Results from",
]
keep_lines_matching = ["ERROR", "WARN", "FATAL", "panic", "OOM"]
max_lines = 40
on_empty = "logq: no errors found"

[[tests.logquery]]
name = "filters to errors only"
input = """
Querying prod logs (last 1h)...
Scanning 42 shards...
Results from us-east-1:
2024-01-15 10:30:01 INFO  Request processed
2024-01-15 10:30:02 INFO  Request processed
2024-01-15 10:30:03 ERROR Connection timeout to redis-primary
2024-01-15 10:30:04 INFO  Request processed
"""
expected = "2024-01-15 10:30:03 ERROR Connection timeout to redis-primary"

```

--------------------------------

### Build Omni from Source

Source: https://context7.com/fajarhide/omni/llms.txt

Instructions for cloning the repository, building the release binary, and placing it in your PATH.

```bash
git clone https://github.com/fajarhide/omni.git
cd omni
cargo build --release
cp target/release/omni ~/.local/bin/
```

--------------------------------

### Session Management Best Practices

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Recommendations for managing OMNI sessions to maximize context boost and avoid data loss.

```bash
# Let OMNI accumulate a few commands before expecting context boost to kick in
# Use `OMNI_CONTINUE=1` when resuming work on the same feature across days
# Check `omni session --status` when debugging — it shows exactly what context OMNI has
```

--------------------------------

### General OMNI Best Practices

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

General recommendations for maintaining OMNI, monitoring performance, and integrating with other tools.

```bash
# Run `omni doctor` after any system update or Claude Code upgrade
# Check `omni stats --passthrough` to see which tools aren't being filtered yet (those are learning opportunities)
# Pair with [Heimsense](https://github.com/fajarhide/heimsense) if using non-Anthropic models
```

--------------------------------

### Diagnose OMNI Installation

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Checks the health of your OMNI installation and can automatically fix detected issues when the `--fix` flag is used.

```bash
omni doctor             # Run diagnostics only
```

```bash
omni doctor --fix       # Diagnose AND auto-fix all issues
```

--------------------------------

### Select Project Data

Source: https://github.com/fajarhide/omni/blob/main/tests/fixtures/sql_query.txt

Retrieves active projects with their ID, name, and version. Ensure the 'projects' table exists and has a 'status' column.

```sql
SELECT id, name, version FROM projects WHERE status = 'active';
```

```text
+----+-----------+---------+
| id | name      | version |
+----+-----------+---------+
| 1  | OMNI      | 0.4.3   |
| 2  | ForgePod  | 1.2.0   |
+----+-----------+---------+
(2 rows returned)
```

--------------------------------

### Insert Initial Project Data

Source: https://github.com/fajarhide/omni/blob/main/tests/fixtures/sql_create.txt

Populates the projects table with initial entries. Use this after table creation to seed the database with essential project information.

```sql
INSERT INTO projects (name, version) VALUES ('OMNI', '0.4.4');
```

```sql
INSERT INTO projects (name, version) VALUES ('ForgePod', '1.2.0');
```

--------------------------------

### Create Projects Table

Source: https://github.com/fajarhide/omni/blob/main/tests/fixtures/sql_create.txt

Defines the schema for the main projects table, including primary key, name, version, status, and creation timestamp. Use this to set up project tracking.

```sql
CREATE TABLE projects (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    version VARCHAR(50),
    status VARCHAR(20) DEFAULT 'active',
    created_at TIMESTAMP DEFAULT NOW()
);
```

--------------------------------

### Initialize Omni for AI Agents

Source: https://context7.com/fajarhide/omni/llms.txt

Sets up Omni for specific AI agents or presents an interactive menu for selection. Use `omni doctor` to verify.

```bash
# Interactive agent-setup menu (choose Claude, Cursor, Zed, Copilot, etc.)
omni init
```

```bash
# Or set up a specific agent directly
omni init --claude       # Claude Code (hooks + MCP)
omni init --cursor       # Cursor AI
omni init --zed          # Zed Editor
omni init --cline        # Cline
omni init --roo          # Roo Code
omni init --copilot      # GitHub Copilot CLI
omni init --gemini       # Gemini CLI
omni init --opencode     # OpenCode
omni init --codex        # Codex CLI
omni init --openclaw     # OpenClaw plugin
omni init --antigravity  # Antigravity IDE
```

--------------------------------

### Upgrade OMNI via Homebrew

Source: https://github.com/fajarhide/omni/blob/main/docs/MIGRATION.md

Recommended upgrade path using Homebrew. Ensure to run `omni init` and `omni doctor` after upgrading.

```bash
brew update
brew upgrade omni
omni init           # Select Claude Code, or run: omni init --claude
omni doctor         # Verify everything
```

--------------------------------

### Create Project-Local Filter Directory

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Command to create the necessary directory for project-specific Omni filters.

```bash
mkdir -p .omni/filters

```

--------------------------------

### Initialize OMNI Hooks

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Run this command to set up the necessary hooks for OMNI to intercept and filter terminal output. This is a crucial step for OMNI's functionality.

```bash
omni init
```

--------------------------------

### Trust a project with OMNI

Source: https://github.com/fajarhide/omni/blob/main/SECURITY.md

Run this command to trust a project for the first time, which involves reviewing its configuration and adding it to the trusted projects registry. Re-run after modifying the local configuration to re-verify and update the trust hash.

```bash
omni trust
```

--------------------------------

### General Help Commands

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Use these commands for general assistance, self-diagnostics, and automated repair.

```bash
omni help          # General help
omni doctor        # Self-diagnostic
omni doctor --fix  # Self-repair
```

--------------------------------

### Auto-Repair Omni Installation

Source: https://context7.com/fajarhide/omni/llms.txt

Automatically fixes common issues detected by `omni doctor` and re-classifies historical statistics.

```bash
# Diagnose AND auto-repair all issues
omni doctor --fix
```

--------------------------------

### Piping Commands to OMNI

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Demonstrates how to pipe the output of other commands into OMNI for processing. Explicit flags are recommended for clarity, especially when learning.

```bash
git diff HEAD~3 | omni --dry-run   # If learning
```

```bash
cargo test 2>&1 | omni             # standard distillation
```

--------------------------------

### Run Vite Build with NPM

Source: https://github.com/fajarhide/omni/blob/main/tests/fixtures/npm_run_build.txt

This command executes the Vite build process for the project. It transforms modules and renders chunks for production.

```bash
my-app@1.0.0 build
> vite build
```

--------------------------------

### Build and Test OMNI Project

Source: https://github.com/fajarhide/omni/blob/main/docs/CLAUDE.md

Common Cargo commands for building, testing, linting, and formatting the OMNI project. Use `--release` for optimized builds.

```bash
cargo build              # Build debug binary
```

```bash
cargo build --release    # Build release binary
```

```bash
cargo test               # Run all tests (147 tests)
```

```bash
cargo test <module>      # Run specific module tests
```

```bash
cargo insta review       # Review snapshot test changes
```

```bash
cargo clippy             # Lint
```

```bash
cargo fmt                # Format
```

--------------------------------

### Pytest Failure Report

Source: https://github.com/fajarhide/omni/blob/main/tests/fixtures/pytest_failures.txt

Example of pytest's summary output when a test fails. This shows the file, line number, and the assertion that failed.

```text
=========================== short test summary info ============================
FAILED tests/test_omni.py::test_failure - assert 1 == 2
========================= 1 failed, 2 passed in 0.05s ==========================
```

--------------------------------

### Clone and Build OMNI

Source: https://github.com/fajarhide/omni/blob/main/CONTRIBUTING.md

Clones the OMNI repository, navigates into the project directory, and builds the project. All tests should pass after building.

```bash
git clone https://github.com/fajarhide/omni.git
cd omni
cargo build
cargo test
```

--------------------------------

### Multi-step Dockerfile Build

Source: https://github.com/fajarhide/omni/blob/main/tests/fixtures/docker_build_layered.txt

Use this Dockerfile to build a layered image. Each step creates a new layer in the Docker image.

```dockerfile
FROM debian:buster
RUN apt-get update && apt-get install -y curl
COPY src /app
WORKDIR /app
CMD ["./run.sh"]
```

--------------------------------

### Check Omni Installation Status

Source: https://context7.com/fajarhide/omni/llms.txt

Verifies the current status of Omni's hooks and MCP server registration for a specific agent without making changes.

```bash
# Check current installation status without modifying anything
omni init --status
```

--------------------------------

### Debug OMNI Sessions

Source: https://github.com/fajarhide/omni/blob/main/docs/SESSION.md

Commands to diagnose and troubleshoot OMNI session issues, including checking session activity, status, hook installation, and forcing a session reset.

```bash
# Check if session is active
omni doctor
```

```bash
# View session status
omni session --status
```

```bash
# Check if hooks are installed
omni init --status
```

```bash
# Force session reset
omni session --clear
```

--------------------------------

### Monitor Daily Stats with OMNI

Source: https://github.com/fajarhide/omni/blob/main/integrations/openclaw/README.md

Check your token and cost savings by running the `omni stats --today` command.

```bash
omni stats --today
```

--------------------------------

### Configure OMNI as an MCP Server in Antigravity IDE

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Manually add this JSON configuration to your Antigravity IDE's `mcp_config.json` file to register OMNI as an MCP server. Ensure the `command` path points to your OMNI binary.

```json
{
  "mcpServers": {
    "omni": {
      "command": "/opt/homebrew/bin/omni",
      "args": ["--mcp"],
      "env": {
        "OMNI_AGENT_ID": "antigravity"
      }
    }
  }
}
```

--------------------------------

### Preview Learned Filters with Dry Run

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Allows you to preview the TOML filters that OMNI would generate without applying them, useful for validation.

```bash
omni learn --dry-run
```

--------------------------------

### Built-in Cargo/Rust Filter Configuration

Source: https://context7.com/fajarhide/omni/llms.txt

This TOML snippet shows the configuration for the built-in Cargo/Rust filter. It matches commands starting with 'cargo' or 'rustc' and strips common compilation-related lines, providing a cleaner output. The `on_empty` field specifies a fallback message for clean builds.

```toml
# Built-in filter behavior (overridable by creating ~/.omni/filters/cargo.toml)
match_command = "^(cargo|rustc)"
strip_lines_matching = ["^\\s*Compiling ", "^\\s*Downloading ", "^\\s*Updating ", ...]
on_empty = "cargo: ok"

```

--------------------------------

### TOML Filter Best Practices

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Guidelines for writing effective TOML filters, including testing and configuration.

```bash
# Always include at least one `[[tests.filter_name]]` block per filter
# Run `omni learn --verify` after writing or editing any filter
# Use `strip_ansi = true` for tools that output colored text
# Start with `--dry-run` before `--apply`
```

--------------------------------

### OMNI Build and Test Commands

Source: https://github.com/fajarhide/omni/blob/main/docs/DEVELOPMENT.md

Common Cargo commands for building, testing, linting, formatting, and reviewing snapshot tests.

```bash
cargo build              # Debug build
cargo build --release    # Release build (~4MB binary)
cargo test               # Run all 147 tests
cargo test <module>      # Run specific tests (e.g., cargo test distillers)
cargo clippy             # Lint (CI enforces -D warnings)
cargo fmt                # Format code
cargo insta review       # Review snapshot test changes
```

--------------------------------

### Approve Project-Local Filters

Source: https://context7.com/fajarhide/omni/llms.txt

After creating project-local filters (e.g., in `.omni/filters/`), use `omni trust` to approve them. This is a security measure to ensure you are aware of and consent to the filters being applied.

```bash
mkdir -p .omni/filters
# Create .omni/filters/my-script.toml ...
omni trust        # Approve project-local filters (security gate)
omni doctor       # Confirm filters are loaded
```

--------------------------------

### OMNI Upgrade Checklist

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Execute these commands after upgrading OMNI to ensure data integrity and continued functionality.

```bash
# Run `omni doctor --fix` (re-classify historical data with new model)
# Run `omni stats` to confirm everything is working
```

--------------------------------

### Docker Build Output

Source: https://github.com/fajarhide/omni/blob/main/tests/fixtures/docker_build.txt

Shows the output logs from a Docker build process. This includes the identification of each step, the image IDs generated, and the final success messages.

```text
Sending build context to Docker daemon  2.048kB
Step 1/5 : FROM alpine:latest
 ---> a1d017b48325
Step 2/5 : RUN apk add --no-cache zig
 ---> Using cache
 ---> f8a3b8d1b60b
Step 3/5 : COPY . /app
 ---> 4c9e2c71c4c5
Step 4/5 : WORKDIR /app
 ---> Running in b4c9e2c71c4c
Successfully built b4c9e2c71c4c
Successfully tagged omni-core:latest
```

--------------------------------

### Vite Build Output

Source: https://github.com/fajarhide/omni/blob/main/tests/fixtures/npm_run_build.txt

Shows the output of the Vite build process, including module transformation, chunk rendering, and gzip size calculations for the generated assets.

```text
vite v5.0.0 building for production...
transforming...
✓ 127 modules transformed.
rendering chunks...
computing gzip size...
dist/index.html                   0.45 kB │ gzip:   0.30 kB
dist/assets/style-Ha1b2c3.css     8.21 kB │ gzip:   2.45 kB
dist/assets/vendor-Xf4g5h6.js    85.30 kB │ gzip:  28.12 kB
dist/assets/index-Ab7c8d9.js    142.67 kB │ gzip:  45.89 kB
✓ built in 3.47s
```

--------------------------------

### Preview Generated TOML Filters with Omni Learn

Source: https://context7.com/fajarhide/omni/llms.txt

Use `omni learn --dry-run` to preview the TOML filters that would be generated from noisy output without applying them.

```bash
# Preview the generated TOML without writing it
omni learn --dry-run < build.log
```

```text
  [filters.detected_1711234567]
  match_command = "^my-deploy"
  strip_lines_matching = [
    "^Uploading artifact",
    "^Waiting for health check",
    "^\s+\d+%",
  ]
```

--------------------------------

### Reset OMNI Configurations

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Performs a clean uninstall and resets configurations. This is often used before restoring backups.

```bash
omni reset
```

--------------------------------

### Review Snapshots

Source: https://github.com/fajarhide/omni/blob/main/CONTRIBUTING.md

Opens an interactive prompt to review snapshot test changes. Use this after making changes that might affect test outputs.

```bash
cargo insta review
```

--------------------------------

### Run Snapshot Tests for Distillers

Source: https://github.com/fajarhide/omni/blob/main/docs/DEVELOPMENT.md

Execute snapshot tests specifically for the distillers module and review any changes.

```bash
cargo test distillers::tests
cargo insta review
```

--------------------------------

### Discover Noise Candidates with Omni Learn

Source: https://context7.com/fajarhide/omni/llms.txt

Use `omni learn --discover` to analyze terminal output and identify repetitive noise patterns that can be converted into TOML filters.

```bash
# Passive: process patterns already queued from background hook activity
omni learn --discover      # Show discovered noise candidates in a table
```

```bash
# Active: pipe a specific noisy log directly
cat build.log | omni learn --discover
```

--------------------------------

### Antigravity IDE MCP Server Configuration

Source: https://context7.com/fajarhide/omni/llms.txt

This JSON configuration shows how to manually register Omni as an MCP server for the Antigravity IDE. It specifies the command to run Omni, its arguments (`--mcp`), and environment variables like `OMNI_AGENT_ID`.

```json
# Antigravity IDE — manual mcp_config.json entry
# ~/.gemini/antigravity/mcp_config.json
{
  "mcpServers": {
    "omni": {
      "command": "/opt/homebrew/bin/omni",
      "args": ["--mcp"],
      "env": { "OMNI_AGENT_ID": "antigravity" }
    }
  }
}

```

--------------------------------

### Learn TOML Filters with OMNI

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Automatically generates TOML filters from passthrough output. Use `--dry-run` to preview suggestions before applying them with `--apply`.

```bash
omni learn --discovery     # Discovery: Search for new noise patterns
```

```bash
omni learn --dry-run    # Preview: Show suggested TOML
```

```bash
omni learn --apply      # Action: Commit to learned.toml
```

```bash
omni learn --verify     # Test: Run inline tests on all filters
```

--------------------------------

### Run Specific Integration Tests

Source: https://github.com/fajarhide/omni/blob/main/docs/DEVELOPMENT.md

Execute specific integration tests by targeting their respective test files.

```bash
cargo test --test hook_e2e           # E2E binary spawn tests
cargo test --test savings_assertions # Savings threshold tests
cargo test --test security_tests     # Security tests
```

--------------------------------

### Company Deploy Tool Filter Configuration

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Configures a filter for a company's internal deploy tool, handling success and rollback scenarios with specific line stripping and output transformations.

```toml
schema_version = 1

[filters.deploy]
description = "Internal deploy pipeline"
match_command = "^deploy\b"
strip_ansi = true
confidence = 0.90

[[filters.deploy.match_output]]
pattern = "Successfully deployed to (\w+)"
message = "deploy: ✓ $1"

[[filters.deploy.match_output]]
pattern = "ROLLBACK"
message = "deploy: ✗ ROLLBACK triggered"

strip_lines_matching = [
    "^\ \[DEBUG\]",
    "^Uploading artifact",
    "^Waiting for health check",
    "^\s*\d+%",
]
max_lines = 20
on_empty = "deploy: completed (no notable output)"

[[tests.deploy]]
name = "success case"
input = """
[DEBUG] Connecting to prod-cluster
Uploading artifact...
  45%
  90%
  100%
Successfully deployed to production
Health check passed
"""
expected = "deploy: ✓ production"

[[tests.deploy]]
name = "rollback case"
input = """
[DEBUG] Deploying v2.0
Health check FAILED
ROLLBACK initiated
"""
expected = "deploy: ✗ ROLLBACK triggered"
```

--------------------------------

### Configure Custom Pricing for OMNI Savings Calculation

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Customize OMNI's cost savings estimation by modifying the 'pricing' section in '~/.omni/config.toml'. Set 'input_price_per_1m' and 'output_price_per_1m' to reflect your token costs.

```toml
[pricing]
# Example: Claude 3.5 Sonnet pricing
input_price_per_1m = 3.0
output_price_per_1m = 15.0
```

--------------------------------

### Run OMNI Snapshot Tests

Source: https://github.com/fajarhide/omni/blob/main/tests/README.md

Execute snapshot tests for the distillers module. Use 'insta review' to review changes to snapshots.

```bash
cargo test distillers::tests
```

```bash
cargo insta review                    # Review changes
```

--------------------------------

### Add ~/.local/bin to PATH

Source: https://github.com/fajarhide/omni/blob/main/docs/MIGRATION.md

Troubleshooting step for 'omni: command not found' errors. Ensures the OMNI executable directory is included in your system's PATH environment variable.

```bash
export PATH="$HOME/.local/bin:$PATH"
```

--------------------------------

### Check OMNI Statistics

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Run 'omni stats' to view OMNI's performance metrics for the last 30 days. Use flags like --today, --week, or --month for different time ranges. The output includes commands processed, bytes saved, signal ratio, and cost savings.

```bash
omni stats              # Last 30 days (default)
omni stats --today      # Today only
omni stats --week       # Last 7 days
omni stats --month      # Last 30 days (explicit)
```

--------------------------------

### Apply Learned Filters with Omni Learn

Source: https://context7.com/fajarhide/omni/llms.txt

Use `omni learn --apply` to automatically generate and append TOML filters based on repetitive noise patterns found in the provided input.

```bash
# Apply: append to ~/.omni/filters/learned.toml
omni learn --apply < build.log
```

--------------------------------

### Discover Patterns for OMNI Learning

Source: https://github.com/fajarhide/omni/blob/main/docs/HOW_TO_USE.md

Initiates the discovery process for OMNI to identify repetitive noise patterns in the terminal output, typically for background learning.

```bash
omni learn --discover
```