Omphalos

Codebase symbol indexer for LLMs.

Omphalos generates a compact, high-signal symbol map (INDEX.md) of your repository. It provides large language models and developers with an instant architectural overview and precise symbol locations—minimizing token usage and eliminating the need to read entire source files just to find declarations.

Table of Contents

• Omphalos
  • Table of Contents
  • Background
  • Install
  • Usage
    • Quick Start
    • CLI Reference
    • LLM / Agent Integration
  • Development
  • Related Efforts
  • Maintainers
  • Contributing
  • License

Background

When providing a full codebase as context to Large Language Models (LLMs) or AI coding agents, feeding entire file contents quickly exhausts the model's context window, degrades reasoning performance, and incurs high token costs.

In practice, an agent rarely needs the implementation bodies of every file at once; it only needs an accurate structural index: what functions, classes, interfaces, and methods exist, where they are defined, and what their docstrings say.

Omphalos was created to solve this problem:

1. Multi-language AST Parsing: Uses Tree-sitter for deterministic parsing across Python, TypeScript/JavaScript, Go, and Rust.
2. Precise Line Numbers (@<line>): Symbols indicate exact declaration line numbers so agents can inspect or slice specific ranges on demand.
3. Internal Logic Hints: Function-like symbols list their deduplicated call targets (calls) and raised exception types (raises), giving agents a control-flow preview without opening the file.
4. Atomic Incremental Cache: Tracks SHA-256 content hashes to re-parse only changed files, guaranteeing rapid re-indexes.
5. CI/CD Integration: Supports --check mode to ensure codebase indexes stay synchronized with changes.
6. Live Watch Mode: Zero-dependency file monitoring (omph watch) automatically re-indexes in milliseconds whenever code files are edited or saved.

Install

Using uv (Recommended)

Run directly without installing:

$ uvx --from git+https://github.com/snui1s/Omphalos.git omph scan

Or install as a standalone CLI tool:

$ uv tool install git+https://github.com/snui1s/Omphalos.git

Using pip

$ pip install git+https://github.com/snui1s/Omphalos.git

Using npm / npx

Run directly via npx:

$ npx omphalos scan

Or install globally:

$ npm install -g omphalos

From Source

$ git clone https://github.com/snui1s/Omphalos.git
$ cd Omphalos
$ uv sync

Usage

Quick Start

1. Initialize Ignore File (creates default .omphignore):

$ omph init

2. Generate the Symbol Index:

$ omph scan

This generates INDEX.md in the root directory:

# Codebase Symbol Index

## src/omphalos/cache.py

- `calculate_sha256()` @15: Calculate the SHA-256 checksum of raw file bytes for change detection. (calls: `hexdigest`, `hashlib.sha256`)
- `save_cache()` @38: Save symbol cache to .omphcache atomically. (calls: `tempfile.mkstemp`, `os.fdopen`, `json.dump`, `os.replace`, `os.unlink`)

## src/omphalos/cli.py

- `_version_callback()` @33: Callback for --version flag to print the version and exit immediately. (calls: `typer.echo`, `_package_version`; raises: `typer.Exit`)

## tests/fixtures/sample.ts

- export interface `UserProfile` @1
- export type `AuthToken` @6
- export function `verifyToken()` @8
- export class `SessionManager` @18
  - `createSession()` @19

3. Keep Index Synchronized in Real Time (Optional):

Run Watch Mode in a background terminal to automatically update INDEX.md on every file save:

$ omph watch
# or: omph scan -w

4. Instruct AI Agents via AGENTS.md:

Create or add to AGENTS.md (or CLAUDE.md / .cursorrules) at the root of your repository so AI agents read INDEX.md before exploring code:

# Agent Guidelines

## Codebase Navigation & Exploration

Before searching, running grep, or opening entire source files across the codebase:

1. **Always read [`INDEX.md`](INDEX.md) first.** It provides an instant symbol map of the entire repository with exact line numbers.
2. Use the symbols, line locations (`@<line>`), and internal logic hints (`calls:`, `raises:`) in [`INDEX.md`](INDEX.md) to pinpoint definitions directly.
3. Inspect or slice-read only the specific line ranges or files needed for the task, rather than loading entire files into context.

CLI Reference

$ omph scan [DIRECTORY] [OPTIONS]
$ omph watch [DIRECTORY] [OPTIONS]

The binary is installed as omph; the full name omphalos is also available as an alias.

Option	Flag	Description
--watch, -w	flag	Watch files for changes and re-index incrementally in real time.
--output, -o	PATH	Custom path for index output (default: INDEX.md).
--format	markdown | json	Output format (default: markdown).
--check	flag	Verify index is up to date without writing. Exits with code 1 if stale.
--git-only	flag	Scan only files tracked by Git (git ls-files).
--no-cache	flag	Bypass cache and re-parse all files.
--no-calls	flag	Omit calls: annotations (about half the index size on large codebases).
--version	flag	Show version and exit.
--help	flag	Show help message.

LLM / Agent Integration

• Automatic Agent Discovery via AGENTS.md: Coding agents (Antigravity, Cursor, Claude Code, GitHub Copilot) automatically load AGENTS.md at conversation start. By telling the agent to consult INDEX.md first, the agent pinpoints definitions immediately without burning tokens on repository-wide grep searches.
• Surgical Inspection: Because each symbol includes @<line>, an LLM can request precise lines via tools (e.g. head -n 50 or view tool slice) rather than ingesting entire files.
• Machine-Readable Formats: Use --format json to integrate with custom RAG systems or agent tools:

$ omph scan --format json -o index.json

Index size on large codebases

INDEX.md is meant to be read in full only on small and medium repositories. Measured on ~900 Python files (~430k lines), the full index is ~1.8 MB; --no-calls brings it to ~0.86 MB. At that scale, point the agent at grep/search inside INDEX.md instead of loading the whole file, and consider --no-calls:

$ omph scan --no-calls

calls: lists are not name-resolved, so they can include noise; raises: annotations are kept either way.

Update notifications and privacy

omph checks PyPI for a newer release and prints a short notice when one exists. Details:

• It sends a single GET https://pypi.org/pypi/omphalos/json request (the only identifier is the User-Agent: omphalos-updater header; no file names, paths or code leave your machine).
• The result is cached in ~/.omphalos/ for 24 hours, so the network is hit at most once a day. The request has a 1 second timeout and failures are silent.
• The check is skipped automatically for --format json, --check, and when CI is set.
• To turn it off entirely, set OMPH_NO_UPDATE_NOTIFIER=1:

$ export OMPH_NO_UPDATE_NOTIFIER=1   # PowerShell: $env:OMPH_NO_UPDATE_NOTIFIER = "1"

Development

# Install development dependencies
$ uv sync --dev

# Run tests
$ uv run pytest

# Run linter and type checker
$ uv run ruff check .
$ uv run mypy src

Related Efforts

• Tree-sitter - Fast, incremental parsing system used under the hood.
• Universal Ctags - Traditional code indexing system.
• Repomix - Repository packager for AI context.

Contributing

Feel free to dive in! Open an issue or submit a Pull Request.

Omphalos follows the Contributor Covenant Code of Conduct.

License

MIT © 2026 snui1s