RepoLens

Understand how a codebase works.

A local-first, evidence-based code intelligence and developer onboarding tool.
No arbitrary 0–100 scores. No repository code execution. No LLM keys required.

The Core Problem

"I cloned this repository. How does it actually work?"

When developers, students, open-source contributors, and engineering teams approach an unfamiliar codebase, they are forced to open dozens of files manually, guess where execution begins, and piece together the mental model from scratch.

Existing tools either:

• Lint your code and tell you what you did wrong (ruff, eslint, sonarqube).
• Draw unreadable spiderwebs of 300 raw dependency edges (madge, pydeps).
• Enforce architectural contracts that require you to already understand the architecture before writing the rules (import-linter, archunit).
• Dump raw files into LLM prompts (repomix, chat assistants) which cost money, hallucinate, and send proprietary code to external clouds.

RepoLens answers the core onboarding questions using deterministic repository evidence:

• Where does this application start?
• What are the important modules?
• Which files depend on which other files?
• What are the main architectural layers?
• Which modules are central coordination hotspots?
• Which files should I read first, in what order, and why?
• What should a new contributor understand in their first 30 minutes?

Key Features

• 🔍 Evidence-Based Entry Points: Identifies execution starting points using AST guards (if __name__ == "__main__":), CLI decorators (Click, Typer), and configuration manifests (pyproject.toml scripts, package.json bins).
• 🧭 Recommended Reading Order: Generates a sequential reading roadmap with an explicit purpose for each file (Documentation $\to$ Manifest $\to$ Entry Point $\to$ Hotspots $\to$ Domain Models $\to$ Tests).
• ⏱️ The First 30 Minutes (repolens onboard): A time-boxed contributor onboarding blueprint broken down into 6 focused phases with specific files and conceptual takeaways.
• ⚡ Structural Hotspots (Without Defect Scoring): High-connectivity modules identified and classified (Foundational Modules, Orchestrators, Structural Nexuses). Connectivity is treated as structural significance, not a "bad code" penalty.
• 🏛️ Architectural Layer Inference: Automatically detects multi-tier layers (CLI, API, Services, Data Access / Storage, Utilities, Configuration, Tests) backed by observable evidence.
• 🗺️ Dependency Maps: Generates clean, copy-pasteable Mermaid flowcharts and Graphviz DOT diagrams with repolens map.
• 🤖 Machine-Readable JSON: Full structured payload export via repolens report . --format json.
• 🔒 Zero-Execution Security: Never runs eval(), exec(), user imports, shell scripts, or test runners. 100% static AST parsing.
• 🌐 100% Offline & Private: Zero network calls, zero telemetry, zero tracking, zero external APIs.

Quickstart

Installation

# Option 1: Install from PyPI (Recommended)
pip install repolens-toolkit

# Option 2: Direct install from official GitHub release wheel
pip install https://github.com/deswanth12/repolens/releases/download/v0.1.1/repolens_toolkit-0.1.1-py3-none-any.whl

# Option 3: Install directly from GitHub
pip install git+https://github.com/deswanth12/repolens.git

# Option 4: Clone and install locally in editable mode
git clone https://github.com/deswanth12/repolens.git
cd repolens
pip install -e .

Note: The package is distributed as repolens-toolkit on PyPI and exposes the runnable repolens CLI.

Basic Usage

Run RepoLens on any directory:

# Analyze current repository
repolens .

# Or analyze a specific repository path
repolens path/to/project

Example Output

RepoLens v0.1.1 -- Understand how a codebase works
------------------------------------------------------------
  Project:                repolens
  Root Path:              /path/to/repolens
  Primary Language:       Python
  Files (Total / Source): 94 total / 30 source
  Tests / Docs:           44 tests / 14 docs
  Total Lines:            6,145
  Entry Points:           1
------------------------------------------------------------
INFERRED ARCHITECTURE
  Layer                    Confidence    Files & Evidence
  CLI / Interface          MEDIUM        repolens/cli.py
                                         Filename matches standard 'cli.py' convention.
  Data Access / Storage    LOW           repolens/models.py
                                         Filename matches standard 'models.py' convention.
  Configuration            LOW           pyproject.toml
                                         Filename matches standard 'pyproject.toml' convention.
  Tests                    HIGH          tests/__init__.py, tests/test_architecture.py (+11 more)
                                         Directory matches 'tests' pattern.
------------------------------------------------------------
APPLICATION ENTRY POINTS
  File                  Category      Confidence    Evidence
  repolens/cli.py       CLI           HIGH          Configured as console script 'repolens' in pyproject.toml
