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

Important

The screen above and the packaged app are both v0.22.0. The PyPI release maps Python, JavaScript, TypeScript, Go, Java, Rust, C#, Ruby, PHP, and mixed projects. At launch, choose free exploration or a guided First Flight; land on any parser-owned world to switch between Easy and Expert evidence, inspect its inbound and outbound connections, then read source or prove understanding. The pinned command and direct downloads below resolve to the same verified release.

Start here

Run v0.22.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.22.0 codemble

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

Use this route when you want an editable checkout:

git clone --branch v0.22.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

View	What it shows	When it helps
Galaxy	Modules as colourful star systems and imports as routes	Learn the shape of the whole project
Solar system	The module anchor as its Sun; named structures as language-styled worlds in call orbits that distinguish certain calls, call roots, and no-path placement	Understand one module and continue through parser-owned neighbouring imports
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
Star chart	Project overview, proven import cycles, progress, and a local Markdown export	Carry parser-owned facts into a handoff
Study	Parser-owned evidence as far as it reaches, a visible proof break when it does not, real source, integrated Impact and Connections, Lens notes, and optional narration	Follow one structure toward its application context without inventing a route

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

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, feature journeys, 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, .cs, .rb, and .php.
• Scale: above roughly 5,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, parser evidence and scale record, 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.22.0
Next	Design the privacy boundary for the planned read-only galaxy link
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. 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.”}