pocketpal-ai README

项目的 README,来自 github.com/a-ghorbani/pocketpal-ai。合并为一个 markdown 文件:README.md。

PocketPal AI logo

PocketPal AI

A private AI assistant that runs entirely on your phone.

Chat with language models, give them a voice, and let them use tools — all on-device. No account, no cloud, no internet required.

pocketpal.dev · Get the app · Leaderboard · PalsHub · Discussions


App Store Google Play

Latest release License: MIT Stars Open issues Sponsor


Why PocketPal AI?

Most AI apps are a thin window onto someone else's server — every message you type gets shipped off, logged, and analyzed somewhere you can't see. PocketPal flips that around: the AI lives on your phone, and your conversations stay on it unless you choose an online feature.

Privacy note: Your chats and documents leave your device only through features you turn on: web search and page reading, a remote server, or a system voice your phone runs online. The app's other network use (model and voice downloads, PalsHub and purchases, device-compatibility rules from the jsDelivr CDN at launch, the opt-in benchmark leaderboard, and feedback or reports you submit) never attaches your chats.

Contents

Features

Get the app

Platform
iOS / iPadOS Download on the App Store
Android Get it on Google Play

Three steps to your first chat:

  1. Install PocketPal from the App Store or Google Play.
  2. Download a model — tap the menu (☰) → Models, pick one that fits your phone, and download (or add one from Hugging Face).
  3. Load it and start chatting — that's it, you're running AI fully offline.

How it works

You don't need to know any of this to use PocketPal — but if you're curious how a phone runs real AI offline, here's the short version.

PocketPal is a four-layer stack, from the silicon up to the chat UI. Each layer has one job, and the dependency direction is strictly top-down — the JS app talks to native bridges, bridges talk to inference engines, engines target hardware backends.

PocketPal AI on-device stack — UI & Tool Use → Bridging → Engine → Hardware
Layer What runs here
UI & Tool Use The React Native app (UI via React Native Paper, state via MobX, chat history in WatermelonDB). The AgentRunner drives each chat turn — streaming tokens, dispatching Talents (tools) when the model calls them, and feeding results back for follow-up reasoning. Pals are configurable personas; PalsHub is the in-app marketplace for sharing and buying them. In voice mode, your speech is transcribed, answered as a normal chat turn, and the reply is spoken back.
Bridging Native modules that connect JavaScript to the engines. llama.rn bridges LLM inference over JSI; whisper.rn bridges speech recognition; @pocketpalai/react-native-speech and onnxruntime-react-native bridge text-to-speech, with the @pocketpalai/react-native-speech-phonon add-on for Phonon.
Engine The inference engines. llama.cpp runs language models in the quantized GGUF format. whisper.cpp runs Whisper speech recognition models in the GGML format. ONNX Runtime runs the Kokoro, Kitten and Supertonic voice models in the ONNX format. Phonon runs natively in its own Rust runtime: a GGUF model on the CPU on Android, a Core ML model on iOS.
Hardware Where the math actually happens. PocketPal targets CPU (universal fallback), GPU (Metal on iOS, OpenCL on Qualcomm Adreno for Android), and NPU (Qualcomm Hexagon, and the Apple Neural Engine for Phonon on iOS) — falling back gracefully and offloading partial layers when a full backend isn't available.

Using the app

📥 Download & load a model
  1. Open the app and tap the Menu (☰), then go to Models.
  2. Pick a model from the list and tap Download, or tap + to add one from Hugging Face or local storage.
  3. From Hugging Face, search GGUF models and choose a quantization that fits your device's memory and storage — download now or bookmark for later.
  4. After downloading, tap Load (or use the chevron icon left of the chat input to load right from the chat screen).
Download Models
💬 Chat
  1. Make sure a model is loaded.
  2. Open the Chat page and start talking.
  3. The screen stays awake during inference and deactivates when idle.
  4. Copy a full response with the copy icon, or long-press a paragraph to copy just that.
  5. Edit any of your messages with a long-press — the AI regenerates from your change. Hit retry for a fresh answer, optionally with a different model.
Chat
🎭 Pals & PalsHub

Create personalized assistants:

  • Assistant Pal — pick a default model, set a system prompt (write it yourself or have the app generate one), and customize the chat input color.
  • Roleplay Pal — everything above, plus location, the AI's role, and other contextual parameters.

Switch personas with the Pal picker on the chat page. Browse PalsHub in-app to discover community Pals, including premium ones via in-app purchase.

