Installation

One current version

The published package, screenshots, and these instructions describe v0.22.0. The current application source preserves that user-facing behavior; this checkout may also contain post-release documentation. Download the wheel or source archive when you do not want the one-command route.

Requirements

• Python 3.11+
• A modern browser. WebGL draws the 3D galaxy; the canvas Map still works without it
• uv for the recommended no-install run, or pipx for a permanent command

An Anthropic or OpenAI key is optional and enables only explanation prose. A local Ollama can narrate instead, with nothing leaving your machine.

Run Codemble

1. 

   Install uv

   Once per machine.

   brew install uv

2. 

   Open Codemble

   Pick a project in the browser. Nothing is added to your system Python.

   uvx --from codemble==0.22.0 codemble

Use uv’s official installation guide if you do not use Homebrew. Prefer a permanent install? Run pipx install codemble==0.22.0, then codemble. Plain pip install codemble==0.22.0 also works inside a virtual environment.

The shorter uvx codemble intentionally follows the newest PyPI release. The version-pinned command above stays aligned with this guide and its screenshots.

Codemble opens an in-app picker. To skip it, pass a folder:

uvx --from codemble==0.22.0 codemble ./your-project

The package contains the production web app, so Node.js is not required. Keep the terminal process open while you use Codemble; it is the local server for that browser tab. Press Ctrl-C in the terminal when you are finished.

If the browser does not open

The active server already prints an Open http://127.0.0.1:PORT loopback URL in the terminal. Leave that process running and open its printed URL in your browser. On a future launch, after stopping the current server with Ctrl-C, you can suppress automatic browser opening and copy the new printed URL yourself:

uvx --from codemble==0.22.0 codemble --no-open

If the 3D galaxy reports that WebGL is unavailable, use the flat Map layer; it keeps the complete parser-owned diagram without WebGL. If project selection reports more than 5,000 supported files, choose one of the offered subdirectories or pass --path ./project/src.

Build 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

Run codemble --version to confirm v0.22.0. Contributors should follow the full source build and verification guide.

Bring your own key—or do not

The galaxy, Map, structural summary, Impact, source viewer, language Lens, checks, lighting, and progress are model-free. To add optional cloud narration, set one of:

export ANTHROPIC_API_KEY=sk-ant-...   # or
export OPENAI_API_KEY=sk-...

You can also create ~/.codemble/config:

provider = "anthropic"   # or "openai"
api_key  = "sk-..."
model    = "claude-sonnet-5"   # optional

Your project is parsed locally. If you configure a narrator, opening Study automatically sends a bounded excerpt to that provider; there is no separate “send” button. Without a configured narrator, Study stays entirely local.

Keep narration local with Ollama

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

Codemble never auto-selects Ollama, and a configured Ollama host must use plain HTTP on loopback. Local output passes the same grounding validation as cloud output.

What grounding can and cannot prove

Validation catches an invented identifier. It cannot catch every wrong claim about a real identifier, and smaller local models make that second kind of error more often. The structural summary, source, Impact, Lens, and checks are parser-owned.

Limits that fail honestly

• Above roughly 5,000 supported source files, choose a subdirectory in the picker or pass --path ./project/src.
• When several entrypoints genuinely tie, choose Home in the app or pass a parser-ranked --entrypoint NODE_ID.
• A syntax-error file stays visible as Unchartable; Codemble does not invent inner structure or narration for it.
• Codemble parses supported source. It does not run source files, package scripts, compilers, or bundlers.

Supported extensions are .py, .js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts, .go, .java, .rs, .cs, .rb, and .php.