spawnllm 0.4.0

Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.

spawnllm

Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.

spawnllm centralizes the LLM-calling plumbing that small tools keep re-inventing: driving the claude and codex CLIs as subshells — with structured Pydantic output, model tiers, and faithful error capture — and running local Apple-Silicon MLX models with adapter fusion, prompt-cache reuse, and batched generation. Depend on it once and each tool keeps only its domain logic instead of its own copy of the backends.

Install

No install needed — run everything through uvx:

uvx spawnllm --help

uvx fetches spawnllm into a throwaway environment and runs it. To add it to a project instead:

uv add spawnllm

For the local MLX engine (Apple Silicon only), pull the extra:

uv add "spawnllm[mlx]"

Quickstart

See which backends are installed and authenticated, and which one auto-selection picks:

uvx spawnllm status

claude: ready
codex: ready
selected: claude

Make a request by passing a prompt as the argument, or piping it over stdin:

uvx spawnllm call --backend claude "What is 2+2? Reply with just the number."

4

--model small|medium|large swaps the tier, which each backend maps to a concrete model. The claude backend resolves small to Haiku, medium to Sonnet, and large to Opus. Add --agent to let the call use tools.

From Python

call_sync runs one request and returns the response. With no backend, it auto-selects the first installed, authenticated CLI (its async companion call mirrors the same signature):

from spawnllm import call_sync

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

Pin a backend and tier explicitly, or pass a Pydantic model to get a validated object back instead of text:

from pydantic import BaseModel

from spawnllm import call_sync, ClaudeCliBackend


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


result = call_sync(
    "What is the capital of France?",
    backend=ClaudeCliBackend(),
    model="large",
    response_model=Capital,
)
print(result.capital)  # Paris

When you don't pin a backend, set specialty= to scope auto-selection by task. The debugging and review specialties route to Codex, and general routes to Claude.

Spec-driven runs

For full control, build a RunSpec and execute it with run_sync (or its async companion run). A RunSpec takes a literal provider model id — no tier mapping — and per-provider flag passthrough via provider_configs. The call returns a RunResult with raw stdout, stderr, and exit code, retrying transient 529/overloaded/rate-limit failures with backoff:

from spawnllm import run_sync, RunSpec, ClaudeConfig, ClaudeCliBackend

result = run_sync(
    RunSpec(
        prompt="What is 2+2? Reply with just the number.",
        model="opus",
        provider_configs={"claude": ClaudeConfig(permission_mode="bypassPermissions")},
    ),
    backend=ClaudeCliBackend(),
)
print(result.stdout)  # 4

What problems does this solve?

Every tool that shells out to claude or codex rebuilds the same plumbing: argv construction, stdin/stdout piping, stderr teeing, and turning non-zero exits into useful errors. spawnllm holds it once.

Structured output is boilerplate too. A Pydantic model becomes a JSON-schema constraint and a parsed, validated result, identically for both CLI backends.

Local MLX is fiddly. Adapter fusion, prompt-cache reuse, worker-thread lifecycle, and batched single-token generation live behind one engine instead of in every consumer.

Behavior drift goes away with the duplication: two tools that call the same models stay byte-for-byte consistent because they share the backend layer, not a pair of diverging copies.

Docs

Read the docs for the full guide and API reference.