------------------------------------------------------------
STRUCTURAL HOTSPOTS (High connectivity / Core coordination)
  Module                          Coupling (In/Out)         Role / Interpretation
  repolens/models.py              26 callers / 0 imports    Foundational module: heavily relied upon across codebase
  repolens/engine.py              3 callers / 12 imports    Orchestrator: aggregates multiple internal subsystems
  repolens/discovery/language.py   9 callers / 1 imports     Foundational module: heavily relied upon across codebase
  repolens/discovery/scanner.py    4 callers / 3 imports     Structural nexus: high two-way connectivity
------------------------------------------------------------
RECOMMENDED READING ORDER
  #   File                  Category        Why Read This
  1   README.md             Documentation   Understand the project's purpose, scope, and user-facing design.
  2   pyproject.toml        Configuration   Inspect declared dependencies, build configuration, and runnable entry points.
  3   repolens/cli.py       Entry Point     Application starting point (CLI); trace execution kickoff and wiring.
  4   repolens/models.py    Core Component  Foundational module: heavily relied upon by other modules.
  5   repolens/engine.py    Core Component  Orchestrator: aggregates multiple internal subsystems.
  6   tests/test_cli.py     Verification    Observe expected inputs, outputs, error conditions, and test contracts.
------------------------------------------------------------
NEXT FILE TO READ: README.md
Understand the project's purpose, scope, and user-facing design.
------------------------------------------------------------

Commands

Contributor Onboarding: "Your First 30 Minutes"

Run repolens onboard to get an actionable walkthrough:

repolens onboard .

RepoLens v0.1.1 -- Contributor Onboarding: repolens
------------------------------------------------------------
YOUR FIRST 30 MINUTES
A structured, time-boxed roadmap to build a working mental model.

[0-3 min] Project Vision & Problem Statement
  Files to open: CONTRIBUTING.md, README.md
  What to understand: Understand why this project exists, who uses it, and its primary value proposition.

[3-7 min] Application Entry Point & Bootstrap
  Files to open: repolens/cli.py
  What to understand: Understand where execution starts, how arguments or configurations are parsed, and how the core coordinator is initialized.

[7-15 min] Core Workflow & Orchestration
  Files to open: repolens/models.py, repolens/engine.py
  What to understand: Understand the primary execution lifecycle, how data enters the pipeline, and how tasks are coordinated.

[15-22 min] Domain Models & Core Entities
  Files to open: repolens/models.py
  What to understand: Understand the primary data representations, contracts, and internal state structures.

[22-27 min] Supporting Infrastructure & Utilities
  Files to open: repolens/discovery/ignore.py, repolens/discovery/scanner.py
  What to understand: Understand foundational helper logic, external service adapters, and configuration loaders.

[27-30 min] Test Contracts & Behavior Verification
  Files to open: tests/test_architecture.py, tests/test_cli.py
  What to understand: Understand how behaviors are verified, how to run tests locally, and how to write a test before opening a PR.

Supported Languages

For unsupported languages (Go, Rust, Java, C++, C#, etc.), RepoLens provides file discovery, language metrics, and regex imports, accompanied by a transparent disclaimer: "Structural analysis is limited for this language."

Security & Privacy Model

• Zero Untrusted Code Execution: RepoLens treats every scanned repository as untrusted input. It never runs eval(), exec(), importlib, setup scripts, or package installers.
• Air-Gapped & Local-First: RepoLens initiates zero network connections. No telemetry, no pings, no cloud uploads.
• Resource Protection: Skips individual files $> 2$ MB for AST parsing and detects binary files via byte inspection.

Troubleshooting & FAQ

How do I ignore build artifacts, vendor directories, or minified files?

RepoLens automatically respects .gitignore rules in the repository root. To ignore additional paths or glob patterns, use the -i / --ignore flag (repeatable):

repolens . -i "build/**" -i "dist/**" -i "*.min.js"

To ignore .gitignore rules and scan everything, pass --no-gitignore.

Can I analyze a subproject within a monorepo?

Yes. Point RepoLens directly to any subdirectory:

repolens packages/backend
repolens onboard packages/backend

How does RepoLens handle large files and binaries?

• Files larger than 2 MB are automatically skipped for AST parsing to prevent high memory usage.
• Binary files and non-text assets are detected via null-byte inspection and skipped cleanly.
• Analysis runs entirely in memory without creating temporary cache files in your repository.

What happens on languages other than Python, JavaScript, and TypeScript?

For languages without dedicated AST parsers (such as Go, Rust, Java, C++, C#), RepoLens performs structural filesystem discovery, line counting, and regex-based import extraction, accompanied by the notice: "Structural analysis is limited for this language."

Can I run RepoLens in air-gapped or offline CI environments?

Yes. RepoLens initiates zero external network calls, zero telemetry, and zero LLM API requests. It is safe for private and air-gapped repositories.

Documentation

• Architecture Overview
• Competitive Research
• Known Limitations
• Project Roadmap
• Launch & Feedback Kit
• Security Policy
• Contributing Guide
• Code of Conduct

License

RepoLens is licensed under the MIT License.