local-ai-chat-frontend 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hidao80
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# local-ai-chat-frontend
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Lint](https://github.com/hidao80/local-ai-chat-frontend/actions/workflows/lint.yml/badge.svg)
+![Audit](https://github.com/hidao80/local-ai-chat-frontend/actions/workflows/audit.yml/badge.svg)
+![Build](https://github.com/hidao80/local-ai-chat-frontend/actions/workflows/build.yml/badge.svg)
+[![Security: Takumi Guard](https://img.shields.io/badge/Security-Takumi%20Guard-blue)](https://github.com/hidao80/mago-vsx/actions/workflows/npm-scan.yml)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/hidao80/local-ai-chat-frontend)
+
+![Claude](https://img.shields.io/badge/Claude-D97757?style=for-the-badge&logo=claude&logoColor=white)
+![GitHub Copilot](https://img.shields.io/badge/github_copilot-8957E5?style=for-the-badge&logo=github-copilot&logoColor=white)
+
+## Overview
+
+A privacy-first, browser-based chat interface for local LLMs (Ollama, GPT4ALL, LM Studio, llama.cpp) and cloud providers. No backend required.
+
+## Issues & Reasons
+
+Local LLM providers lack easy-to-deploy, cross-platform GUIs. local-ai-chat-frontend runs in any browser (Win/macOS/Linux/Android/iOS/iPadOS), connecting instantly to your local network providers.
+
+<img width="30%" alt="Config Screen" src="https://github.com/user-attachments/assets/c29e1f02-bd8e-4996-af37-a130e78abf5d" />&emsp;
+<img width="30%" alt="Chat Screen" src="https://github.com/user-attachments/assets/e2aa651b-6ec8-4bac-90f2-299c5830523e" />&emsp;
+<img width="30%" alt="Chat History Menu" src="https://github.com/user-attachments/assets/132f6ac9-8b38-4799-a9b7-2c3044abeeaa" />
+
+## Features
+
+### Core Functionality
+
+- **Multi-provider support** — Works with OpenAI, LM Studio, GPT4ALL, and Ollama. Point it at any OpenAI-compatible endpoint you have running.
+- **Dynamic model selection** — Available models are fetched from the server when you select a provider. No manual configuration needed.
+- **Reasoning model support** — For advanced reasoning models (o1, GPT-OSS, DeepSeek-R1), configure reasoning depth (low/medium/high). The app automatically detects reasoning-capable models.
+- **System prompts per model** — System prompts are saved separately for each provider-model combination. Switch between models and your custom prompts are automatically restored.
+
+### Chat Management
+
+- **Chat history** — All conversations are stored in IndexedDB and persist across sessions. Browse past chats from the sidebar.
+- **Sidebar navigation** — Desktop users see a persistent sidebar; mobile users access it via hamburger menu.
+- **Delete with confirmation** — Remove unwanted chats with a confirmation modal to prevent accidental deletion.
+- **Message copy** — Copy any message to clipboard with one click. Visual feedback confirms the action.
+
+### User Experience
+
+- **Client-side storage** — API keys and endpoint configuration are persisted in IndexedDB and never leave your device.
+- **Markdown rendering** — AI responses are rendered as Markdown via `marked`, sanitized with DOMPurify before display, supporting code blocks, lists, and formatting.
+- **Performance metrics** — See tokens per second and timestamp for each AI response.
+- **Conversation minimap** — A compact minimap beside the scrollbar shows all messages color-coded by sender. Click any block to jump to that message instantly.
+
+### Internationalization & Accessibility
+
+- **i18n (Japanese / English)** — The UI supports Japanese and English; language preference is persisted in IndexedDB and auto-detected from the browser on first visit.
+- **Dark mode** — Toggle between light and dark themes via the nav bar; preference is persisted in IndexedDB across sessions.
+- **Responsive design** — Optimized layouts for mobile (hamburger menu) and desktop (persistent sidebar).
+
+### Deployment
+
+- **npx one-liner** — Run instantly from GitHub without cloning: `npx https://github.com/hidao80/local-ai-chat-frontend`.
+- **Docker-ready** — Production image serves the static build via nginx; a dev compose file is included for local development.
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| UI Framework | React 19 |
+| Language | TypeScript (strict) |
+| Bundler | Vite 7 |
+| Styling | Tailwind CSS 4 |
+| Markdown | marked + DOMPurify (sanitization) |
+| Storage | IndexedDB (native) |
+| i18n | i18next / react-i18next |
+| Server | sirv-cli |
+
+### Key Technologies
+
+- **State Management**: React hooks (useState, useEffect, useRef)
+- **Storage**: IndexedDB for chat history and system prompts
+- **Routing**: Single-page app with conditional rendering (no router)
+- **API Integration**: OpenAI-compatible REST APIs with fetch
+- **Styling**: Tailwind CSS with dark mode support
+
+## Quick Start
+
+### Run instantly (no install)
+
+```bash
+npx github:hidao80/local-ai-chat-frontend
+```
+
+> `bunx` does not reliably build `devDependencies` from a raw git ref, so `npx` is the recommended way to run this project directly from GitHub. If you use Bun, clone the repo and run `bun install && bun run build && bun start` instead.
+
+### Custom port / LAN access
+
+```bash
+PORT=8080 npx github:hidao80/local-ai-chat-frontend
+HOST=0.0.0.0 PORT=3000 npx github:hidao80/local-ai-chat-frontend
+```
+
+### Run with Docker
+
+```bash
+# Development
+docker compose up
+
+# Production build
+docker build -t local-ai-chat-frontend .
+docker run -p 80:80 local-ai-chat-frontend
+```
+
+### Run with Podman
+
+```bash
+# Development
+podman compose up
+
+# Production build
+podman build -t local-ai-chat-frontend .
+podman run -p 80:80 local-ai-chat-frontend
+```
+
+### Development
+
+```bash
+bun install
+bun run dev
+```
+
+## Configuration
+
+### Supported Providers
+
+The application supports multiple LLM providers with automatic model discovery:
+
+| Provider | Default Endpoint | Authentication | Reasoning Support | Notes |
+|----------|-----------------|----------------|-------------------|-------|
+| **OpenAI** | `https://api.openai.com` | API Key required | Yes (`reasoning_effort`) | Official OpenAI API |
+| **Ollama** | `http://localhost:11434` | No auth | Yes (`think`) | Local models via Ollama |
+| **GPT4ALL** | `http://localhost:4891` | No auth | No | Local OpenAI-compatible endpoint |
+| **LM Studio** | `http://localhost:1234` | Optional | Yes (`reasoning_effort`) | Local OpenAI-compatible endpoint |
+| **llama.cpp** | `http://localhost:8080` | No auth | Yes (`reasoning_effort`) | llama-server built-in HTTP server |
+
+### Provider-Specific Features
+
+- **OpenAI / LM Studio / llama.cpp**: Supports `reasoning_effort` parameter (low/medium/high)
+- **Ollama**: Supports `think` parameter for reasoning models like GPT-OSS and DeepSeek-R1
+- **llama.cpp**: CORS enabled by default — no proxy or special configuration needed
+
+### CORS Configuration
+
+**GPT4ALL**: Uses Vite proxy in development mode. When running via `npx` or `bun start`, sirv-cli serves with `--cors` enabled so the browser can reach `localhost:4891` directly.
+
+**Ollama**: Set environment variable before starting:
+```bash
+# Windows
+set OLLAMA_ORIGINS=*
+ollama serve
+
+# Linux/Mac
+OLLAMA_ORIGINS=* ollama serve
+```
+
+**LM Studio**: Enable CORS in Server Settings
+
+## Development
+
+### Build
+
+```bash
+bun run build
+```
+
+### Type Check
+
+```bash
+bunx tsc --noEmit
+```
+
+### Project Structure
+
+```
+src/
+├── components/
+│   └── ChatAndSettings.tsx  # Main UI components
+├── locales/
+│   ├── en.json              # English translations
+│   └── ja.json              # Japanese translations
+├── App.tsx                  # Root component
+├── i18n.ts                  # i18n configuration
+├── index.css                # Global styles
+├── main.tsx                 # Entry point
+└── vite-env.d.ts            # Vite type declarations
+```
+
+## :handshake: Contributing
+
+Contributions are welcome!  
+Please note that this project uses [Takumi Guard](https://github.com/flatt-security/setup-takumi-guard-npm) in CI workflows to scan dependencies for malware and ensure supply chain security. This scanning only applies to CI and does not affect your local development environment.
+
+## :page_facing_up: License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/bin/start.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, '..');
+const distDir = join(rootDir, 'dist');
+
+if (!existsSync(join(distDir, 'index.html'))) {
+  console.log('  dist/ not found, building (first run)...');
+  const build = spawnSync('npx', ['vite', 'build'], { cwd: rootDir, stdio: 'inherit', shell: true });
+  if (build.status !== 0) {
+    console.error('Build failed.');
+    process.exit(build.status || 1);
+  }
+}
+
+const PORT = process.env.PORT || '3000';
+const HOST = process.env.HOST || 'localhost';
+
+console.log('');
+console.log('  local-ai-chat-frontend');
+console.log('  ====================================');
+console.log(`  Server: http://${HOST}:${PORT}`);
+console.log('');
+console.log('  Recommended LLM provider ports:');
+console.log('    Ollama:    http://localhost:11434');
+console.log('    GPT4ALL:   http://localhost:4891');
+console.log('    LM Studio: http://localhost:1234');
+console.log('');
+console.log('  Tip: Customize with environment variables');
+console.log('    PORT=8080 npx https://github.com/hidao80/local-ai-chat-frontend');
+console.log('    HOST=0.0.0.0 PORT=3000 npx https://github.com/hidao80/local-ai-chat-frontend  (LAN access)');
+console.log('');
+
+const sirv = spawn(
+  'npx',
+  ['sirv-cli', distDir, '--port', PORT, '--host', HOST, '--single', '--cors', '--dev'],
+  { stdio: 'inherit', shell: true }
+);
+
+sirv.on('error', (err) => {
+  console.error('Failed to start server:', err.message);
+  process.exit(1);
+});
+
+process.on('SIGINT', () => {
+  console.log('\n  Shutting down...');
+  sirv.kill('SIGINT');
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  sirv.kill('SIGTERM');
+  process.exit(0);
+});