ruth-code 0.1.7

Interactive codebase topology visualizer — Google Maps for your repo

Ruth

Google Maps for your codebase.
Navigate, understand, and explore any codebase as an interactive visual map.

---

Ruth parses your codebase, builds a full dependency graph, auto-detects architectural landmarks, overlays quality metrics, and renders everything as a live, explorable map in the browser. Think of it as satellite view for software — zoom in on any file, trace dependency paths between modules, and spot architectural patterns at a glance.

Install

pip install ruth-code

Quick Start

cd your-project
pip install ruth-code
ruth serve

Your browser opens to http://localhost:4150 with a live topology map of your codebase.

Features

Landmarks & Points of Interest

Ruth auto-detects the architecturally significant files in your project and pins them on the map:

Landmark	What it means	How it's detected
Entry Point	Where execution begins	main.py, index.ts, cli.py, app.py, etc.
Orchestrator	Wires your app together	High out-degree — imports many other modules
Hub	Core dependency everyone relies on	High in-degree — imported by many modules
Island	Disconnected file, possibly dead code	Zero in-degree and zero out-degree

Dependency Path Tracing

Click two nodes to trace the import chain between them — like getting directions on a map. The full dependency route highlights across the graph so you can see exactly how module A reaches module Z.

Traffic Lanes

Import edges scale in thickness based on connection weight. Heavily coupled modules get visually thicker lanes, making it easy to spot tight coupling and high-traffic corridors in your architecture.

Code Preview

Click any node and hit View Code to instantly preview the source file — line numbers, syntax, and a copy button. No need to leave the map.

Overlays

Switch between views like map layers:

Overlay	What it shows
Complexity	Cyclomatic complexity heatmap (green to red)
Security	Vulnerability overlay via Semgrep/OSV
Coverage	Test coverage mapping from lcov/coverage.json

Live Updates

WebSocket-powered real-time graph. Edit a file, save it, and watch the map update.

Multi-Language

Full parsing support for Python, TypeScript, JavaScript, Rust, Go, Java, Ruby, and C/C++.

Commands

ruth serve

Start the visualization dashboard.

ruth serve                        # analyze current directory
ruth serve --port 8080            # custom port
ruth serve --no-open              # don't auto-open browser

If the port is taken, Ruth automatically finds the next available one.

ruth analyze

Export the dependency graph as JSON for CI pipelines or custom tooling.

ruth analyze -o graph.json         # export current directory
ruth analyze -g function           # function-level granularity
ruth analyze -g class              # class-level granularity

ruth scan

Quick project scan — file counts, line counts, and language breakdown without building the full graph.

ruth scan

Keyboard Shortcuts

Key	Action
Cmd + K	Command palette — search and jump to any node
/	Focus the search filter

How It Works

your-project/
    │
    ▼
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Discovery │───▶│  Parser  │───▶│  Graph   │───▶│ Frontend │
│           │    │          │    │  Engine  │    │          │
│ Scan files│    │ tree-    │    │ Nodes,   │    │ React    │
│ by lang   │    │ sitter   │    │ edges,   │    │ Flow +   │
│           │    │ AST      │    │ roles,   │    │ WebSocket│
│           │    │ parsing  │    │ overlays │    │          │
└──────────┘    └──────────┘    └──────────┘    └──────────┘

1. Discovery — Walks your project tree, identifies source files by language, respects .gitignore
2. Parsing — Extracts imports, exports, classes, and functions using tree-sitter ASTs
3. Graph Engine — Builds the dependency graph, detects landmarks via topology analysis, accumulates edge weights
4. Frontend — Renders the interactive map with React Flow, dagre layout, and real-time WebSocket updates

API

Ruth exposes a local REST API alongside the dashboard:

Endpoint	Description
GET /api/health	Server status and connection count
GET /api/graph	Full dependency graph as JSON
GET /api/file?path=<relative-path>	Source file contents (path-traversal protected)
WS /ws	WebSocket for real-time graph updates

Development

# Clone
git clone https://github.com/kossisoroyce/ruth.git
cd ruth

# Backend
pip install -e ".[dev]"

# Frontend
cd frontend
npm install
npm run dev

The dev server proxies API requests to the Python backend. Run ruth serve in one terminal and npm run dev in another for hot-reload frontend development.

Requirements

• Python 3.10+
• No runtime dependencies beyond pip — the frontend ships pre-built in the wheel

License

Proprietary — Electric Sheep Africa

Personal, non-commercial use only. See LICENSE for details.