Getting Started
Getting Started
Note: Part of this guide is outdated. It will be updated soon.
Installation
iPhone users can grab it here: PocketPal AI on the App Store
Android users can get it from here: PocketPal AI on Google Play
Note: This is a personal project, so I am working on it in my spare time. It might have bugs and issues, and obviously, I have not tested it on all devices. If you encounter any issues, open an issue, or even better, contribute to the project!
Available Models
PocketPal AI comes pre-configured with some popular SLMs:
- Danube 2 and 3
- Phi
- Gemma 2
- Qwen
Modells need to be downloaded before use. You can download and use these models directly from the app and load any other GGUF models you like!
<div style="display: flex; justify-content: center;">
<img src="../assets/models_page.webp" alt="Models Page" style="width: 33%;">
</div>
Using PocketPal AI
Downloading a Model
- Tap the burger menu
- Navigate to the “Models” page
- Choose your desired model and hit download
<div style="display: flex; justify-content: center;">
<img src="../assets/add_model_1.webp" alt="Navigate to Models Page" style="width: 33%;">
<img src="../assets/add_model_2.webp" alt="Download a Model" style="width: 33%;">
<img src="../assets/add_model_3.webp" alt="Load a Model" style="width: 33%;">
</div>
Loading a Model
After downloading, tap Load to bring the model into memory. Now you’re ready to chat!
Tips
On iOS devices, Apple’s GPU API (Metal) is activated by default. If you experience any hiccups, try deactivating it.
#### iOS Metal
#### Auto Offload/Load
To keep the device running smoothly, PocketPal AI can automatically manage memory usage:
- Enable “Auto Offload/Load” on the model page (by default it is)
- The app will offload the model when in the background
- It’ll reload when you return (give it a few seconds for larger models)
#### Advanced Settings
Click the chevron icon to access advanced LLM settings like:
- Temperature
- BOS token
- Chat template options
- etc.
<div style="display: flex; justify-content: center;">
<img src="../assets/model_config_1.webp" alt="Navigate to Models Page" style="width: 33%;">
<img src="../assets/model_config_2.webp" alt="Download a Model" style="width: 33%;">
<img src="../assets/model_load.webp" alt="Load a Model" style="width: 33%;">
</div>
Finally, Let’s Chat!
Once your model is loaded, head to the “Chat” page and start conversing with the loaded model!
The generation performance metric is also displayed. If interested, watch the chat bubble for real-time performance metrics: Tokens per second and Milliseconds per token.
<div style="display: flex; justify-content: center;">
<img src="../assets/chat_1.webp" alt="Navigate to Models Page" style="width: 33%;">
<img src="../assets/chat_2.webp" alt="Download a Model" style="width: 33%;">
</div>
Copying Text
Important Note: As of now, I haven’t found an easy way to select and copy text from the generated responses while preserving the text formatting, particularly Markdown support.
In the meantime, here are the current options for copying text:
- Paragraph-level copying: Long-press on a specific paragraph to copy its content.
- Full response copying: Use the copy icon at the bottom of the text bubble to copy the entire AI-generated response.
I know these options might not be ideal, and this is one of my frustrations with using other apps. The difficulty of copying portions of text used to be a particularly annoying aspect of chat apps like ChatGPT and others.
Developers: PocketPal AI is built using React Native. Finding an easy solution that balances text selection with preserved formatting (especially Markdown support) has been tricky for me. If you have experience in this area, I’d love to hear from you!
Feedback Welcome!
If you have suggestions for new models or features, please let us know by creating an issue.
Happy exploring! 🚀📱✨
---
CONTRIBUTING
Contributing
Thank you for your interest in contributing! We welcome all contributions, from bug reports and feature requests to code changes. Please feel free to put up a PR for any issue or feature request.
Code of Conduct
Please be respectful to others in all interactions related to this project. We expect contributors to adhere to the code of conduct.
Creating issues
If you find any bugs, have suggestions for improvements, or encounter unexpected behavior, please open an issue.
Creating an issue before submitting a PR helps us discuss the problem or feature request in advance.
Submitting Pull Requests
We are grateful for any pull requests! To ensure a smooth contribution process, please follow these steps:
Workflow for Contributing
1. Fork this repository.
2. Clone your fork
3. Create a new branch
4. Make your changes: Implement your feature, fix the issue, or improve the code.
5. Test your changes: Please make sure your changes are tested locally (for all affected devices).
Testing Your Changes
We highly encourage testing your changes before submitting a pull request.
- Run the Metro server:
yarn start:reset- Run the app on iOS:
yarn ios- Run the app on Android:
yarn androidLinting and Type Checking
Make sure your code passes the lint and type check processes:
- Lint your code with ESLint:
yarn lint- Type check your code with TypeScript:
yarn typecheckWriting Tests
Please add tests for any new features or changes. We use Jest for unit testing:
- Run tests:
yarn testIf your changes affect the app's behavior, ensure you include or update tests as appropriate.
Translations (Localization)
PocketPal uses Weblate for managing translations. When adding or changing user-facing strings:
- Only edit src/locales/en.json (the English source file). Do not edit ja.json, zh.json, or other language files directly — they are managed by translators through Weblate and will be overwritten.
- Use {{placeholder}} syntax (double braces) for dynamic values, e.g. "Imported {{count}} sessions".
- Run yarn l10n:validate to check that your JSON is valid and placeholders are consistent.
To contribute translations, visit PocketPal on Weblate — no code changes needed.
Commit Message Guidelines
We follow the Conventional Commits specification for our commit messages to ensure clarity and consistency. Use one of the following prefixes for your commits:
- feat: New features (e.g., feat: add new model support functionality).
- fix: Bug fixes (e.g., fix: resolve crash on app startup).
- docs: Documentation changes (e.g., docs: update README.md).
- chore: Refactoring, tooling, testing, or configuration changes (e.g., chore: update CI pipeline).
Opening a Pull Request
1. Commit your changes following the commit message guidelines.
2. Push your branch to your fork.
3. Open a pull request from your branch in your fork to the main branch of this repository.
4. Follow the pull request template and fill in all relevant details.
Before opening a pull request, make sure:
- Your changes are focused and kept to a single logical change.
- Your code is linted and passes type checks.
- Tests are added or updated if applicable.
---
README
<div align="center">
<img src="src/assets/pocketpal-dark-v2.png" alt="PocketPal AI logo" width="120" />
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.
<a href="https://pocketpal.dev/"><strong>pocketpal.dev</strong></a> ·
<a href="#get-the-app">Get the app</a> ·
<a href="https://pocketpal.dev/leaderboard">Leaderboard</a> ·
<a href="https://palshub.ai/">PalsHub</a> ·
<a href="https://github.com/a-ghorbani/pocketpal-ai/discussions">Discussions</a>
<br/>
[](https://apps.apple.com/us/app/pocketpal-ai/id6502579498)
[](https://play.google.com/store/apps/details?id=com.pocketpalai)
[](https://github.com/a-ghorbani/pocketpal-ai/releases)
[](LICENSE)
[](https://github.com/a-ghorbani/pocketpal-ai/stargazers)
[](https://github.com/a-ghorbani/pocketpal-ai/issues)
[](https://github.com/sponsors/a-ghorbani)
</div>
---
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 never leave it.
- 🔒 Private by default — every prompt, response, and document stays on your device. Nothing is uploaded or stored on external servers.
- ✈️ Works offline — download a model once and it just works, with no connection and no account. On a plane, on a trail, anywhere.
- 📱 Runs on hardware you already own — real language models, voices, and tools, tuned to make the most of your phone's CPU, GPU, and NPU.
- 🆓 Free and open source — no subscription, no "pro" tier to unlock the AI. MIT-licensed and built in the open.
Privacy note: The only data that ever leaves your device is what you explicitly choose to share — benchmark results (if you opt into the leaderboard) and feedback you submit through the app.
Contents
- Features
- Get the app
- How it works
- Using the app
- For developers
- Contributing
- Roadmap
- Community & support
- License
Features
- 🧠 On-device chat — run GGUF language models (Gemma, Qwen, Phi, Llama, and more) fully offline.
- 🗣️ Text-to-speech — give your assistant a voice with on-device neural TTS (Kokoro and other engines), no cloud calls.
- 🎭 Pals — create personalized assistants with their own model, system prompt, and personality (Assistant and Roleplay types).
- 🛍️ PalsHub — discover and install community Pals, including premium ones via in-app checkout.
- 🛠️ Talents & tools — let capable Pals call built-in tools (calculator, date/time, rich HTML rendering) inside a tool-use loop.
- 📥 Hugging Face integration — search and download GGUF models, including gated ones, directly from the HF Hub with your access token.
- 📊 Benchmarking — measure tokens/sec and memory, and optionally compare on the AI Phone Leaderboard.
- ⚡ Hardware acceleration — CPU, GPU (Metal on iOS, OpenCL/Adreno on Android), and NPU (Qualcomm Hexagon) inference paths, with graceful fallback.
- 🌍 Localized — available in 11 languages, on phones and tablets, including full iPad support.
Get the app
| Platform | |
| --- | --- |
| iOS / iPadOS | [](https://apps.apple.com/us/app/pocketpal-ai/id6502579498) |
| Android | [](https://play.google.com/store/apps/details?id=com.pocketpalai) |
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.
<div align="center">
<img src="assets/images and logos/stack-diagram-dark.png" alt="PocketPal AI on-device stack — UI & Tool Use → Bridging → Engine → Hardware" width="100%">
</div>
| 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. |
| Bridging | Native modules that connect JavaScript to the engines. llama.rn bridges LLM inference over JSI; react-native-speech and onnxruntime-react-native bridge text-to-speech. |
| Engine | The inference engines. llama.cpp runs language models in the quantized GGUF format. ONNX Runtime runs TTS voice models in the ONNX format. |
| 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) — falling back gracefully and offloading partial layers when a full backend isn't available. |
Using the app
<details>
<summary><strong>📥 Download & load a model</strong></summary>
<br/>
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).
<img src="assets/images and logos/Download_models.png" alt="Download Models" width="100%">
</details>
<details>
<summary><strong>💬 Chat</strong></summary>
<br/>
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.
<img src="assets/images and logos/Chat.png" alt="Chat" width="83%">
</details>
<details>
<summary><strong>🎭 Pals & PalsHub</strong></summary>
<br/>
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 checkout (US iOS & Android).
<img src="assets/images and logos/Pals.png" alt="Assistant Pal" width="100%">
<p><em>Creating a cocktail-recipe assistant</em></p>
</details>
<details>
<summary><strong>📊 Benchmark your device</strong></summary>
<br/>
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.
<img src="assets/images and logos/Benchmark.png" alt="Benchmark" width="100%">
</details>
<details>
<summary><strong>🔑 Set up a Hugging Face token (for gated models)</strong></summary>
<br/>
1. Create an access token in your Hugging Face account (docs).
2. In PocketPal, go to Settings → Set Token, paste it, and save.
<img src="assets/images and logos/Token_in_pocketpal.png" alt="Token setup" width="66%">
</details>
<details>
<summary><strong>💌 Send feedback</strong></summary>
<br/>
Go to App Info → "Sharing your thoughts", type your feedback — feature requests, suggestions, anything — and submit.
<img src="assets/images and logos/Send_Feedback.png" alt="Send feedback" width="50%">
</details>
For developers
PocketPal is a standard React Native app. If you can build a React Native project, you can build PocketPal.
Prerequisites
- Node.js — version is pinned in .nvmrc (currently 22.21.0); run nvm use to match it. Older Node will fail the engines check.
- Yarn 1 (Classic) — packageManager is pinned to [email protected].
- Xcode + CocoaPods, and Ruby + Bundler (for iOS / Fastlane tooling).
- Android Studio + Android SDK/NDK.
See the React Native environment setup for platform details.
Clone, install & run
git clone https://github.com/a-ghorbani/pocketpal-ai
cd pocketpal-ainvm 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 changepackage.json, a native module,ios/,android/, the Podfile, orbuild.gradle, re-runpod installand 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)Run yarn lint && yarn typecheck && yarn test before opening a PR. Commits are validated by Commitlint (Conventional Commits) via a Husky hook.
<details>
<summary><strong>Repository layout</strong></summary>
<br/>
src/
├── screens/ # Chat, Models, Pals, Benchmark, Settings, About, …
├── components/ # Reusable UI
├── store/ # MobX stores (Model, ChatSession, Pal, TTS, HF, Benchmark, …)
├── services/
│ ├── agent/ # AgentRunner — the chat / tool loop
│ ├── talents/ # Tool engines + registries
│ ├── tts/ # TTS engines (kokoro, kitten, supertonic, system)
│ ├── palshub/ # PalsHub marketplace integration
│ └── 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/</details>
<details>
<summary><strong>Tech stack</strong></summary>
<br/>
Versions are pinned in package.json; the highlights:
| Area | Choice |
| --- | --- |
| Framework | React Native 0.82.1, React 19.1.1 (New Architecture) |
| Language | TypeScript 5.0.4 |
| UI | React Native Paper 5.14.5, React Navigation |
| State | MobX 6 (mobx, mobx-react, mobx-persist-store) |
| Persistence | WatermelonDB (chat history), AsyncStorage (settings), Keychain (secrets) |
| LLM | llama.rn 0.12.4 → llama.cpp · GGUF |
| TTS | react-native-speech 2.3.1 + onnxruntime-react-native 1.23.2 · ONNX |
| Tooling | Yarn 1 (Classic), ESLint, Prettier, Jest, Husky + Commitlint |
</details>
<details>
<summary><strong>Extending PocketPal</strong></summary>
<br/>
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 |
Good first contributions:
- A new Talent — implement a TalentEngine and register it in src/services/talents/.
- A new TTS engine — add it under src/services/tts/engines/.
- A new locale — add a JSON file in src/locales/ (or translate on Weblate).
</details>
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
- Tool use expansion — grow the Talents catalog and deepen the agentic loop so Pals can do more, fully on-device.
Have an idea or found a bug? Open an issue or start a discussion.
Community & support
- 💬 Questions & ideas — GitHub Discussions
- 🐛 Bugs & requests — GitHub Issues
- 🌐 Website — pocketpal.dev
- ❤️ Support development — PocketPal is free and ad-free; sponsoring helps keep it that way.
License
Licensed under the MIT License.
Acknowledgements
PocketPal AI stands on the shoulders of the open-source community, including:
- llama.cpp — efficient on-device LLM inference.
- llama.rn — llama.cpp bindings for React Native.
- react-native-speech — React Native TTS bridge powering on-device voices.
- ONNX Runtime — cross-platform inference engine powering on-device TTS.
- React Native, MobX, React Native Paper, React Navigation, WatermelonDB, and many other open-source libraries that make this project possible.
<div align="center">
<br/>
Made with ❤️ for people who want AI that stays on their phone.
<br/>
<sub>If PocketPal is useful to you, consider giving it a ⭐ — it helps others find the project.</sub>
</div>
---