Run Claude Code, Codex CLI, and VS Code Copilot Chat with local models on your Mac.
| Your tool | What you run |
|---|---|
| Claude Code | claude-local |
| Codex CLI | codex-local |
| VS Code | local models in Copilot Chat |
Local models. Local data. One configuration.
ailocal runs the coding tools you already use against models on your own machine. Nothing is sent to Anthropic or OpenAI, and there is nothing to pay per token.
What it configures for you: the models, the local API they are served on, and every supported client you have installed. You do not edit a config file by hand.
What it does not do: install software. You install the prerequisites and whichever clients you want; ailocal detects what is present and configures it. Every client is optional.
Requirements: macOS on Apple Silicon, 16 GB unified memory minimum.
If you do not have Homebrew, install it first from brew.sh.
Docker Desktop and Ollama are required. They run the models and the local API; ailocal cannot work without them.
brew install --cask docker-desktop ollama-appNow open Docker Desktop and Ollama once, from your Applications folder. Both need one manual launch before anything can use them.
pipx is how you install ailocal, not something ailocal needs at runtime:
brew install pipxpipx brings its own Python — you do not need to install Python or set up a virtual environment.
Language servers are optional and only matter for Claude Code. Install the ones for languages you work in; ailocal enables the matching plugin for each server it finds. See Language servers.
npm i -g pyright # Python
npm i -g typescript-language-server typescript # TypeScript/JavaScript
brew install gopls # Go
xcode-select --install # C/C++ (clangd)Install whichever you want to use, or none. You can add one later at any time.
brew install --cask claude-code # Claude Code
brew install --cask codex # Codex CLI
brew install --cask visual-studio-code # VS Code Copilot ChatIf you install VS Code, open it once — it creates its settings folder on first launch, and ailocal cannot configure it before that.
ailocal works with no client at all: it still serves a local OpenAI- and Anthropic-compatible API at http://127.0.0.1:4000 for any app you point at it.
pipx install git+https://github.com/DevelopSolutionsLLC/ailocal.git
ailocal installailocal install measures your Mac, picks models that fit its memory, downloads them, starts the services, and configures the clients it finds. It will ask you before touching any client configuration.
Expect a download of roughly 6–40 GB of models, depending on your Mac. Run it once; it is safe to re-run.
ailocal checkSuccess is CHECK: OK on the last line. The report is grouped by area; the Clients group shows what ailocal did with each supported client:
Clients
✓ Claude Code configured
— Codex CLI not installed (optional)
→ brew install --cask codex
✓ VS Code configured
✓— configured and working.—— not installed. Not an error: ailocal left it alone. Install it and runailocal clientsif you want it.⚠— advisory. The line below it is the exact command that fixes it.
Open a new terminal, then:
claude-local # Claude Code, against your local models
codex-local # Codex CLI, against your local modelsInstalled a client after ailocal? Run ailocal clients and it picks it up.
VS Code keeps model API keys in its own encrypted storage, which no other program can write to, so this one step is yours. Everything else on the VS Code side is already configured.
grep LITELLM_MASTER_KEY ~/.local/state/ailocal/envThen in VS Code: Copilot Chat → model picker → Manage Models… → LiteLLM → paste the key. The ailocal-* models appear in the picker right after.
Until you do, ailocal check reports VS Code provider configured; API key not initialized and repeats these two steps.
Copilot Chat ships inside VS Code — there is no extension to install and no Copilot subscription needed.
| Command | What it does |
|---|---|
ailocal install |
set everything up (run once) |
ailocal install --reset-config |
re-take the shipped policy defaults, backing up your edits first |
ailocal start |
bring the models and proxy up |
ailocal stop |
bring them down |
ailocal status |
what is loaded right now |
ailocal check |
is everything configured and working? |
ailocal clients |
configure the supported clients you have installed |
ailocal check answers the whole question end to end — configuration, running services, every model, and one real response — and prints the fixing command next to anything that is wrong.
To upgrade: pipx upgrade ailocal && ailocal start.
| Tool | Status |
|---|---|
| Claude Code | Fully supported — tools, web search, language servers, and local artifacts |
| VS Code Copilot | Supported for chat and code completion |
| Codex CLI | Configured and routed correctly, but interactive sessions do not finish — an upstream bug (BerriAI/litellm#27442) |
Any OpenAI- or Anthropic-compatible app also works directly: point it at http://127.0.0.1:4000 with the key in ~/.local/state/ailocal/env.
Local models are capable everyday assistants, not frontier models. Expect strong routine work, not hosted Opus or GPT on the hardest problems.
ailocal enables the official Claude Code LSP plugin for each language whose server binary you already have. It installs no language ecosystem, and reports the fixing command for a language whose server is absent.
| Language | Server binary | You install it with | Plugin ailocal enables |
|---|---|---|---|
| Python | pyright-langserver |
npm i -g pyright |
pyright-lsp |
| TypeScript | typescript-language-server |
npm i -g typescript-language-server typescript |
typescript-lsp |
| Go | gopls |
brew install gopls |
gopls-lsp |
| C/C++ | clangd |
xcode-select --install |
clangd-lsp |
Install a server, re-run ailocal clients claude, and the plugin follows — in ailocal's
own root only. Plugin state is per config root, so this root is self-sufficient and
depends on nothing your hosted client has.
Your hosted claude is yours; ailocal never adds plugins to it. To get the same
languages there, run /plugin in a hosted session once.
There is no bash plugin in the official marketplace, so shell is covered by ShellCheck instead — static analysis, not LSP.
claude-local searches the live web: the local proxy intercepts the request, runs it against ailocal's own SearXNG instance, and returns results the model answers with sources.
Claude Code may display 0 searches on a clearly sourced answer. That counter tracks Anthropic-hosted search, which never runs here; retrieval still happened.
Brave Search is optional. Without a key, search uses the keyless engines. Adding a Brave API key enables an API-backed general-web engine, which is more reliable for broad questions:
$EDITOR ~/.config/ailocal/.env.local # set BRAVE_API=your-key
ailocal start # re-renders the search settingsThe key stays in that file on your machine. It is never committed, never printed, and never leaves the local search container.
Anthropic's hosted Artifact tool publishes to claude.ai and is unavailable to a
locally-routed session. claude-local gets a local equivalent instead: ailocal ships the
artifact renderer inside the package and ailocal clients claude provisions it, so there is
nothing extra to clone, install, or keep in sync.
Ask for a diagram, a page, or a report and the model calls mcp__artifact__publish. The
result opens in your browser from 127.0.0.1 and the canonical source is written to
.artifacts/ in your project, so it survives the session and can be committed.
| Format | Rendered by | Needs |
|---|---|---|
html, markdown |
bundled marked |
— |
mermaid |
bundled mermaid |
— |
architecture |
bundled elkjs, laid out in Node |
node on PATH |
The model supplies only semantics — components, edges, groupings. Layout is computed by ELK and presentation comes from a design token file, so the same input renders the same way every time rather than depending on the model's sense of geometry.
The page cannot reach the network. The artifact renders in a sandboxed iframe with an
opaque origin under connect-src 'none', served separately from the viewer that frames it.
Every asset is vendored; nothing is fetched from a CDN.
Your hosted claude is untouched — it keeps the real Artifact tool.
ailocal measures your Mac's memory and chooses a profile automatically. You do not need to think about this to install or use it.
| Memory | Main model | Context window | Models on disk |
|---|---|---|---|
| 16 GB | qwen3.5:4b |
96K | ~6 GB |
| 32 GB | qwen3.5:9b |
128K | ~9 GB |
| 64 GB | gemma4:26b-mlx |
192K | ~40 GB |
| 128 GB | gemma4:26b-mlx |
256K | ~40 GB (sized from model limits, not yet measured on hardware) |
ailocal never picks a profile your machine cannot hold. To override it: ailocal profile use 32gb, then ailocal start.
A long conversation compacts automatically before it reaches that window. Your client does the compacting; ailocal supplies the threshold. The full window stays available for one-off large requests.
To change which model a profile uses, edit the file in ~/.config/ailocal/profiles/ and run ailocal start. Your edits are preserved across upgrades.
What a fresh install gives you, without configuring anything.
| Default | Change it with | |
|---|---|---|
| Inference | Ollama, via LiteLLM on 127.0.0.1:4000 |
— |
| Profile | chosen from your Mac's memory | edit ~/.config/ailocal/profiles/, then ailocal start |
| LiteLLM | pinned by digest, version reported by ailocal check |
a deliberate upgrade, then the gate |
Tool search (claude-local) |
on (ENABLE_TOOL_SEARCH=true) |
AILOCAL_TOOL_SEARCH=… |
Native Workflow (claude-local) |
off | AILOCAL_NATIVE_WORKFLOWS=1 |
| Local artifacts | on, bundled | — |
| Web search | ailocal's own SearXNG, keyless | add BRAVE_API |
| Context | the profile's num_ctx; 1M-context beta off |
profile |
Hosted claude, ~/.claude |
never touched | — |
Every claude-local variable is process-scoped — set it inline for one session. The full
table, with accepted values and effects, is in docs/claude-local.md.
None of these are required, and ailocal does not install them.
- Cadence — composes engineering
instructions, skills and agents. Separately owned; ailocal does not depend on it, and
claude-localworks normally without it. - Native Workflow —
AILOCAL_NATIVE_WORKFLOWS=1 claude-localrestores Claude Code's built-in Workflow tool for one session. It is off by default because its schema cannot be deferred and it was never invoked in 148 measured sessions. - Language servers — install a server binary and re-run
ailocal clients claude; the plugin follows, in ailocal's root only. - Brave Search — an API-backed general-web engine for broad questions.
- Node.js — only the
architectureartifact format needs it.
| Document | Purpose |
|---|---|
| docs/claude-local.md | what claude-local is, tool search, Workflow, every variable |
| docs/architecture.md | how the pieces fit together |
| docs/troubleshooting.md | symptoms and fixes |
| docs/security.md | secrets, permissions, exposure |
| docs/adr/011-bundled-artifacts.md | why artifacts ship inside the package |
| AGENTS.md | developing and validating ailocal |
Apache-2.0 — see LICENSE.
Developed and maintained by Victor T. Chevalier for DevelopSolutions, LLC.