Atlas User Guide

Atlas is Ranex's local-first code indexing system for Python projects.

What Atlas does

• Indexes Python source files under a project root
• Extracts artifacts such as:
  • functions and async functions
  • classes and methods
  • FastAPI endpoints (when detectable)
  • models (when detectable)
• Enables:
  • fast name-based search
  • file-to-file dependency queries
  • impact analysis based on dependency relationships
  • cycle detection and basic duplicate/pattern detection

Where Atlas stores data

• .ranex/atlas.sqlite

If you delete this file, Atlas will require a new scan.

Basic workflow

1. Scan: ranex atlas scan
2. Search: ranex atlas search "<query>"
3. Assess risk before edits:
   • ranex atlas file-impact <file_path>
   • ranex atlas function-impact <qualified_name>

Search

• Use broad queries first (module names, feature names, common prefixes), then refine.
• JSON mode is recommended for tooling: --json.

Dependencies and impact

Atlas provides file-level dependency graph helpers:

• ranex atlas dependencies <file_path>
• ranex atlas dependents <file_path>

Impact reports:

• ranex atlas file-impact <file_path>
• ranex atlas function-impact <qualified_name>

Cycles and duplicates

• ranex atlas cycles finds circular dependencies between files.
• ranex atlas duplicates finds potential duplicates. This is a heuristic feature and should be treated as a starting point for review, not proof.

Span tools

Span tools are useful for automation and AI assistants:

• ranex atlas grep "<text>"
• ranex atlas search-spans "<query>"
• ranex atlas read-span <file_path> <start_line> <end_line>

These are designed to return small, targeted excerpts or ranges (rather than dumping entire files).

FastAPI tooling

If your project uses FastAPI, Atlas can provide additional analysis:

• Scaling analysis policy + report
• Router topology
• Truth capsule generation for a specific route/handler

See FastAPI Scaling Analysis for details.