Installation

Polyglot tester release

The complete learning loop supports Python, JavaScript, TypeScript, and mixed projects. Human first-run evidence is still being collected separately.

Requirements

• Python 3.11+
• A modern browser. WebGL is needed for the 3D galaxy, which renders locally in your browser; without it the 2D Map layer still works, because it is plain SVG over the same graph
• uv — install it first; it fetches and runs Codemble without touching your system Python

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

Install and run

1. Install uv

   Once per machine.

   brew install uv

2. Chart your project

   Every time you want the atlas. Nothing is left behind.

   uvx codemble

Installing uv without Homebrew

# macOS · Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Prefer a permanent install? pipx install codemble (then run codemble) and plain pip install codemble both work and need no uv.

Codemble opens your browser to an in-app picker — browse your home folders or reopen a recent project, no path typing required. To skip the picker, pass a path directly: codemble ./your-project.

The Python wheel already contains the production web app. Node is needed only when developing Codemble itself.

Bring your own key

Codemble never ships or proxies a key. Set one of:

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

or create ~/.codemble/config:

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

Your code is parsed locally. The only network calls are the LLM requests you configured, sent directly from your machine to your provider.

Or no key at all: narrate locally

If you would rather nothing left your machine, point Codemble at a local Ollama:

ollama pull gemma4:12b
export CODEMBLE_PROVIDER=ollama
export CODEMBLE_OLLAMA_MODEL=gemma4:12b   # optional; this is the default

The equivalent config keys are provider = "ollama", ollama_model, and ollama_host. This is always an explicit choice — Codemble never detects a local model and switches to it for you — and the host is refused at startup unless it is plain http on loopback, so “local” cannot quietly stop being local. Local output passes exactly the same grounding validation as a cloud provider’s.

Read this before trusting a small local model

Grounding validation catches an invented identifier. It cannot catch a wrong claim about a real one, and smaller local models make that second kind of mistake more often. The structural summary, source, Lens, and checks are model-free and stay trustworthy either way.

No model? Still useful

Without any provider you still get the full galaxy and Map, the structural summary, source, parser relationships, language lens, and checks — only the prose explanations need a model.

Limits that fail honestly

• More than 1,000 supported source files: run codemble --path ./project/subdirectory; the picker offers the same busiest-first scopes as clickable buttons, plus a typed path field. Both stay inside your home directory.
• Ambiguous startup: choose Home in the app or pass a parser-ranked node with --entrypoint NODE_ID.
• Syntax error: the file remains visible as Unchartable, with raw source; no inner structure or model narration is invented.

Supported source extensions are .py, .js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, and .cts. Codemble parses them; it does not run source files, package scripts, compilers, or bundlers.