Assistant Pal

Creating a cocktail-recipe assistant

📊 Benchmark your device
  1. Open the Benchmark page.
  2. Run performance tests to compare speed and efficiency across models.
  3. Review tokens/sec and memory usage.
  4. Optionally share your results to the AI Phone Leaderboard.
Benchmark
🔑 Set up a Hugging Face token (for gated models)
  1. Create an access token in your Hugging Face account (docs).
  2. In PocketPal, go to Settings → Set Token, paste it, and save.
Token setup
💌 Send feedback

Go to App Info → "Sharing your thoughts", type your feedback — feature requests, suggestions, anything — and submit.

Send feedback

For developers

PocketPal is a standard React Native app. If you can build a React Native project, you can build PocketPal.

Prerequisites

See the React Native environment setup for platform details.

Clone, install & run

git clone https://github.com/a-ghorbani/pocketpal-ai
cd pocketpal-ai

nvm use                       # match the pinned Node version
yarn install                  # install JS dependencies
(cd ios && pod install)       # iOS only

yarn start                    # Metro bundler
yarn ios                      # build + run on iOS simulator
yarn android                  # build + run on Android emulator

Core on-device chat works without any backend keys; only PalsHub/auth features need additional configuration.

Native-change rule: if you change package.json, a native module, ios/, android/, the Podfile, or build.gradle, re-run pod install and rebuild both platforms — a JS reload won't pick up native changes.

Quality gates

yarn lint           # ESLint
yarn typecheck      # tsc --noEmit
yarn test           # Jest
yarn l10n:validate  # validate locale JSON (placeholders, integrity)
yarn test:perf      # render-performance tests (Reassure)
yarn test:perf:compare [base]  # render counts of HEAD vs. base (default: merge-base with origin/main)

Run yarn lint && yarn typecheck && yarn test before opening a PR. Pull requests also run the render-count comparison; see render-performance tests. Commits are validated by Commitlint (Conventional Commits) via a Husky hook.

Repository layout
src/
├── screens/        # Chat, Models, Pals, Benchmark, Settings, Plus, About, …
├── components/     # Reusable UI
├── store/          # MobX stores (Model, ChatSession, Pal, TTS, ASR, VoiceMode, HF, Benchmark, …)
├── services/
│   ├── agent/      # AgentRunner — the chat / tool loop
│   ├── talents/    # Tool engines + registries
│   ├── search/     # Web search providers for the search talents
│   ├── tts/        # TTS engines (kokoro, kitten, supertonic, phonon, system)
│   ├── asr/        # Whisper speech recognition (dictation and voice mode)
│   ├── voice/      # Hands-free voice mode
│   ├── plus/       # Plus feature catalog and gate
│   ├── iap/        # In-app purchases (store bridge)
│   ├── palshub/    # PalsHub marketplace integration
│   ├── deviceRules/ # Device-compatibility rules: parse, classify, launch-time fetch
│   └── downloads/  # Model download manager
├── database/       # WatermelonDB schema, models, migrations
├── repositories/   # Data-access layer over the DB
├── locales/        # i18n JSON + lazy loader (index.ts is the registry)
└── hooks/  api/  theme/  utils/  config/  specs/
Tech stack

Versions are pinned in package.json; the highlights:

Area Choice
Framework React Native 0.87.1, React 19.2.3 (New Architecture)
Language TypeScript 5.9.3
UI React Native Paper 5.15.3, React Navigation
State MobX 6 (mobx, mobx-react, mobx-persist-store)
Persistence WatermelonDB (chat history), AsyncStorage (settings), Keychain (secrets)
LLM llama.rn 0.13.0-rc.11 → llama.cpp b12292 · GGUF
ASR whisper.rn 0.7.4 → whisper.cpp · GGML; mic via @fugood/react-native-audio-pcm-stream 1.1.4
TTS @pocketpalai/react-native-speech 2.8.2 + onnxruntime-react-native ^1.23.2 · ONNX; @pocketpalai/react-native-speech-phonon 0.1.3
Tooling Yarn 1 (Classic), ESLint, Prettier, Jest, Husky + Commitlint
Extending PocketPal

A Talent is a tool the model can call mid-conversation. Engines are registered in a TalentRegistry, exposed to the model as tool schemas; the AgentRunner detects a call, runs the engine, and returns the result for the next turn.

