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.
| Mac | Memory | Status | Notes |
|---|---|---|---|
| M5 Apple Silicon | up to 128 GB | Tested | Primary development machine (M5 Max) |
| M4 MacBook | 16 GB | Tested | Validated at the 16 GB floor |
| M1/M2/M3 Apple Silicon | 16 GB+ | Not yet tested | Expected to work, but needs validation |
| M4 Apple Silicon | 24 GB+ | Not yet tested | Expected to support larger contexts, but needs validation |
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.
| Model | Size (quant) | Active params | Min RAM | Architecture |
|---|---|---|---|---|
| Gemma 4 12B | 7.4 GB (Q4) | 12B (dense) | 16 GB | gemma4-iswa |
| Gemma 4 26B-A4B | 11.2 GB (Q3) | 3.8B (8/128 experts) | 24 GB | gemma4-iswa |
| Qwen 3.6 35B-A3B | 10.7 GB (Q2) | 3.0B (8+1/256) | 24 GB | qwen35moe |
| Qwen 3.8 27B | 17.9 GB (Q4) | 27B (dense) | 32 GB | qwen35 |
| Muse Glimmer 30B † | 15.9 GB (Q4) | 30B (dense, multimodal) | 32 GB | muse_glimmer |
| DiffusionGemma 26B-A4B † | 15.7 GB (Q4) | 4B (diffusion MoE) | 32 GB | diffusion_gemma |
| North-Mini-Code 30B-A3B † | 17.9 GB (Q4) | 3B (30B MoE) | 36 GB | cohere2_moe |
| Gemma 4 12B (full) | 23.8 GB (BF16) | 12B (dense) | 48 GB | gemma4-iswa |
| Gemma 4 26B-A4B | 28 GB (Q8) | 3.8B (8/128 experts) | 64 GB | gemma4-iswa |
| Qwen 3.6 35B-A3B | 38.5 GB (Q8) | 3.0B (8+1/256) | 96 GB | qwen35moe |
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; Muse Glimmer's muse_glimmer arch isn't in the TurboQuant server, so LocalCode builds a dedicated stock llama-server (llama.cpp PR #26841) on first use and serves it without TurboQuant KV compression.
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_mbfor 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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file localcode-0.3.53.tar.gz.
File metadata
- Download URL: localcode-0.3.53.tar.gz
- Upload date:
- Size: 10.1 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ca4ae49ab7b0db0ad5c9e9a0ec530f0a1dd56320c4942d588c01761d264c8c03
|
|
| MD5 |
53918ce9659cef4ace0bf4ca2131ab3b
|
|
| BLAKE2b-256 |
92f8cc2fe79dca0ef0d468b3e10b45b9bf1cabd6045ce0e2a700ed3f233c9d82
|
Provenance
The following attestation bundles were made for localcode-0.3.53.tar.gz:
Publisher:
publish.yml on mjwsolo/localcode
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
localcode-0.3.53.tar.gz -
Subject digest:
ca4ae49ab7b0db0ad5c9e9a0ec530f0a1dd56320c4942d588c01761d264c8c03 - Sigstore transparency entry: 2507026590
- Sigstore integration time:
-
Permalink:
mjwsolo/localcode@e1a7ba85c59fea3ae6bf4b5419a143fc1480a190 -
Branch / Tag:
refs/tags/v0.3.53 - Owner: https://github.com/mjwsolo
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@e1a7ba85c59fea3ae6bf4b5419a143fc1480a190 -
Trigger Event:
push
-
Statement type:
File details
Details for the file localcode-0.3.53-py3-none-any.whl.
File metadata
- Download URL: localcode-0.3.53-py3-none-any.whl
- Upload date:
- Size: 6.0 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9c4da8d8e180e0cdcdb8f59a252c33fb49f9e34cf54c84891edca22b9912ee89
|
|
| MD5 |
4ce271416df246fdc379d55f6512a0f8
|
|
| BLAKE2b-256 |
6177a0c81434ea2f3c59c7582282ba7b1de3c32d8a6cc91fb66394ba59b3e235
|
Provenance
The following attestation bundles were made for localcode-0.3.53-py3-none-any.whl:
Publisher:
publish.yml on mjwsolo/localcode
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
localcode-0.3.53-py3-none-any.whl -
Subject digest:
9c4da8d8e180e0cdcdb8f59a252c33fb49f9e34cf54c84891edca22b9912ee89 - Sigstore transparency entry: 2507026584
- Sigstore integration time:
-
Permalink:
mjwsolo/localcode@e1a7ba85c59fea3ae6bf4b5419a143fc1480a190 -
Branch / Tag:
refs/tags/v0.3.53 - Owner: https://github.com/mjwsolo
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@e1a7ba85c59fea3ae6bf4b5419a143fc1480a190 -
Trigger Event:
release
-
Statement type:
