localcode 0.3.42

High-performance AI coding on consumer hardware.
No cloud, no API keys, no data leaving your machine.

⚠️ Alpha software. Active development; expect rough edges, breaking changes between versions, and bugs. Issues and feedback welcome.

Install

pip install localcode      # or: uv pip install localcode

Run

cd your-project
localcode

Docs

Docs are published at mjwsolo.github.io/localcode.

What it does

• Reads and edits files — understands your codebase, makes surgical edits, refuses destructive overwrites
• Runs commands — tests, builds, git, shell; auto-detects long-running servers and backgrounds them
• Searches code — by filename pattern, content (grep), or directory structure
• Builds and launches apps — detects package.json / pyproject.toml / static, picks a free port, starts and verifies the process
• Tracks tasks across turns — task state, stage (scaffolding → implementing → verifying), and goal carry between user messages
• Adaptive thinking — uses reasoning for planning and debugging, skips it for routine codegen
• Uses tools automatically — the model picks its own tools

> build me a Flask app for studying music theory with quizzes

LocalCode infers the goal, scaffolds the project, writes the files, runs pip install, launches the server, opens it in your browser, and verifies it responds — all locally.

Why local?

We are building for a world of truly democratized AI — where everyone has access to powerful, personalized AI on any device, in any location. True local-first AI. LocalCode is the first step toward that vision.

Requirements

• Mac with Apple Silicon
• 16 GB RAM minimum
• Python 3.10+
• ~12 GB free disk (10 GB model + server)

Tested hardware

LocalCode is early software. Hardware support is expected to broaden, but only the configuration below has been tested by the maintainers so far.

Linux installs and runs in CI for development, but Apple Silicon is the supported target — the Metal-accelerated inference path is Mac-only.

Models

On launch, LocalCode recommends the best model for your Mac's RAM — there's no fixed default. You can pick any of these (or a different quant) in the model picker.

Min RAM is the threshold for auto-recommendation (weights ≤ ~55% of unified memory, leaving room for KV cache + OS); you can still pick a heavier model manually. † experimental — pickable but not auto-recommended (DiffusionGemma needs a separate runner; cohere2_moe is unvalidated on this stack).

How LocalCode works

LocalCode runs a custom llama.cpp fork with TurboQuant KV cache compression — a technique from Google's ICLR 2026 paper that we patched into llama.cpp for Apple Silicon. This compresses the KV cache 3.8× — fitting 32K context in 355 MiB on a 16 GB MacBook.

LocalCode picks a model based on your Mac's RAM — there's no fixed default. It scales from Gemma 4 12B on 16 GB up to Qwen 3.6 35B-A3B on 64 GB+. The recommended models are Mixture-of-Experts — only ~3.8 B parameters active per token — which is what makes ~27 tok/s possible on a laptop.

Under the hood:

• TurboQuant KV cache — asymmetric q8_0-K + turbo4-V quantization, 3.8× compression vs. f16
• Multi-region mmap patch — fixes a Metal OOM crash where llama.cpp's loader spanned the entire GGUF file into one Metal buffer
• GPU memory unlock — auto-prompts to raise iogpu.wired_limit_mb for full Metal offload
• Agent loop — goal-typed routing (build / edit / run / chat) with task state, evidence-driven completion, and recovery modes for small-model failure patterns

Sponsors

If you'd like to sponsor LocalCode, reach out.

Contributing

See CONTRIBUTING.md.

License

Apache 2.0 — see LICENSE.