Talent Engine Does
calculate CalculateEngine Arithmetic / expression evaluation
datetime DatetimeEngine Current date / time
render_html RenderHtmlEngine Renders model-produced HTML in chat
web_search WebSearchEngine Searches the web (opt-in; needs a configured provider)
read_url ReadUrlEngine Reads a web page from search results, a site you named, or a link on a page it read (opt-in; needs a configured provider)

Good first contributions:

  • A new Talent — implement a TalentEngine and register it in src/services/talents/.
  • A new TTS engine — model it on an existing engine in src/services/tts/engines/, register it in engineRegistry.ts, wire it into TTSStore, then search src/ for that engine's name, ignoring case, to find every other entry it needs, such as its type, constants, setup-sheet entries and strings.
  • A new locale — translate on Weblate; registering a new language in the app follows the steps in src/locales/index.ts.

Contributing

Contributions are welcome — bug reports, fixes, features, translations, and docs all help.

  1. Fork and branch: git checkout -b feature/your-feature-name
  2. Make your changes; run on a device/emulator (yarn ios / yarn android). Re-run pod install + rebuild if you touched native code.
  3. Gate locally: yarn lint && yarn typecheck && yarn test
  4. Commit with Conventional Commits: git commit -m "feat: add new talent"
  5. Push and open a pull request.

Please read the Contributing Guidelines and Code of Conduct first. Want to translate PocketPal into your language? Join us on Weblate.

Roadmap

Have an idea or found a bug? Open an issue or start a discussion.

Community & support

License

Licensed under the MIT License.

Acknowledgements

PocketPal AI stands on the shoulders of the open-source community, including:


Made with ❤️ for people who want AI that stays on their phone.


If PocketPal is useful to you, consider giving it a ⭐ — it helps others find the project.

pocketpal-ai (a-ghorbani/pocketpal-ai)

正在搜索数据库…

这是什么?PocketPal AI 是一款免费的开源应用,可直接在手机上运行语言模型,让你无需账号、离线、私密地与 AI 聊天。
这是手机应用,还是可以接入我自己代码的库?这是一款成品移动应用,适用于 iOS、iPadOS 和 Android,基于 React Native 开发。你可以从 App Store 或 Google Play 安装,无需编写任何代码。
我该怎么让它运行起来?从 App Store 或 Google Play 安装 PocketPal。然后点击菜单(☰),进入「模型」,选择适合你手机的模型并下载,再点击「加载」。无需注册账号。
有什么可能会让我踩坑的地方?硬件决定了使用上限。更大的模型需要更多内存,因此请选择与手机 RAM 和存储空间相匹配的量化版本。「基准测试」页面会显示你的设备运行每个模型的速度。
它在平板上也能用吗,还是只支持手机?手机和平板都支持,并且完整支持 iPad。界面提供 16 种语言。
没有网络也能用吗?可以。下载一次模型后,聊天功能完全离线可用,无需账号,在飞机上或任何没有网络的地方都能使用。
它真的免费且开源吗?是的,采用 MIT 许可证。聊天、模型、语音和工具均免费使用,无需账号。唯一收费的是可选的一次性购买项目 PocketPal Plus,仅在 App Store 和 Google Play 版本中提供,它增加了免提语音和本地 API 服务器功能。
它会使用我手机的 GPU 或 NPU 吗?会。它可以在 iOS 上使用 Metal,在 Android 上使用 Qualcomm Adreno 的 OpenCL,也可以使用 Qualcomm Hexagon NPU。如果某个后端不可用,则会退回到 CPU。
什么是 PocketPal Plus?这是在 App Store 和 Google Play 版本中提供的可选一次性购买项目,可增加免提语音对话和本地 API 服务器功能。源码编译版本,以及后续发布版本中的 GitHub APK 均包含该功能。
什么是 Talents?内置工具,例如计算器、日期和时间、HTML 渲染,以及需要手动开启的网页搜索和网页读取功能。能力较强的 Pal 可以在对话过程中调用这些工具。
什么是 Pals 和 PalsHub?Pals 是个人助手,每个都有自己的模型、系统提示词和个性。PalsHub 是应用内的市场,你可以在这里找到并安装社区 Pals,其中一些是付费的。
我可以使用需要授权的 Hugging Face 模型吗?可以。在「设置」中添加你的 Hugging Face 访问令牌,之后就能直接从 Hub 搜索并下载 GGUF 模型,包括需要授权才能访问的模型。
大小
52.7 MB
星标
9.5K
时长
2年
提交 · 90 天