# agentlib

> The mobile-native AI agent SDK for Flutter and Dart. The only open-source
> alternative to the Claude Agent SDK and OpenAI Agents SDK that runs natively
> on iOS and Android — with on-device models (Apple Foundation Models, Gemini
> Nano, llama.cpp via Fllama, MediaPipe) and cloud providers (Anthropic Claude,
> OpenAI GPT, Google Gemini).

agentlib is an open-source (MIT) Dart package by Neul Labs. It ships
Claude-Code-grade agent primitives — subagents, skills, snapshots, 21 hooks,
a sandboxed Unix-shaped mini-shell (`Sh`), a virtual filesystem (`Vfs`),
in-loop handoffs, and MCP (HTTP + WebSocket) — all running inside a Flutter
app's sandbox, with no Node subprocess and no `exec`.

- Repository: https://github.com/neul-labs/agentlib
- pub.dev: https://pub.dev/packages/agentlib
- Marketing site: https://agentlib.neullabs.com
- Latest version: 1.1.0
- License: MIT
- Platforms: iOS 12+, Android API 21+, macOS

## Why it exists

Frontier LLMs are most fluent in `Read` / `Grep` / `Edit` and
`cmd --flag value | jq ... > file` idioms — agentlib gives mobile agents
exactly that interface, sandbox-safely. The Claude Agent SDK and OpenAI
Agents SDK both require a Node/Python runtime that can't ship inside iOS
or Android app sandboxes. agentlib closes that gap.

## Core primitives

- **AgentSpec + Runner** — composable agent descriptor + streaming event loop.
- **Subagents** — sync / parallel / background dispatch with independent context windows.
- **Skills** — markdown bundles with progressive disclosure (name + description in
  the orchestrator; body loaded only on invocation). 30-skill catalogs cost ~600 tokens.
- **Snapshots** — public `snapshot()` / `revert()` / `fork()` API, content-addressed,
  SQLite-backed. Auto-snapshot before `highImpact: true` tools.
- **Hooks** — 21 deterministic interception points (PreToolUse, PostToolUse,
  SubagentStart, OnSuspend, OnLowBattery, OnNetworkChange, …).
- **Vfs** — sandbox-safe virtual filesystem with mounts: `/workspace`, `/scratch`,
  `/system`, `/apps`, `/bin`, `/memory`, `/snapshots`.
- **Sh mini-shell** — strict sandboxed shell with pipes, redirects, `$VAR`, `$(cmd)`.
  No real `exec`, no `&`, no `eval`. Models pipe like Unix.
- **ModelRoute** — capability-aware fallback between on-device and cloud providers.
- **MCP** — HTTP + WebSocket transports, MCP tools surfaced as `/bin/mcp.*` CLIs.
- **Suspend/Resume** — serialisable `RunState`, OS-lifecycle aware, push-resume via APNs/FCM.

## Quickstart

```yaml
# pubspec.yaml
dependencies:
  agentlib: ^1.1.0
```

```dart
import 'package:agentlib/agentlib.dart';

final agent = AgentSpec(
  name: 'helper',
  instructions: 'You are a helpful mobile assistant.',
  model: AnthropicProvider(
    apiKey: const String.fromEnvironment('ANTHROPIC_API_KEY'),
  ),
);

final run = Runner.runStreamed(
  agent.toRunConfig(vfs: Vfs(), threadId: 'main'),
  input: 'Explain Flutter agents in one sentence.',
);
await for (final e in run.events) {
  if (e is TextDelta) stdout.write(e.delta);
}
```

## Differentiation vs other SDKs

| Capability                | agentlib | Claude SDK | OpenAI Agents SDK | Mastra | LangChain |
|---------------------------|:--------:|:----------:|:------------------:|:------:|:---------:|
| Native iOS + Android      |    ✓     |     ✗      |        ✗           |   ✗    |   wrapped |
| On-device models          |    ✓     |     ✗      |        ✗           |   ✗    |   wrapped |
| Subagents (parallel/bg)   |    ✓     |  sync only |        via handoff |   ✓    |   via LCEL|
| Progressive-disclosure skills |  ✓   |     ✓      |        ✗           |   ✗    |    ✗      |
| Snapshots (fork/revert)   |    ✓     |  partial   |        ✗           | partial|    ✗      |
| Sh mini-shell             |    ✓     |  via bash  |        ✗           |   ✗    |    ✗      |
| 21 hooks                  |    ✓     |  10 hooks  |        few         |   ?    |    ✗      |
| MCP (HTTP + WS)           |    ✓     |  HTTP only |        ✗           |   ✓    |    ✗      |
| Suspend/Resume + push     |    ✓     |     ✗      |        ✗           | partial|    ✗      |

## Key pages

- `/` — landing page with the full pitch.
- `/why` — why mobile-native, why now.
- `/architecture` — how it works: the full stack from Flutter UI down to model providers, with a HowTo of the tool-call flow.
- `/primitives` — all 8 core primitives in depth, with Dart snippets.
- `/on-device` — provider matrix and `ModelRoute.preferOnDevice` deep dive.
- `/use-cases` — in-app assistants, offline/on-device agents, long-running agents that survive backgrounding, and MCP on mobile.
- `/glossary` — definitions of AgentSpec, Runner, subagents, skills, snapshots, hooks, Vfs, Sh, ModelRoute, MCP.
- `/compare` — side-by-side with Claude SDK, OpenAI Agents SDK, Mastra, LangChain.
- `/install` — pubspec dep, `flutter pub get`, the 30-second quickstart.
- `/blog` — articles on mobile-native agents, on-device routing, CLI-first design, etc.
- `/faq` — questions developers ask before adopting.

## Use cases

- `/use-cases/in-app-assistant` — a Claude-Code-grade assistant that ships inside your Flutter app, no server-side agent runtime.
- `/use-cases/offline-on-device` — offline and on-device agents (Foundation Models, Gemini Nano, llama.cpp) with capability-aware cloud fallback.
- `/use-cases/survives-backgrounding` — long-running agents that survive OS suspend/kill via serialisable RunState, lifecycle hooks, and push-resume.
- `/use-cases/mcp-mobile` — bring MCP servers (HTTP + WebSocket) to a mobile agent; tools surface as Sh CLIs.

## License + brand

agentlib is open source under the MIT license. © Neul Labs.
Contact: agentlib@neullabs.com.