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, follow parser-proven routes as far as the evidence goes, and light only what you prove you understand.

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

_{Codemble v0.23.0 · choose free exploration or a guided First Flight · land on a world for Easy or Expert evidence · visiting charts a route; passing checks lights a system amber}

Start here

Run v0.23.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.23.0 codemble

No Homebrew? Use uv's official installer, or install permanently with pipx install codemble==0.23.0 and run codemble. Pass a folder to skip the project picker: uvx --from codemble==0.23.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.23.0 app from source

Use this route when you want an editable checkout:

git clone --branch v0.23.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
	Choose your launch. Explore freely in a fully visible, colourful galaxy, or take a guided First Flight from Home. Learning guidance may quiet unvisited context; free exploration keeps it alive.
	Read a real solar system. Each module becomes a system whose module anchor is its Sun. Named functions and classes orbit through parser-owned call placement, with language-shaped colour, terrain, bands, and motion.
	Follow the constellation. A nearby-systems console names certain and possible inbound and outbound imports, keeps their certainty visible, and lets you continue directly into a connected solar system.
	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, C#, Ruby, and PHP 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
Choose free exploration or First Flight; guided stops can land directly into Study and checks.	Follow real imports from Home; unreachable modules are counted, not erased.

03 · Inspect	04 · Prove
Land on a structure, change its explanation register in place, and follow its real connections.	Pass checks drawn from the graph; only then does the system turn amber.

One graph, two useful views

The default all-language Map is a complete viewport-rendered canvas; an explicit language focus keeps every item in that named projection. Both remain usable on a machine that cannot render the WebGL galaxy without creating one DOM element per module. Easy mode shows an overview and guides one cited journey step at a time. Expert mode keeps that exact step selected and adds its parser rule and observation evidence. Impact, Connections, and bounded test candidates describe the selected feature as a whole, not the current route step. Neither mode changes the underlying evidence, route certainty, 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, Home candidates, and application/test roles come from parsers with exact source evidence.
• Unproven relationships are labelled possible and drawn differently on both the galaxy and the map. A feature journey stops at the proof break before showing a target-relevant possible frontier; colour never upgrades 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. The parser evidence and scale record credits the exact pinned open-source revisions behind the current cache and benchmark design; Codemble copied no source or assets from them.

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