Code Lantern

Self-hosted code analysis tool. Illuminate your codebase — analyze any project locally and visualize its architecture, dependencies, and complexity with AI-powered insights. Your code never leaves your machine.

What It Does

Point Code Lantern at any project folder on your machine and get:

• Architecture Maps — interactive tree diagrams of your file and function structure
• Dependency Graphs — visual maps of how files and functions connect, powered by Cytoscape.js
• Complexity Heatmaps — spot technical debt instantly with AST-based cyclomatic complexity scoring
• AI Deep Dive — click any function to get an AI-generated description of what it does, its inputs/outputs, and call relationships
• Project Summary — auto-generated overview with language breakdown, key metrics, and architecture insights

Everything runs locally in Docker. No accounts, no uploads to external servers, no rate limits.

Requirements

• Docker (Docker Desktop or Docker Engine)
• A free LLM API key for AI features (optional — analysis works without one)

Quick Start

git clone https://github.com/Tjindl/code-lantern.git
cd code-lantern
./run.sh

The script will:

1. Check Docker is running
2. Ask for a free API key if you don't have one (get one at console.groq.com)
3. Ask which project folder to analyze
4. Build and start the app
5. Open your browser to http://localhost:3000

That's it. Click "Analyze Mounted Folder" and explore.

To stop

./run.sh stop

To analyze a different project

./run.sh stop
./run.sh
# Enter a different folder path when prompted

Supported Languages

Code Lantern uses Tree-sitter for accurate AST parsing — the same technology used by GitHub, Neovim, and other major tools.

Language	Extensions
Python	.py
JavaScript	.js, .jsx
TypeScript	.ts, .tsx
Java	.java
C++	.cpp, .cc, .cxx, .h, .hpp
Rust	.rs

How It Works

Your Project Folder ──► Docker Mount (read-only) ──► Tree-sitter AST Parser ──► Analysis Results
                                                                                       │
                                                              ┌────────────────────────┘
                                                              ▼
                                                    React Frontend at :3000
                                                    ├── Architecture Tab (file tree + metrics)
                                                    ├── Dependencies Tab (interactive graph)
                                                    ├── Complexity Tab (heatmap)
                                                    └── Deep Dive Tab (AI function analysis)

Backend (FastAPI + Tree-sitter): Parses your code into an AST, extracts functions/classes/imports, calculates complexity metrics, and resolves call relationships. AI descriptions are generated on-demand using your own API key.

Frontend (React + Cytoscape.js): Renders interactive visualizations — dependency graphs you can filter, complexity heatmaps, and expandable function explorers.

Docker: Two containers (backend + frontend with Nginx proxy). Your project folder is mounted read-only — nothing is modified.

Configuration

The only config needed is an LLM API key in the root .env file. The ./run.sh script creates this for you, or you can do it manually:

# Set whichever key(s) you have — Code Lantern auto-detects and falls back between them
OPENAI_API_KEY=your_key_here        # OpenAI (platform.openai.com)
ANTHROPIC_API_KEY=your_key_here     # Anthropic Claude (console.anthropic.com)
GROQ_API_KEY=your_key_here          # Groq — fastest, free tier (console.groq.com)
GEMINI_API_KEY=your_key_here        # Google Gemini — free tier (aistudio.google.com)
OPENROUTER_API_KEY=your_key_here    # OpenRouter — 100+ models (openrouter.ai)
COHERE_API_KEY=your_key_here        # Cohere (dashboard.cohere.com)

Only one key is needed. If multiple are set, Code Lantern uses them as fallbacks in the order above.

Note: Architecture analysis, dependency graphs, and complexity metrics work without any API key. AI is only used for the Deep Dive function descriptions and project summaries.

Tech Stack

Layer	Technology
Frontend	React 18, Vite, Tailwind CSS, Cytoscape.js
Backend	FastAPI, Python 3.11+, Tree-sitter
AI	OpenAI, Anthropic, Groq, Gemini, OpenRouter, Cohere (automatic fallback)
Infrastructure	Docker, Nginx, Gunicorn + Uvicorn

Privacy

• Your code is mounted read-only — nothing is modified
• Analysis happens entirely on your machine — no external uploads
• AI calls send only individual function snippets to the LLM provider (when you click "Deep Dive")
• No accounts, no tracking, no telemetry
• No database — results are stored in-memory and on local disk only

Project Structure

code-lantern/
├── run.sh                      # One-command launcher
├── docker-compose.local.yml    # Local Docker config (2 services, no Redis)
├── .env                        # Your LLM API keys
├── backend/
│   ├── core/analyzer.py        # Tree-sitter AST analysis engine
│   ├── routes/analysis.py      # Analysis API endpoints
│   ├── routes/clone.py         # Local mount endpoint
│   ├── services/llm_provider.py # Multi-LLM fallback chain
│   └── services/rate_limiter.py # In-memory cache for AI results
└── frontend/
    ├── src/pages/              # UploadPage, ProjectDetailPage
    ├── src/components/         # Tabs, graphs, visualizations
    └── nginx.conf              # Reverse proxy config

Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to change.

# Development setup (without Docker)
cd backend && pip install -r requirements.txt && python main.py
cd frontend && npm install && npm run dev

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License — see LICENSE for details.