Quickstart

1. Install uv

Codemble runs through uv, which fetches the pinned packaged release 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==0.22.0 needs no uv at all.

2. Point it at your project

uvx --from codemble==0.22.0 codemble

Codemble opens your browser to an in-app picker: browse your home folders or reopen a recent project, then pick it. Codemble reads Python, JavaScript, TypeScript, Go, Java, Rust, C#, Ruby, PHP, and mixtures of those languages. To skip the picker, pass a path directly:

uvx --from codemble==0.22.0 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. Keep that terminal process open while you explore; press Ctrl-C there to stop the local server when you are done.

For a project above 5,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:

uvx --from codemble==0.22.0 codemble --path ./my-project/src

3. Find Home

Your entrypoint system is marked Home — where execution starts. On most projects Codemble settles it without asking. A candidate that lives in a test folder (tests/, test/, testing/, __tests__/, spec/), or is named like one (test_*, *_test, conftest), ranks below your project’s own code — so a repository whose fixtures carry their own main() no longer buries the real entrypoint among them.

That rule reads the file’s path, so it holds for every language Codemble reads, not just the one whose test convention you happen to use. It has to: a Go, Java, Rust or C# fixture under tests/ usually carries an ordinary, unmarked main() that no language’s own test marker (#[test], @Test, [Fact]) would ever catch. Test candidates are demoted, not removed: a project that is a test suite still gets a Home, and the rank you are shown is the real one.

If your project declares a program in its own packaging manifest — a [project.scripts] or [project.gui-scripts] entry in pyproject.toml — that declaration settles Home ahead of every other candidate. It is the strongest evidence there is: the manifest states which module the installed command actually runs, where a __main__ guard only says a file can be run, and a repository full of maintenance scripts usually has several of those. A declared module the parser never saw contributes nothing, and a missing or malformed manifest is ignored rather than treated as an error. As with the test rule, this biases only the ordering — the rank you are shown stays the parser’s own.

When candidates genuinely tie for best rank, Codemble asks rather than guessing. It offers only parser-ranked candidates; the CLI equivalent is --entrypoint module.qualname, and an unranked value is rejected.

The picker states how many candidates there are and groups them by the top-level folder each one really lives in. The best-ranked group opens first, and Explore without Home stays on screen however long the list is: every system, check, explanation and lens note works without a Home.

4. Choose your launch, then zoom in

On the first run, Explore freely opens the complete Galaxy immediately; Take a first flight tours Home and the modules it directly imports. If Home needs calibration, that guided intent waits for the learner’s honest selection. At any stop, Land and learn opens a parser-owned structure; after reading its Easy or Expert landing brief, choose Prove understanding to begin the existing graph-derived quiz. Choose Easy for plain language or Expert for parser detail. This is a presentation choice, not a different graph, and you can change it in the header or on any landing.

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. Both first-run launch choices enter the Galaxy; the Map remains one explicit switch away, and you can move between layers at any time. In a mixed project the Focus control offers All plus one button per language actually present, with its system count. 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 visible, colourful star systems; imports as routes	Orientation
Solar system	The module anchor as its Sun; named functions and classes as language-styled worlds in parser-owned call placement; certain and possible imports as neighbouring systems	Structure and continuation
Study	A landing brief, parser-owned evidence from Home as far as it reaches, a visible proof break and separate possible frontier when it does not, real source, integrated Impact and Connections, and optional grounded narration	Learning one feature without inventing a route

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

Easy mode labels the same surfaces in plainer words — the layer is Diagram and the tabs are How it fits together and What runs first. The views are identical; only the wording follows the audience.

Click a box and the Map offers both halves of a step: Read the source opens that module’s feature journey, real source, lens notes and relationships without leaving the layer, and Prove understanding starts its checks. Escape steps back a level, as it does in the Galaxy.

On a compact screen the Map opens at readable 100%, centred on Home or the selected parser-backed target. Use Fit when you want the whole diagram as an overview, and press the percentage button to return to 100%. Codemble keeps your zoom and pan when fresh Map data arrives or you briefly switch layers.

Landing on a function or class first opens its model-free brief. When role evidence exists, Easy explains that parser-known purpose in plain language and Expert names the exact role rule. Without role evidence, both say purpose is unknown rather than guessing. Both show inbound and outbound graph connections so the next jump stays grounded in the code.

No API key is required to follow the journey or inspect source, parser relationships, Lens notes, or checks. Easy shows one cited current step; Expert keeps that step and adds its parser-rule evidence. The selected feature’s Impact, dependencies, and bounded verification candidates remain clearly separate from that moving step. 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. Model-free Impact lists show what a change would reach and what it depends on. When proof cannot reach the selected feature, the journey stops before a separate possible frontier instead of turning that evidence into fact.

5. Study, then light it up

Open one system, read a real structure, then choose Prove understanding. Pass the region’s graph-derived checks and its stars light up—permanently. Watch your star chart grow as you meet language concepts.

Codemble separately charts the systems you visit and keeps their routes drawn. That trail records where you have been; it never substitutes for the check that records understanding.

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.