RepoLens

Understand how a codebase works.

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

⚡ 30-Second Quickstart

# 1. Install via pip (official PyPI package)
pip install repolens-toolkit

# 2. Understand any repository immediately
repolens /path/to/project

# 3. Get a structured contributor roadmap
repolens onboard /path/to/project

Package Name Note: The distribution package is repolens-toolkit on PyPI, and installs the runnable command repolens into your environment.

The Core Problem

"I just cloned this unfamiliar repository. Where do I even start?"

When software engineers, open-source contributors, tech leads, and students approach a new codebase, they are forced to open dozens of files manually, guess where execution starts, and piece together the mental model from scratch.

Existing developer tools fail to solve this:

Linters & SAST tools (ruff, eslint, sonarqube) point out syntax rules and security vulnerabilities, but never explain what the project actually does or how modules connect.
Raw dependency dumpers (madge, pydeps) output tangled, unreadable spiderwebs of 300+ nodes without architectural context or hierarchy.
Architecture linters (import-linter, archunit) require you to already understand the architecture before writing the enforcement rules.
LLM context dumpers (repomix, AI prompt stuffers) burn thousands of tokens, hallucinate relationships, and send proprietary IP to external servers.

RepoLens answers the essential onboarding questions using deterministic repository evidence:

🚀 Where does this application start? (CLI entry points, web servers, background workers)
🗺️ What are the foundational modules? (Central components vs. leaf utilities)
🏛️ What is the high-level architecture? (CLI $\to$ Services $\to$ Storage $\to$ Tests)
🧭 In what order should I read the code? (A progressive, rationale-backed sequence)
⏱️ What should I understand in my first 30 minutes? (Time-boxed onboarding roadmap)
🤖 Can I feed a clean repo map to AI agents? (Structured JSON and Mermaid diagrams)

Architecture at a Glance

RepoLens automatically infers modular architecture and generates native Mermaid dependency diagrams:

graph TD
    CLI["repolens/cli.py<br/><b>CLI Interface & Entry Point</b>"] --> Engine["repolens/engine.py<br/><b>Core Analysis Orchestrator</b>"]
    Engine --> Scanner["repolens/discovery/scanner.py<br/><b>Filesystem & Ignore Filters</b>"]
    Engine --> PyAnalyzer["repolens/analyzers/python.py<br/><b>Python AST Extraction</b>"]
    Engine --> JsAnalyzer["repolens/analyzers/javascript.py<br/><b>Tree-Sitter JS/TS Extraction</b>"]
    Engine --> Graph["repolens/graph/builder.py<br/><b>Module Dependency Graph</b>"]
    Engine --> Onboarding["repolens/onboarding/planner.py<br/><b>Onboarding Roadmap Engine</b>"]
    Engine --> Models["repolens/models.py<br/><b>Domain Contracts & Types</b>"]
    Scanner --> Models
    PyAnalyzer --> Models
    JsAnalyzer --> Models
    Graph --> Models
    Onboarding --> Models

Key Capabilities

1. Contributor Onboarding: "Your First 30 Minutes"

Run repolens onboard to get an actionable, time-boxed walkthrough designed to build a working mental model in half an hour:

repolens onboard .

RepoLens v0.1.2 -- Contributor Onboarding: my-project
------------------------------------------------------------
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: README.md, CONTRIBUTING.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: mycli/main.py
  What to understand: Understand where execution starts, how arguments are parsed, and how the coordinator initializes.

[7-15 min] Core Workflow & Orchestration
  Files to open: mycli/processor.py, mycli/engine.py
  What to understand: Understand the primary execution lifecycle, data pipelines, and internal task coordination.

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

[22-27 min] Supporting Infrastructure & Utilities
  Files to open: mycli/utils.py, mycli/config.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_processor.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.

2. Structural Hotspots & Coupling Analysis

Connectivity is an indicator of architectural importance, not a code defect. RepoLens categorizes high-connectivity modules into actionable roles:

repolens hotspots .

RepoLens v0.1.2 -- Structural Code Hotspots
------------------------------------------------------------------------------------------
  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/scanner.py  4 callers / 3 imports     Structural nexus: high two-way connectivity
------------------------------------------------------------------------------------------

3. Progressive Reading Order

Rather than opening files at random, RepoLens computes a rational, sequential reading list:

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.

4. Visual Dependency Maps (`Mermaid` & `DOT`)

Export visual dependency graphs directly into your documentation or terminal:

# Generate Mermaid diagram for GitHub/Notion documentation
repolens map . > ARCHITECTURE.md

# Generate Graphviz DOT format for SVG/PNG rendering
repolens map . --format dot | dot -Tpng -o dependencies.png

5. Machine-Readable JSON for AI Coding Agents & CI/CD

Dramatically reduce context window overhead compared to dumping raw source files into LLM prompts. Feed clean, deterministic structural metadata to AI agents (Claude, Cursor, Copilot, Antigravity):

repolens report . --format json > repo-map.json

