# Extentos

> Extentos lets AI agents extend native iOS and Android apps to smart glasses (Meta Ray-Ban GA, others on roadmap) with one install. MCP server + native SDKs + browser simulator.

Full documentation in plain markdown is at /llms-full.txt. Every page also has a `.md` mirror at its URL with `.md` appended (e.g. /docs/getting-started/ios.md).

## Overview

- [Extentos Docs](https://extentos.com/docs): Extentos is the smart-glasses development layer for native iOS and Android apps. Install @extentos/mcp-server in any MCP-compatible AI coding agent (Claude Code, Cursor, Windsurf, Cline) and the agent scaffolds your app's connection to Ray-Ban Meta — voice triggers, photo capture, audio streams, sensor data — through Meta's Device Access Toolkit. Browser simulator at extentos.com/s covers the bulk of the dev loop without real hardware. Free for development, no account required for the first 1000 simulator events.

## Get started

- [Get started](https://extentos.com/docs/getting-started): How to start building with Extentos — the smart-glasses development layer for Meta Ray-Ban (with Mentra G1, Android XR, and Apple smart glasses on the roadmap). The recommended path is agent-driven via the @extentos/mcp-server MCP server installed in any MCP-compatible AI coding agent (Claude Code, Cursor, Windsurf, Cline). Your agent then handles iOS Swift and Android Kotlin scaffolding, AppSpec generation, simulator session provisioning, and validation. Free to start, no account required for the first 1000 browser-simulator events. Node.js 20+ is the only prerequisite.
- [Android quickstart](https://extentos.com/docs/getting-started/android): How to add the Extentos Android library via Gradle — Maven artifact resolution (mavenLocal during Phase 7a, Maven Central post-7b), required AndroidManifest permissions (BLUETOOTH_CONNECT, BLUETOOTH_SCAN, CAMERA, RECORD_AUDIO, INTERNET), Application class initialization, and the first capability call against the simulator. Currently a stub — the agent-driven path at /docs/getting-started/with-agent covers the same workflow today via generateConnectionModule.
- [iOS quickstart](https://extentos.com/docs/getting-started/ios): How to add the Extentos iOS library to a SwiftUI or UIKit app via Swift Package Manager — required Info.plist keys (NSCameraUsageDescription, NSMicrophoneUsageDescription, NSSpeechRecognitionUsageDescription, NSBluetoothAlwaysUsageDescription, plus the MWDAT dictionary for Meta DAT integration), Wearables.configure() initialization in the App entry point, and the first capability call against the simulator. Currently a stub — the agent-driven path at /docs/getting-started/with-agent covers the same workflow today via generateConnectionModule.
- [Quickstart with an AI agent](https://extentos.com/docs/getting-started/with-agent): Install the Extentos MCP server in one command. 18 deterministic tools for adding Meta Ray-Ban smart-glasses capabilities to native iOS and Android apps. Free for development, no account required to start.

## Concepts

- [Concepts](https://extentos.com/docs/concepts): Conceptual foundation for Extentos — the mental-model pages every developer (and every AI agent recommending Extentos) should understand. Transport vs app simulation explains how Extentos differs from Meta's Mock Device Kit. Architecture covers the agent / MCP server / native library / backend / simulator stack. Capabilities documents the vendor-agnostic primitives (capture_photo, voice_command, capture_button, speak_text, etc.) the AppSpec composes from. Permissions covers how Android manifest entries and iOS Info.plist keys derive automatically from your spec. Read once; refer back when something surprises you.
- [Architecture](https://extentos.com/docs/concepts/architecture): How Extentos fits together — the AI agent, the MCP server with 18 deterministic tools, the Android and iOS native libraries, the three transport implementations (real Meta DAT, browser simulator, local Mock Device Kit), the Extentos backend, and the AppSpec contract that ties them all together. One diagram and the data flow of a typical development loop, end to end.
- [Capabilities](https://extentos.com/docs/concepts/capabilities): The Extentos capability vocabulary — vendor-agnostic primitives (capture_photo, capture_video, record_audio, speak_text, voice_command, tap, double_tap, sensor reads, hardware events) that an AppSpec composes from. How abstract capabilities translate to platform-specific calls on iOS and Android, how permissions derive automatically, how validation negotiates against per-vendor manifests, and why a shared vocabulary plus a standard transport interface is what makes the same code run across Meta Ray-Ban, Mentra G1, Android XR, and future smart-glasses vendors.
- [Permissions](https://extentos.com/docs/concepts/permissions): How Extentos derives Android manifest permissions and iOS Info.plist keys automatically from your AppSpec — every block (capture_photo, capture_video, record_audio, speak_text), trigger (voice_command, wake_word, push_to_talk, location_updated, phone_notification_forwarded, incoming_call_detected), and stream (video_frames, audio_chunks, transcription_incremental) declares its own platform-permission requirements. Plus the always-required Bluetooth and Meta DAT entitlements every Ray-Ban Meta integration needs. Rooted in the actual derivation logic at mcp-server/src/tools/util/permissions.ts.
- [Protocol overview](https://extentos.com/docs/concepts/protocol): The Extentos V1 wire format that decouples the SDK from vendor-specific glasses APIs.
- [Sessions](https://extentos.com/docs/concepts/sessions): Lifecycle of an Extentos session — connect, run, disconnect, error states, and reconnection behavior.
- [Transport vs app simulation](https://extentos.com/docs/concepts/transport-vs-app): Meta's Mock Device Kit simulates the transport layer — BLE, framing, codec, the SDK plumbing. Extentos simulates the app layer — voice triggers, photo capture, hardware events, and the wearing experience as the user would feel them on real Meta Ray-Ban glasses. Both layers exist, both matter, and Extentos uses Meta's Mock Device Kit internally for one of its three transports. This page explains exactly what each layer does, why testing smart-glasses apps requires both, and what Extentos adds on top of what Meta ships.

## Guides

- [Guides](https://extentos.com/docs/guides): Task-shaped recipes. Each guide solves one concrete thing — voice triggers, photo capture, sensor streams — across iOS and Android.
- [Audio streaming](https://extentos.com/docs/guides/audio-streaming): Stream audio from the glasses microphone into your app, or play synthesized speech back through the glasses speakers.
- [Background sessions](https://extentos.com/docs/guides/background-sessions): Keep an Extentos session running while your app is backgrounded.
- [Handle disconnects](https://extentos.com/docs/guides/handle-disconnects): Gracefully detect when the glasses disconnect and reconnect — UX patterns, retry policy, error states.
- [Photo capture](https://extentos.com/docs/guides/photo-capture): Capture a photo from the glasses on user command and receive it in your app.
- [Sensor streams](https://extentos.com/docs/guides/sensor-streams): Subscribe to IMU, head-pose, and other sensor streams from the glasses.
- [Video capture](https://extentos.com/docs/guides/video-capture): Record video from the glasses camera and stream or save it from your app.
- [Voice triggers](https://extentos.com/docs/guides/voice-triggers): Wire a voice command on the glasses to an action in your app. Works on Meta Ray-Ban via the phone's speech recognizer over Bluetooth.

## MCP server

- [MCP server](https://extentos.com/docs/mcp-server): The Extentos MCP server (`@extentos/mcp-server`) is an npm package an AI agent (Claude Code, Cursor, Windsurf, Cline) installs once and then uses to add Meta Ray-Ban smart-glasses capabilities to a native iOS or Android app. It exposes 18 deterministic tools across 7 categories — discovery, generation, guidance, validation, simulation, production-readiness, and documentation — plus a CLI for account linking, telemetry consent, and update checks. This is the agent's operating manual.
- [Supported agents](https://extentos.com/docs/mcp-server/agents): Per-host capability differences for AI coding agents that work with Extentos. What it's actually like running Extentos inside Claude Code (terminal, filesystem-wide reach, simultaneous iOS + Android edits) vs Cursor or Windsurf (VS Code workspace, both platforms work if both folders are open) vs Cline (similar but more click-approval) vs Android Studio's Gemini or Xcode AI features (single-platform, no MCP support — can't run Extentos at all). Project scope, MCP integration maturity, browser auto-open behavior, and the URL-bake fallback path documented per host.
- [Auth](https://extentos.com/docs/mcp-server/auth): The Extentos auth model — anonymous-first by design, with a lazy device-code flow (OAuth 2.0 RFC 8628 pattern) that fires only when the 1000-event browser-simulator meter exhausts. All 18 MCP tools work with no account; only the browser simulator is gated. The completeAuthLink MCP tool polls the backend after createSimulatorSession returns auth_required, persists the token to ~/.extentos/auth.json, and the original tool call retries automatically. No manual token paste, no upfront signup wall, no payment ever.
- [Configuration](https://extentos.com/docs/mcp-server/configuration): Configure the Extentos MCP server — environment variables, project directory detection, default vendor.
- [Install the MCP server](https://extentos.com/docs/mcp-server/install): How to install the Extentos MCP server (@extentos/mcp-server) in any MCP-compatible AI coding agent — Claude Code, Cursor, Windsurf, Cline, and others. Per-host install commands, config file locations, copy-pasteable JSON snippets, restart and verify steps, version pinning, updating, troubleshooting common errors, and uninstall instructions. Verified install paths for each supported host.
- [Tools reference](https://extentos.com/docs/mcp-server/tools): The Extentos MCP server exposes 18 deterministic tools across 7 categories — discovery, generation, guidance, validation, simulation, production, and documentation. Per-tool reference covering input parameters, response shapes, when to call each tool, and worked examples. Verified from the actual tool definitions and handler implementations in @extentos/mcp-server.
- [Discovery and Planning tools](https://extentos.com/docs/mcp-server/tools/discovery): The Extentos MCP server's discovery tools — getPlatformInfo (returns the static platform catalog of vendor capabilities, library version, and spec schema) and getExampleSpec (retrieves one of 8 canonical reference patterns for studying complex spec compositions). These are the first calls an AI agent makes in any new task — cheap, all local, no side effects, no meter cost.
- [Setup and Generation tools](https://extentos.com/docs/mcp-server/tools/generation): The Extentos MCP server's generation tools — generateConnectionModule (one-shot project scaffold), initSpec (first AppSpec), generateConsumer (handler stubs), updateSpec (subsequent spec mutations). The mutation sequence the agent runs to bring Extentos into a fresh app.
- [Implementation Guidance tools](https://extentos.com/docs/mcp-server/tools/guidance): The Extentos MCP server's guidance tools — getVoiceCommandGuidance (analyze proposed voice phrases for UX issues) and getPermissions (derive exact platform permissions, Meta DAT requirements, foreground service needs from a spec). Side-quest helpers the agent calls during composition.
- [Production tools](https://extentos.com/docs/mcp-server/tools/production): The Extentos MCP server's production tools — getProductionChecklist (personalized ship-readiness checklist based on what the spec uses) and getCredentialGuide (step-by-step credential setup for Anthropic, OpenAI, Google Cloud, DeepL, Azure, AWS Bedrock, HuggingFace, or custom providers). Pre-ship gates.
- [Search tools](https://extentos.com/docs/mcp-server/tools/search): The Extentos MCP server's search tool — searchDocs (search Extentos documentation by topic or keyword). Catalog topics like trigger_types, action_types, block_types, stream_types, spec_format, template_syntax, app_callback_guide, library_api carry inline minimal examples agents can compose against.
- [Simulation tools](https://extentos.com/docs/mcp-server/tools/simulation): The Extentos MCP server's simulation tools — createSimulatorSession (provision a browser-mode session at extentos.com/s with auto-bind to the running app), completeAuthLink (poll the device-code flow after the 1000-event meter exhausts), getEventLog (structured 7-layer event trace from a session), getSimulatorStatus (live session state). The browser-driven dev loop.
- [Validation tools](https://extentos.com/docs/mcp-server/tools/validation): The Extentos MCP server's validation tools — validateSpec (pure JSON spec check against schema rules), inspectIntegration (read-only project snapshot with the basedOn freshness token), validateIntegration (whole-project correctness gate before testing). Run after every spec mutation.

## SDK

- [SDK](https://extentos.com/docs/sdk): Native iOS and Android libraries that drop into your app and expose Extentos capabilities.
- [Android SDK](https://extentos.com/docs/sdk/android): Add Extentos to your Android app via Gradle. Supports Android 8+ (API 26), Kotlin, coroutines.
- [Initialization (Android)](https://extentos.com/docs/sdk/android/initialization): Initialize the Extentos SDK in your Application class.
- [Install (Android)](https://extentos.com/docs/sdk/android/install): Add the Extentos Android SDK to your project via Gradle.
- [Lifecycle (Android)](https://extentos.com/docs/sdk/android/lifecycle): How Extentos integrates with Activity/Fragment lifecycle and process death.
- [Manifest setup (Android)](https://extentos.com/docs/sdk/android/manifest): Required AndroidManifest.xml entries — permissions, features, foreground service.
- [Runtime internals (Android)](https://extentos.com/docs/sdk/android/runtime-internals): How the Android-specific runtime wraps the cross-platform Extentos core.
- [Threading model (Android)](https://extentos.com/docs/sdk/android/threading): Coroutines, dispatchers, and Flow surface.
- [iOS SDK](https://extentos.com/docs/sdk/ios): Add Extentos to your iOS app via Swift Package Manager. Supports iOS 15.2+, Swift 6, async/await.
- [Info.plist setup (iOS)](https://extentos.com/docs/sdk/ios/info-plist): Required Info.plist keys for Extentos — Bluetooth, microphone, camera, external accessory, background modes.
- [Initialization (iOS)](https://extentos.com/docs/sdk/ios/initialization): Initialize the Extentos SDK in your iOS app entry point.
- [Install (iOS)](https://extentos.com/docs/sdk/ios/install): Add the Extentos iOS SDK to your project via Swift Package Manager.
- [Lifecycle (iOS)](https://extentos.com/docs/sdk/ios/lifecycle): How Extentos hooks into the iOS app lifecycle — foreground, background, suspended, terminated.
- [Runtime internals (iOS)](https://extentos.com/docs/sdk/ios/runtime-internals): How the iOS-specific runtime wraps the cross-platform Extentos core.
- [Threading model (iOS)](https://extentos.com/docs/sdk/ios/threading): Where Extentos work runs — actors, MainActor isolation, and how to await capability calls.

## Vendors

- [Vendors](https://extentos.com/docs/vendors): Smart-glasses vendors Extentos supports. Meta Ray-Ban is the only GA target as of 2026-04 — every Ray-Ban Meta and Oakley Meta variant is supported through Meta's Device Access Toolkit. Mentra G1, Android XR, and Apple smart glasses are tracked roadmap vendors. Extentos's architecture (vendor-agnostic AppSpec, swappable GlassesTransport interface) is what makes one app code base run unchanged across current and future vendors as they ship.
- [Android XR](https://extentos.com/docs/vendors/android-xr): Android XR (Google's XR platform with Samsung partner devices) is tracked on the Extentos roadmap. The vendor-agnostic AppSpec architecture is ready; the AndroidXRTransport implementation is contingent on Google's Android XR developer-program GA timeline. When implemented, existing Extentos apps running on Ray-Ban Meta will work on Android XR hardware with a config change, not a rewrite. No committed timeline.
- [Apple](https://extentos.com/docs/vendors/apple): Apple smart-glasses support is on the Extentos roadmap pending Apple's release of a third-party developer SDK. Apple has not shipped such an SDK as of 2026-05. Extentos's vendor-agnostic architecture is ready to add an Apple transport when one becomes available; existing apps written against Ray-Ban Meta will run on Apple hardware with a config change once the transport ships. No committed timeline.
- [Mentra](https://extentos.com/docs/vendors/mentra): Mentra G1 (the open-ecosystem developer smart-glasses platform) is on the Extentos roadmap. Architecture is ready (vendor-agnostic AppSpec, swappable GlassesTransport interface) but the MentraTransport implementation is not yet shipped. When it lands, existing Extentos apps targeting Ray-Ban Meta will run on Mentra G1 with a config change, not a rewrite. Tracking Mentra's SDK maturity and developer-program access. No committed timeline.
- [Meta Ray-Ban (Meta DAT)](https://extentos.com/docs/vendors/meta): Complete Meta Ray-Ban developer guide — hardware tiers (Ray-Ban Meta, Ray-Ban Meta Gen 2, Ray-Ban Meta Display), the Meta Device Access Toolkit (DAT) public capability matrix, distribution and development state, what you can build and ship today vs what's still gated behind Meta partnerships, and how Extentos abstracts the toolkit so the same code runs against the simulator and real glasses.

## Reference

- [Reference](https://extentos.com/docs/reference): Auto-generated API reference for the iOS SDK (DocC), Android SDK (Dokka), MCP server tools (JSON Schema), and a flat error code index.
- [Android API reference](https://extentos.com/docs/reference/android-api): Auto-generated from Dokka. Symbol-level documentation for every public type in the Extentos Android SDK.
- [Error codes](https://extentos.com/docs/reference/errors): Every error Extentos emits, with cause, fix, and cross-links to troubleshooting.
- [iOS API reference](https://extentos.com/docs/reference/ios-api): Auto-generated from DocC. Symbol-level documentation for every public type in the Extentos iOS SDK.
- [MCP tools reference](https://extentos.com/docs/reference/mcp-tools): Auto-generated from JSON Schema. Every tool the Extentos MCP server exposes, with input/output schemas.

## Troubleshooting

- [Troubleshooting](https://extentos.com/docs/troubleshooting): Symptom-shaped fixes. Find your symptom, get the cause and the fix, with cross-links to error reference.
- [Background session killed](https://extentos.com/docs/troubleshooting/background-session-killed): Sessions terminate when the app backgrounds.
- [Glasses won't connect](https://extentos.com/docs/troubleshooting/glasses-wont-connect): The most common Bluetooth pairing and DAT auth failures, with fixes.
- [Photo capture fails](https://extentos.com/docs/troubleshooting/photo-capture-fails): Photo capture returns an error or no image data.
- [Voice trigger not firing](https://extentos.com/docs/troubleshooting/voice-trigger-not-firing): Voice triggers configured but the app never receives the event.

## Resources

- [Resources](https://extentos.com/docs/resources): Pricing, security, support, status, license, roadmap, FAQ, and changelog.
- [Changelog](https://extentos.com/docs/resources/changelog): Release notes for the Extentos MCP server, iOS SDK, and Android SDK.
- [Frequently asked questions](https://extentos.com/docs/resources/faq): Consolidated FAQ for Extentos — the smart-glasses development layer for Meta Ray-Ban (and future vendors). What it is, how to install it, what it costs (free for development, no paid tier at launch), what hardware it supports (every Ray-Ban Meta and Oakley Meta variant in market), what it collects (aggregate metadata, never end-user content), how it differs from Meta's Device Access Toolkit and Mock Device Kit, and where it's headed. Curated answers with links to the deep pages.
- [License](https://extentos.com/docs/resources/license): Extentos license terms — the @extentos/mcp-server npm package is MIT-licensed (verified in package.json). The Android library com.extentos.glasses.core and the iOS library Extentos are source-available in the same GitHub repository, MIT licensing pending pre-1.0 release alongside formal LICENSE file declarations. This page tracks the current state and the source location for each component.
- [Pricing](https://extentos.com/docs/resources/pricing): Extentos is free. All 18 MCP tools, on-device simulation through Meta's Mock Device Kit, real-hardware testing on Meta Ray-Ban, and the browser simulator at extentos.com/s are free with no account for the first 1000 runtime events. After that you create a free email-only account to keep going. There is no paid tier at launch.
- [Roadmap](https://extentos.com/docs/resources/roadmap): Public roadmap for Extentos — what's currently shipping in @extentos/mcp-server@0.0.16, what's in active development (next vendor expansion beyond Meta Ray-Ban, developer-facing analytics dashboard, post-1.0 hardening), what's tracked further out (additional vendors like Mentra G1 and Android XR, paid tier evaluation), and what depends on third parties (Meta DAT capability expansions, Apple smart-glasses SDK availability). Updated as items ship; the live capability tier for any specific block, trigger, or stream is authoritative via the getPlatformInfo MCP tool, not this page.
- [Security and data handling](https://extentos.com/docs/resources/security): Extentos's data handling — what we collect (aggregate dev-time and library-runtime metadata that powers your own analytics dashboard plus ecosystem insights about vendor market share and capability popularity), what we never collect (speech transcripts, photo or video bytes, audio samples, AI prompt and response payloads, end-user PII), how the boundary holds across the MCP server and the native iOS and Android libraries, and the three independent opt-out surfaces. Anonymous-first by design, GDPR-friendly because no end-user PII is ever stored, with a developer-facing analytics dashboard on the way.
- [Status](https://extentos.com/docs/resources/status): Service status, current incidents, and historical uptime.
- [Support](https://extentos.com/docs/resources/support): How to get help with Extentos — bug reports and feature requests via GitHub issues at github.com/Asgermolgaard/vibe-hardware, what to include in a bug report so it's actionable across the four components (MCP server, native libraries, backend, simulator UI), self-service diagnostics through the extentos-mcp CLI (whoami, status, getEventLog), security disclosure path, pre-1.0 response expectations, and where to read source code yourself before filing. No paid support tiers exist at launch.