omniseek

OmniSeek

Citation-grounded codebase intelligence. OmniSeek reviews a repository through four lenses (architecture, security, performance, product) and backs every finding with file:line evidence. Then it checks that evidence against your files, so a hallucinated line number or invented function cannot slip into the report.

• Runs anywhere, immediately. Pure Python standard library: no compiler, no native wheels, no mandatory dependencies.
• Deterministic by default. More than 40 built-in rules, with Python rules evaluated on the syntax tree, so code inside strings and comments never matches. The same tree gives the same findings.
• Bring your own model. Add --model anthropic/…, openai/… or gemini/… and your own key for deeper, cross-file findings. Model findings are verified like everything else, and the ones whose citations do not exist are dropped.
• Verifies anyone's claims. omniseek verify checks any findings file (yours, another tool's, an AI assistant's) against the working tree or a git revision and scores it from 0.0 to 1.0.
• Ships where you work. A self-contained HTML dossier, SARIF 2.1.0 for GitHub code scanning, Markdown for pull requests, and an MCP server for Claude, Cursor and other assistants.

60-second quickstart

pipx install omnirogue-omniseek                # or: pip install omnirogue-omniseek

omniseek scan . --output findings.json --html dossier.html
omniseek verify findings.json --repo .
open dossier.html                                           # xdg-open on Linux

No install at all? From a checkout, python3 -m omniseek scan . works with any Python 3.10+.

Package name. On PyPI this tool is omnirogue-omniseek; the command and the Python package are omniseek. The PyPI project called omniseek is unrelated. To install straight from this repository instead: pipx install "git+https://github.com/omnirogue/omniseek".

Try it on the deliberately flawed demo app, including a findings file with planted hallucinations:

bash examples/run_demo.sh            # writes the dossier, SARIF and Markdown to a temp directory

How it works

                      ┌──────────────────────── omniseek scan ─────────────────────────┐
  local dir           │  repo walker ──▶ heuristic lenses ──┐                          │
  or git URL ────────▶│  (git ls-files,  architecture       │                          │
                      │   .gitignore,    security           ├──▶ findings ──▶ verifier ├──▶ findings.json
                      │   no symlinks)   performance        │    + citations   (0.0-1.0)│      (omniseek.findings/v1)
                      │                  product            │                          │
                      │  optional: --model provider/model ──┘  redacted, line-numbered │
                      │            (your key; ungrounded findings dropped)             │
                      └────────────────────────────────────────────────────────────────┘
                                                   │
          ┌────────────────────┬───────────────────┼────────────────────┬─────────────────────┐
          ▼                    ▼                   ▼                    ▼                     ▼
  omniseek report       omniseek report     omniseek report     omniseek verify       omniseek cloud-sync
  --format html         --format sarif      --format md         any findings file     (optional, OmniSI Cloud)
  dark-mode dossier     GitHub code         PR comments         vs. working tree
                        scanning                                or a git revision

  omniseek-mcp: the same scan, verify and render as MCP tools (stdio, or streamable HTTP)

Commands

