Skills

A skill is a package of structured files that teaches an AI coding agent how to work with a specific tool or framework. The skill below was generated by Great Docs from this project’s documentation. Install it in your agent and it will be able to run commands, edit configuration, write content, and troubleshoot problems without step-by-step guidance from you.

Any agent — install with npx:

npx skills add https://yasyf.github.io/spawnllm/

Codex / OpenCode

Tell the agent:
Fetch the skill file at https://yasyf.github.io/spawnllm/skill.md and follow the instructions.

Manual — download the skill file:

curl -O https://yasyf.github.io/spawnllm/skill.md

Or browse the SKILL.md file.

SKILL.md

---
name: spawnllm
description: >
  Delete your subprocess wrappers around claude, codex, and gemini. Use when writing Python code that uses the spawnllm package.
license: MIT
compatibility: Requires Python >=3.13.
---

# spawnllm

Delete your subprocess wrappers around claude, codex, and gemini.

## Installation

```bash
pip install spawnllm
```

## API overview

### Calling

One-shot LLM calls, text and structured.

- `call.call`
- `call.call_sync`
- `extract.extract`
- `extract.extract_sync`
- `structured.extract_json_block`
- `structured.structured_value`

### Running

Spec-driven execution with envelope-aware retry, async and sync.

- `run.run`
- `run.run_sync`
- `RunSpec`: A single configured run, translated per backend at execution time
- `Response`: A backend's fully-resolved outcome: the spec, the raw output, and exactly one of result/error
- `Result`: A successful run: the extracted final text and the optional validated model
- `Output`: The full unparsed transport stream, present on success and failure alike
- `Error`: A failed run: a human-readable message plus the underlying exception
- `DiscardedAttempt`: A transient failure the retry loop threw away, summarized for spend accounting
- `AppleConfig`: Apple Foundation Models knobs applied only by the Apple backend
- `ClaudeConfig`: Claude CLI flag passthrough applied only by the Claude backend
- `CodexConfig`: Codex CLI knobs applied only by the Codex backend
- `GeminiConfig`: Gemini CLI knobs applied only by the Gemini and Antigravity backends

### Backends

CLI backends (Claude, Codex, and the Gemini family), the in-process Claude Agent SDK backend, the Apple Foundation Models backend over its bundled Swift sidecar, the MLX and OpenAI-endpoint backends, the specialty registry, backend selection, and install/auth status checks.

- `LlmBackend`: Abstract execution contract for an LLM backend
- `CliBackend`: Execution contract for the subprocess-backed LLM family
- `ClaudeCliBackend`: `CliBackend` for the Anthropic `claude` CLI
- `ClaudeSdkBackend`: Claude backend hosted through the optional `claude-agent-sdk` package
- `CodexCliBackend`: `CliBackend` for the OpenAI `codex` CLI
- `GeminiCliBackend`: `CliBackend` for Google's `gemini` CLI
- `AntigravityCliBackend`: `CliBackend` for the Antigravity `agy` CLI, a Gemini-family successor
- `AppleBackend`: `CliBackend` for the `spawnllm-apple` on-device Foundation Models sidecar
- `MlxBackend`: In-process backend that runs a prompt through a local `MlxEngine`
- `OpenAiEndpointBackend`: `LlmBackend` that POSTs to an OpenAI-compatible `/chat/completions` endpoint
- `LlmBackends`: Registry mapping each specialty to the `LlmBackend` that serves it
- `select_backend`: Return the first installed, authenticated backend in priority order
- `BackendStatus`: Represent a PEP 604 union type
- `BackendReady`: A backend whose CLI is installed and authenticated
- `BackendNotInstalled`: A backend whose CLI is not on PATH
- `BackendNotAuthenticated`: A backend whose CLI is installed but not authenticated
- `BackendUnavailable`: Raised when no backend is ready (installed and authenticated)

### Transport

Subprocess plumbing shared by the CLI backends.

- `proc.run_cli`
- `proc.arun_cli`
- `proc.capture_cli`
- `proc.acapture_cli`
- `proc.collect_process`
- `proc.map_concurrent`
- `proc.RunResult`

### Types

Shared type aliases.

- `types.TModel`
- `types.TSpecialty`

### MLX

Local Apple-Silicon engine, adapter codec, fuser, and runtime patches.

- `mlx.MlxEngine`
- `mlx.AdapterCodec`
- `mlx.AdapterFuser`
- `mlx.MLXPatches`

## Resources

- [Full documentation](https://yasyf.github.io/spawnllm/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/yasyf/spawnllm)