Your codebase,
as a night sky.
One command turns any repository into a single, self-contained, interactive HTML file. Every file is a star — its brightness is how much the rest of the code depends on it — directories are constellations, and lines connect what imports what.
Quickstart
No config, no account, no server. One command, one file.
npx skyscope .
# -> skyscope.html — open it in any browser, share it, host it. Works offline.Or install it globally:
npm install -g skyscope
skyscope ~/code/my-app --out sky.html --title "my app @ v2.1"Programmatic use:
import { analyze, renderSky } from 'skyscope';
const model = analyze('/path/to/repo'); // pure data: stars, links, stats
const html = renderSky(model, { title: 'my app' });Gallery
Real skies, generated by one command each. Every image below is a screenshot of a real generated file — not a mockup.
Reading the sky
The map is not decoration — it is a legible architectural diagram.
| In the sky | In your repo |
|---|---|
| a star | a file |
| star brightness | how much the rest of the code imports it (PageRank) |
| star color | language (JS, TS, Python, Go, Rust, …) |
| a constellation | a top-level directory |
| a line between stars | an import |
The brightest stars are your load-bearing files. A sky dominated by one giant star is a monolith. A tight bright cluster with a dim halo is a well-factored core with a thin shell. You can read the architecture from across the room.
Interactions: drag to pan, scroll/pinch to zoom, hover for paths, click a star for its dossier (size, tokens, imports, imported-by, git recency), / to search, 0 to reset, legend chips to filter languages.
How it works
- Walk.gitignore-aware traversal; vendored code, lockfiles and binaries skipped.
- Parseimport extraction with regexes across a dozen languages — no tree-sitter, no native builds.
- RankPageRank over the import graph: brightness is importance-by-dependency, not file size.
- Placeconstellations on a ring, each star on a deterministic orbit hashed from its path. Same repo, same sky — every time.
- Renderone self-contained HTML file: canvas star field with glow, twinkle and diffraction spikes, plus a full pan/zoom/search UI in vanilla JS.
One file
No remote assets, no fonts, no frameworks. Email it, drop it in a PR, host it anywhere.
Deterministic
Identical input yields an identical sky. Two people, same commit, same picture.
Private by construction
Your source never leaves the file. The sky embeds paths and structure — never file contents.
CLI reference
| Flag | Description | Default |
|---|---|---|
[path] | Repository to map | . |
-o, --out <file> | Output HTML file | skyscope.html |
-t, --title <text> | Header title | repo name |
--no-git | Skip git recency data | off |
--max-files <n> | Cap files rendered | 4000 |
Exit codes: 0 ok · 1 runtime error · 2 usage error.
FAQ
Does it send my code anywhere?
No. The CLI reads files locally and writes one HTML file. The file has no remote assets and makes no network requests. It embeds file paths and structure — never file contents.
Why are my test files dim?
Tests are usually imported by nothing, so PageRank gives them near-zero. That's the point: brightness is importance-by-dependency, not activity.
Is the output reproducible?
Yes. Layout positions are derived from hashes of file paths, not physics or randomness. Determinism is enforced by tests and by CI.
Can I change the colors?
Yes — one map at the top of src/render.js (LANG_COLORS).
The brightness curve lives in src/engine.js (magnitudeOf).
Which Node versions are supported?
Node.js 18 and later. CI runs the suite on 18, 20 and 22.