Codemble

Explore the code AI left behind.

Codemble reads a project on your machine and turns its real structure into a galaxy you can explore or a diagram you can follow. Study any file, see what a change reaches, and light only what you prove you understand.

Start here · See the loop · Trust boundary · Website · Docs

_{Codemble v0.16.0 · every module is represented before the first lesson · labels declutter automatically and every parser-owned name is available on hover · visiting charts a route; passing checks lights a system amber}

Important

The screen above and the packaged app are both v0.16.0. The PyPI release maps Python, JavaScript, TypeScript, Go, Java, Rust, C#, and mixed projects; it includes the explorer trail, parser-owned Impact, and automatic Home selection. The pinned command and direct downloads below resolve to the same verified release.

Start here

Run v0.16.0 — recommended

Install uv once, then open Codemble whenever you need it:

	Step	Command
	Install uv — a clean Python app runner	brew install uv
	Open this release — pick a project in the browser	uvx --from codemble==0.16.0 codemble

No Homebrew? Use uv's official installer, or install permanently with pipx install codemble==0.16.0 and run codemble. Pass a folder to skip the project picker: uvx --from codemble==0.16.0 codemble ./my-project. Use the shorter uvx codemble when you intentionally want whatever release is newest on PyPI.

Wheel · Source archive · SHA256 digests · Release notes

Build the same v0.16.0 app from source

Use this route when you want an editable checkout:

git clone --branch v0.16.0 --depth 1 https://github.com/udhawan97/Codemble.git
cd Codemble
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install -e .
codemble

Read the full build guide for the verification commands.

What Codemble does

	Plain-English answer
	Explore first. Every module is represented and coloured on the first frame. Labels rank and declutter; hover reveals every parser-owned name. Visiting leaves a local trail without claiming understanding.
	See how it fits together. Switch between a 3D galaxy, an import architecture map, and the call workflow from Home.
	Know what a change touches. Impact traces what depends on a structure and what it depends on, with real file locations and certainty labels.
	Prove what you understand. Graph-derived checks—not a narrator—are the only way to light a system amber.
	Keep the project local. Parsing, maps, source, Impact, checks, and progress stay on your machine.
	Read mixed projects. Python, JavaScript, TypeScript, Go, Java, Rust, and C# share one graph and one honesty contract.

Codemble reads supported source. It does not run your app, package scripts, compilers, or tests.

See the learning loop

01 · Explore	02 · Map
Fly to a module. Its routes remain charted.	Follow real imports from Home; unreachable modules are counted, not erased.

03 · Inspect	04 · Prove
See what a structure controls and what can break it—no model needed.	Pass checks drawn from the graph; only then does the system turn amber.

One graph, two useful views

View	What it shows	When it helps
Galaxy	Modules as systems and structures as worlds	Learn the shape of the whole project
Map · Architecture	Modules grouped by folder and layered by proven imports from Home	See how parts fit together
Map · Workflow	Certain calls from the selected entrypoint, depth by depth	See what runs first
Study	Real source, Impact, relationships, Lens notes, and optional narration	Understand one structure in context

The Map is plain SVG, so it remains usable on a machine that cannot render the WebGL galaxy. Easy mode uses plainer labels and lower density; Expert mode shows more graph detail. Neither changes the underlying evidence or scoring.

What Codemble can prove

Codemble is built for readers who may not yet spot a confident mistake, so its limits are part of the interface:

• Nodes, routes, language concepts, and Home candidates come from parsers.
• Unproven relationships are labelled possible and drawn differently on both the galaxy and the map.
• Impact and check answers come from the graph and need no API key.
• Unsupported or broken source is counted and named instead of silently hidden.
• Charting records where you went. Only a passed check records understanding.
• Changing a file re-dims only that file's proof; the rest of your progress stays.

Read the correctness contract. A wrong node, edge, citation, Lens note, or check answer is a highest-severity bug—report it.

Local-first, with an explicit AI boundary

Stays on your machine	Leaves only when Study opens with a configured narrator
Project discovery and parsing	A bounded Study excerpt sent to your configured narrator
Graph, maps, source, structural summary, Impact, Lens, and checks	A request triggered when you open Study
Progress and narration cache in ~/.codemble/	No background requests
Narration too, when you choose local Ollama	No accounts, telemetry, or Codemble cloud

No model? Everything except optional prose narration remains available. To add cloud narration, set ANTHROPIC_API_KEY or OPENAI_API_KEY. To keep narration local as well:

ollama pull gemma4:12b
export CODEMBLE_PROVIDER=ollama
export CODEMBLE_OLLAMA_MODEL=gemma4:12b

Project and rendering limits

• Supported languages: .py, .js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts, .go, .java, .rs, and .cs.
• Scale: above roughly 1,000 supported files, choose a subdirectory in the picker or pass --path ./project/src.
• Ambiguous Home: choose a parser-ranked candidate in the app or pass --entrypoint NODE_ID.
• Broken source: safe partial evidence stays visible; Codemble never invents the missing structure.
• Rendering: the galaxy needs WebGL; the flat Map does not.

Develop and verify

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest && ruff check .

(cd web && npm install && npm run check)
(cd docs-site && npm install && npm run check && npm run build)

The architecture, contributing guide, design system, and agent operating guide keep the load-bearing decisions explicit.

Help test the loop

The most useful contribution is a ten-minute first run on a real AI-built project:

1. Follow the privacy-safe tester guide.
2. Light one system without maintainer help.
3. Report the first confusing moment in your own words—never paste private code, project names, credentials, or API keys.

🧭 Open an early-tester report

Roadmap

Horizon	Work
Now	Collect unaided learner evidence and correctness reports on v0.16.0
Next	Level-of-detail rendering and clustering for larger repositories
Later	Read-only sharing, new quest types, and a coordinated public launch

Milestones move only when their acceptance evidence exists. See the public roadmap.

License and acknowledgements

Codemble is released under the Apache License 2.0. It is built with tree-sitter, FastAPI, React, and 3d-force-graph. The flat-map approach draws inspiration from dagre, Eclipse ELK, and archify; the community constellations were inspired by Graphify.

---

_{Built for the moment after “AI made it work” and before “I know how it works.”}