Get one local model provider ready.

Choose a model that may fit your Mac, approve the setup, then connect a script or agent to its API. Your client supplies the prompts, files and tools.

Candidate 0.7.0rc1Private preview. No stable setup is published. See the release notes for the tested hardware and remaining limits.

Before you start

The current candidate targets macOS on Apple Silicon. You need Python 3.11 or later and uv.

Model fit depends on memory available now, not only the memory printed on the box. Close memory-heavy applications before preparing a provider.

Install the candidate

Download the exact files from the 0.7.0rc1 release page, verify SHA256SUMS, and install the wheel with its retained constraints.

# Download the wheel and constraints from /releases/0.7.0-rc.1,
# then verify both files against SHA256SUMS.
uv tool install --force \
  --constraints localcode-0.7.0-rc.1-runtime-constraints.txt \
  ./localcode_prototype-0.7.0rc1-py3-none-any.whl

localcode --version

2
Inspect this machine
```
localcode doctor
```
Check the detected chip, total and currently available memory, disk, cached model revisions, runtimes, optional editor tools and local endpoints.
3
Ask for a provider
```
localcode recommend \
  --task "Fix the failing tests in this repository" \
  --project "$PWD" \
  --channel candidate
```
This does not install or start anything. LocalCode checks known candidates against your Mac and memory limits. The queue suggests what to try; it does not prove which model will do the task best. Add --choose for a numbered chooser, --details for the evidence, or --refresh to fetch current model and benchmark information without downloading weights.
4
Review and apply
```
localcode recommend \
  --task "Fix the failing tests in this repository" \
  --project "$PWD" \
  --channel candidate \
  --prepare
```
Review the model, downloads and server changes before confirming. A new candidate may need several checks; follow the next command LocalCode prints. The complete one-confirmation human flow is not finished. Agents can use a bounded session authorization; the agent workflow documents that path and localcode acquire apply.
5
Use it
```
localcode status --json
```
READY gives your application or coding agent the verified loopback endpoint and model name. LocalCode has prepared the provider; it has not performed the task. A second compatible request can reuse the same provider without restarting it.

When nothing fits

The command should tell you what to do next.

For example, a memory refusal looks like this (queue omitted). Close applications or inspect smaller candidates before trying again.

Not enough memory to start this setup.
Memory: 8.0 GiB available now; 11.1 GiB required by this setup's memory
        estimate.
Task performance has not been established for this request.

Next: close memory-heavy apps and repeat this command.
To inspect options with smaller estimates, repeat with --prefer low-memory.
No provider change has been applied.

For automation or debugging, retain the complete evidence:

localcode recommend --task "Fix the failing tests" --channel candidate --json

Use the model API

The provider capability returned by recommend --prepare contains the loopback endpoint and model alias. Pass those to any OpenAI-compatible client. The older serve, setup and launch commands remain available for explicit legacy profiles and optional Aider use.

Use LocalCode from Codex or Claude Code

Install the CLI first, then install its matching skill. The default destination is Codex; a custom destination can target another skill-compatible agent. This gives the agent control of a separate local provider. It does not change the agent's own model.

# Codex
localcode integration install

# Claude Code
localcode integration install --destination "$HOME/.claude/skills/localcode"

Ask the agent: Use the localcode skill to recommend and prepare a local model provider for this project. Stop for approval before applying changes.

Stop and roll back

localcode disconnect --json
localcode rollback PREPARATION_ID

Disconnect stops only a provider process owned by LocalCode. Rollback restores LocalCode-owned configuration and retains reusable model files.

Model weights are separate from the application. Hugging Face cache pruning does not know which snapshots LocalCode uses: a snapshot without a branch reference may still be needed. Check individual files before deleting them, especially before offline use.

Core concepts

Stable: A profile supported for ordinary use. None is published today.
Candidate: A pinned development profile that requires explicit opt-in.
Execution profile: One exact model, quantization, runtime, context, harness, protocol and resource policy.
Plan digest: The identity of the reviewed effects. Apply rejects a changed plan or material inventory.
Provider READY: The exact model server passed its declared identity and API checks and remains accountable and reversible.
Aider probe: One supplied file was exercised through the isolated editor configuration. This is not autonomous-agent readiness.

CLI commands

localcode doctor

Inspect hardware and installed models, runtimes and agents.

localcode recommend

Select or reuse an admitted provider for a task, machine and owner policy.

localcode acquire apply

Apply one exact saved provider plan after approval.

localcode status

Revalidate the currently prepared capability.

localcode disconnect

Disable launches and stop only a LocalCode-owned provider.

localcode rollback

Restore LocalCode-owned configuration for one preparation.

localcode setup / launch

Use the legacy optional Aider integration explicitly.

Run localcode COMMAND --help for complete arguments. Machine-readable callers should use --json and preserve typed error codes.

Before you start

Install the candidate

Inspect this machine

Ask for a provider

Review and apply