{
  "project_name": "repolens",
  "root_path": "/path/to/repolens",
  "languages": { "Python": 30 },
  "entry_points": [
    {
      "path": "repolens/cli.py",
      "category": "cli",
      "confidence": "high",
      "evidence": ["Configured as console script 'repolens' in pyproject.toml"]
    }
  ],
  "architecture_layers": [
    { "layer_name": "CLI / Interface", "confidence": "medium", "files": ["repolens/cli.py"] }
  ]
}

📦 Installation Options

Standard Installation

# Recommended: Install from PyPI
pip install repolens-toolkit

# Using pipx (isolated application environment)
pipx install repolens-toolkit

# Using uv
uv pip install repolens-toolkit

Direct Release Download

# Install directly from the verified GitHub Release v0.1.1 asset
pip install https://github.com/deswanth12/repolens/releases/download/v0.1.1/repolens-0.1.1-py3-none-any.whl

Note: On PyPI, the package is distributed as repolens-toolkit (installing the repolens CLI). On GitHub Releases v0.1.1, the attached standalone wheel artifact is repolens-0.1.1-py3-none-any.whl.

From Source

# Install latest development version from Git
pip install git+https://github.com/deswanth12/repolens.git

# Local editable installation
git clone https://github.com/deswanth12/repolens.git
cd repolens
pip install -e ".[dev]"

🛠️ CLI Command Reference

Command	Usage	Description
`repolens`	`repolens [PATH]`	Comprehensive codebase overview (entry points, layers, hotspots, reading order).
`repolens onboard`	`repolens onboard [PATH]`	Generate the "Your First 30 Minutes" structured contributor guide.
`repolens hotspots`	`repolens hotspots [PATH]`	Inspect module connectivity table (callers, dependencies, structural role).
`repolens map`	`repolens map [PATH] [--format mermaid\|dot\|json]`	Output module dependency graph for visualization.
`repolens explain`	`repolens explain <FILE> [--repo PATH]`	Deep-dive into a specific file: extracted symbols, incoming callers, and dependencies.
`repolens scan`	`repolens scan [PATH]`	Fast file discovery pass with language distribution and category breakdown.
`repolens report`	`repolens report [PATH] [--format text\|json]`	Complete codebase understanding report.

Global Options

--json: Output machine-readable JSON across all commands.
-i, --ignore <pattern>: Add custom glob ignore patterns (e.g. -i "legacy/**"). Can be specified multiple times.
--no-gitignore: Bypass .gitignore rules and include ignored files in analysis.
--version: Display version information and exit.
--help: Show CLI help and options.

🧩 Common Recipes

# 1. Quick overview of a new repo in your terminal
repolens .

# 2. Onboard a new team member to a monorepo service
repolens onboard packages/backend

# 3. Export dependency architecture to documentation
repolens map . --format mermaid >> docs/ARCHITECTURE.md

# 4. Investigate why a core module is frequently touched
repolens explain repolens/engine.py

# 5. Filter out third-party or vendored paths
repolens . -i "vendor/**" -i "external/**" -i "fixtures/**"

# 6. Pipe clean architecture metadata to an LLM script or CI runner
repolens report . --format json | jq '.entry_points'

🌐 Supported Languages & Analysis Depth

Language	AST Symbol Extraction	Import & Dependency Resolution	Entry-Point Detection	Analysis Mode
Python	✅ Native AST (`ast` stdlib)	✅ Relative & absolute imports	✅ High (`__main__`, CLI frameworks, `pyproject.toml`)	`ast`
JavaScript	✅ Tree-Sitter AST	✅ ES Modules & CommonJS (`require`)	✅ High (`package.json`, Express/Fastify/Next.js)	`tree_sitter`
TypeScript / TSX	✅ Tree-Sitter AST	✅ ES Modules & path aliases	✅ High (`package.json`, framework entry points)	`tree_sitter`
Go	⚠️ Structural Fallback	✅ Multi-line & single import extraction	✅ High (`func main()`, `package main`)	`regex_fallback`
Rust	⚠️ Structural Fallback	✅ `use` declaration extraction	✅ High (`fn main()`, `main.rs`)	`regex_fallback`
Java	⚠️ Structural Fallback	✅ `import` statement extraction	✅ High (`Main.java`, `main()` methods)	`regex_fallback`
C / C++	⚠️ Structural Fallback	✅ `#include` header extraction	✅ High (`main()` function, `main.c/cpp`)	`regex_fallback`
Other Languages	⚠️ Structural Fallback	⚠️ Regex import pattern matching	⚠️ Filename heuristics	`regex_fallback`

For languages analyzed via fallback, RepoLens surfaces language statistics, imports, and entry points while transparently setting analysis_mode="regex_fallback" and noting: "Structural analysis is limited for this language."

🔒 Security & Privacy Guarantees

RepoLens was engineered with strict security boundaries and verified against real-world repositories:

🛡️ Zero Runtime Code Execution: RepoLens parses files strictly as static text using AST grammars. It never invokes eval(), exec(), __import__(), setup scripts, or project test suites. Untrusted repository code cannot execute on your machine.
📴 100% Offline & Private: Zero telemetry, zero phone-home pings, zero cloud analytics, and zero external API dependencies. RepoLens runs cleanly in air-gapped environments.
🚷 Symlink & Path Traversal Containment: Canonical symlink targets are resolved (resolve(strict=True)). Symlinks pointing outside the repository root and directory symlinks are safely skipped.
⚡ Resource Protection: Files larger than 2 MiB (2,097,152 bytes) and binary files are skipped from line counting and AST parsing to prevent memory exhaustion.
🔄 Iterative Dependency Traversal: Cycle detection uses heap-allocated iterative DFS, eliminating RecursionError crashes even on deep cyclic graphs.
🔐 Secret & Sensitive File Protection: Automatically excludes .env, *.pem, *.key, id_rsa, and sensitive credential files from inspection.
📋 Responsible Disclosure: See our Security Policy for vulnerability reporting guidelines and response timelines.

❓ Frequently Asked Questions (FAQ)

Why is the PyPI package named repolens-toolkit?

The PyPI distribution is named repolens-toolkit to avoid namespace conflicts, while the binary installed in your environment remains repolens. You install with pip install repolens-toolkit and run commands as repolens ..

Does RepoLens execute any code from the repository?

No. RepoLens uses purely static AST parsing (Python's built-in ast module and Tree-Sitter for JavaScript/TypeScript). It never imports or executes scanned repository code.

How do I handle monorepos or subpackages?

RepoLens works seamlessly with subpaths. Simply pass the path to the subpackage:

repolens services/auth
repolens onboard services/billing

Can I integrate RepoLens into GitHub Actions?

Yes! You can run RepoLens on pull requests to ensure architecture documentation remains updated or generate onboarding summaries for new contributors:

- name: Analyze repository with RepoLens
  run: |
    pip install repolens-toolkit
    repolens onboard .

Does RepoLens send data to OpenAI, Anthropic, or external servers?

Never. RepoLens requires no API keys, makes no network calls, and collects zero telemetry. Everything runs 100% locally on your machine.

📚 Project Documentation

Architecture Overview — Comprehensive design and subsystem breakdowns.
Launch Kit — Feature highlights, messaging, and quick demos.
Competitive Research — Detailed comparison with existing tools.
Known Limitations — Transparent boundaries and current scope.
Roadmap — Planned language parsers and future features.
Contributing Guide — How to develop, test, and contribute.
Security Policy — Vulnerability reporting and security models.
Code of Conduct — Community standards.

🤝 Contributing & Community

RepoLens is built in the open, and we welcome contributions from everyone! Whether you are fixing a typo, adding a language analyzer, improving documentation, or optimizing performance, your help is appreciated.

🚀 New to RepoLens? Check out our curated Good First Issues designed to help newcomers get started with guided mentorship.
📖 Contributor Guide: Read CONTRIBUTING.md for full development environment setup, architecture subsystem maps, and pull request testing instructions.
💡 Feature Ideas & Bug Reports: Have a suggestion or encountered an issue? Open an issue on our GitHub Issue Tracker.
📜 Community Standards: We follow the Contributor Covenant. Please review our Code of Conduct.

📄 License

RepoLens is open-source software licensed under the MIT License.

Navigation Menu

Repository navigation

About

Repository files navigation

RepoLens

⚡ 30-Second Quickstart

The Core Problem

Architecture at a Glance

Key Capabilities

1. Contributor Onboarding: "Your First 30 Minutes"

2. Structural Hotspots & Coupling Analysis

3. Progressive Reading Order

4. Visual Dependency Maps (`Mermaid` & `DOT`)

5. Machine-Readable JSON for AI Coding Agents & CI/CD

📦 Installation Options

Standard Installation

Direct Release Download

From Source

🛠️ CLI Command Reference

Global Options

🧩 Common Recipes

🌐 Supported Languages & Analysis Depth

🔒 Security & Privacy Guarantees

❓ Frequently Asked Questions (FAQ)

📚 Project Documentation

🤝 Contributing & Community

📄 License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
repolens		repolens
samples/pentrare		samples/pentrare
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

RepoLens

⚡ 30-Second Quickstart

The Core Problem

Architecture at a Glance

Key Capabilities

1. Contributor Onboarding: "Your First 30 Minutes"

2. Structural Hotspots & Coupling Analysis

3. Progressive Reading Order

4. Visual Dependency Maps (Mermaid & DOT)

5. Machine-Readable JSON for AI Coding Agents & CI/CD

📦 Installation Options

Standard Installation

Direct Release Download

From Source

🛠️ CLI Command Reference

Global Options

🧩 Common Recipes

🌐 Supported Languages & Analysis Depth

🔒 Security & Privacy Guarantees

❓ Frequently Asked Questions (FAQ)

📚 Project Documentation

🤝 Contributing & Community

📄 License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

4. Visual Dependency Maps (`Mermaid` & `DOT`)