Local Commands¶

The superqode local command group is the local-first toolkit: detect hardware, find and serve models, generate a transparent starter harness, and check readiness. It is built for Local Agentic Coding (open models on your own hardware, no token bills).

New to local models? Start with the Local Providers guide, then use this page as the command reference.

superqode local COMMAND [OPTIONS]

Command Summary¶

Getting Started¶

local setup¶

The recommended first command for new local-model users. It does not download models or start servers; it prints a TUI-first path that tells you what to run:

superqode local setup qwen3-coder --repo .

In the TUI, use:

:local setup qwen3-coder --repo .

The guide sequences model search, explicit download, server start, context choice, harness build, and smoke test. It also repeats the product contract: packs are starter templates, not a finished harness. Build or bring your own harness, then tune prompts, skills, memory, routing, and context to your repo.

local airplane¶

Prepare a strict offline coding harness for the current repo plus optional read-only reference repos.

superqode local airplane doctor --repo . --ref ~/src/reference
superqode local airplane prepare --repo . --ref ~/src/reference --model ollama/qwen3:8b
superqode local airplane index --repo . --ref ~/src/reference
superqode local airplane smoke --repo . --ref ~/src/reference
superqode local airplane models
superqode local airplane health

Inside the TUI, use the same subcommands after :local:

:local airplane doctor --repo . --ref ~/src/reference
:local airplane prepare --repo . --ref ~/src/reference --model ollama/qwen3:8b --force
:local airplane smoke --repo . --ref ~/src/reference
:harness superqode.airplane.yaml

prepare writes superqode.airplane.yaml, .superqode/airplane/manifest.json, and by default .superqode/code-search.sqlite3. The harness sets allow_network: false, blocks network/fetch/download categories, and advertises only local coding and local search tools.

local init¶

The one-command path: detect hardware, recommend a trusted model, run a smoke test, and write a starter superqode.local.yaml that you own and can edit.

superqode local init --repo .
superqode local init --repo . --pack minimax-m1 --skip-smoke
superqode --harness superqode.local.yaml

local doctor¶

Detect hardware, installed engines, and downloaded models, then recommend the best engine + model for this machine (preferring what you already have).

superqode local doctor --repo .
superqode local doctor --generate superqode.local.yaml
superqode local doctor --generate superqode.local.yaml --pack minimax-m1

local build¶

Guided local harness builder. It runs the migration scan, selects or drafts a model pack, generates a harness with that pack, and prints the final live smoke commands. It does not call a model. The result is intended to be customized: shipped packs are starting points, not proof that a model is optimized for your repo.

superqode local build --repo . --model MiniMaxAI/MiniMax-M1 --pack minimax-m1
superqode local build --repo . --model MiniMaxAI/MiniMax-M1 --dry-run

Finding Models¶

local search¶

Find models matching a query in the trusted catalog and show, per model, the real native download command for every engine it can run on (Ollama, llama.cpp, LM Studio, MLX) plus a superqode models download alternative, an approximate size, whether you already have it, and a rough memory-fit verdict for your hardware. With --hub it also queries the Hugging Face Hub live (trusted publishers only) for the newest releases.

superqode local search qwen3-coder
superqode local search glm --hub
superqode local search minimax --hub
superqode local search qwen3-coder --hub --gguf

In the TUI this is :local search <name>, or enter :hub model-search mode and just type names.

local labs¶

Browse local-friendly model labs from models.dev (GLM, MiniMax, Qwen, Gemma, DeepSeek, Mistral). Use it before downloading weights.

superqode local labs
superqode local labs minimax
superqode local labs alibaba

local migrate¶

Dry-run migration plan for project prompts, skills, role files, existing harnesses, and config. It does not rewrite files.

superqode local migrate --repo .
superqode local migrate --repo . --endpoint http://localhost:8000/v1 --model MiniMaxAI/MiniMax-M1
superqode local migrate --repo . --json

local packs¶

List model-policy packs (shipped plus ~/.superqode/model-packs/). A pack carries starter defaults for one open-model family; reference one from a harness with model_policy.pack, then override it in your own harness as you learn what your model and repo need.

