@capgo/capacitor-llm

Run large language models on the device from your Capacitor app: Apple Intelligence on iOS, Gemini Nano or LiteRT-LM on Android, and Gemma web models in the browser. Private and free per request.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-llm in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-llm to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Chat sessions: createChat() and sendMessage(), with streamed textFromAi, aiFinished and generationError events.
• Model choice: setModel() picks Apple Intelligence, Gemini Nano or a custom .litertlm model.
• Model download: downloadModel() fetches a model to the device with downloadProgress events.
• Readiness: getReadiness() and the readinessChange event tell you when the model can answer.
• Platforms: iOS, Android and Web. Web uses Gemma models through @mediapipe/tasks-genai. It loads the runtime from a CDN and needs the model file, so it works offline only once both are available locally.

On-device LLM support for Capacitor.

Current platform strategy:

• iOS: Apple Intelligence by default, plus LiteRT-LM .litertlm custom models in SwiftPM integrations when the path ends in .litertlm or modelType: 'litertlm' is passed
• Android: Gemini Nano system model on supported devices where it is already available, LiteRT-LM for .litertlm bundles, and a compatibility fallback for legacy MediaPipe .task models
• Web: Gemma 4 web models through @mediapipe/tasks-genai

Documentation

The most complete plugin docs are available at capgo.app/docs/plugins/llm.

Compatibility

Note: The plugin major version follows the Capacitor major version. Use the version that matches your Capacitor installation.

Installation

npm install @capgo/capacitor-llm
npx cap sync

If you use the web implementation, also install the MediaPipe peer dependency:

npm install @mediapipe/tasks-genai

Model Setup

iOS

Recommended path:

• Use Apple Intelligence with path: 'Apple Intelligence'
• Requires iOS 26.0+

Custom iOS LiteRT-LM path:

• Available only when the plugin is integrated into the iOS app through Swift Package Manager
• Uses the official LiteRT-LM Swift API and prebuilt iOS xcframework for .litertlm models
• Selected only when the path ends in .litertlm or modelType: 'litertlm' is passed
• CocoaPods builds keep Apple Intelligence and the legacy MediaPipe .task compatibility path
• Other custom iOS model types keep the legacy MediaPipe compatibility path for backward compatibility

Example:

import { CapgoLLM } from '@capgo/capacitor-llm';

await CapgoLLM.setModel({ path: 'Apple Intelligence' });
const chat = await CapgoLLM.createChat();

Android

Recommended path:

• Use Gemini Nano with path: 'Gemini Nano' when the Android device already has it available through AICore
• Use LiteRT-LM .litertlm bundles
• Gemma 4 E2B and E4B are good default examples
• Models are available from the public litert-community Hugging Face repos

Gemini Nano system model example:

await CapgoLLM.setModel({ path: 'Gemini Nano' });
const chat = await CapgoLLM.createChat();

Optional: ML Kit GenAI Agent API (Gemini Nano agentic workflows)

Google's ML Kit GenAI Agent API (com.google.mlkit:genai-agent:1.0.0-alpha1) adds AgentRunner managed multi-turn sessions on top of Gemini Nano (including Gemini Nano v4 on supported devices). It is opt-in so apps that do not use it do not pull the dependency.

Docs:

• Agentic workflows overview
• Get started
• ML Kit GenAI overview
• Release notes

Enable the native dependency (pick one):

1. capacitor.config.ts (runs capacitor:sync:before hook):

plugins: {
  CapgoLLM: {
    android: {
      genaiAgent: {
        include: true,
        dependencyType: 'implementation',
      },
    },
  },
},

2. App android/gradle.properties or variables.gradle:

capacitorLLM.genaiAgent.include=true

Use the agent backend (default remains direct genai-prompt access):

await CapgoLLM.setModel({
  path: 'Gemini Nano',
  androidGeminiBackend: 'agent',
});

Requirements: Android API 26+, Android 14 (API 34)+ with AICore for agent previews, Kotlin 2.3+ in the plugin when enabled. See Google's device support list for Gemini Nano model versions.

Fallback: If genai-agent is not included, androidGeminiBackend: 'agent' fails model load with a clear error. Use androidGeminiBackend: 'prompt' (default) or omit the field for the existing Prompt API path.

compileOnly: Set dependencyType: 'compileOnly' in config when your app adds implementation 'com.google.mlkit:genai-agent:1.0.0-alpha1' itself.

Quickstart with a downloaded Gemma 4 model:

import { CapgoLLM } from '@capgo/capacitor-llm';

const result = await CapgoLLM.downloadModel({
  url: 'https://huggingface.co/litert-community/gemma-4-E2B-it-litert-lm/resolve/main/gemma-4-E2B-it.litertlm?download=true',
  filename: 'gemma-4-E2B-it.litertlm',
});

await CapgoLLM.setModel({
  path: result.path,
  modelType: 'litertlm',
  maxTokens: 4096,
  topk: 40,
  temperature: 0.8,
});

const chat = await CapgoLLM.createChat();

Bundled asset example:

await CapgoLLM.setModel({
  path: '/android_asset/gemma-4-E2B-it.litertlm',
  modelType: 'litertlm',
  maxTokens: 4096,
});

Legacy compatibility:

• Existing Android .task models still load through the compatibility path
• New integrations should prefer .litertlm

Web

The web implementation uses @mediapipe/tasks-genai with web-ready model artifacts.

Gemma 4 web models are published next to the mobile LiteRT-LM bundles and use *-web.task.

Example:

