๐ฑ Omni โ The All-Seeing Eye

The Federation Governance Tricorder โ A modular, extensible observation engine that scans, maps, and guards codebases at galactic scale.
"Never trust documentation, trust reality." โ ACE
Omni is a Python-powered passive observation platform that discovers the truth about your code. It doesn't modify files or break builds โ it sees, maps, and reports. Think of it as a tricorder for your codebase: point it at any directory and it reveals structure, dependencies, health, drift, and compliance in seconds.
โจ At a Glance
๐ Quick Start
New Here? Check out the Beginner's Guide: Zero to Hero for a step-by-step setup tutorial.
Install
# Recommended: Install from PyPI
pip install omni-governance
# Or install from source:
# pip install -e .
Your First Scan
# Scan the current directory with all static scanners
omni scan .
# Run a specific scanner
omni scan . --scanner surfaces
# See what Omni knows about itself
omni introspect
Explore the Ecosystem
# Map your entire project constellation
omni map
# Check governance compliance
omni gate .
# Generate a full report
omni report . --format markdown
๐๏ธ Architecture โ The Trinity
Omni follows the Trinity Architecture โ three layers with strict separation of concerns:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ CLI (cli.py) โ โ User interface
โ 14 verbs, 1 brain โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโ
โ โ โ
โโโโโโโโโโโผโโโโโโโ โโโโโโโโโผโโโโโโโโโ โโโโโโโโผโโโโโโโโ
โ ๐ง CORE โ โ ๐๏ธ PILLARS โ โ ๐ LIB โ
โ Identity โ โ Cartography โ โ I/O, Render โ
โ Registry โ โ Intel โ โ Reporting โ
โ Gate โ โ Gatekeeper โ โ Tree, TAP โ
โ Paths โ โ Registry โ โ Requirementsโ
โโโโโโโโโโโฌโโโโโโโ โโโโโโโโโฌโโโโโโโโโ โโโโโโโโโโโโโโโโ
โ โ
โโโโโโโโโโโผโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ SCANNERS (55 Instruments) โ
โ 12 categories โข Dynamic plugin loading โ
โ Each scanner: scan(target: Path) โ dict โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโผโโโโโโโ
โ ๐ง BUILDERS โ โ The only layer that writes
โ Registry Gen โ
โ Report Gen โ
โโโโโโโโโโโโโโโโโโ
Read-Only Guarantee: Scanners never modify source files. Only Builders write, and only to designated artifact directories.
For the full architectural deep-dive, see ARCHITECTURE.md.
๐ Scanner Categories
Omni's 55 scanners are organized into 12 categories. Each scanner implements the universal scan(target: Path) โ dict contract and is auto-discovered via SCANNER_MANIFEST.yaml files.
Open Source Scanners (Included in Build)
Federation-Exclusive Scanners (Not in Open Source Build)
These scanners require the Federation Heart backend and are part of the proprietary governance layer. They appear in
omni introspectwhen the Heart is available but are not distributed with the open-source release.
Each category has its own README with detailed scanner documentation. See the Scanner Architecture Guide for the complete reference.
๐๏ธ The Four Pillars
Pillars are orchestration subsystems that coordinate multiple scanners and produce higher-level intelligence:
See Pillars Architecture for the deep dive.
โก CLI Command Reference
๐ Federation Mode vs. Standalone
Omni operates in two modes, transparently:
Standalone Mode (Default)
No external dependencies. Configuration from omni.yml and environment variables. All open-source scanners work perfectly. Ideal for individual developers and open-source projects.
Federation Mode (Optional)
When federation_heart is installed, Omni gains:
- CartographyPillar โ Canonical path resolution across the entire Federation
- Constitution โ Governance rule enforcement from a central authority
- CMP Integration โ Project identity resolution against the Canonical Master Project database
- Runtime Health โ Live status of Federation services, stations, and tunnels
The integration is handled by a single shim (omni/config/settings.py) that bridges to the Heart when available and falls back gracefully when it's not.
๐ง MCP Server
Omni includes a Model Context Protocol (MCP) server that exposes all 55 scanners as AI-callable tools. Any MCP-compatible AI assistant can invoke Omni's scanners programmatically.
Quick Start (npx)
The absolute easiest way to use the MCP Server is via npx (requires Node.js):
npx -y @modelcontextprotocol/inspector mcp-server-omni-governance
Run from Source
# The MCP server auto-discovers all registered scanners
python -m mcp_server.omni_mcp_server
See MCP Server Documentation for setup and configuration.
๐ Project Structure
omni/
โโโ README.md โ You are here
โโโ ARCHITECTURE.md โ Full architectural deep-dive
โโโ CONTRIBUTING.md โ How to add scanners and contribute
โโโ CHANGELOG.md โ Version history
โโโ ROADMAP.md โ Future plans
โโโ pyproject.toml โ Package definition
โโโ omni/
โ โโโ cli.py โ CLI entry point (14 commands)
โ โโโ core/ โ Brain โ identity, registry, gate, paths
โ โโโ config/ โ Configuration & Federation Heart bridge
โ โโโ scanners/ โ 55 scanners across 12 categories
โ โโโ pillars/ โ 4 orchestration subsystems
โ โโโ lib/ โ Shared utilities (I/O, rendering, reporting)
โ โโโ builders/ โ Registry and report generators
โ โโโ scaffold/ โ Project templates
โ โโโ templates/ โ Jinja2 report templates
โโโ mcp_server/ โ MCP server exposing scanners as AI tools
โโโ scripts/ โ Operational scripts
โโโ tests/ โ Test suite (pytest)
โโโ docs/ โ Historical docs and plans
โโโ contracts/ โ Crown Contracts (C-TOOLS-OMNI-*)
๐ง Configuration
Omni follows a strict configuration hierarchy (highest priority wins):
- CLI flags (e.g.,
--scanner surfaces) - Environment variables (e.g.,
OMNI_ROOT) omni.yml(project-level configuration)- Built-in defaults (sensible fallbacks)
Key environment variables:
See Configuration Guide for full details.
๐งช Testing
# Run all tests
pytest tests/ -v
# With coverage
pytest tests/ --cov=omni --cov-report=html
See Test Suite Documentation for fixtures, standards, and CI setup.
๐ค Contributing
We welcome new scanners, pillars, and improvements. The scanner plugin system makes it straightforward to add new observation capabilities:
- Create a scanner file with a
scan(target: Path) โ dictfunction - Register it in the category's
SCANNER_MANIFEST.yaml - Add tests and documentation
See CONTRIBUTING.md for the full guide.
๐ Requirements
- Python: 3.8+
- Dependencies:
pyyaml,pydantic(core);federation_heart(optional, for Federation mode) - OS: Windows, macOS, Linux
๐ License
Open source. See LICENSE for details.