superqode local packs

local pack init¶

Create a user-owned pack without probing a live model. Use --dry-run while planning, then write the pack when you are ready. Later, after a live smoke run, pass the saved smoke --json payload with --from-smoke to derive conservative defaults from measured behavior.

superqode local pack init --model MiniMaxAI/MiniMax-M1 --dry-run
superqode local pack init --model MiniMaxAI/MiniMax-M1
superqode local pack init --from-smoke smoke.json --output .superqode/model-packs/my-model.yaml

Servers¶

MLX and llama.cpp serve one model per process; Ollama and LM Studio run as background apps. serve is an explicit start command: it launches a managed daemon that survives SuperQode exiting, records pid/log metadata under ~/.superqode/servers/, and can be stopped with superqode local stop <engine>. If a server is already answering on the target port, SuperQode adopts it for status display and does not restart or kill it.

Nothing in local init, local build, local migrate, or local smoke starts a model server for you. They print the command to run. In the TUI, direct MLX/llama.cpp model selection asks before starting a one-model server; type manual if you prefer to run the command yourself.

local serve¶

superqode local serve ollama
superqode local serve ds4 --ctx 32768
superqode local serve mlx --model mlx-community/Qwen3-Coder-30B-A3B-Instruct-4bit --port 8090
superqode local serve llama.cpp --model /path/to/model.gguf --ctx 16384

Engines: ollama, lmstudio, mlx, ds4, llama.cpp.

For DS4, the managed default is conservative: --ctx 32768 plus disk KV cache under ~/.superqode/ds4-kv. Use --ctx 100000 for long coding sessions when memory headroom allows. Think Max needs --ctx 393216 or higher. New DS4 flags can be passed with repeated --extra, for example:

superqode local serve ds4 --ctx 32768 \
  --extra=--ssd-streaming \
  --extra=--ssd-streaming-cache-experts \
  --extra=32GB

For MLX, SuperQode refuses a missing Hugging Face model by default because starting mlx_lm.server could trigger a multi-GB download. Use --allow-download only when you are comfortable with that.

local servers¶

Show the status of every known local server (running, managed, pid).

superqode local servers

local stop¶

Stop a server SuperQode started (adopted servers are left untouched).

superqode local stop mlx

local models¶

List chat-capable models on running local servers (embedding/reranker models are hidden). Omit the engine to scan every running server.

superqode local models
superqode local models ollama

Readiness And Performance¶

local warm¶

Preload a model and report first-token latency. Run it before a session so the first real prompt does not pay the model-load cost. A high TTFT here usually means the context window is too large for the hardware.

When you connect a local model from the TUI, SuperQode also sends a tiny best-effort warmup request automatically. This keeps the first real prompt from paying the cold model load when the local server supports it. The connection still succeeds if warmup fails or times out.

superqode local warm ollama --model qwen3:8b

Warmup environment variables:

local smoke¶

Non-destructive coding-readiness check: server reachable, chat model loaded (not embedding-only), context window detected, TTFT/decode measured, and clean tool-call/patch output on a tiny prompt. Never reads or edits your repo.

superqode local smoke --repo .

local bench¶

Measure TTFT and decode speed with a coding prompt. Without --endpoint, benches the first model of every running engine. TTFT (prefill) matters most for agent loops.

superqode local bench
superqode local bench --endpoint http://localhost:11434/v1 --agentic

local optimize¶

Benchmark candidate models and recommend role-specific routing (planner / implementer / reviewer / utility), optionally writing a role-routed harness.

superqode local optimize --repo .
superqode local optimize --generate superqode.local.yaml

local guardrails¶

Recommend conservative runtime limits (context cap, worker concurrency, memory headroom) for this machine.

superqode local guardrails --repo .

Related¶

• Local Providers: the guided local-coding walkthrough.
• Local Agentic Coding: the local-first positioning.
• Local Stack Doctor: how the recommendation matrix works.
• Harness Commands: the superqode harness group.