Chat client for local LLMs served by LM Studio. React Native + Expo app (Android, iOS and web) where every message stays on your own network: no cloud, no API key, no telemetry.

About

Running a model locally in LM Studio is easy; having a decent chat UI for it on the phone is not. LocalMind is that client: it talks straight to the LM Studio local server (the OpenAI-compatible /v1 endpoints) over your LAN or localhost, streams the answer token by token, keeps chat sessions on the device and renders Markdown with code blocks.

It is an alpha project. There is no backend, no account and no server to deploy: the app is only the client, and the model runs on your machine.

How it works

Expo app (Android / iOS / web)
  app/chat, app/settings ......... screens (expo-router, file based)
  hooks/useLMStudio .............. sendMessage / regenerate / stop, stream callbacks
  services/lmStudioApi ........... HTTP + SSE client
  store/useAppStore .............. Zustand + AsyncStorage (sessions, settings, theme)
            |
            |  GET  /v1/models
            |  POST /v1/chat/completions   (stream: true -> SSE)
            v
  LM Studio local server  (default http://localhost:1234)

The connection settings (host, port, optional API key) live in the Zustand store and are persisted with AsyncStorage.
services/lmStudioApi.ts builds the base URL as http(s)://<host>:<port>/v1 and streams the response: XMLHttpRequest progress events on native platforms, fetch + ReadableStream on web.
Each request carries a fixed system prompt (constants/SystemPrompt.ts); temperature is 0.7 and max_tokens is 2048.
Every finished (or stopped) exchange is saved as a chat session (title taken from the first user message), so History can reload it later. Writes to AsyncStorage are debounced (400 ms) so streaming does not serialize the whole history on every token.
When the chat opens, the app checks the saved server once and loads its model list; the selected model is remembered between launches.

Stack

Layer	Choice
Runtime	Expo SDK 54, React Native 0.81.5, React 19.1
Routing	expo-router 6 (typed routes experiment on, React Compiler experiment on)
State	Zustand 5 with `persist` + `@react-native-async-storage/async-storage`
Animation / gestures	react-native-reanimated 4, react-native-gesture-handler
Icons	lucide-react-native
Markdown	`@ronradtke/react-native-markdown-display`
Streaming	XMLHttpRequest (native) / fetch ReadableStream (web)
Tooling	TypeScript 5.9 (`strict`), ESLint 9 flat config (`eslint-config-expo`), Jest 29 with `jest-expo` and Testing Library
Model server	LM Studio local server, OpenAI-compatible `/v1` API

Requirements

Node.js >= 20.19.4 (required by React Native 0.81.5; CI uses Node 22, local runs were done on Node 26.7.0)
npm to install dependencies (the committed package-lock.json is the maintained lockfile)
LM Studio with a model downloaded, the local server started and CORS enabled (Local Server tab, default port 1234)
To run the app: Expo Go on a physical device, an Android/iOS emulator, or a browser for the web target

Quick start

git clone https://github.com/evandrodevbr/LocalMind.git
cd LocalMind
npm install
npx expo start

Then pick a target from the Expo CLI: w for web, a for Android, i for iOS, or scan the QR code with Expo Go.

Start the model side first:

Open LM Studio, download a model and go to the Local Server tab (the <-> icon).
Enable CORS and keep the port at 1234 (or note whatever you change it to).
Click Start Server.

Finally, in the app:

Open Settings (gear icon in the chat header).
Fill Host IP / Address and Port Number. On a physical device this must be your machine's LAN address (192.168.x.x), not localhost.
Tap Test Connection. The badge turns to Connected and the model list becomes available in the chat header selector.

Usage

Screen	What it does
Chat (`/chat`)	Conversation list with Markdown rendering, streaming answers, copy code blocks, edit / delete / regenerate a message, stop generation while it streams, model selector in the header, "new chat" button.
History (`/chat/history`)	Saved sessions, most recent first, with message count and date; tap to reload, trash icon to delete.
Settings (`/settings`)	Host, port and optional API key, connection test and status badge, light/dark toggle, app info.

API

The app is a client of the LM Studio OpenAI-compatible API. Endpoints actually used:

Call	Where	Notes
`GET /v1/models`	`testConnection()`, `getModels()`	The connection test aborts after 5 s; the model list feeds the header selector.
`POST /v1/chat/completions`	`chatCompletion()`, `chatCompletionStream()`	Streaming (`stream: true`) is the path used by the chat; SSE lines with `choices[0].delta.content` are appended to the last message.

Base URL: http://<host>:<port>/v1 (http:// is prepended when the host has no http:// or https:// scheme).
An Authorization: Bearer <apiKey> header is sent only when an API key is filled in.
GET /v1/models responds with the OpenAI shape { "data": [ { "id": ... } ] }.

Web target

The same codebase exports a static web build:

npx expo export --platform web      # writes dist/
npx serve dist                      # or any static server that maps /chat -> chat/index.html

The export generates /, /chat, /chat/history, /settings, /_sitemap and /+not-found. Use a static server that resolves extension-less URLs (npx serve, nginx try_files $uri $uri.html $uri/ =404); point unknown paths at +not-found.html for the app's 404 screen.

Project structure

app/
├── _layout.tsx            root stack, theme provider, splash screen
├── index.tsx              redirects to /chat
├── +not-found.tsx         404 screen
├── chat/
│   ├── _layout.tsx        chat header (model selector, history, new chat, settings), auto-connect
│   ├── index.tsx          conversation screen, edit/regenerate flow
│   └── history.tsx        saved sessions
└── settings/index.tsx     composes the settings cards
components/
├── chat/                  ChatInput, MessageList, MessageBubble, MessageContent, CodeBlock,
│                          MessageActions, ModelSelector, EmptyState, OfflineBanner, TypingIndicator
├── settings/              ServerConnectionCard, AppearanceCard, AboutCard, LabeledInput, SettingsSection
└── ui/                    ConnectionBadge
constants/                 Colors, SystemPrompt (system prompt sent to the model)
hooks/                     useLMStudio (chat flow), useAutoConnect, useThemeColor, useColorScheme
services/                  lmStudioApi (HTTP/SSE), types
store/                     useAppStore (Zustand), debouncedStorage (AsyncStorage wrapper)
utils/                     pure helpers (server form parsing, theme, chat selectors)
__tests__/                 Jest tests
docs/                      LM Studio API notes and design reference
.agent/                    AI development tooling (agents, skills, rules), not app code

Scripts

Command	What it does
`npm start`	Expo dev server (`npm run web`, `npm run android`, `npm run ios` pick a target)
`npm run typecheck`	`tsc --noEmit`
`npm run lint`	`expo lint`
`npm test`	Jest (`jest-expo`), tests in `__tests__/`
`npm run build`	`expo export --platform web`, writes `dist/`

The GitHub Actions workflow (.github/workflows/ci.yml) runs typecheck, lint, test and build on pushes to main and on pull requests.

Tests

npm test runs 11 suites (120 tests) covering the pure and stateful logic and the main screens:

lmStudioApi: base URL building, SSE parsing, connection test and timeout, model list, web (fetch) and native (XMLHttpRequest) streaming, HTTP and connection errors;
useAppStore, debouncedStorage: messages, chat sessions, persistence, write debouncing;
useLMStudio, useAutoConnect: sending, regenerating, stopping, model loading;
ChatScreen, SettingsScreen, MessageBubble, MessageList, ChatInput (rendered with Testing Library) and utils.

The native streaming path is exercised against a fake XMLHttpRequest, not a real device.

Verification

Last run on Windows 11 (Node 26.7.0, npm): npm ci, npm run typecheck, npm run lint (0 errors, 0 warnings), npm test (120 passed) and npm run build (6 static routes in dist/) all succeed.

Not verified: Android and iOS builds (no emulator or device available) and a run against a real LM Studio server. An earlier manual run of the exported web build against a mock of the /v1 API (headless Chromium) answered a chat message and persisted the session in localStorage under localaiapp-storage.

Current state and limitations

Alpha. It was built against models served by LM Studio and has no fallback to any cloud API.
The server is checked once when the chat opens and whenever the model selector is refreshed or Settings tests the connection; there is no periodic reconnect.
The stored model id is not validated against the server's model list after a restart.
Both package-lock.json and pnpm-lock.yaml are committed; only package-lock.json is kept in sync (CI uses npm ci).
app.json still carries the previous project name (LocalAiApp / slug localaiapp) and the persisted storage key is localaiapp-storage.
No license file.

Documentation

Document	Content
`docs/Documentação de Implementaçoes Futuras.md`	Notes on the LM Studio API (`/api/v0`, `/v1`, SDKs, CLI) and roadmap ideas (in Portuguese)
`docs/evandro-design-system.html`	Visual reference of the design system used in the UI

README.md

LocalMind