evandro/LocalMind
1
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): redesenha o README com hero em SVG [skip ci]

Browse Source
This commit is contained in:
evandro committed 2026-10-24 04:57:51 -03:00
1 parent c246e68edd
commit a8321ea498
2 files changed
+89 -118
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+43 -118
View File
@@ -1,158 +1,83 @@
<div align="center">
<h1>LocalMind</h1>
<img src="assets/readme/hero.svg" width="100%" alt="LocalMind: chat with your LM Studio models from a phone or browser on your own network">
<p><strong>Chat client for local LLMs served by LM Studio, on Android, iOS and web. Every message stays on your network: no cloud.</strong></p>
![React Native 0.81](https://img.shields.io/badge/React_Native-0.81-61DAFB?style=flat-square&logo=react&logoColor=black)
![Expo 54](https://img.shields.io/badge/Expo-54-1C1E24?style=flat-square&logo=expo&logoColor=white)
![TypeScript 5.9](https://img.shields.io/badge/TypeScript-5.9-3178C6?style=flat-square&logo=typescript&logoColor=white)
![Platforms](https://img.shields.io/badge/platforms-Android_%7C_iOS_%7C_Web-555?style=flat-square)
![Status](https://img.shields.io/badge/status-alpha-orange?style=flat-square)
<a href="#-quickstart">Quickstart</a> ·
<a href="#-architecture">Architecture</a> ·
<a href="https://git.evandro.dev.br/evandro/LocalMind/issues">Issues</a>
![Stack](https://img.shields.io/badge/Stack-React_Native_0.81_%2B_Expo_54-1C1E24?logo=expo&logoColor=white)
![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)
![Status](https://img.shields.io/badge/status-alpha-orange)
![License](https://img.shields.io/badge/license-none_defined-lightgrey)
[Quick start](#quick-start) · [Issues](https://git.evandro.dev.br/evandro/LocalMind/issues)
</div>
<hr />
## What it is
## 📌 The problem
LocalMind is a chat client for the models you run in [LM Studio](https://lmstudio.ai). It is an Expo app for Android, iOS and the web that talks to LM Studio's OpenAI-compatible `/v1` API over your LAN or `localhost`. It is only the client: there is no backend, no account and no server to deploy.
Running a model locally in LM Studio is easy; having a decent chat UI for it on your phone is not. Hosted chat apps send every message to a cloud service, which defeats the point of running the model yourself.
## Why use it
LocalMind is only the client. There is no backend, no account and no server to deploy: the model runs on your machine and the app talks to it over your LAN or `localhost`.
- **Your messages stay on your network.** The app only talks to the LM Studio address you set in Settings. There is no cloud API and no fallback to one.
- **Real streaming on every target.** Requests go out with `stream: true` and each SSE `choices[0].delta.content` is appended as it arrives: through `XMLHttpRequest` progress events on native, through `fetch` with a `ReadableStream` on the web. You can stop generation mid-stream.
- **The chat basics are there.** Markdown with copyable code blocks, edit, delete and regenerate, a model selector fed by LM Studio, history saved on the device, and light, dark or system theme.
## ✨ What it does
**When not to use it:** if you want a cloud model, a server other than LM Studio (the app was built against LM Studio only), or a verified phone build. The Android and iOS builds and the native streaming path have not been verified yet.
- Connects to the LM Studio local server through its OpenAI-compatible `/v1` API.
- Streams answers token by token and lets you stop generation while it streams.
- Renders Markdown with code blocks, with a copy button for code.
- Edits, deletes and regenerates messages in the conversation.
- Lists the models loaded in LM Studio in a header selector.
- Saves every finished exchange as a chat session on the device; History reloads or deletes it.
- Tests the server connection from Settings and shows a Connected / Disconnected badge.
- Switches between light, dark and system themes.
## How it works
## 🚀 Quickstart
- Screens are file-based routes (`expo-router`): `app/chat`, `app/chat/history` and `app/settings`. `hooks/useLMStudio` exposes send, regenerate, stop and model fetching.
- `services/lmStudioApi` builds `http(s)://<host>:<port>/v1`, calls `GET /v1/models` for the selector and the connection test, and streams `POST /v1/chat/completions`.
- `store/useAppStore` (Zustand) persists theme, server settings, chat sessions and the current chat in `AsyncStorage`. A finished exchange becomes a session titled from the first user message.
| Tool | Minimum version |
|---|---|
| Node.js | `>= 20.19.4` (required by React Native 0.81.5; not declared in `package.json`) |
| npm | any recent version (`package-lock.json` is committed; `pnpm-lock.yaml` too) |
| [LM Studio](https://lmstudio.ai) | with at least one model downloaded; local server on port `1234` by default |
| Run target | [Expo Go](https://expo.dev/go) on a device, an Android/iOS emulator, or a browser |
## Quick start
### 1. Start the model server (LM Studio)
You need Node.js 20.19.4 or newer (required by React Native 0.81; not declared in `package.json`), npm, and LM Studio with at least one model downloaded. To run the app, use [Expo Go](https://expo.dev/go) on a device, an Android or iOS emulator, or a browser.
1. Open LM Studio, download a model and go to the **Local Server** tab (the `<->` icon).
2. Load the model, enable **CORS** and keep the port at `1234` (or note the one you choose).
3. Click **Start Server**.
**1. Start LM Studio's server.** Open the **Local Server** tab (the `<->` icon), load a model, enable **CORS**, keep the port at `1234` (or note yours) and click **Start Server**.
### 2. Run the app
**2. Run the app.**
```bash
git clone https://git.evandro.dev.br/evandro/LocalMind.git
cd LocalMind
npm install
npm run start # Expo CLI: press w (web), a (Android), i (iOS) or scan the QR with Expo Go
# or go straight to a target:
npm run android
npm run ios
npm run web
npm run start # Expo CLI: press w (web), a (Android), i (iOS) or scan the QR code with Expo Go
```
### 3. Point the app at LM Studio
`npm run android`, `npm run ios` and `npm run web` open a target directly. Do not run `npm run reset-project`: it is the Expo template script and moves or deletes `app/`, `components/`, `hooks/`, `constants/` and `scripts/`.
1. Open **Settings** (gear icon in the chat header).
2. Fill **Host IP / Address** and **Port Number**. On a physical device the host must be your machine's LAN address (`192.168.x.x`), not `localhost`.
3. Tap **Test Connection**. The badge turns to *Connected* and the loaded models appear in the header selector.
**3. Point the app at LM Studio.** Open **Settings** (gear icon in the chat header), fill **Host IP / Address** and **Port Number**, then tap **Test Connection**. On a physical device the host must be your computer's LAN address (`192.168.x.x`), not `localhost`. The badge turns to *Connected* and the loaded models appear in the header. Until then the chat shows *Server offline*: the app does not connect on launch.
Until you do this the chat shows *Server offline*: the app does not connect on launch.
## Configuration
### Network configuration
The app reads no environment variables. The server address is a runtime setting stored on the device:
The app has no `.env.example` and reads no environment variables. The server address is a runtime setting stored on the device.
| Setting | Required | Description |
| Setting | Default | Notes |
|---|---|---|
| Host IP / Address | Yes | Default `localhost` (`DEFAULT_SERVER_CONFIG` in `services/types.ts`). `http://` is prepended when the value does not start with `http`. |
| Port Number | Yes | Default `1234`, the LM Studio default. |
| API Key (optional) | No | Empty by default. Sent as `Authorization: Bearer <key>` only when filled in. |
| Host IP / Address | `localhost` | `http://` is prepended when the value does not start with `http` |
| Port Number | `1234` | LM Studio's default port |
| API Key (optional) | empty | Sent as `Authorization: Bearer <key>` only when filled in |
The resulting base URL is `http(s)://<host>:<port>/v1`. Defaults for a local LM Studio: `http://localhost:1234/v1`.
Everything else lives in code: `temperature: 0.7` and `max_tokens: 2048` in `services/lmStudioApi.ts` (the connection test gives up after 5 s), the fixed system prompt in `constants/SystemPrompt.ts`, and the persisted state under the `localaiapp-storage` key in `store/useAppStore.ts`.
Other configuration lives in code, not in the UI:
## Project status
| Where | What |
|---|---|
| `services/lmStudioApi.ts` | `temperature: 0.7`, `max_tokens: 2048`; the connection test aborts after 5 s |
| `constants/SystemPrompt.ts` | Fixed system prompt sent with every request |
| `app.json` | App name `LocalAiApp`, scheme `localaiapp`, `newArchEnabled`, `web.output: static`, `typedRoutes` and `reactCompiler` experiments |
| `store/useAppStore.ts` | Persisted under the `localaiapp-storage` key: theme, server config, chat sessions, current messages |
Alpha, with no tests and no CI. Known gaps:
## 🧱 Architecture
```mermaid
flowchart LR
Screens["Screens: app/chat, app/settings"] --> Hook["hooks/useLMStudio"]
Hook --> Api["services/lmStudioApi"]
Hook --> Store["store/useAppStore"]
Store --> Storage[("AsyncStorage")]
Api -->|"GET /v1/models, POST /v1/chat/completions"| LM["LM Studio local server"]
```
- Screens are file-based routes (`expo-router`). `useLMStudio` exposes send, regenerate, stop and model fetching.
- `lmStudioApi` builds the base URL and streams the response: `XMLHttpRequest` progress events on native, `fetch` with `ReadableStream` on web.
- Streaming uses `stream: true`; SSE lines with `choices[0].delta.content` are appended to the last message.
- `GET /v1/models` feeds the model selector and the connection test.
- The Zustand store is persisted with `AsyncStorage`; a finished exchange becomes a session titled from the first user message.
## 🗂️ Structure
```
app/ expo-router screens: chat/, chat/history, settings/, +not-found
components/ chat/ (ChatInput, MessageBubble, ModelSelector...) and ui/
constants/ Colors, theme, SystemPrompt, Models (unused)
hooks/ useLMStudio, useThemeColor, useColorScheme
services/ lmStudioApi (HTTP + SSE), types (ServerConfig, defaults)
store/ useAppStore (Zustand + AsyncStorage)
docs/ LM Studio API notes, design system reference
.agent/ AI development tooling, not app code
```
## 🧪 Scripts
| Command | What it does |
|---|---|
| `npm run start` | `expo start`: Expo dev server, pick a target from the CLI |
| `npm run android` | `expo start --android` |
| `npm run ios` | `expo start --ios` |
| `npm run web` | `expo start --web` |
| `npm run lint` | `expo lint` (ESLint 9 flat config, `eslint-config-expo`) |
| `npm run reset-project` | `node ./scripts/reset-project.js`: Expo template script that moves or deletes `app/`, `components/`, `hooks/`, `constants/` and `scripts/`. **Do not run it on this project.** |
Not scripts, but used by this project: `npx tsc --noEmit` (strict TypeScript check) and `npx expo export --platform web` (static build into `dist/`; serve it with a static server that resolves extension-less URLs, such as `npx serve dist`).
## 📚 Documentation
- [`docs/Documentação de Implementaçoes Futuras.md`](docs/Documenta%C3%A7%C3%A3o%20de%20Implementa%C3%A7oes%20Futuras.md): notes on the LM Studio API (`/api/v0`, `/v1`, SDKs, CLI) and ideas, in Portuguese.
- [`docs/evandro-design-system.html`](docs/evandro-design-system.html): visual reference of the design system used in the UI.
## 🛣️ Limitations and next steps
- Alpha. Built against models served by LM Studio; no fallback to any cloud API.
- No auto-connect on launch: the server is only checked from Settings or when the model selector refreshes.
- `activeModelId` and `availableModels` are not persisted, so you select a model again after a restart.
- The selected model and the model list are not persisted, so you pick a model again after a restart.
- `constants/Models.ts` (a Qwen model catalog) and the `react-native-sse` dependency are not used by any code.
- `app.json` and the storage key still carry the previous project name (`LocalAiApp`, `localaiapp-storage`).
- Both `package-lock.json` and `pnpm-lock.yaml` are committed.
- No tests and no CI. The previous README reported `npx tsc --noEmit` clean and `npx expo lint` with 0 errors and 3 warnings; Android and iOS builds, and the native `XMLHttpRequest` streaming path, were never verified.
## 🤝 Contributing
Before opening a PR, run `npm run lint` (Expo's ESLint config) and `npx tsc --noEmit`. Notes on the LM Studio API, in Portuguese, are in [`docs/`](docs/).
There is no test suite. Before opening a PR, make sure `npm run lint` and `npx tsc --noEmit` pass, and open issues on the [issue tracker](https://git.evandro.dev.br/evandro/LocalMind/issues).
## License
## 📄 License
No published license: all rights reserved.
No license defined — all rights reserved.
<div align="center">
<sub>Made by <a href="https://evandro.dev.br">Evandro Fonseca Junior</a> · <a href="https://git.evandro.dev.br/evandro">git.evandro.dev.br</a></sub>
</div>
assets/readme/hero.svg
+46
View File
@@ -0,0 +1,46 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="420" viewBox="0 0 1200 420" role="img" aria-labelledby="title desc">
<title id="title">LocalMind</title>
<desc id="desc">LocalMind: a phone chat screen marked Connected talks over the local network to LM Studio running on your computer at port 1234, path /v1.</desc>
<rect width="1200" height="420" rx="24" fill="#09090B"/>
<g id="title-block" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif">
<text x="64" y="170" font-size="64" font-weight="700" fill="#FAFAFA">LocalMind</text>
<text x="64" y="226" font-size="28" fill="#FAFAFA">Chat with your LM Studio models</text>
<text x="64" y="264" font-size="28" fill="#FAFAFA">from a phone or browser on your LAN.</text>
<text x="64" y="322" font-size="20" fill="#A1A1AA" font-family="ui-monospace, 'SF Mono', Consolas, monospace">React Native 0.81 · Expo 54 · TypeScript</text>
</g>
<g id="phone" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif">
<rect x="644" y="44" width="216" height="332" rx="34" fill="#18181B" stroke="#3F3F46" stroke-width="3"/>
<rect x="722" y="58" width="60" height="8" rx="4" fill="#3F3F46"/>
<rect x="662" y="82" width="134" height="32" rx="16" fill="#052E16"/>
<circle cx="680" cy="98" r="5" fill="#BBF7D0"/>
<text x="692" y="104" font-size="18" fill="#BBF7D0">Connected</text>
<rect x="696" y="132" width="146" height="40" rx="16" fill="#FAFAFA"/>
<text x="769" y="158" font-size="20" fill="#09090B" text-anchor="middle">Explain SSE</text>
<rect x="662" y="188" width="164" height="104" rx="16" fill="#27272A"/>
<rect x="680" y="208" width="128" height="10" rx="5" fill="#A1A1AA"/>
<rect x="680" y="232" width="112" height="10" rx="5" fill="#A1A1AA"/>
<rect x="680" y="256" width="72" height="10" rx="5" fill="#A1A1AA"/>
<rect x="760" y="252" width="10" height="18" rx="2" fill="#FAFAFA"/>
<rect x="662" y="314" width="180" height="40" rx="20" fill="#09090B" stroke="#3F3F46" stroke-width="2"/>
<text x="682" y="340" font-size="18" fill="#A1A1AA">Message</text>
<circle cx="822" cy="334" r="13" fill="#FAFAFA"/>
<path d="M822 340 v-12 M816 333 l6 -6 l6 6" fill="none" stroke="#09090B" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
</g>
<g id="lan-link" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif">
<path d="M872 206 h80" stroke="#A1A1AA" stroke-width="2" stroke-dasharray="8 6"/>
<text x="912" y="190" font-size="18" fill="#A1A1AA" text-anchor="middle">LAN</text>
</g>
<g id="computer" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif">
<rect x="960" y="140" width="176" height="124" rx="12" fill="#18181B" stroke="#3F3F46" stroke-width="3"/>
<text x="1048" y="194" font-size="20" font-weight="700" fill="#FAFAFA" text-anchor="middle">LM Studio</text>
<text x="1048" y="228" font-size="20" fill="#A1A1AA" text-anchor="middle" font-family="ui-monospace, 'SF Mono', Consolas, monospace">:1234/v1</text>
<rect x="1032" y="264" width="32" height="24" fill="#3F3F46"/>
<rect x="1004" y="288" width="88" height="10" rx="4" fill="#3F3F46"/>
<text x="1048" y="334" font-size="18" fill="#A1A1AA" text-anchor="middle">your machine</text>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 3.3 KiB