why mobile-native

Every other agent SDK is a Node subprocess away from your users.

The Claude Agent SDK and OpenAI Agents SDK are great — but they assume a runtime that doesn't fit on a phone. agentlib is pure Dart, no exec, no subprocess, with native bridges for on-device models on iOS and Android.

The mobile gap

Pick up any of the popular agent frameworks today and you find the same shape: a Python or TypeScript SDK that talks to OpenAI / Anthropic / Google over HTTPS, plus optional MCP servers spawned as subprocesses, plus a runtime — Node, Bun, Deno, or CPython — that hosts it all.

That stack is wonderful on a laptop, a server, or a Cloudflare Worker. It is a non-starter inside an iOS app sandbox. iOS doesn't let you fork(2) or exec(2). Android lets you, but only inside the JVM, with all the ceremony that implies. Even if you embed a Node binary (some apps do), you're shipping ~50 MB of unused runtime and a long list of code-review questions you don't want to answer.

What we needed instead

The mobile platform asks for an SDK with five properties at once:

Native to the language Flutter/iOS/Android devs already write. That's Dart on the Flutter side, Swift on iOS, Kotlin on Android — agentlib is Dart with platform channels for the other two.
No subprocess, no exec. Every "shell" in agentlib runs in-process via the Sh mini-shell. No real binaries are spawned.
On-device models as a first-class citizen. Apple Foundation Models (iOS 19+), Gemini Nano (Pixel 8+, S24+), llama.cpp via Fllama, MediaPipe — every one is a ModelProvider implementation with the same shape as AnthropicProvider.
OS-lifecycle aware. Apps get backgrounded, killed, woken by push. Every Runner state in agentlib is serialisable, and there are hooks for OnSuspend, OnResume, OnLowBattery, OnNetworkChange.
Claude-Code-grade behaviour. Subagents, skills, snapshots, hooks, a Unix-shell tool surface — the primitives the frontier LLMs are most fluent in.

The "frontier LLMs speak Unix" insight

Frontier LLMs are most fluent in Read / Grep / Edit and cmd --flag value | jq ... > file idioms. agentlib gives the model exactly that — sandbox-safely.
— The single biggest unlock

Look at any leaked Claude system prompt, any GPT-4 tool spec, any high-performing agent transcript: they're all Unix-shaped. Read file. Grep pattern. cmd | jq | xargs. That's not an accident — it's the densest token-efficient idiom in the training data.

Most agent SDKs throw that away. Their tool surface is JSON-RPC: one tool call per turn, no pipes, no composition. agentlib doesn't. The Sh mini-shell parses real pipes (|), redirects (>, >>), variables ($VAR), and command substitution ($(cmd)) — but doesn't actually exec anything. Each "binary" is a registered Dart function; each pipe is a stream in memory.

model output → agentlib

Sh("contacts grep 'Mom' | jq -r .number | xargs whatsapp send --message 'Late'")

One model turn. Three composed CLIs. Zero subprocesses. The consent sheet, the snapshot-before-send, the audit log — all wired in by hooks, deterministically, in Dart.

Why pure Dart, not a Rust core with a Dart binding?

We weighed it. The case for Rust is performance and code reuse with desktop. The case for Dart — which we picked — is that every Flutter dev already speaks it, the package shows up native on pub.dev, and there's no FFI surface to debug across iOS/Android/macOS. The agent loop is overwhelmingly I/O-bound (waiting on a model stream); the few CPU-hot paths (snapshot hashing, JSON parsing) are handled by Dart's optimised standard library or fast Dart-native libs like sqflite. Performance isn't the bottleneck here — fluency for Flutter devs is.

What this isn't

agentlib is not a Python replacement. If you're already running a Claude Agent SDK pipeline behind a web app, keep doing that — agentlib doesn't need to win on the server. agentlib's territory is the device: a Flutter app, a Dart desktop tool, a watch face, an automotive head unit. Anywhere a CPython interpreter or a Node runtime can't easily live.

What you'll see next

From here, the natural reading order is:

Primitives — the eight load-bearing APIs in detail, with Dart snippets.
On-device — the four on-device providers and ModelRoute.preferOnDevice([...]).
Compare — agentlib next to Claude SDK, OpenAI Agents SDK, Mastra, LangChain.
Install — the 60-second quickstart.