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.17.0 · every module is represented before the first lesson · related systems and proven routes share a subtle colour cue · visiting charts a route; passing checks lights a system amber}

[!IMPORTANT] The screen above and the packaged app are both v0.17.0. The PyPI release maps Python, JavaScript, TypeScript, Go, Java, Rust, C#, and mixed projects; it includes First Flight, the local project-brief export, proven import-cycle facts, 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.17.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.17.0 codemble

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

Wheel · Source archive · SHA256SUMS · PyPI files · Release notes

Build the same v0.17.0 app from source

Use this route when you want an editable checkout:

git clone --branch v0.17.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 on the first frame. Subtle colour joins systems inside the same import community, while proven bridges stay neutral and possible routes stay dashed. First Flight gives Home a short, repeatable orientation path.
	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
Follow a colour corridor or take First Flight; keyboard focus keeps the active system and its neighbours on the current route mesh named.	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

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; colour never upgrades their certainty.
• 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

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

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)

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

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.”}