Code Cosmos

Explore your codebase as an interactive 3D universe.

Files become planets. Folders become stars. Dependencies become constellation lines.

What is Code Cosmos?

Large codebases are hard to understand at a glance. After a certain size, no amount of file-tree browsing gives you a real sense of how pieces connect. Code Cosmos maps your entire repository into a navigable 3D space — folders orbit as stars, files orbit those stars as planets, and every import statement becomes a visible line between them.

It lives in your VS Code sidebar as a persistent panel. It is not a replacement for your editor — it is a way to understand before you code. See the shape of a project you just cloned. Spot tightly coupled clusters before you refactor. Trace a bug across file boundaries visually.

Demo

📹 Videos below show individual features. Each is recorded on a real codebase.

Overview — Your Codebase as a Universe

Navigation — Orbit, Zoom, Fly

Plain click on any planet highlights it. Alt+click flies the camera to it. F enters Pilot Mode — fly freely with WASD.

Search — Jump to Any File Instantly

Press / or Ctrl+F to open the search bar. Type any filename. Use ↑↓ arrow keys to step through results and Enter to fly there.

Dependency Visualization — See What Connects to What

Import statements parsed across 13 languages. Toggle layers on and off individually. Circular dependencies pulse red automatically.

Focus Mode — Isolate a File's Connections

Ctrl+click any planet to enter Focus Mode. Everything else dims. Only that file's direct imports and importers stay visible. A popup lets you open the file or keep exploring.

Path Trace — Find the Route Between Any Two Files

Shift+click two planets to select them. Code Cosmos finds the shortest dependency path between them using BFS and draws it in gold. If there's no direct path it finds the closest common ancestor.

Git Heatmap — See What's Hot

Enable the git heatmap to colour-code your universe by commit activity. Frequently changed files shift toward orange and white-hot. Untouched files sit cool and blue. Uncommitted changes appear as glowing animated rings.

Camera Bookmarks — Save Your Favourite Views

Click + Save View in the top-right to name and save your current camera position. Return with one click or Ctrl+1–5. Bookmarks persist in your .cosmos file per project.

Spacecraft Mode — Fly Through Your Code

Press F to unlock the mouse and fly freely through the universe.

Settings & Spacing — Customise the Cosmos

Press G or click the ⚙️ button. Adjust the Spacing slider to spread planets and folders further apart if things feel cluttered. Choose from three presets: Clean, Full Detail, Performance.

Installation

Search for Code Cosmos in the VS Code Extensions panel (Ctrl+Shift+X) and click Install.

Or install from the command line:

code --install-extension Yashwanth.code-cosmos

Requirements: VS Code 1.120.0 or higher. No additional dependencies required.

Getting Started

1. Open any project folder in VS Code (File → Open Folder)
2. Click the Code Cosmos icon in the Activity Bar (left sidebar)
3. The universe builds automatically — a progress bar shows scan status
4. First launch shows an interactive guide. Press ? anytime to bring it back.

Tip: For large projects (500+ files) Code Cosmos will offer to enable Performance Mode before rendering. This keeps the frame rate smooth on any hardware.

How the Universe Maps to Your Code

Keyboard Shortcuts

Settings Reference

Open with G or the ⚙️ button. All settings are saved to your .cosmos file per project.

Layout

Dependency Lines

Animations

Overlays

Rendering

Presets: Clean (minimal), Full Detail (everything on), Performance (optimised for large repos).

Excluding Files and Folders

Create a .cosmosignore file in your project root. Uses the same glob syntax as .gitignore.

# .cosmosignore

# Already excluded by default:
# node_modules, .git, dist, build, out, .next, __pycache__

# Add your own:
coverage
**/*.test.ts
**/*.spec.js
**/__mocks__
*.min.js
*.d.ts

The following are always excluded automatically: node_modules, .git, dist, build, out, .next, __pycache__, lock files, and Code Cosmos's own .cosmos / .cosmos.cache files.

The .cosmos File

Code Cosmos creates two files in each project root:

.cosmos — your personal settings for this project. Stores camera bookmarks, toggle states, and the spacing preference. Always gitignored automatically. Never shared.

.cosmos.cache — a cache of the parsed dependency graph and git data. Makes subsequent opens near-instant by skipping AST parsing and git log when no files have changed. Regenerated automatically when files are added, removed, or modified. Safe to delete — it will be rebuilt on next open.

Both files are added to .gitignore automatically on first use.

Supported Languages

Files in unsupported formats still appear as planets — they just have no dependency lines.

Performance

Code Cosmos is designed to handle real projects, not just small demos.

Performance Mode uses GPU instanced mesh rendering — all planets drawn in a single draw call, dramatically reducing GPU overhead on large repos.

The cache system computes a lightweight fingerprint (file sizes, modification times, git HEAD) on every open. If nothing has changed, the expensive work (AST parsing and git log) is skipped entirely. Only a force-refresh (Ctrl+U) bypasses the cache.

Known Limitations

• Monorepos — each workspace folder renders as a separate galaxy. Cross-package dependencies between workspace roots are not yet visualised.
• Dynamic imports — import() expressions and require() calls with variable paths cannot be statically resolved and will not appear as dependency lines.
• Very large repos (3,000+ files) — even with Performance Mode, rendering and parsing will be slower on lower-end hardware. Excluding generated files and test fixtures via .cosmosignore helps significantly.

Roadmap

See the open issues for the full list.

Contributing

Contributions are welcome. The codebase is TypeScript throughout — VS Code extension host on the Node.js side, Three.js WebView on the render side. See CONTRIBUTING.md for architecture overview and PR guidelines.

License

MIT — see LICENSE for details.