Command	What it does
omniseek scan <path_or_git_url> [--lenses architecture,security,performance,product] [--model provider/model] [--output findings.json] [--html report.html] [--sarif out.sarif] [--md out.md] [--fail-on high]	Scans a local directory, or shallow-clones an https://, ssh:// or git@ URL first. Findings go to --output (or stdout); the summary goes to stderr
omniseek verify <findings.json> --repo <path> [--ref HEAD] [--min-score 1.0] [--output verified.json] [--json]	Checks every citation; prints the grounding score and each flagged citation
omniseek report <findings.json> --format html|md|sarif --output <file> [--verify-repo <path>]	Renders a findings file; --verify-repo verifies first so the badges are current
omniseek cloud-sync <findings.json> [--api-url https://api.omnirogue.com] [--no-snippets] [--dry-run]	Optional: sends a findings file to OmniSI Cloud (needs OMNISI_API_KEY)
omniseek rules [--lens security] [--json]	Lists the built-in rules

Exit codes: 0 success, 1 a gate failed (--fail-on severity or --min-score), 2 bad input or usage.

Lenses

Lens	Examples of what the built-in rules find
security	Hardcoded credentials (never copied into output), committed .env files, SQL built from strings (including through a variable), shell commands with shell=True/os.system, eval/new Function, pickle and unsafe YAML, disabled TLS verification, innerHTML/dangerouslySetInnerHTML, wildcard CORS, debug mode, injectable GitHub Actions, actions pinned to branches, root containers, :latest base images, unpinned dependencies
performance	HTTP or database calls inside loops (N+1), blocking calls in async code, sequential await in loops, forEach(async …), JSON deep clones, SELECT *
architecture	Import cycles (Python and JS/TS), very large files, long and highly complex functions, change hotspots from git history, swallowed exceptions, wildcard imports, deep relative imports, TODO/FIXME debt
product	Missing README, license, security policy or contributing guide; README without install/usage; broken relative links in Markdown; no tests; no CI; incomplete package metadata; placeholder (lorem-ipsum) copy in user-facing files

Test and example code is not held to the architecture and performance rules, and security findings there are marked low confidence. Add an .omniseekignore file (one glob per line) to skip more paths.

The citation verifier

A finding is only as good as its evidence. Every finding carries citations:

{
  "rule_id": "security/sql-string-building",
  "lens": "security",
  "severity": "high",
  "title": "SQL built from strings",
  "citations": [
    {"kind": "span", "path": "app.py", "start_line": 17, "end_line": 17,
     "snippet": "return conn.execute(f\"SELECT id, email FROM users WHERE name = '{name}'\").fetchone()",
     "symbol": "find_user"},
    {"kind": "absence", "globs": ["license", "license.*"]}
  ]
}

omniseek verify checks that the path stays inside the repository (no .., no absolute paths, no symlinks out), the file exists and is text, the line range is inside the file, the quoted snippet appears in exactly those lines (whitespace-insensitive), and the symbol appears there as a whole identifier. An absence citation is verified only if none of its paths or globs exist.

Status	Score	Meaning
verified	1.0	Path, range, quote and symbol all check out
drifted	0.5	The quote or symbol exists in the file, but at other lines (the actual lines are reported)
unanchored	0.5	The range exists but nothing was quoted, so the content could not be checked
hallucinated	0.0	The file, quote or symbol does not exist, or a claimed absence is present
invalid	0.0	Malformed, or points outside the repository

A finding's grounding_score is the mean of its citation scores (0.0 when it cites nothing), and the document's score is the mean over findings. Verification proves provenance, not correctness: a verified citation shows the evidence exists where the finding says it does.

Shorthand citations such as "app.py:15-17" and {"file": …, "lines": "15-17"} are accepted, so you can verify output from other tools and assistants. Use --ref <sha> to verify against a commit instead of the working tree.

Bring your own model

export ANTHROPIC_API_KEY=...                       # or OPENAI_API_KEY / GEMINI_API_KEY
omniseek scan . --model anthropic/claude-sonnet-5-5 --html dossier.html
omniseek scan . --model openai/<model-id>
omniseek scan . --model gemini/<model-id>

Provider	Key	Endpoint override
openai/<model>	OPENAI_API_KEY	OPENAI_BASE_URL (any OpenAI-compatible server, including local ones on http://localhost)
anthropic/<model>	ANTHROPIC_API_KEY	ANTHROPIC_BASE_URL
gemini/<model>	GEMINI_API_KEY or GOOGLE_API_KEY	GEMINI_BASE_URL

What is sent: a file list, the heuristic leads, and line-numbered excerpts (lead areas, entry points, configuration, then the largest source files) within --max-context-chars (default 120,000). .env files, key files and lockfiles are never sent, and values that look like credentials are replaced with «redacted» first. Keys are read from the environment only. Requests go over HTTPS (plain HTTP only to localhost). Install omnirogue-omniseek[httpx] to use httpx instead of urllib.

The model's findings are validated against the schema, then verified; findings with no valid citation are dropped unless you pass --keep-ungrounded.

MCP server

omniseek-mcp exposes three tools: omniseek_scan (read-only, offline), omniseek_verify_citations (read-only) and omniseek_render_dossier (writes a file only when given output_path, and never overwrites without overwrite: true). Every path must be inside a --root directory (default: the working directory). Scans through MCP never call a model; your assistant already is one.

Claude Code:

claude mcp add omniseek -- omniseek-mcp --root /path/to/project

Claude Desktop, Cursor, OmniConsole and other clients that read an mcpServers file:

{
  "mcpServers": {
    "omniseek": {
      "command": "omniseek-mcp",
      "args": ["--root", "/path/to/project"]
    }
  }
}

Without installing, use "command": "python3", "args": ["-m", "omniseek.mcp_server", "--root", "/path/to/project"] with "env": {"PYTHONPATH": "/path/to/omniseek"}.

Streamable HTTP (needs pip install "omnirogue-omniseek[mcp]", works with MCP SDK 1.x and 2.x):

omniseek-mcp --transport streamable-http --root /path/to/project --port 8765   # http://127.0.0.1:8765/mcp

It binds to 127.0.0.1 and has no authentication of its own; put it behind your own authenticating proxy if you expose it.

GitHub code scanning (SARIF)

Copy examples/github-action-sarif.yml to .github/workflows/omniseek.yml:

name: omniseek
on:
  push:
    branches: [main]
  pull_request:
permissions:
  contents: read
  security-events: write
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install "omnirogue-omniseek==0.1.0"
      - run: omniseek scan . --output omniseek-findings.json --sarif omniseek.sarif --html omniseek-dossier.html --md omniseek.md
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: omniseek.sarif
          category: omniseek
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: omniseek-dossier
          path: omniseek-dossier.html

Results appear under Security → Code scanning. Security rules carry a security-severity, so GitHub ranks them as critical, high, medium or low. Add --fail-on high to the scan step to block merges on serious findings.

OmniSeek open source vs. OmniSI Cloud

OmniSeek is the open-source core of OmniSI. OmniSI Cloud is a separate, proprietary service built on the OmniRogue Rust Engine. cloud-sync is the only bridge between them: it is optional, sends only a findings file you already have (never your repository), and nothing leaves your machine without OMNISI_API_KEY.

	OmniSeek (this repository, Apache-2.0)	OmniSI Cloud (proprietary, OmniRogue Rust Engine)
Where it runs	Your machine or CI, offline by default	Hosted service
Analysis	40+ deterministic rules across 4 lenses, plus your own model	Parallel Rust ingestion of large monorepos and evidence packs; multi-stage model pipeline
Verification	Deterministic citation and grounding verifier	Cross-family adversarial verification: findings challenged by models from different labs
Memory	Stateless; one findings file per run	Organization memory: deduplicates findings across repositories and runs
Action	HTML, SARIF, Markdown, MCP	Turns a confirmed finding into a Decision your team approves, then executes the action exactly once
Models and keys	Bring your own (OpenAI, Anthropic, Gemini, OpenAI-compatible)	Managed
Price	Free	Commercial
Bridge	omniseek cloud-sync findings.json	Receives findings from OmniSeek

export OMNISI_API_KEY=...
omniseek cloud-sync findings.json --dry-run     # see exactly what would be sent
omniseek cloud-sync findings.json --no-snippets # send without quoted code

cloud-sync posts omniseek.cloud-sync/v1 JSON to {api_url}/v1/omniseek/scans with an idempotency key. The local repository path is never sent.

Privacy and security

• scan, verify and report make no network calls. Only --model, cloud-sync and scanning a git URL do, and only to the endpoint you chose.
• Secret values are never copied into findings or reports: citations quote the text before the value plus its first four characters, and code excerpts are redacted.
• The HTML dossier is one file with no external requests. All content is escaped and the inline script is pinned by a Content-Security-Policy hash.
• The scanner never follows symlinks out of the repository, and the verifier rejects citations that escape it.

Report vulnerabilities privately; see SECURITY.md.

Findings schema

omniseek.findings/v1: schema, tool, generated_at, repo (name, commit, files_scanned, languages), analyzer (mode, model, lenses), summary, findings[] and, after verification, verification plus a verification block on each finding. Each finding has id (stable across line moves), rule_id, lens, severity (critical, high, medium, low, info), confidence, title, description, remediation[], citations[] and source (heuristic or llm:<provider>/<model>). See examples/sample_findings.json.

Development

python -m unittest discover -s tests        # no dependencies needed
python -m omniseek scan . --output /tmp/self.json && python -m omniseek verify /tmp/self.json --repo .

Tested on Linux and macOS with Python 3.10 to 3.13. See CONTRIBUTING.md to add a rule.

License

Apache-2.0. See NOTICE.