Swallowtail is a Rust library for discovering, preparing, and driving AI model providers and agent harnesses through explicit, testable boundaries.
It provides provider-neutral contracts, an executor-neutral runtime, local host services, protocol codecs, and opt-in adapters. Applications keep their prompts, tools, permissions, routing, fallback policy, persistence, billing, and product state.
New here? Two short reads get you from zero to a working run:
- Key Concepts — the shared vocabulary in plain English, before the type names pile up
- Quick Start — one Codex structured run, end to end, with a minimal example
v0.3.2 is the current supported source identity. Releases are distributed as
annotated Git tags from the
canonical repository.
There is no crates.io publication, GitHub Release object, binary bundle, or
installer in this release line.
The canonical v0.3.2 tag resolves to the reviewed CI-green release commit.
Post-tag work must use an explicitly approved revision and must not be
presented as part of that immutable release.
The 30 tagged packages share version 0.3.2 and provide 36 production routes,
including Command Code, idioms, Codex spawn admission, and Claude Code
response-only execution. The release preserves the Rust 1.95.0 floor and is
not an API 1.0 promise.
Swallowtail does not choose a provider, model, credential, endpoint, executable, billing arrangement, or fallback.
- Choose one of the 36 production routes.
- Read its canonical guide through the integration guide map.
- Add only the adapter and shared packages your application imports.
- Use the adapter's prepared facade for normal integration. Low-level runtime roles remain available for advanced composition.
The feature matrix compares model catalogues, runs, sessions, reasoning, callbacks, activity, recovery, management, and other portable features without hiding route differences.
Use the same Git URL and exact tag for every direct Swallowtail dependency. This example selects Codex and the shared types and local host services used by a typical application:
[dependencies]
swallowtail-core = { git = "https://github.com/inflatable-cookie/swallowtail", tag = "v0.3.2" }
swallowtail-runtime = { git = "https://github.com/inflatable-cookie/swallowtail", tag = "v0.3.2" }
swallowtail-host-local = { git = "https://github.com/inflatable-cookie/swallowtail", tag = "v0.3.2" }
swallowtail-adapter-codex = { git = "https://github.com/inflatable-cookie/swallowtail", tag = "v0.3.2" }Replace the Codex adapter with the route package you selected. Keep the shared packages only when your code imports them directly. Cargo resolves their internal workspace dependencies from the same tagged source.
Do not mix the tag with a moving branch, a local path, a crates.io placeholder,
another Swallowtail tag, or an unreviewed commit. Commit Cargo.lock in
applications so the selected source identity and third-party graph remain
reviewable.
There is no umbrella crate. Every package is independently selectable.
| Purpose | Packages |
|---|---|
| Portable contracts and execution | swallowtail-core, swallowtail-runtime |
| Host integration, idioms, and conformance | swallowtail-host-local, swallowtail-idioms, swallowtail-testkit |
| Protocols and transport | swallowtail-protocol-acp, swallowtail-protocol-openai-chat, swallowtail-transport-acp-remote |
| Installed agent harnesses | swallowtail-adapter-antigravity, swallowtail-adapter-claude-agent, swallowtail-adapter-codex, swallowtail-adapter-command-code, swallowtail-adapter-cursor, swallowtail-adapter-grok, swallowtail-adapter-kimi, swallowtail-adapter-muse, swallowtail-adapter-oh-my-pi, swallowtail-adapter-opencode, swallowtail-adapter-pi, swallowtail-adapter-qwen |
| Hosted APIs and SDKs | swallowtail-adapter-alibaba-model-studio, swallowtail-adapter-anthropic, swallowtail-adapter-bedrock, swallowtail-adapter-deepseek, swallowtail-adapter-gemini, swallowtail-adapter-kimi-platform, swallowtail-adapter-openai, swallowtail-adapter-xai |
| Local model runtimes | swallowtail-adapter-llama-cpp, swallowtail-adapter-ollama |
Some packages expose several explicitly separate routes. For example, the Gemini adapter contains installed CLI and hosted Live integrations; the Kimi adapter contains ACP, headless, and local-server routes. Package selection does not make every route or capability in that package available.
Prepared facades follow a common sequence without becoming a generic router:
- the host approves references, services, credentials, and runtime targets
- the adapter discovers or validates the exact provider interface
- the application selects an explicit configured instance and model route
- the adapter prepares immutable evidence, a preflight plan, and a typed operation
- the application dispatches the operation and drains bounded events until terminal and cleanup truth is known
Provider differences remain observable through capabilities and prepared types. Do not infer support from provider prose or parse provider-native payloads in the consumer. Start with:
- provider selection and preparation
- ordinary operation lifecycle
- generation controls and input authority
- observable activity
- working-state restoration
- portable failure handling
- Rust
1.95.0or newer for everyv0.3.2package - Apple Silicon macOS is the verified release target; other targets are unverified, not prohibited
- installed harnesses, attached services, model artifacts, authentication, and provider billing are external prerequisites named by each route guide
Swallowtail never searches for or installs an executable, starts an attached service, acquires a model, or logs into a provider implicitly. The host admits those resources explicitly.
The Claude Agent ACP route needs the separately pinned
@agentclientprotocol/claude-agent-acp npm sidecar. A Rust source tag does not
contain node_modules; follow the
Claude Agent guide for the
application-local sidecar boundary. The native claude -p route is separate
and does not use that sidecar.
Swallowtail package versions and provider-interface versions are independent.
An adapter documents exact maintained, deprecated, excluded, and sometimes
visible unverified-newer provider versions. Installing package 0.2.0 does
not guarantee every provider or harness release.
Before 1.0:
- compatible API and guaranteed-behavior changes advance the patch version
- breaking API or guaranteed-behavior changes advance the minor version
- raising an MSRV, shrinking a guaranteed provider range, changing route identity, or weakening lifecycle and authority truth is breaking
See Contract 036 and the v0.3.2 release notes.
The repository uses Effigy for task routing:
effigy tasks
effigy doctor
effigy test --plan
effigy qaLive and authenticated probes are separate, opt-in tasks. Normal QA is credential-free and must not contact providers.
Repository architecture, contracts, roadmaps, and logs start at docs/README.md. Contribution rules are in CONTRIBUTING.md.
Use GitHub Issues for reproducible bugs and integration questions. Include the Swallowtail source identity, route ID, qualified provider version, safe diagnostic code, target, and smallest credential-free reproduction. Do not include credentials, provider payloads, private prompts, or consumer data.
Read SUPPORT.md for the support boundary. Report vulnerabilities privately under SECURITY.md, not in a public issue.
Swallowtail is licensed under the MIT License.