await CapgoLLM.setModel({
  path: 'https://huggingface.co/litert-community/gemma-4-E2B-it-litert-lm/resolve/main/gemma-4-E2B-it-web.task?download=true',
  modelType: 'task',
  maxTokens: 4096,
});

Usage

import { CapgoLLM } from '@capgo/capacitor-llm';

const { readiness } = await CapgoLLM.getReadiness();
console.log('LLM readiness:', readiness);

const { id } = await CapgoLLM.createChat();

await CapgoLLM.addListener('textFromAi', (event) => {
  console.log('chunk', event.text);
});

await CapgoLLM.addListener('aiFinished', ({ chatId }) => {
  console.log('finished', chatId);
});

await CapgoLLM.sendMessage({
  chatId: id,
  message: 'Explain why local inference is useful on mobile.',
});

Notes

• Android now prefers LiteRT-LM and Gemma 4 style .litertlm bundles.
• iOS LiteRT-LM custom-model support now uses the official LiteRT-LM Swift API and prebuilt iOS binaries, is available only in SwiftPM integrations of this plugin, and is selected only for explicit .litertlm models.
• CocoaPods builds on iOS should use Apple Intelligence or the legacy MediaPipe .task compatibility path.
• Web uses Gemma 4 *-web.task artifacts through @mediapipe/tasks-genai.
• Apple Intelligence remains the preferred default on iOS where available.

• createChat()
• sendMessage(...)
• getReadiness()
• setModel(...)
• downloadModel(...)
• addListener('textFromAi', ...)
• addListener('aiFinished', ...)
• addListener('generationError', ...)
• addListener('downloadProgress', ...)
• addListener('readinessChange', ...)
• getPluginVersion()
• Interfaces

LLM Plugin interface for interacting with on-device language models

createChat()

createChat() => Promise<{ id: string; instructions?: string; }>

Creates a new chat session

Returns: Promise<{ id: string; instructions?: string; }>

sendMessage(...)

sendMessage(options: { chatId: string; message: string; }) => Promise<void>

Sends a message to the AI in a specific chat session

getReadiness()

getReadiness() => Promise<{ readiness: string; }>

Gets the readiness status of the LLM

Returns: Promise<{ readiness: string; }>

setModel(...)

setModel(options: ModelOptions) => Promise<void>

Sets the model configuration

• iOS: Use "Apple Intelligence" as path for the system model. Custom LiteRT-LM .litertlm models are supported on iOS only when this plugin is integrated through Swift Package Manager, and are selected only when modelType: 'litertlm' is passed or the path ends in .litertlm.
• Android: Use "Gemini Nano" for the AICore system model on supported devices where it is already available. Set androidGeminiBackend: 'agent' to use the ML Kit GenAI Agent API (com.google.mlkit:genai-agent) for managed multi-turn Gemini Nano sessions (opt-in native dependency). Prefer LiteRT-LM .litertlm bundles for custom models; legacy MediaPipe .task models are still supported
• Web: Provide a web-ready model asset for @mediapipe/tasks-genai such as Gemma 4 *-web.task

downloadModel(...)

downloadModel(options: DownloadModelOptions) => Promise<DownloadModelResult>

Downloads a model from a URL and saves it to the appropriate location

• iOS: Downloads to the app's documents directory
• Android: Downloads to the app's files directory

Returns: Promise<DownloadModelResult>

addListener('textFromAi', ...)

addListener(eventName: 'textFromAi', listenerFunc: (event: TextFromAiEvent) => void) => Promise<{ remove: () => Promise<void>; }>

Adds a listener for text received from AI

Returns: Promise<{ remove: () => Promise<void>; }>

addListener('aiFinished', ...)

addListener(eventName: 'aiFinished', listenerFunc: (event: AiFinishedEvent) => void) => Promise<{ remove: () => Promise<void>; }>

Adds a listener for AI completion events

Returns: Promise<{ remove: () => Promise<void>; }>

addListener('generationError', ...)

addListener(eventName: 'generationError', listenerFunc: (event: GenerationErrorEvent) => void) => Promise<{ remove: () => Promise<void>; }>

Adds a listener for generation failures that happen after streaming starts

Returns: Promise<{ remove: () => Promise<void>; }>

addListener('downloadProgress', ...)

addListener(eventName: 'downloadProgress', listenerFunc: (event: DownloadProgressEvent) => void) => Promise<{ remove: () => Promise<void>; }>

Adds a listener for model download progress events

Returns: Promise<{ remove: () => Promise<void>; }>

addListener('readinessChange', ...)

addListener(eventName: 'readinessChange', listenerFunc: (event: ReadinessChangeEvent) => void) => Promise<{ remove: () => Promise<void>; }>

Adds a listener for readiness status changes

Returns: Promise<{ remove: () => Promise<void>; }>

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

ModelOptions

Model configuration options Only path is required. All other properties are optional overrides.

DownloadModelResult

Result of model download

DownloadModelOptions

Options for downloading a model Only url is required. companionUrl and filename are optional.

TextFromAiEvent

Event data for text received from AI

AiFinishedEvent

Event data for AI completion

GenerationErrorEvent

Event data for generation failures chatId is optional and may be omitted when the failure is not tied to a specific chat.

DownloadProgressEvent

Event data for download progress

ReadinessChangeEvent

Event data for readiness status changes

Example App

The repo includes an example-app/ that demonstrates:

• Apple Intelligence on iOS
• Gemma 4 LiteRT-LM model downloads on Android

See example-app/README.md for local setup instructions.