Delete your subprocess wrappers around claude, codex, and gemini. spawnllm subshells all three CLIs plus local MLX and returns one Pydantic-validated Response, so the per-model plumbing you hand-rolled goes away.

Get started

uvx spawnllm status

Driving with an agent? Paste this:

Run `uv add spawnllm` in this project.
Replace our hand-rolled claude/codex subprocess code with spawnllm's `call_sync`,
or `extract_sync` with a Pydantic response model for structured output.
Verify available backends with `uvx spawnllm status`.
Docs: https://yasyf.github.io/spawnllm/

Use cases

Delete your hand-rolled claude/codex subprocess plumbing

Every small tool grows its own subprocess.run(["claude", "-p", ...]) — argv quirks, stdin piping, exit-code guesswork — and each copy drifts. One call replaces all of it:

from spawnllm import call_sync

print(call_sync("Reply with just the word: pong"))

Prints pong. With no backend=, spawnllm auto-selects the first installed, authenticated CLI, pipes the prompt over stdin, and retries transient 529/overloaded/rate-limit failures with capped backoff.

Get a validated Pydantic object back, not a string to parse

Scraping JSON out of a model's stdout means regexes, code fences, and silent schema drift. extract_sync validates instead:

from pydantic import BaseModel

from spawnllm import extract_sync


class Capital(BaseModel):
    country: str
    capital: str


result = extract_sync("What is the capital of France?", Capital)
print(result.capital)  # Paris

The backend turns Capital into a JSON-schema constraint on the call itself, and a non-conforming reply raises pydantic.ValidationError instead of sneaking downstream.

Run Apple-Silicon MLX models with fused adapters and prompt-cache reuse

Shipping a LoRA-tuned local model means hand-rolling adapter fusion, model caching, and worker-thread lifecycle. The MLX extra owns all three:

uv add "spawnllm[mlx]"

AdapterFuser.ensure_fused fuses your compressed adapter into the base model once and caches the result in the Hugging Face hub layout; MlxEngine loads it on a dedicated worker thread, precomputes a prompt cache for your shared prefix messages, and batches generation. Wrap the engine in an MlxBackend and the same run_sync call works.

More in the docs

• Spec-driven runs — a literal model id, per-provider flag passthrough, and envelope-aware retry via RunSpec — Running reference
• Backend selection — the priority chain, plus specialty= routing (debugging and review go to Codex, general to Claude) — Backends reference
• Transport helpers — run_cli, collect_process, and map_concurrent, the subprocess plumbing shared by every CLI backend — Transport reference
• The CLI — spawnllm call, status, and backends from any shell — CLI reference
• MLX internals — the adapter codec, fuser, and runtime patches behind the local engine — MLX reference

Read the docs for the full guide and API reference. Licensed under MIT.