Quickstart

1. Install uv

Codemble runs through uv, which fetches the current release on demand and leaves nothing in your system Python. Install it once:

brew install uv

No Homebrew? Use the official installer — curl -LsSf https://astral.sh/uv/install.sh | sh on macOS and Linux, or powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" on Windows. If you would rather install Codemble permanently, pipx install codemble needs no uv at all.

2. Point it at your project

uvx codemble

Codemble opens your browser to an in-app picker: browse your home folders or reopen a recent project, then pick your Python, JavaScript, TypeScript, or mixed project. To skip the picker, pass a path directly:

codemble ./my-project

Codemble parses locally, chooses a free localhost port, and opens the galaxy. It keeps syntax-error files visible and labels unresolved calls instead of guessing. Use --no-open when you want to copy the printed URL yourself. Codemble reads supported source; it never runs your project or package scripts.

For a project above 1,000 supported source files, the picker offers the busiest-first subdirectories as buttons and accepts a typed path, right in the UI. From the CLI, select the scope yourself:

codemble --path ./my-project/src

3. Find Home

Your entrypoint system is marked Home — where execution starts. If the entrypoint is ambiguous, Codemble shows only parser-ranked candidates and you pick. The CLI equivalent is --entrypoint module.qualname; an unranked value is rejected rather than guessed.

4. Choose a layer, then zoom in

The header switches between two layers. Galaxy is the 3D view; its camera moves on rails through three levels. Map is a flat diagram with two tabs. Easy mode starts on the Map, Expert starts on the Galaxy, and you can switch at any time. In a mixed project, use the Focus control to show All, Python, JavaScript, or TypeScript. Focus and layer are only views: neither alters coordinates, progress, or graph evidence.

Galaxy level	What you see	What it’s for
Galaxy	Source modules as star systems, imports as routes	Orientation
System	Functions and classes in call-depth orbits — the inner ring runs first	Structure
Study	Real source with line numbers and a validated, cached explanation	Learning

Map tab	What you see	What it’s for
Architecture	Modules as boxes, grouped by folder, layered by import distance from Home	Seeing how the project fits together
Workflow	The call tree from your entrypoint, depth by depth	Seeing what runs first

No API key is required to inspect source and parser relationships. With a key, Codemble sends only the selected source context directly to your configured provider when you open Study; it does not run narration in the background.

5. Light it up

Pass a region’s checks and its stars light up — permanently. Watch your star chart grow as you meet new language concepts.

A fully lit galaxy means you understand your project. That’s the game.

Ready to help? Follow the ten-minute early-tester guide and report the first confusing moment in your own words.