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

Related MCP server: architectos

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

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

Lenses

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.

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>

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.

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.