CubicLM

KO | EN

gitlite — search

#markdown #database #bash #shell #self-hosted #golang #javascript #github #redis #awesome

(★ 9)

CubicLM is a cross-platform AI client for seamless switching between cloud APIs and local, offline inference of custom and uncensored models.

파일 탐색기

ZIP 다운로드

파일 수가 많아 일부만 표시됩니다. 전체 파일은 위 다운로드 버튼으로 확인해 주세요.

- - 01-bug-report.yml
  - 02-feature-request.yml
  - 03-documentation.yml
  - 04-performance.yml
  - 05-ui-ux.yml
  - 06-security-advisory.yml
  - 07-accessibility.yml
  - 08-api-issue.yml
  - 09-mobile-bug.yml
  - 10-regression.yml
  - 12-build-failure.yml
  - 13-integration-request.yml
  - 14-translation.yml
  - 15-question.yml
  - config.yml
- - auto-label.yml
  - ci.yml
  - label-pr-size.yml
  - stale.yml
  - welcome.yml
- CODE_OF_CONDUCT.md
- CODEOWNERS
- CONTRIBUTING.md
- create-labels.sh
- dependabot.yml
- FUNDING.yml
- labeler.yml
- PULL_REQUEST_TEMPLATE.md
- release.yml
- SECURITY.md
- SUPPORT.md
- launch.json
- settings.json
- - build.gradle.kts
  - proguard-rules.pro
- .gitignore
- build.gradle.kts
- gradle.properties
- key.properties.example
- settings.gradle.kts
- - models.json
- - CubicLM.png
  - CubicLM_Icon.png
- - bn_en_translator.md
  - code_reviewer.md
  - creative_writer.md
  - efficient_prompting.md
  - study_helper.md
- adblock_hosts.txt
- AGENT_IDE_DESIGN.md
- ARCHITECTURE.md
- BUILD_AND_RUN.md
- CUBIC_WEB_SYSTEM_LOGS.md
- PLATFORM_DIFFERENCES.md
- PLATFORM_LINKS.md
- quick_release.md
- terminal.md
- web_builder_nextjs.md
- web_builder_react(vite).md
- - AppFrameworkInfo.plist
  - Debug.xcconfig
  - Release.xcconfig
- - AppDelegate.swift
  - Info.plist
  - LlamaFlutterAndroidPlugin.h
  - LlamaFlutterAndroidPlugin.m
  - Runner-Bridging-Header.h
- - project.pbxproj
- - contents.xcworkspacedata
- - RunnerTests.swift
- .gitignore
- Podfile
- Podfile.lock
- - agent_controller.dart
  - battle_arena_controller.dart
  - browser_controller.dart
  - chat_controller.dart
  - cloud_model_controller.dart
  - home_controller.dart
  - model_controller.dart
  - server_controller.dart
  - settings_controller.dart
  - slide_deck_controller.dart
  - task_controller.dart
  - vision_live_controller.dart
- - app_translations.dart
  - assets_data.dart
  - colors.dart
  - constants.dart
  - languages.dart
  - routes.dart
  - theme.dart
- - sd_ffi_bindings.dart
  - sd_ffi_bindings_io.dart
  - sd_ffi_bindings_web.dart
- - ai_model.dart
  - chat_message.dart
  - chat_session.dart
  - folder_model.dart
  - notification_entry.dart
  - project_model.dart
  - skill_model.dart
  - task_model.dart
  - web_source.dart
- - agent_workspace.dart
  - app_log_service.dart
  - chat_backup.dart
  - cloud_service.dart
  - code_interpreter_service.dart
  - crash_reporting_service.dart
  - deploy_service.dart
  - device_info_native.dart
  - device_info_service.dart
  - device_info_web.dart
  - document_extractor_service.dart
  - download_native.dart
  - download_service.dart
  - download_web.dart
  - execution_service.dart
  - hive_service.dart
  - image_generation_notification_service.dart
  - inference_android.dart
  - inference_gguf.dart
  - inference_litert.dart
  - inference_service.dart
  - inference_stub.dart
  - inference_text.dart
  - inference_types.dart
  - local_image_service.dart
  - memory_service.dart
  - notification_history_service.dart
  - openai_server_service.dart
  - openai_server_service_io.dart
  - openai_server_service_stub.dart
  - preview_server.dart
  - sd_isolate_processor.dart
  - sd_isolate_worker.dart
  - sd_isolate_worker_io.dart
  - sd_isolate_worker_web.dart
  - secure_key_store.dart
  - soc_family.dart
  - stats_service.dart
  - tts_service.dart
  - update_service.dart
  - usage_tracker_service.dart
  - vector_service.dart
  - web_fetch_service.dart
  - win_toast_io.dart
  - win_toast_notify.dart
  - win_toast_stub.dart
- - design_tokens.dart
- - app_snackbar.dart
  - artifact_parser.dart
  - battle_scoring.dart
  - browser_utils.dart
  - export_file.dart
  - history_budget.dart
  - prompt_export.dart
  - slide_deck.dart
  - slide_palette.dart
  - slide_pptx.dart
  - syntax_highlight.dart
  - thought_parser.dart
  - web_download.dart
  - web_download_stub.dart
  - web_download_web.dart
  - web_notify.dart
  - web_notify_stub.dart
  - web_notify_web.dart
  - web_project.dart
- - about_view.dart
  - agent_ide_view.dart
  - app_settings_view.dart
  - battle_arena_view.dart
  - chat_view.dart
  - explore_skills_mcp_tabs.dart
  - gallery_view.dart
  - home_view.dart
  - language_picker_view.dart
  - log_view.dart
  - model_view.dart
  - notification_history_view.dart
  - onboarding_view.dart
  - server_view.dart
  - settings_view.dart
  - slide_deck_view.dart
  - splash_view.dart
  - system_logs_view.dart
  - task_view.dart
  - toolkit_view.dart
  - update_settings_view.dart
  - update_view.dart
- - app_ui.dart
  - artifact_renderer.dart
  - attachment_preview.dart
  - chat_branch_timeline.dart
  - chat_bubble.dart
  - citation_chip.dart
  - cli_sheets.dart
  - code_block.dart
  - image_viewer.dart
  - model_switcher_sheet.dart
  - suggestion_chips.dart
  - thinking_orb.dart
  - thought_disclosure.dart
  - typing_indicator.dart
  - typing_text.dart
  - voice_overlay.dart
- main.dart
- - analysis_options.yaml
  - CHANGELOG.md
  - CONTRIBUTING.md
  - LICENSE
  - pubspec.yaml
  - README.md
- - analysis_options.yaml
  - CHANGELOG.md
  - CONTRIBUTING.md
  - LICENSE
  - README.md
- .gitignore
.firebaserc
.gitignore
.gitmodules
.markdownlint.json
analysis_options.yaml
CHANGELOG.md
cspell.json
LICENSE
README.md
RELEASE_NOTES.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

파일 목록이 많아 일부만 표시됩니다.

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## CubicLM
Computational Universe for Building Intelligent Learning Machines

### The Cross-Platform AI Chat Powerhouse

**Run LLMs locally on your Android device** via GPU-accelerated **llama.cpp** 🦙 & Google's **LiteRT-LM** ⚡<br/>
**Connect to 23+ cloud providers** ☁️ · **Extend with Skills** 🧩 · **Built-in OpenAI-compatible API** 🔌

<br/>

[![Release](https://img.shields.io/github/v/release/abir2afridi/CubicLM?label=Latest%20Release&style=for-the-badge&color=FF4D00&labelColor=0d1117&logo=github)](https://github.com/abir2afridi/CubicLM/releases/tag/v1.12.0)
[![Downloads](https://img.shields.io/github/downloads/abir2afridi/CubicLM/total?style=for-the-badge&color=22c55e&labelColor=0d1117&logo=github)](https://github.com/abir2afridi/CubicLM/releases)
[![Stars](https://img.shields.io/github/stars/abir2afridi/CubicLM?style=for-the-badge&color=facc15&labelColor=0d1117&logo=github)](https://github.com/abir2afridi/CubicLM/stargazers)
[![Forks](https://img.shields.io/github/forks/abir2afridi/CubicLM?style=for-the-badge&color=3b82f6&labelColor=0d1117&logo=github)](https://github.com/abir2afridi/CubicLM/network/members)

<br/>

[![Platform-Android](https://img.shields.io/badge/Android-Full%20Support-3DDC84?style=for-the-badge&logo=android&logoColor=white&labelColor=0d1117)](https://github.com/abir2afridi/CubicLM/releases/tag/v1.12.0)
[![Platform-Windows](https://img.shields.io/badge/Windows-Cloud%20Mode-0078D4?style=for-the-badge&logo=windows&logoColor=white&labelColor=0d1117)](https://github.com/abir2afridi/CubicLM/releases/tag/v1.12.0)
[![Platform-Web](https://img.shields.io/badge/Web-Planned-6b7280?style=for-the-badge&logo=googlechrome&logoColor=white&labelColor=0d1117)](https://raw.githubusercontent.com/abir2afridi/CubicLM/main/)
[![Website](https://img.shields.io/badge/Website-Live-FF4D00?style=for-the-badge&logo=vercel&logoColor=white&labelColor=0d1117)](https://cubiclm.vercel.app)

<br/>

<a href="#-tech-stack"><img src="https://img.shields.io/badge/Flutter-3.x-02569B?style=flat-square&logo=flutter&logoColor=white" alt="Flutter"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/Dart-0175C2?style=flat-square&logo=dart&logoColor=white" alt="Dart"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/Kotlin-7F52FF?style=flat-square&logo=kotlin&logoColor=white" alt="Kotlin"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/C++-00599C?style=flat-square&logo=cplusplus&logoColor=white" alt="C++"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/GetX-8A2BE2?style=flat-square" alt="GetX"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/Hive-FFA000?style=flat-square" alt="Hive"/></a>
<a href="#-tech-stack"><img src="https://img.shields.io/badge/Firebase-FFCA28?style=flat-square&logo=firebase&logoColor=black" alt="Firebase"/></a>
<a href="#-license"><img src="https://img.shields.io/badge/License-MIT-22c55e?style=flat-square" alt="License"/></a>

<br/>

<table>
<tr>
<td align="center" width="16.66%">
  <img src="https://img.shields.io/badge/23%2B-Cloud%20Providers-FF4D00?style=flat-square" alt="23+ Providers"/>
  <br/><sub><b>Cloud AI</b></sub>
</td>
<td align="center" width="16.66%">
  <img src="https://img.shields.io/badge/15-Languages-8b5cf6?style=flat-square" alt="15 Languages"/>
  <br/><sub><b>Localization</b></sub>
</td>
<td align="center" width="16.66%">
  <img src="https://img.shields.io/badge/18%2B-Bundled%20Models-22c55e?style=flat-square" alt="18+ Models"/>
  <br/><sub><b>On-Device</b></sub>
</td>
<td align="center" width="16.66%">
  <img src="https://img.shields.io/badge/5-Starter%20Skills-3b82f6?style=flat-square" alt="5 Skills"/>
  <br/><sub><b>Extensions</b></sub>
</td>
<td align="center" width="16.66%">
  <img src="https://img.shields.io/badge/3-Supported%20Shells-facc15?style=flat-square" alt="3 Shells"/>
  <br/><sub><b>Multi-Platform</b></sub>
</td>
<td align="center" width="16.66%">
  <img src="https://img.shields.io/badge/100%25-Offline%20Ready-0ea5e9?style=flat-square" alt="Offline"/>
  <br/><sub><b>Privacy First</b></sub>
</td>
</tr>
</table>

<br/>

> 📱⚡ A cross-platform AI chat application with local on-device inference and multi-provider cloud AI support. Runs LLMs directly on your Android device via GPU-accelerated **llama.cpp** 🦙 and Google's **LiteRT-LM** runtime ⚡, with an optional built-in OpenAI-compatible API server 🔌.

<br/>

[**📥 Download**](#-download--v1120) &nbsp;·&nbsp; [**✨ Features**](#-features) &nbsp;·&nbsp; [**🤖 Models**](#-supported-models) &nbsp;·&nbsp; [**🛠️ Stack**](#-tech-stack) &nbsp;·&nbsp; [**📂 Structure**](#-project-structure) &nbsp;·&nbsp; [**🚀 Setup**](#-getting-started) &nbsp;·&nbsp; [**⚙️ Config**](#️-configuration) &nbsp;·&nbsp; [**❓ FAQ**](#-frequently-asked-questions) &nbsp;·&nbsp; [**🤝 Contribute**](#-contributing)

</div>

---

## <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/target/target2.gif" width="90" /> 
## What is CubicLM?

</div>

### 💡 The Idea

**CubicLM** is a *single Flutter codebase* that ships as a **native Android app**, a **Windows desktop app**, and (soon) a **web app** — with zero feature forks. Whether you're running a 16B MoE model on your phone's GPU, streaming tokens from GPT-5.2, or spinning up a local OpenAI-compatible API server for your homelab, it's all the *same `lib/` directory*.

**No cloud lock-in. No telemetry by default. No dark patterns.** Just a clean, warm, Claude-inspired chat interface that respects your device, your data, and your time.

</td>
<td width="50%" valign="top">

### 🎁 What You Get

- 🔒 **Full offline capability** — download a model once, chat forever without internet
- ⚡ **GPU acceleration** — Vulkan / OpenCL on Android for real-time token streaming
- ☁️ **23+ cloud providers** — swap between OpenAI, Anthropic, Gemini, Groq, or any OpenAI-compatible endpoint
- 🧩 **Extensible** — Skills for prompt injection, MCP for live tools
- 🔌 **Built-in API server** — turn your phone into an OpenAI-compatible endpoint on port `8080`
- 🎨 **Beautiful UI** — warm Claude-inspired palette, thinking orbs, streaming markdown
- 🌍 **15 languages** — EN, BN, HI, AR, ZH, ES, FR, JA, KO, PT, DE, TR, ID, RU, UR

</td>
</tr>
</table>

---

## <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/download/installing-updates.gif" width="80" /> 
## Download — `v1.12.0`

> 🎉 **Latest release** · Build date: current · [View full changelog →](CHANGELOG.md)

</div>

<table>
<thead>
<tr>
<th align="center" width="40">Platform</th>
<th align="left">Architecture</th>
<th align="left">File</th>
<th align="right">Size</th>
<th align="center">Download</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center"><img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/android/android.png" width="120" /></td>
<td><b>Android</b><br/><sub>arm64-v8a · modern phones</sub></td>
<td><code>cubiclm-v1.12.0-arm64-v8a.apk</code></td>
<td align="right"><b>62 MB</b></td>
<td align="center"><a href="https://github.com/abir2afridi/CubicLM/releases/download/v1.12.0/cubiclm-v1.12.0-arm64-v8a.apk"><img src="https://img.shields.io/badge/⬇_GET-FF4D00?style=for-the-badge&logo=android&logoColor=white" alt="Download"/></a></td>
</tr>
<tr>
<td align="center"><img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/android/android.png" width="120" /></td>
<td><b>Android</b><br/><sub>armeabi-v7a · older devices</sub></td>
<td><code>cubiclm-v1.12.0-armeabi-v7a.apk</code></td>
<td align="right"><b>16 MB</b></td>
<td align="center"><a href="https://github.com/abir2afridi/CubicLM/releases/download/v1.12.0/cubiclm-v1.12.0-armeabi-v7a.apk"><img src="https://img.shields.io/badge/⬇_GET-FF4D00?style=for-the-badge&logo=android&logoColor=white" alt="Download"/></a></td>
</tr>
<tr>
<td align="center"><img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/android/android.png" width="120" /></td>
<td><b>Android</b><br/><sub>x86_64 · emulators, tablets</sub></td>
<td><code>cubiclm-v1.12.0-x86_64.apk</code></td>
<td align="right"><b>28 MB</b></td>
<td align="center"><a href="https://github.com/abir2afridi/CubicLM/releases/download/v1.12.0/cubiclm-v1.12.0-x86_64.apk"><img src="https://img.shields.io/badge/⬇_GET-FF4D00?style=for-the-badge&logo=android&logoColor=white" alt="Download"/></a></td>
</tr>
<tr>
<td align="center"><img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/windows/windows%20(2).png" width="120" /></td>
<td><b>Windows</b><br/><sub>x64 · requires WebView2</sub></td>
<td><code>cubiclm-v1.12.0-windows-x64.zip</code><br/><sub>unzip & run <code>cubiclm.exe</code></sub></td>
<td align="right"><b>17 MB</b></td>
<td align="center"><a href="https://github.com/abir2afridi/CubicLM/releases/download/v1.12.0/cubiclm-v1.12.0-windows-x64.zip"><img src="https://img.shields.io/badge/⬇_GET-0078D4?style=for-the-badge&logo=windows&logoColor=white" alt="Download"/></a></td>
</tr>
<tr>
<td align="center"><img src="https://github.com/abir2afridi/abir2afridi/blob/main/lock.png" width="120" /></td>
<td><b>Checksums</b><br/><sub>SHA-256 verification</sub></td>
<td><code>checksums.sha256</code></td>
<td align="right">—</td>
<td align="center"><a href="https://github.com/abir2afridi/CubicLM/releases/download/v1.12.0/checksums.sha256"><img src="https://img.shields.io/badge/⬇_VERIFY-6b7280?style=for-the-badge&logo=shield&logoColor=white" alt="Verify"/></a></td>
</tr>
</tbody>
</table>

### 🧭 Which Build Should I Choose?

> [!NOTE]
> **🌐 Website:** [cubiclm.vercel.app](https://cubiclm.vercel.app) — landing page + direct APK / Windows downloads
> **📝 Full release notes:** [CHANGELOG.md](CHANGELOG.md) · [GitHub Release page](https://github.com/abir2afridi/CubicLM/releases/tag/v1.12.0)
> **ℹ️ Platform status:** Web (`dart:ffi`-blocked) is tracked for a future release — **Android + Windows** are the supported targets for `v1.12.0`.

---

<br/>

<h2>🧭 Navigation</h2>

**<sub>Everything you need — organized into <b>3 zones</b> · <b>23 sections</b> · <b>instant jump</b></sub>**

<br/>

<br/>

---

## 🗂️ Documentation Zones

<sub><b>🎯 Start here · Features · Models</b></sub>

<br/>

---

**🎯 Introduction**

*Get to know CubicLM*

🎯 [What is CubicLM?](#-what-is-cubiclm)
📥 [Download — v1.12.0](#-download--v1120)

---

**✨ Core Features**

*What makes it powerful*

🧠 [Local AI Inference](#-local-ai-inference)
🎛️ [Inference Parameters](#️-inference-parameters-nodes--config)
🚀 [Startup & Onboarding](#-startup-onboarding--splash)
🌐 [Web Access](#-web-access-independent-chat)
🧠 [Chat Context Memory](#-chat-context-memory-follow-ups-dont-get-lost)
☁️ [Cloud Providers](#️-cloud-ai-providers)

---

**🤖 Model Catalog**

*18+ ready-to-run models*

⚡ [LiteRT-LM Models](#-supported-models)
🐫 [GGUF Models](#-supported-models)
🎨 [Image Generation](#-supported-models)
📊 [Selection Guide](#-supported-models)

<br/>

</td>

<sub><b>🧩 Power features · Integrations</b></sub>

<br/>

---

**🧩 Extend & Integrate**

*Add new capabilities*

🧩 [Skills System](#-skills--offline-instruction-extensions)
🔌 [MCP Server](#-custom-mcp-server--single-remote-connection-no-marketplace)
🔌 [Built-in API](#-built-in-openai-compatible-api-server)

---

**🌐 Build & Deploy**

*Create & ship apps*

🌐 [CubicWeb Builder](#-cubicweb-builder-toolkit--v1120)
🖥️ [Multi-Platform](#️-universal-multi-platform--one-codebase-three-shells)
🔄 [Model Switcher](#-universal-multi-platform--one-codebase-three-shells)

---

**🩺 Monitor & Design**

*Debug & beautify*

🩺 [System Diagnostics](#-system-diagnostics-nodes--config--system-logs)
🎨 [Theming & UX](#-theming--ux-deep-dive)
🔮 [Thinking Orbs](#-theming--ux-deep-dive)

<br/>

</td>

<sub><b>📖 Docs · Setup · Community</b></sub>

<br/>

---

**🛠️ Technical Docs**

*Under the hood*

🛠️ [Tech Stack](#-tech-stack)
📂 [Project Structure](#-project-structure)
📋 [Requirements](#-requirements)

---

**🚀 Build & Configure**

*From clone to release*

🚀 [Getting Started](#-getting-started)
⚙️ [Configuration](#️-configuration)
🔐 [Security & Privacy](#-security--privacy)

---

**💬 Help & Community**

*Support & contribution*

❓ [FAQ](#-frequently-asked-questions)
🐛 [Troubleshooting](#-troubleshooting)
🗺️ [Roadmap](#️-roadmap)
🤝 [Contributing](#-contributing)
💖 [Acknowledgments](#-acknowledgments)
📄 [License](#-license)

<br/>

</td>

</tr>
</tbody>
</table>

## Choose Your Path
<sub><i>Pick the journey that matches your goal</i></sub>

<br/>

**First Time Here?**

<sub>Get up and running in 5 minutes</sub>

<br/>

<sub>1️⃣ Download → 2️⃣ Install → 3️⃣ Chat</sub>

</td>

**Exploring Features?**

<sub>See what CubicLM can do</sub>

<br/>

<sub>Local · Cloud · Vision · Image</sub>

</td>

**Power User?**

<sub>Extend with Skills & MCP</sub>

<br/>

<sub>Tools · Automation · APIs</sub>

</td>

**Developer?**

<sub>Build from source</sub>

<br/>

<sub>Fork · Build · PR</sub>

</td>

</tr>
</table>

</div>

---

<sub><i>Everything CubicLM can do — organized by capability</i></sub>
## <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/ai/icons8-ai.gif" width="80" /> 
</div>

## 🧠 Local AI Inference

> **Your phone is the datacenter.** Download once, chat forever — no internet, no API keys, no rate limits.

### 🦙 llama.cpp Engine
- **LLM inference** via llama.cpp with **GGUF** models
- **GPU acceleration** — Vulkan / OpenCL backends
- **GPU crash recovery** — automatic CPU fallback if the GPU backend fails mid-generation
- **Custom Flutter plugin** (`local_plugins/llama_flutter_android`) with direct FFI bindings

### ⚡ Google LiteRT-LM
- **LiteRT-LM inference** via Google's runtime for `.litertlm` models
- **NPU-optimized** for modern Android SoCs
- **Custom Flutter plugin** (`local_plugins/flutter_litert_lm`)

### 🎨 Stable Diffusion 1.5
- **On-device image generation** from safetensors
- **Isolate-based processing** (`sd_isolate_processor.dart`) keeps the UI at 60fps
- **CPU / Vulkan / OpenCL** backend toggle with automatic model reload

</td>
<td width="50%" valign="top">

### 👁️ Vision Models
- **Qwen2-VL-2B** — image understanding
- **Gemma 4 E2B / E4B** — Google's multimodal Gemma
- Attach images from camera, gallery, or files

### 🎬 Streaming Generation
- **Real-time tokens-per-second** display
- Long answers stream as **plain text** (full markdown rendered on completion)
- **Adaptive flush** (150ms / 300ms) so the chat never janks during heavy generations

### 🔍 Device Intelligence
- **Auto-configuration** — context size & max tokens adapt to detected RAM tier
- **Device specification card** (`Nodes → Config`) — brand, model, OS, CPU cores/ABI, RAM bar, display size, one-tap refresh
- **Real hardware identification** — reads `ro.soc.*` system properties to show the actual SoC (Snapdragon 8 Gen 2, Dimensity 9000, Tensor G3…) and probes Vulkan for the GPU renderer name (Adreno, Mali…)
- **SoC-aware quantization recommendations** based on the detected family

</td>
</tr>
</table>

---

### ⚙️ Device Intelligence

| Feature | Description |
| :--- | :--- |
| 🎚️ **Device-tier auto-configuration** | Adjusts context size and max tokens based on detected RAM |
| 📊 **Device specification card** | `Nodes → Config` shows brand+model, OS version, CPU cores/ABI, RAM free-space bar, display size, one-tap refresh |
| 🔍 **Real hardware identification** | Reads `ro.soc.*` system properties to show the actual processor (Snapdragon 8 Gen 2, Dimensity 9000, Google Tensor G3…) and probes Vulkan for the GPU renderer name (Adreno, Mali…) instead of a generic "Unknown" label |
| 💡 **SoC-aware recommendations** | Quantization recommendations follow from the detected family |

---

## 🎛️ Inference Parameters *(Nodes › Config)*

### 🪄 Auto Tune <sub>(default ON)</sub>

> One switch that keeps limits optimal for your device.

- ✅ Context window and output budget set to the **highest the device's RAM can safely run** (tier-based)
- ✅ Cloud requests sent **without an output cap** — large models write full detailed answers instead of stopping mid-response
- ✅ Inline **(i) info dialog** explains exactly what it does

### 🎚️ Manual Mode

> Flip Auto off for direct control with extended ranges.

</td>
<td width="50%" valign="top">

### 📊 Full Parameter Reference

### 🛡️ RAM Guard *(new in v1.12.0)*

- `DeviceInfoService.canAllocateContextSize()` — computes `fileBytes + KV~2.5KB×context` vs 80% available RAM
- `SettingsController.setContextSize` clamps to `maxSafeContextSize` with snackbar
- `ModelController._confirmModelLoadSafety` includes KV estimate before showing *Restart recommended*

</td>
</tr>
</table>

---

## 🚀 Startup, Onboarding & Splash

### 🎬 Splash Screen

> No white flash, no jank, no waiting.

- **Warm native splash** — `launch_background` is `#F8F4ED` (matches `Dt.canvas`), `NormalTheme` matches — seamless native→Flutter transition
- **Animated CubicLM** — 44–48sp PlusJakartaSans w900
- Shimmer `LinearGradient` isolated in `RepaintBoundary`
- `760ms` fade-in/out · `1380ms` dwell → onboarding/home
- **No jank** after `runApp()` was moved to critical path

</td>
<td width="50%" valign="top">

### 👋 First-Run Onboarding *(new)*

`onboarding_view.dart` — 3-page `PageView`:

| Page | Topic | Icon |
| :---: | :--- | :---: |
| 1 | *Private by Default* | 🛡️ |
| 2 | *Or Use Any Cloud* (23+ providers) | ☁️ |
| 3 | *Pick Your First Model* (recommended chip) | 🎯 |

- Dots pagination + `Skip / Next / Start Chatting`
- Hive-persisted (`onboarding_done_v1`)
- i18n `onboarding_*` EN+BN, fallback for 13 langs

</td>
</tr>
</table>

### ⚙️ Initialization Strategy

**⏳ Deferred Heavy Init**
- `NotificationHistory / Skill / MCP / DeviceInfo / CrashReporting / ImageNotifications` start **`2200ms` after `runApp()`** (after splash completes)
- `Hive` per-box `3s` timeout with `_MemoryBox` fallback
- Result: native `launch_background` **never hangs**

</td>
<td width="50%" valign="top">

**🔄 Auto-Load Last Model** *(App Settings → STARTUP)*

Controlled by `AppConstants.keyAutoLoadLastModel`:

🛑 **Prevents** `mmap 2-7GB` during splash which previously froze 2nd open.

</td>
</tr>
</table>

---

## 🌐 Web Access *(independent chat)*

> The chat page can fetch live web content on its own — **no external services, no API keys, no third-party middlemen**.

### 🔧 How It Works

1. 🔘 Toggle the **🌐 button** in the chat input bar
2. 🔗 When on, any `https://…` links in your message are **downloaded automatically**
3. 🧹 Pages are stripped to **clean readable text** (scripts/styles removed, HTML entities decoded)
4. 🧠 Content injected into the model's context — works for **both local and cloud models**

</td>
<td width="50%" valign="top">

### 📏 Limits & Transparency

</td>
</tr>
</table>

> [!TIP]
> No more "is web search working?" — you see exactly which sites were used, like ChatGPT/Claude, and can tap to open them. Great for **"summarize this article"**, **"what changed on this docs page"**, or grounding answers in real data.

---

## 🧠 Chat Context Memory *(follow-ups don't get lost)*

### 📦 History Storage
- **From storage, not the UI window** — every send rebuilds context from Hive
- Last **40 turns**, chronological
- The visible list is **paged** and never truncates what the model sees

### ✂️ Token-Budget Trim

- Oversized single turns (e.g. a full HTML file) are **middle-truncated** — head + tail kept, `…middle trimmed…` marker
- Current + previous turn are **always kept** — so "make this better" still resolves to the code above it

</td>
<td width="50%" valign="top">

### 🛟 Safety Nets
- **UI fallback** — if storage ever returns empty while the chat shows turns, the visible list is used (with a warning in System Logs) instead of sending zero context silently

### 🧾 Proof in Logs
- Every send writes `Chat context: N turns, ~M tokens (user…user[, trimmed K])` to System Logs (Chat category)
- Roles + sizes only — **never content**

### 💡 Tip for Code Follow-Ups
- Long code answers eat context fast
- Use a **3B+ model** (or a strong cloud model)
- Raise **Nodes › Config → Context Size** if the device allows
- Small 0.6B–1B models may still ask "which game?" on their own

</td>
</tr>
</table>

---

## ☁️ Cloud AI Providers

> **23+ providers, one unified interface.** Every provider implements the same `CloudProvider` interface and registers in `CloudProviderRegistry`.

### 🔀 Aggregators / Gateways

</td>
<td width="50%" valign="top">

### 🏢 First-Party Providers

</td>
</tr>
<tr>
<td width="50%" valign="top">

### ⚡ High-Speed Inference

</td>
<td width="50%" valign="top">

### 🎨 Special & Utilities

</td>
</tr>
</table>

> [!IMPORTANT]
> **Unified plugin architecture** — All providers share `lib/services/cloud/providers/`. Model lists auto-fetch from each provider's API on key save/refresh (with catalog fallback for providers without a `/models` endpoint), with FREE model tagging and filtering where supported. With **Auto Tune** enabled, cloud requests carry no output-token cap — models with 128K+ output budgets answer at full length.

### 🏷️ Auto-Detected Company Filter

> For aggregator providers that host multiple companies' models under `vendor/model` IDs (OpenRouter, Hugging Face, xKiro, TokenRouter, NVIDIA NIM, Together AI, Fireworks…), a company filter chip row appears automatically above the model list.

---

## 🧩 Skills — Offline Instruction Extensions

> Skills are **offline, static prompt-injection blocks** (markdown) that teach the model how to handle a class of tasks. **No network, no SDK** — just text appended to the system prompt. Works identically for **local** (llama.cpp / LiteRT-LM) and **cloud** models.

<details>
<summary><b>🔧 Architecture & Data Model — click to expand</b></summary>

<br/>

| Component | Path | Purpose |
| :--- | :--- | :--- |
| **Data model** | `lib/models/skill_model.dart` | `id / name / description / author / version / content / enabled / isBuiltIn / source / createdAt`; plain text; file fallback for >100 KB |
| **Registry** | `lib/services/skills/skill_registry_service.dart` | Hive `skillsBox` with `installBuiltIns()` (idempotent), `importFromMarkdown`, `enable / disable / delete / getEnabled / getAll`; 5 bundled starters in `assets/skills/` seeded on first run |
| **Injection** | `lib/services/skills/skill_injector.dart` | `buildInjectedContext()` / `buildForSkills()` concatenate skills as `### Skill: {name}` blocks, stably ordered |

**🧠 Intelligent per-prompt activation:**
- `selectRelevantSkills(prompt, max 2)` scores enabled skills by keywords, Bangla-script detection, code-block presence, etc. (threshold `0.6`)
- Only matching skills are injected via `SettingsController.effectiveSystemPromptForPrompt(model, prompt)` → read by `ChatController` for every generation
- The assistant bubble then shows **"Skills used"** chips (check + name, e.g., *Code Reviewer*) — exactly like ChatGPT/Claude's skill indicator
- **If none match: no injection, no chip** — keeps the system prompt lean

</details>

### 📦 Starter Skills *(real content, not placeholders)*

### 🎛️ Skills UI

**📍 Access Points**
- Dedicated **Explore → Skills** tab (4-way toggle: Local / Online / Skills / MCP)
- Same card in **Nodes › Config → SKILLS** (next to Global System Prompt) for quick access

</td>
<td width="50%" valign="top">

**📥 Import Methods**
- **Import → From file** (file_picker)
- **Browse Anthropic skills** (`anthropics/skills` via GitHub REST + raw fetch, cached 6h, rate-limit safe)
- **From URL** — any raw markdown URL, size/type checked, preview-before-enable

</td>
</tr>
</table>

- Preview dialog shares a re-importable `.md` bundle
- GitHub browse is a flat list (no search/categories) with per-item **Import**
- URL import shows preview (frontmatter-parsed name/description) before save
- All imports converge on `importFromMarkdown`

---

## 🔌 Custom MCP Server — Single Remote Connection *(no marketplace)*

> A power-user setting in **Nodes › Config** to connect one user-provided **remote** MCP server (Streamable HTTP / SSE). No stdio, no marketplace, no multi-server, no OAuth UI — **intentionally minimal**.

### 🔨 Implementation

**SDK**
- `dart_mcp ^0.5.2` (labs.dart.dev) + `mcp_client` fallback checked
- Only remote transport is exposed
- Hand-rolled JSON-RPC avoided where the SDK fits
- Flutter ergonomics fallback is HTTP/SSE via `dio`

**Connection** (`lib/services/mcp/mcp_connection.dart`)
- `connect()` — `initialize → notifications/initialized → tools/list`
- `listTools()`, `callTool(name, args)` (size-capped, untrusted), `disconnect()`
- `statusStream` (disconnected / connecting / connected / error) with typed errors (auth / timeout / unreachable)
- Session ID via `mcp-session-id` header, SSE data-frame parsing, bearer auth from secure storage

**Config** (`lib/services/mcp/mcp_config.dart`)
- Single `McpConfig` (name / url / transport / bearer / enabled)
- Transport auto-inferred from URL
- Hive `mcpBox` single record

**Registry** (`lib/services/mcp/mcp_registry_service.dart`)
- Hive + `flutter_secure_storage` (Keystore / Keychain) for token — **never in Hive / plaintext**
- `saveConfig / testConnection / enable / disable / remove`
- Status/tools observables
- `WidgetsBindingObserver` to disconnect on background and reconnect on resume

</td>
<td width="50%" valign="top">

### 🧠 LLM Wiring

- `CloudProvider.supportsMcpTools` + `buildRequestBody(mcpTools)` adds `tools` / `tool_choice: auto` for OpenAI-compatible providers
- `OpenAICompatibleProvider.sendMessage/streamMessage` detects `tool_calls`, calls `McpRegistryService.callTool`, round-trips `tool` result via second request, then returns final answer
- **Streaming** buffers tool deltas and re-emits final answer chunked
- **Local models skip tools** (no reliable structured output) but still benefit from Skills
- Offline / unreachable still advertises tools; failed `callTool` surfaces as error tool-result

### 🖥️ UI

- **Explore → MCP** tab + same form in **Nodes › Config → CUSTOM MCP SERVER** (`_McpSection` + `explore_skills_mcp_tabs.dart`)
- Single form: name, URL, bearer token (eye toggle), transport auto
- **Save / Test / Enable-Disable** (with pre-enable tool preview dialog) **/ Remove**
- Live status dot + banner, exposed-tools list (name + description) before enabling
- 🔒 Stored token **never** enters LLM context
- Explore's 4-way toggle (Local / Online / Skills / MCP) keeps everything discoverable in one place

</td>
</tr>
</table>

> [!WARNING]
> **Ask-before-run** — every tool call shows **Deny / Allow once / Always-allow** (fail-closed, per-tool memory); toggle in the MCP header card.

---

## 🔌 Built-in OpenAI-Compatible API Server

> Turn your phone into an OpenAI-compatible endpoint on port **8080** — use local models from any client on your network.

**Example usage:**
```bash
curl http://<device-ip>:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

---

## 🧩 Additional Features

### 🧭 Navigation

> **Chat · Explore · Nodes · App Settings**

| Destination | Contents |
| :--- | :--- |
| 🔍 **Explore** | Two tabs — **Model Hub** (Local / Online / Skills / MCP scopes) and **Toolkit** (Battle Arena + Slide Maker + CubicWeb Builder widget cards) |
| 🖥️ **Nodes** | Two tabs — **Node** (local API server) and **Config** (diagnostics, hardware capabilities, inference mode, system prompt, Skills, Custom MCP Server, local model & imaging parameters) |
| ⚙️ **App Settings** | Theme mode, typography scale, **Thinking Orbs**, **Language** (15 languages), **Startup → Auto-load last model**, app info |

### 💬 Chat & Sessions

| Feature | Description |
| :--- | :--- |
| 📚 **Multi-session chat** | History (Hive persistence) + **full-text searchable** sidebar drawer (`HiveService.searchMessages` scans `content`) with swipe-to-delete, long-press Export/Delete, and header Export (`share_plus` Markdown) |
| 💬 **Message actions** | Copy, **share**, regenerate, branch into a new chat, and edit with full revision history (step back and forth between edited versions) |
| 📝 **Prompt templates** | 6 built-ins + custom (composer button → bottom sheet, one-tap insert, Hive-persisted) |
| ☑️ **Multi-select** | Long-press or header toggle → bulk copy/share/delete via the selection bar |
| 📌 **Per-chat model pin** | Switcher-sheet toggle pins the active local/cloud model to one chat (📌 pill), auto-applied on open |
| ⚖️ **Side-by-side compare** | One-shot challenger answers the same prompt (`⚖️` message), primary setup restored afterwards |
| 🏟️ **Battle Arena** | Chat ⋮ menu → up to **4 cloud models** race one prompt with live monitor + overall verdict |
| 🏷️ **Chat labels** | Free-form folder label per chat with drawer filter chips |
| 🔒 **Per-chat lock** | Device-auth gate on open; **undo delete** (5s snackbar) |
| 📄 **Whole-chat PDF** | Chat menu export alongside Markdown / .txt |
| 💻 **Code blocks** | Syntax highlighting, one-tap copy, and export/share |

### 🎨 Visual & UX

| Feature | Description |
| :--- | :--- |
| 🔮 **Thinking Orbs** | 3D particle sphere animation (9 states: Working, Searching, Solving, Listening, Connecting, Weaving, Composing, Breathing, Shaping) with grayscale ink, size-aware speeds, and phase-continuous hard cuts |
| 🖼️ **Empty state** | `assets/icons/CubicLM.png` 64×64 + animated shimmer above suggestions — never a blank screen |
| 🔄 **Header & composer sync** | `chat_view.dart:302,1185` both `Obx` on `InferenceService.loadedModelName` / `LocalImageService.loadedModelName` + `SettingsController` mode |
| 🏷️ **Chat enrichments** | Assistant bubbles show **Sources** chips (favicon + domain + title, tap to open) when web search was used, and **Skills used** chips (check + skill name) when a prompt matched enabled skills |

### 🔔 Notifications & Background

<details>
<summary><b>Click to expand</b></summary>

<br/>

**🔔 Notification History**
- Bell in chat header with unread badge
- Slide-in page grouped by **Today / Yesterday / weekday** with relative timestamps (Just now / 5m ago / 2h ago)
- Swipe-to-delete, mark-all-read & clear-all
- Every model switch (local / cloud / back-to-local) auto-logs with timestamp and shows as a **top spring-animated toast** (`AppSnackbar.showTop` `lib/utils/app_snackbar.dart:29`)
- Hive-persisted, max 100
- `LogView` copy now also uses top toast, not bottom

**📥 Background Model Download**
- Foreground service — downloads keep running when the app is closed or swiped away
- Notification with **Pause / Cancel** actions
- HTTP Range resume picks up at the **exact byte offset** after pause or app restart (`START_STICKY`)
- **🆕 Resume race + atomicity fixed** — `download_service:68` atomic `.tmp→rename` for `paused_downloads.json`; `download_native:427` `validateDownloadedFile()` (GGUF `GGUF` / litertlm `LITERTLM` / safetensors `{` + 1% size); `reconcileActiveDownloads` prefers native and cleans stale completed before restore; `model_controller:199` async header check for imported files

**🔔 Background-done Ping**
- Answers finishing while backgrounded fire a notification with preview

</details>

### 📎 Input & Sharing

- **Share-target (Android)** — text shared from any app lands in the composer via `ACTION_SEND` + method channel (cold + warm paths)
- **Offline outbox** — failed sends queue and auto-send when back online
- **Attachments** — camera, gallery, or files (PDF/text extraction)
- **Image sharing and export**
- **Dark/light theme** with adjustable font scale

### 🔧 System

- 🔥 **Firebase Crashlytics** integration
- 🔋 **Background service** and boot persistence
- 📥 **In-app model download** with byte-exact pause / resume / cancel, plus file import

---

## 🌐 CubicWeb Builder *(Toolkit)* — `v1.12.0`

> **The AI-powered web builder baked into CubicLM.** Stream code, preview live, deploy in one click.

### 🎬 Build Experience
- **Live streaming builds** — files appear in the explorer as the AI writes (writing badges, live highlighted editor)
- Static preview reloads live; cancel rolls back to checkpoint
- **Plan mode, checkpoints/undo, diff view**
- **Responsive viewports** (mobile / tablet / desktop)
- Screenshot-to-code, keyboard shortcuts, 6 project templates

### 🖥️ Runtime
- **Real local runtime** — project detection (static / Vite / Next / Node)
- Source validation
- Dev-server manager (install, free-port pick, URL parse, health check, crash watcher, restart)
- Real shell terminal

### 🚀 Deploy & Share
- One-click **Vercel / Netlify** deploy
- Share links, GitHub export
- Component library
- Extended-thinking + web-search toggles
- Browser auto-test

</td>
<td width="50%" valign="top">

### ⚛️ Next.js Pipeline
- Atomic writes, byte-for-byte integrity gates
- Framework adapters
- `npm run build` validation
- External-browser preview

### 🧑‍💻 Developer Tools
- **Terminal + CLI manager** — real shell with history/autocomplete/stdin attach
- One-tap installs for **Claude Code, OpenCode, Cline, Kilo**
- Open / Verify / Update / Repair / Uninstall with persistent registry

### 📊 Diagnostics & Cloud Tools
- **CubicWeb System Logs** — structured `CW-*` diagnostics separate code bugs from missing runtimes / device limits (see Nodes › Config › System Logs + AppBar activity icon); AI skips rewrites for environment failures
- **Cloud model tools** — import from `/models` with new-count report, test-all with online/failed dots, auto-hide failed, auto-sync interval (configurable)

</td>
</tr>
</table>

---

## 🖥️ Universal Multi-Platform — *One Codebase, Three Shells*

> [!IMPORTANT]
> **Web ⇄ Windows Desktop ⇄ Android** — same `lib/` product, **not three forks**. Per `docs/PLATFORM_DIFFERENCES.md` (AUDIT→PLAN→BUILD).

### 🤖 Android *(primary, full)*
- `android/` Gradle 8.14
- `ModelDownloadService.kt` (FGS, Range, `START_STICKY`)
- Native storage
- Background service & boot persistence
- **Full local inference** via llama.cpp + LiteRT-LM

</td>
<td width="33%" valign="top">

### 🌐 Web *(Flutter Web)*
- `web/` static shell (`index.html`, `manifest.json`)
- Hive IndexedDB
- `dart:io` stubs (`download_web.dart`, `inference_stub.dart`)
- `flutter build web` → `build/web`
- **Cloud-only** until `dart:ffi` is solved

</td>
<td width="33%" valign="top">

### 🪟 Windows Desktop
- **Flutter Windows**, not Tauri per §8.5
- `windows/` CMake runner
- `window_manager 0.4.3` (`400×700` min, `1280×800` default, centered, `CubicLM` title, `waitUntilReadyToShow`)
- Native file dialogs via `file_picker`
- `flutter build windows` → `build/windows/runner/Release/cubiclm.exe`
- **Cloud-only** until `llama.dll` is ported

</td>
</tr>
</table>

<details>
<summary><b>🤔 Why Flutter Windows, not Tauri?</b></summary>

<br/>

Existing `shared` is Dart (`lib/`), not TS — Tauri would require rewriting `lib/` in TS/Svelte or bridging Dart→Rust; `flutter create --platforms=windows` reuses **100% of `lib/` for free** (lower total cost, §8.5 justification).

</details>

### 🧭 Architecture & Consistency

| Principle | Details |
| :--- | :--- |
| **Single source of truth** | `shared/constants/platform_links.dart` + `lib/shared/constants/platform_links.dart` (now set to `https://cubiclm.vercel.app` + GitHub Releases). `About → AVAILABLE ON` links to the *other two* platforms + centralized `CHANGELOG.md`, never to itself, via `launchUrl(externalApplication)` (Web `_blank`, Desktop OS browser, Android Browser tab) — see `docs/PLATFORM_LINKS.md` |
| **Responsive, not forked** | `lib/shared/theme/tokens.dart` (`Breakpoints.phone 360 / tablet 600 / laptop 900 / desktop 1280 / wide 1920`, `Spacing`, `TypographyTokens`) + `Dt` tokens; `HomeView._isWide 800` (sidebar vs bottom nav), `Flexible` pill `14` chars, `Expanded` header — verified `360/768/1280/1920` + manual resize `400×700` → `1920` per §5.3 |
| **Docs** | `docs/PLATFORM_DIFFERENCES.md` (local inference cloud-only on Web/Windows until `local_plugins/llama_flutter_windows` ported), `docs/ARCHITECTURE.md`, `docs/BUILD_AND_RUN.md`, `scripts/build-all.ps1` / `.sh` |
| **Windows local inference** | *(intentional gap §8.3)* — `local_plugins` are Android FFI only → `supportsLocalInference=false` on `TargetPlatform.windows`, shows cloud banner; roadmap is `local_plugins/llama_flutter_windows` (`llama.dll`) |

### 🔄 In-Chat Model Switcher

> Opened from the chat header — mirrors the Explore page's layout.

**🏠 Local tab**
- Search box over downloaded models
- LiteRT / GGUF / "In memory" badges
- Live load progress

</td>
<td width="50%" valign="top">

**☁️ Cloud tab**
- Every configured provider gets a collapsible section styled like the Explore provider cards
- Count badges, FREE badge + filter chip
- Per-provider search
- Auto-detected company filter chips
- Scrollable boxed model list
- A global search box above matches models across **all providers at once** (results show the owning provider); picking a result switches the active provider automatically

</td>
</tr>
</table>

> [!TIP]
> Deactivating the active cloud provider switches inference back to local mode and **auto-loads the last downloaded model**.

---

## 🩺 System Diagnostics *(Nodes › Config › System Logs)*

### 💚 Health Dashboard

Auto-detects **10 crash patterns**:

| # | Pattern |
| :---: | :--- |
| 1 | Model file missing |
| 2 | Context overflow |
| 3 | Model load failure |
| 4 | GPU error |
| 5 | Cloud API error |
| 6 | Out of memory |
| 7 | Generation hang |
| 8 | Stale multi-model slot |
| 9 | Import failure |
| 10 | Firebase init |

> `RenderFlex overflow` is logged as `ERROR [System]` but correctly shows **No crash patterns** (layout, not model).

### 🔎 Filters
- **Category filters** — System, Model, Cloud, Chat, Server, Image
- **Level filters** — ALL, ERROR, WARNING, INFO, DEBUG
- **Full-text search** across log messages and details

</td>
<td width="50%" valign="top">

### 💾 Persistence & Export
- **Log persistence** — logs survive app restarts (saved to JSON, max 500 entries)
- **Export** — copies full diagnostic report (health summary + all logs) to clipboard (top toast)

### 🔬 Deep Insights
- **Crash pattern details** — occurrence count, last-seen timestamp, and fix suggestion for each detected issue
- **Chat context proof** — every chat send logs `Chat context: N turns, ~M tokens…` (Chat category) so a "model forgot" report is instantly diagnosable

</td>
</tr>
</table>

---

## 🎨 Theming & UX Deep Dive

<details>
<summary><b>Click to explore the design system</b></summary>

<br/>

### 🎨 Color Palette

> Claude APK-measured warm palette, defined in `lib/core/design_tokens.dart`.

### 📐 Breakpoints

### 🔮 Thinking Orbs

3D particle sphere animation with **9 named states**:

`Working` · `Searching` · `Solving` · `Listening` · `Connecting` · `Weaving` · `Composing` · `Breathing` · `Shaping`

- **Grayscale ink** rendering
- **Size-aware speeds** — larger orbs rotate slower
- **Phase-continuous hard cuts** — no visual snapping
- **Random** shuffle or fixed state per context (chatting / image gen / analyzing)
- Live previews in the picker (**App Settings › Thinking Orbs**)

### ✨ Animation Timings

</details>

---

# <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/ai/ai.gif" width="120" /> 
# Supported Models

<sub><i>18+ curated models across 3 runtimes — all downloadable in-app</i></sub>

</div>

### ⚡ LiteRT-LM *(on-device)*

| Model | Size | Params | Best For |
| :--- | ---: | :---: | :--- |
| **Qwen3-0.6B** | 586 MB | 0.6B | Smallest chat model for low-RAM phones |
| **Qwen2.5-1.5B Instruct** | 1.49 GB | 1.5B | Balanced int8 quantized chat model |
| **DeepSeek-R1-Distill-Qwen-1.5B** | 1.71 GB | 1.5B | Reasoning-focused model |
| **Gemma 4 E2B Instruct** | 2.46 GB | 2B | Google Gemma vision + chat |
| **Gemma 4 E4B Instruct** | 3.40 GB | 4B | Highest quality LiteRT option |

### 🐫 GGUF *(llama.cpp)*

| Model | Size | Params | Best For |
| :--- | ---: | :---: | :--- |
| **Kimi Moonlight 16B-A3B (Q3_K_S)** | 7.1 GB | 16B MoE (3B active) | High-capability MoE, efficient inference |
| **Qwen2.5-3B Instruct (Q4_K_M)** | 2.1 GB | 3B | Best mobile speed/quality |
| **Qwen2-VL-2B (Q4_K_M)** | 1.5 GB | 2B | Vision-capable |
| **Phi-3.5 Mini (Q4_K_M)** | 2.2 GB | 3.8B | Microsoft reasoning model |
| **Gemma 2 2B (Q4_K_M)** | 1.71 GB | 2B | Google lightweight chat |
| **Llama-3.2-3B Uncensored** | 2.1 GB | 3B | Unrestricted assistant |
| **Llama-3.2-1B Instruct** | 0.8 GB | 1B | Ultra-lightweight |
| **+ uncensored / abliterated variants** | — | — | Dolphin, SmolLM2, Gemma abliterated |

### 🎨 Image Generation *(Stable Diffusion 1.5)*

| Model | Size | Style |
| :--- | ---: | :--- |
| **DreamShaper 8 LCM** | 2.0 GB | Fast 4-step generation |
| **CyberRealistic V8 FP16** | 2.0 GB | Photorealistic, uncensored |
| **Realistic Vision V5.1 FP16** | 2.0 GB | Popular portrait / scene model |
| **AbsoluteReality 1.8.1** | 2.0 GB | General-purpose photorealistic |
| **AnyLoRA** | 2.0 GB | Anime / stylized |

### 📊 Model Selection Guide

| Device RAM | Recommended Models |
| :--- | :--- |
| **4 GB** | Qwen3-0.6B, Llama-3.2-1B, Qwen2.5-1.5B |
| **6 GB** | Gemma 2 2B, Qwen2-VL-2B, Phi-3.5 Mini |
| **8 GB** | Qwen2.5-3B, Llama-3.2-3B, Gemma 4 E2B |
| **12 GB+** | Gemma 4 E4B, Kimi Moonlight 16B-A3B |

---

<div align="center">
<h1>🛠️ Tech Stack</h1>
<sub><i>Technologies powering CubicLM</i></sub>
</div>

<br/>

| Category | Technologies |
| :--- | :--- |
| 🎯 **Framework** | Flutter 3.x |
| 💻 **Language** | Dart, Kotlin, C++ (native plugins) |
| 🔄 **State Management** | GetX |
| 💾 **Local Storage** | Hive |
| 🌐 **Networking** | dio, http |
| 🧠 **Local Inference** | `llama_flutter_android`, `flutter_litert_lm`, `sd_flutter_android` (custom plugins) |
| ☁️ **Cloud Backend** | Firebase Core, Firebase Messaging, Firebase Crashlytics |
| 🌍 **Localization** | 15 languages — EN, BN, HI, AR, ZH, ES, FR, JA, KO, PT, DE, TR, ID, RU, UR<br>GetX Translations with Hive persistence<br>90+ keys — `nav_*`, `chat_*`, `model_*`, `nodes_*`, `about_*`, `settings_*`, `onboarding_*`<br>`fallbackLocale EN`<br>App Settings + bottom nav + all 5 views reactive via `'.tr'` |
| 📦 **Other Libraries** | `google_fonts` · `flutter_markdown` · `image_picker` · `share_plus` · `permission_handler` · `speech_to_text` · `lucide_icons` · `url_launcher` · `file_picker` · `flutter_secure_storage` · `dart_mcp` · `window_manager` |

<br/>

---

### 📊 Dependency Highlights

</div>

---

# 📂 Project Structure

</div>

<details>
<summary><b>🗂️ Click to expand full directory tree</b></summary>

<br/>

```text
lib/
├── main.dart                              # App entry point — critical path (Hive 5s + Settings), heavy services 2200ms deferred
├── core/
│   ├── app_translations.dart              # GetX Translations — ~160 keys × 15 languages
│   ├── assets_data.dart                   # Embedded asset catalog helpers
│   ├── colors.dart                        # App color palette (warm Claude-inspired)
│   ├── constants.dart                     # Settings keys, model catalog, API endpoints
│   ├── languages.dart                     # 15 supported languages (code, name, nativeName, flag, Locale)
│   ├── routes.dart                        # Route definitions
│   └── theme.dart                         # Light/dark theme with warm accent palette
├── theme/
│   └── design_tokens.dart                 # Claude APK-measured warm palette (canvas #F8F4ED, pill, accent, hairline)
├── models/
│   ├── ai_model.dart                      # AI model data class
│   ├── chat_message.dart                  # Chat message (revision history + webSources + usedSkills)
│   ├── chat_session.dart                  # Chat session model
│   ├── folder_model.dart                  # Chat folder/label model
│   ├── notification_entry.dart            # Model-switch history entry
│   ├── project_model.dart                 # CubicWeb project model
│   ├── skill_model.dart                   # Skill (name/description/content/enabled/isBuiltIn/source)
│   ├── task_model.dart                    # Automated task model
│   └── web_source.dart                    # Web source (url/domain/favicon/title/success)
├── controllers/
│   ├── agent_controller.dart              # Agent/skill lifecycle
│   ├── battle_arena_controller.dart       # Side-by-side model comparison
│   ├── chat_controller.dart               # Chat logic, streaming, per-prompt skill/web-source tracking
│   ├── cloud_model_controller.dart        # Cloud model selection
│   ├── home_controller.dart               # Tab navigation, model resume (520ms delay, async file check, 90s crash guard)
│   ├── model_controller.dart              # Model download/import management
│   ├── server_controller.dart             # Local API server
│   ├── settings_controller.dart           # App settings + locale, effectiveSystemPromptForPrompt, autoLoadLastModel
│   ├── slide_deck_controller.dart         # Slide Maker engine
│   ├── task_controller.dart               # Automated task execution
│   └── vision_live_controller.dart        # Live vision camera
├── services/
│   ├── agent_workspace.dart               # Skill/agent workspace persistence
│   ├── app_log_service.dart               # App logging with categories & crash detection
│   ├── chat_backup.dart                   # Chat backup/restore
│   ├── cloud_service.dart                 # Multi-provider cloud API (delegates to providers) + usage tracking
│   ├── code_interpreter_service.dart      # Sandboxed code execution
│   ├── crash_reporting_service.dart       # Firebase Crashlytics
│   ├── deploy_service.dart                # Vercel/Netlify deploy
│   ├── device_info_native.dart            # Native device info (Android)
│   ├── device_info_service.dart           # RAM/tier + SoC/GPU detection
│   ├── device_info_web.dart               # Web device info stubs
│   ├── document_extractor_service.dart    # PDF/text extraction
│   ├── download_native.dart               # Resumable streaming downloader (HTTP Range)
│   ├── download_service.dart              # Download orchestrator (native FGS + Dart fallback)
│   ├── download_web.dart                  # Web stubs
│   ├── execution_service.dart             # Task execution engine
│   ├── hive_service.dart                  # Local persistence (7 boxes, per-box 3s timeout)
│   ├── image_generation_notification_service.dart
│   ├── inference_android.dart             # Android llama.cpp / LiteRT engine bridge
│   ├── inference_gguf.dart                # GGUF inference backend
│   ├── inference_litert.dart              # LiteRT-LM inference backend
│   ├── inference_service.dart             # Cross-platform inference orchestrator
│   ├── inference_stub.dart                # Web/no-ffi stub
│   ├── inference_text.dart                # Text inference helpers
│   ├── inference_types.dart               # Inference type definitions
│   ├── local_image_service.dart           # Stable Diffusion inference
│   ├── memory_service.dart                # Context memory management
│   ├── notification_history_service.dart  # Model-switch history (Hive, max 100)
│   ├── openai_server_service.dart         # Built-in OpenAI-compatible server
│   ├── openai_server_service_io.dart      # IO platform implementation
│   ├── openai_server_service_stub.dart    # Web stub
│   ├── preview_server.dart                # CubicWeb preview server
│   ├── sd_isolate_processor.dart          # SD processing in isolates
│   ├── sd_isolate_worker.dart             # SD isolate worker
│   ├── sd_isolate_worker_io.dart          # IO platform SD worker
│   ├── sd_isolate_worker_web.dart         # Web platform SD worker
│   ├── secure_key_store.dart              # Secure key storage
│   ├── soc_family.dart                    # SoC family detection
│   ├── stats_service.dart                 # Usage statistics
│   ├── tts_service.dart                   # Text-to-speech
│   ├── update_service.dart                # App update checker
│   ├── usage_tracker_service.dart         # Per-provider/model token usage (Hive JSON, chars/4)
│   ├── vector_service.dart                # Vector embedding service
│   ├── web_fetch_service.dart             # URL fetching → clean text + WebSource
│   ├── win_toast_io.dart                  # Windows toast notification (IO)
│   ├── win_toast_notify.dart              # Windows toast notification
│   ├── win_toast_stub.dart                # Windows toast stub
│   ├── browser/
│   │   └── adblock_service.dart           # Privacy browser adblock (318 rules)
│   ├── cloud/                             # Cloud provider plugin architecture
│   │   ├── cloud_provider.dart            # Abstract CloudProvider interface
│   │   ├── cloud_provider_config.dart     # Provider configuration
│   │   ├── cloud_provider_registry.dart   # Provider registry (ID → instance)
│   │   ├── model_health.dart              # Model health tracking
│   │   └── providers/                     # 26 provider files
│   │       ├── openai_compatible_provider.dart
│   │       ├── openai_provider.dart
│   │       ├── anthropic_provider.dart
│   │       ├── google_provider.dart
│   │       ├── deepseek_provider.dart
│   │       ├── zai_provider.dart
│   │       ├── groq_provider.dart
│   │       ├── mistral_provider.dart
│   │       ├── together_provider.dart
│   │       ├── xai_provider.dart
│   │       ├── perplexity_provider.dart
│   │       ├── cerebras_provider.dart
│   │       ├── fireworks_provider.dart
│   │       ├── cohere_provider.dart
│   │       ├── huggingface_provider.dart
│   │       ├── xkiro_provider.dart
│   │       ├── tokenrouter_provider.dart
│   │       ├── agentrouter_provider.dart
│   │       ├── orcarouter_provider.dart
│   │       ├── apinex_provider.dart
│   │       ├── kimi_provider.dart
│   │       ├── nvidia_provider.dart
│   │       ├── openrouter_provider.dart
│   │       ├── stability_provider.dart
│   │       └── custom_provider.dart
│   ├── cubicdata/                         # CubicDataSheet engine
│   │   ├── controller.dart
│   │   ├── formulas.dart
│   │   ├── models.dart
│   │   ├── search.dart
│   │   └── vault_store.dart
│   ├── cubicweb/                          # CubicWeb event system
│   │   ├── cubicweb_event.dart
│   │   └── cubicweb_logger.dart
│   ├── mcp/                               # MCP (Model Context Protocol)
│   │   ├── mcp_config.dart
│   │   ├── mcp_connection.dart
│   │   └── mcp_registry_service.dart
│   ├── runtime/                           # CubicWeb dev-server + CLI manager
│   │   ├── ansi.dart
│   │   ├── cli_manager.dart
│   │   ├── cli_manifest.dart
│   │   ├── cli_providers.dart
│   │   ├── cloud_runtime.dart
│   │   ├── dev_server_manager.dart
│   │   ├── dev_url_parser.dart
│   │   ├── framework_runtime.dart
│   │   ├── preview_router.dart
│   │   ├── process_runner.dart
│   │   ├── project_detector.dart
│   │   ├── project_validator.dart
│   │   ├── runtime_manager.dart
│   │   └── frameworks/                    # Framework adapters
│   │       ├── framework.dart
│   │       ├── nextjs.dart
│   │       ├── node_generic.dart
│   │       ├── static_site.dart
│   │       └── vite.dart
│   └── skills/                            # Skills system
│       ├── skill_registry_service.dart
│       ├── skill_injector.dart
│       ├── github_skill_source.dart
│       └── url_skill_source.dart
├── views/
│   ├── splash_view.dart                   # 1380ms shimmer + 760ms fade-out
│   ├── onboarding_view.dart               # 3-page PageView + dots + Hive persist
│   ├── home_view.dart                     # Main navigation scaffold (IndexedStack 5 tabs)
│   ├── chat_view.dart                     # Chat interface
│   ├── model_view.dart                    # Model Hub — 4-way toggle (Local/Online/Skills/MCP)
│   ├── explore_skills_mcp_tabs.dart       # Explore Skills + MCP tabs
│   ├── server_view.dart                   # Nodes page — Node + Config tabs
│   ├── settings_view.dart                 # Config sections
│   ├── app_settings_view.dart             # App Settings
│   ├── language_picker_view.dart          # Full-page language picker
│   ├── about_view.dart                    # About page
│   ├── notification_history_view.dart     # Notification history page
│   ├── log_view.dart                      # System diagnostics viewer (Live Logs + Saved Files)
│   ├── system_logs_view.dart              # CubicWeb system logs
│   ├── task_view.dart                     # Automated tasks
│   ├── toolkit_view.dart                  # Toolkit hub (Battle Arena, Slide Maker, CubicWeb Builder)
│   ├── battle_arena_view.dart             # Side-by-side model comparison
│   ├── agent_ide_view.dart                # Agent IDE
│   ├── gallery_view.dart                  # Image gallery
│   ├── slide_deck_view.dart               # Slide Maker composer
│   ├── update_view.dart                   # Update checker
│   ├── update_settings_view.dart          # Update settings
│   ├── chat/                              # Chat decomposition
│   │   ├── chat_bars.dart
│   │   ├── chat_dialogs.dart
│   │   ├── chat_format.dart
│   │   ├── chat_sidebar.dart
│   │   ├── chat_widgets.dart
│   │   ├── empty_state.dart
│   │   ├── input_bar.dart
│   │   ├── project_context_view.dart
│   │   ├── selection_bar.dart
│   │   └── template_sheets.dart
│   ├── cubicdata/                         # CubicDataSheet views
│   │   ├── dashboard_view.dart
│   │   ├── datasheet_home_view.dart
│   │   ├── doc_view.dart
│   │   ├── hybrid_view.dart
│   │   ├── palette_view.dart
│   │   └── sheet_view.dart
│   ├── cubicweb/                          # CubicWeb Builder views
│   │   ├── agent_preview.dart
│   │   ├── browser_view.dart
│   │   ├── chat_cards.dart
│   │   ├── component_card.dart
│   │   ├── diff_view.dart
│   │   ├── file_cards.dart
│   │   ├── knowledge_graph_view.dart
│   │   ├── project_sheets.dart
│   │   ├── responsive_grid_view.dart
│   │   └── version_timeline.dart
│   ├── explore/                           # Explore tab components
│   │   ├── add_model_sheet.dart
│   │   ├── local_model_card.dart
│   │   ├── provider_cards.dart
│   │   ├── provider_dialogs.dart
│   │   ├── provider_theme.dart
│   │   └── toolkit_tab.dart
│   ├── settings/                          # Settings sub-sections
│   │   ├── apple_widgets.dart
│   │   ├── device_card.dart
│   │   ├── model_params.dart
│   │   └── skills_section.dart
│   └── slides/                            # Slide Maker sub-views
│       ├── slide_canvas.dart
│       ├── slide_charts.dart
│       ├── slide_dialogs.dart
│       ├── slide_outline_view.dart
│       ├── slide_painters.dart
│       └── slide_present_view.dart
├── widgets/
│   ├── app_ui.dart                        # Shared UI components
│   ├── artifact_renderer.dart             # Markdown/artifact rendering
│   ├── attachment_preview.dart            # Attachment preview chips
│   ├── chat_branch_timeline.dart          # Branch history timeline
│   ├── chat_bubble.dart                   # Message bubble + _sanitizeUtf16
│   ├── citation_chip.dart                 # Source citation chip (favicon + domain)
│   ├── cli_sheets.dart                    # CLI terminal sheets
│   ├── code_block.dart                    # Syntax-highlighted code blocks
│   ├── image_viewer.dart                  # Full-screen image viewer
│   ├── model_switcher_sheet.dart          # In-chat model switcher
│   ├── thinking_orb.dart                  # 3D particle sphere animation (9 states)
│   ├── thought_disclosure.dart            # Reasoning tag expansion
│   ├── typing_indicator.dart              # Typing animation
│   ├── typing_text.dart                   # Typewriter text animation
│   └── voice_overlay.dart                 # Voice input overlay
├── ffi/
│   ├── sd_ffi_bindings.dart               # FFI bindings for SD native lib
│   ├── sd_ffi_bindings_io.dart            # IO platform bindings
│   └── sd_ffi_bindings_web.dart           # Web platform bindings
├── utils/
│   ├── app_snackbar.dart                  # Top spring-animated toast
│   ├── artifact_parser.dart               # Markdown artifact extraction
│   ├── battle_scoring.dart                # Battle Arena scoring
│   ├── export_file.dart                   # Log export (copy/share/save)
│   ├── history_budget.dart                # Token budget trimming
│   ├── prompt_export.dart                 # Chat export (Markdown/PDF/TXT)
│   ├── slide_deck.dart                    # Slide deck data model + PPTX import
│   ├── slide_palette.dart                 # Slide color palette derivation
│   ├── slide_pptx.dart                    # PPTX generation
│   ├── syntax_highlight.dart              # Code syntax highlighting
│   ├── thought_parser.dart                # <thought> tag parser
│   ├── web_download.dart                  # Cross-platform web download
│   ├── web_download_stub.dart             # Web stub
│   ├── web_download_web.dart              # Web platform download
│   ├── web_notify.dart                    # Web notification
│   ├── web_notify_stub.dart               # Web stub
│   ├── web_notify_web.dart                # Web platform notification
│   └── web_project.dart                   # Web project helpers
└── shared/
    ├── constants/
    │   └── platform_links.dart            # Centralized platform URLs
    └── theme/
        └── tokens.dart                    # Breakpoints, Spacing, TypographyTokens

local_plugins/
├── llama_flutter_android/                 # llama.cpp Flutter plugin (GGUF inference)
├── flutter_litert_lm/                    # Google LiteRT-LM Flutter plugin
├── sd_flutter_android/                   # Stable Diffusion Flutter plugin
├── lucide_icons/                         # Vendored Lucide icon pack (v0.257.0)
└── speech_to_text_windows/               # Windows speech-to-text plugin

android/
├── app/src/main/kotlin/com/cubiclm/app/
│   ├── MainActivity.kt                   # Flutter engine + channel wiring
│   ├── ModelDownloadService.kt           # Foreground service: Range resume, notification
│   └── BootReceiver.kt                   # Boot persistence
└── res/values+drawable/launch_background.xml  # Warm #F8F4ED

windows/
├── runner/                               # Win32 runner (window_manager)
├── CMakeLists.txt
├── installer/cubiclm.iss                 # Inno Setup installer script
└── updater_config.json                   # auto-update scaffolding (disabled)

web/
├── index.html
└── manifest.json

scripts/
├── build-all.ps1                         # One-command build (Android + Windows)
├── build-all.sh                          # One-command build (Android + Web + Windows)
└── sync-opencode-models.mjs              # Model catalog sync

assets/
├── adblock_hosts.txt                     # Privacy browser host blocklist
├── catalog/models.json                   # Bundled model catalog
├── icons/
│   ├── CubicLM.png                       # App icon (splash)
│   └── CubicLM_Icon.png                  # App icon (launcher)
└── skills/                               # 5 bundled starter skills
    ├── bn_en_translator.md
    ├── code_reviewer.md
    ├── creative_writer.md
    ├── efficient_prompting.md
    └── study_helper.md

docs/
├── ARCHITECTURE.md                       # One product, three shells
├── PLATFORM_DIFFERENCES.md               # Android full vs Web/Windows cloud-only
├── BUILD_AND_RUN.md                      # Clean clone → Android/Web/Windows
├── PLATFORM_LINKS.md                     # Single-file link editing
├── AGENT_IDE_DESIGN.md                   # Agent IDE design doc
├── CUBIC_WEB_SYSTEM_LOGS.md              # CubicWeb diagnostics doc
├── quick_release.md                      # Release checklist
├── terminal.md                           # Terminal feature doc
├── web_builder_nextjs.md                 # Next.js pipeline doc
└── web_builder_react(vite).md            # Vite/React pipeline doc
```

</details>

---

# 📋 Requirements

</div>

### 🎯 Minimum

| Requirement | Version |
| :--- | :--- |
| 🐦 **Flutter** | `3.3.0+` |
| 🤖 **Android SDK** | minSdk 28 / Android 9+ |
| ☕ **Java** | 17 |
| 💾 **Storage** | ~500 MB (app + smallest model) |
| 🧠 **RAM** | 4 GB |

</td>
<td width="50%" valign="top">

### 🚀 Recommended

### 🔑 For Release Builds
- Keystore configured at `android/key.properties`
- See `android/key.properties.example` for template

</td>
</tr>
</table>

---

# 🚀 Getting Started

</div>

### 1️⃣ Clone & Install

```bash
# Clone the repository
git clone https://github.com/abir2afridi/CubicLM.git
cd CubicLM

# Install dependencies
flutter pub get

# Verify Flutter setup
flutter doctor
```

### 2️⃣ Run

```bash
# Auto-picks Android/Windows/Web device from `flutter devices`
flutter run

# Android — full local inference
flutter run -d android

# Web — cloud-only (Hive IndexedDB), responsive reflow
flutter run -d chrome

# Windows — 1280×800 window_manager, cloud-only until llama.dll ported
flutter run -d windows
```

### 📦 Release Build

#### 🔑 Setup

1. Copy `android/key.properties.example` → `android/key.properties`
2. Fill in your keystore credentials and path:
   ```properties
   storePassword=your_store_password
   keyPassword=your_key_password
   keyAlias=your_key_alias
   storeFile=/path/to/your/keystore.jks
   ```

</td>
<td width="50%" valign="top">

#### 🏗️ Build Commands

```bash
# Android APK
flutter build apk --release
# → build/app/outputs/flutter-apk/app-release.apk

# Windows
flutter build windows
# → build/windows/runner/Release/cubiclm.exe
#   (41 MB bundle; zip: 16 MB)

# Web (currently blocked by dart:ffi)
flutter build web
# → build/web

# Or one command for supported shells:
pwsh -File scripts/build-all.ps1   # Windows PowerShell
bash scripts/build-all.sh          # Linux/macOS
```

</td>
</tr>
</table>

> [!NOTE]
> **Windows build prerequisites (v1.2.0):**
> - `nuget.exe` on `PATH` (`flutter_inappwebview_windows` dependency)
> - ATL headers — `Microsoft.VisualStudio.Component.VC.ATL` via Visual Studio Installer
> - Short build path if your checkout contains spaces (e.g. `C:\CLM` junction)
> - `CL=/D_SILENCE_EXPERIMENTAL_COROUTINE_DEPRECATION_WARNINGS` for MSVC 14.51
> - See [`windows/CMakeLists.txt:1,35,47`](windows/CMakeLists.txt) and [`docs/BUILD_AND_RUN.md`](docs/BUILD_AND_RUN.md)

> [!TIP]
> Set `CUBICLM_ALLOW_DEBUG_RELEASE_SIGNING=true` to skip keystore validation during development.

---

# ⚙️ Configuration

</div>

### 🔑 Cloud API Keys

> Tap **Add API Key** on any provider card in the **Explore** tab.

| Step | Action |
| :---: | :--- |
| 1️⃣ | 📋 Paste the key |
| 2️⃣ | ✅ Hit **Verify** — live endpoint check, nothing saved |
| 3️⃣ | 💾 **Save Key** unlocks once it shows *Verified — N models found* |

**🔀 Sorting behavior:**
- 🔝 Keyed providers sort to the top (Custom always first, then pinned, then by key-set time or A–Z)
- 🔒 Keyless ones sit in an *Add API Key* section below and **never appear in the chat model switcher**

**🔄 Refresh options:** ↻ button on a provider card, or probe every model with the activity (Test all) button.

---

### 💾 Local Models

- 📥 Download models from the **Explore** tab (with pause / resume / cancel support)
- 📁 Or import `.gguf` / `.litertlm` / `.safetensors` files via the file picker
- 🔐 Models are stored in **app-private storage**
- 🛡️ Loading is guarded — missing or corrupted files are detected before reaching the native engine, and stale download pointers are cleaned up automatically

---

### 🌐 Local API Server

> Open the **Nodes** tab › **Node** and flip the switch.

Once running, point any OpenAI-compatible client at `http://<device-ip>:8080` to use your local models programmatically.

---

### 🧩 Skills

> Manage in **Nodes › Config → SKILLS** (next to Global System Prompt).

> [!NOTE]
> Every import shows a preview before saving; skills are **pure text injection, never executable**. Nothing about installed skills is sent to any Abir/Anthropic server.

---

### 🔌 Custom MCP Server

> Configure in **Nodes › Config → CUSTOM MCP SERVER**.

- 🌐 Single remote HTTP/SSE URL, optional bearer token (secure storage), transport auto-detected
- 🎛️ **Save / Test Connection / Enable-Disable** (with tool-preview dialog) **/ Remove** with live status (disconnected / connecting / connected / error)
- 🧠 When enabled, its tools are added to OpenAI-compatible cloud requests (`tools` / `tool_choice: auto`); tool results are round-tripped via `chat_controller` and capped
- 📴 If offline, tools are still advertised and failed calls return an error `tool_result` — **never silently omitted**
- 🏠 Local models don't use live tools (Skills still apply)

---

### ⚙️ Engine & App Configuration

#### 🖥️ Nodes › Config
- 🔍 Diagnostics
- 🧮 Hardware capabilities
- 🎯 Inference mode
- 🪄 **Auto Tune** (context/output limits)
- 📝 Global system prompt
- 🧩 **Skills**
- 🔌 **Custom MCP Server**
- 🎨 Local model & imaging parameters

</td>
<td width="50%" valign="top">

#### 📱 App Settings
- 🎨 Theme, typography scale
- 🔮 **Thinking Orbs** (Random or fixed state per context)
- 🌍 **Language** (15 languages with instant switch)
- 🚀 Startup auto-load
- 🔒 **App Lock** re-lock timeout + biometric-only
- 💾 **Auto backup** (silent JSON every N days, last 3 kept)
- 📤 **Settings export/import** (no secrets)
- ℹ️ App info (View Update center + settings)

</td>
</tr>
</table>

### 🔐 Privacy & Chat Controls

- 🕵️ **Hidden chats** — stronger hide than archive (out of drawer AND search), per-chat menu toggle with show/hide reveal
- 🌐 **Web Access toggle** — in the chat input bar; reads links from your message into the model's context

---

# 🔐 Security & Privacy

</div>

### 🛡️ What Stays On-Device

### 🔒 Secure Storage

- MCP bearer tokens use **`flutter_secure_storage`** → Android Keystore / iOS Keychain
- **Never** written to Hive or plaintext
- **Never** enters LLM context

</td>
<td width="50%" valign="top">

### 🌐 What Leaves Your Device

Only what you explicitly configure:

- ☁️ **Cloud API requests** — only to providers whose keys you've saved
- 🐙 **Skills browse** — `github.com/anthropics/skills` REST + raw fetch (cached 6h)
- 🔗 **Web Access fetches** — direct `https://…` URLs from your message
- 📊 **Firebase Crashlytics** — anonymous crash reports (can be disabled in build)
- 📥 **Model downloads** — direct from Hugging Face / release URLs

### 🚫 What CubicLM Never Does

- ❌ No telemetry beyond Crashlytics
- ❌ No analytics SDKs (no Google Analytics, no Mixpanel, no Amplitude)
- ❌ No cloud sync of chats (unless you export)
- ❌ No "phone home" pings
- ❌ No training on your data

</td>
</tr>
</table>

> [!IMPORTANT]
> **Skills are never executed.** They are **static markdown text** appended to the system prompt. No JavaScript, no shell, no FFI. A malicious skill can only try to influence the LLM's output — it cannot run code on your device.

---

# <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/question/question1.gif" width="120" /> 
## Frequently Asked Questions

</div>

<details>
<summary><b>🤔 Is CubicLM really free?</b></summary>

<br/>

Yes — CubicLM is **MIT-licensed** and free forever. There's no premium tier, no feature gates, no ads. Cloud providers may charge you for API usage (their terms, not ours), but the app itself is 100% free and open-source.

</details>

<details>
<summary><b>📱 Will it work on my phone?</b></summary>

<br/>

Minimum is **Android 9 (API 28)** with **4 GB RAM**. For a smooth experience:

| RAM | What You Can Run |
| :--- | :--- |
| 4 GB | Qwen3-0.6B, Llama-3.2-1B |
| 6 GB | Qwen2.5-1.5B, Gemma 2 2B, Qwen2-VL-2B |
| 8 GB | Qwen2.5-3B, Llama-3.2-3B, Gemma 4 E2B |
| 12 GB+ | Gemma 4 E4B, Kimi Moonlight 16B-A3B |

</details>

<details>
<summary><b>🔋 Does local inference drain my battery?</b></summary>

<br/>

Local inference is CPU/GPU-intensive — expect **~15-25%/hour** of screen-on chat with a small model on a modern phone. Larger models (7B+) can drain faster. **Cloud providers use almost no battery** (just network I/O).

**Tips:**
- Use a smaller quantized model (Q3/Q4) for casual chat
- Enable **GPU acceleration** (Vulkan) in `Nodes → Config` — faster + more efficient than CPU
- Use cloud providers for long sessions when plugged in

</details>

<details>
<summary><b>🌐 Can I use CubicLM completely offline?</b></summary>

<br/>

**Absolutely.** Once you've downloaded a model, you can chat forever without internet:
- ✅ Local inference works offline
- ✅ Chat history is local
- ✅ Skills work offline
- ✅ Web Access is optional (obviously needs internet)
- ✅ MCP requires network (it's remote)

Turn off Wi-Fi / cellular and CubicLM still functions perfectly with local models.

</details>

<details>
<summary><b>💻 Why isn't there a macOS / Linux / iOS build?</b></summary>

<br/>

The `lib/` code is **platform-agnostic** — it would run on iOS/macOS/Linux with `flutter create --platforms=<target>`. The gaps are:

- **iOS** — Apple's App Store review process for on-device LLMs is strict; also no Vulkan (Metal would need porting in `llama_flutter_android`)
- **macOS** — Same Metal issue; would need `llama_flutter_macos` plugin
- **Linux** — Would need `llama_flutter_linux` plugin; low priority given Windows covers desktop

If you want to port it: fork `local_plugins/llama_flutter_android` and adapt the FFI bindings. PRs welcome!

</details>

<details>
<summary><b>🔌 How do I use CubicLM as an API server for my homelab?</b></summary>

<br/>

1. Load a model in CubicLM
2. Go to **Nodes → Node** and flip the server switch
3. Find your phone's IP (Settings → About → Status)
4. Point any OpenAI-compatible client at `http://<phone-ip>:8080`

**Example (Python):**
```python
from openai import OpenAI
client = OpenAI(base_url="http://192.168.1.42:8080/v1", api_key="not-needed")
resp = client.chat.completions.create(
    model="local",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(resp.choices[0].message.content)
```

</details>

<details>
<summary><b>🧩 What's the difference between Skills and MCP?</b></summary>

<br/>

**Use Skills** for: consistent tone, coding style, translation rules, domain knowledge.
**Use MCP** for: real-time data, external APIs, database queries, file operations.

</details>

<details>
<summary><b>🔄 How do I update CubicLM?</b></summary>

<br/>

- **Android**: Download the new APK from [Releases](https://github.com/abir2afridi/CubicLM/releases). Installing over the old version preserves all data.
- **Windows**: Download the new zip, extract over the old folder. Or use the About page → View Update center (when auto-update is enabled).

Your models, chats, skills, and API keys are all preserved across updates.

</details>

<details>
<summary><b>🐛 I found a bug — where do I report it?</b></summary>

<br/>

Open an issue on [GitHub Issues](https://github.com/abir2afridi/CubicLM/issues) with:

1. **Device info** — copy from `Nodes → Config → Device Specification card`
2. **Reproduction steps**
3. **System Logs** — `Nodes → Config → System Logs` → Export → paste
4. **Screenshot / video** if visual

The in-app **System Logs** export includes a health dashboard that already tells us a lot — please include it.

</details>

<details>
<summary><b>💰 Can I sponsor / support development?</b></summary>

<br/>

The best support is:
- ⭐ **Star the repo** on GitHub
- 🐛 **Report bugs** with detailed info
- 📣 **Share** CubicLM with others
- 🤝 **Contribute** code or documentation

There's no donation link — this is a passion project. If you build something cool with it, let us know!

</details>

---

# 🐛 Troubleshooting

</div>

> [!TIP]
> **Before filing a bug:** export `Nodes → Config → System Logs` — the health dashboard + last 500 log entries usually pinpoint the issue instantly.

---

# 🗺️ Roadmap

</div>

### ✅ Shipped *(v1.12.0)*
- [x] Android full support (llama.cpp + LiteRT-LM)
- [x] Windows desktop (cloud-only)
- [x] 23+ cloud providers
- [x] Skills + MCP
- [x] Built-in OpenAI-compatible API server
- [x] CubicWeb Builder (Toolkit)
- [x] Thinking Orbs animation
- [x] 15 languages
- [x] Battle Arena (up to 4 models)
- [x] Per-chat model pin & lock
- [x] Web Access with visible sources
- [x] RAM guard + crash-loop guard

</td>
<td width="50%" valign="top">

### 🚧 In Progress / Planned

**Near-term**
- [ ] **Windows local inference** — `local_plugins/llama_flutter_windows` (`llama.dll`)
- [ ] **Web build unblocked** — `dart:ffi` alternative for cloud-only Web
- [ ] **Auto-update** — Windows `updater_config.json` enablement
- [ ] **iOS feasibility study** — Metal backend for llama.cpp

**Mid-term**
- [ ] **Voice mode** — end-to-end speech-to-text + TTS
- [ ] **Multi-modal local** — more VLMs (LLaVA, Moondream)
- [ ] **Local embeddings** — remove the honest 400 on `/v1/embeddings`
- [ ] **Plugin marketplace** — community Skills + MCP registry

**Long-term**
- [ ] **Linux desktop** — `flutter create --platforms=linux`
- [ ] **macOS desktop** — Metal + `llama_flutter_macos`
- [ ] **Distributed inference** — split model across devices on LAN

</td>
</tr>
</table>

---

# 🤝 Contributing

</div>

Contributions are welcome — code, docs, translations, bug reports, or feature ideas.

### 🛠️ Code Contributions

1. **Fork** the repo
2. **Branch** — `git checkout -b feature/my-feature`
3. **Follow conventions:**
   - Dart: `flutter analyze` clean
   - Kotlin: follow Android style
   - Commit: [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`)
4. **Test** on Android + Windows if possible
5. **PR** with a clear description + screenshots

</td>
<td width="50%" valign="top">

### 🌍 Translation Contributions

Adding a language is easy:

1. Open `lib/core/app_translations.dart`
2. Copy the `en` block to a new locale (e.g. `'it'`)
3. Translate the ~160 keys
4. Add to `lib/core/languages.dart`
5. Bump the `Language` count in the README

**Currently supported:** EN, BN, HI, AR, ZH, ES, FR, JA, KO, PT, DE, TR, ID, RU, UR

</td>
</tr>
</table>

### 📜 Code of Conduct

Be kind. Be patient. Assume good faith. This is a hobby project — maintainers contribute in their spare time.

### 🐛 Reporting Bugs

Use the [GitHub Issues](https://github.com/abir2afridi/CubicLM/issues) template. Include:
- Device info (from `Nodes → Config` card)
- Steps to reproduce
- System Logs export
- Screenshots if visual

---

<div align="center">
  
# <img src="https://github.com/abir2afridi/abir2afridi/blob/main/asset/love/icons8-heart-balloon.gif" />
## Acknowledgments

</div>

CubicLM stands on the shoulders of giants:

And to the **open-source community** that made every one of these tools free and accessible.

---

# 📄 License

**MIT License**

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. See [LICENSE](LICENSE) for full text.

</div>

---

<br/>

### ⭐ If CubicLM made your day, consider starring the repo!

It helps others discover the project and keeps development going.

<br/>

<p>
  <sub>Built with ❤️ by <a href="https://github.com/abir2afridi"><b>Abir Afridi</b></a> and contributors</sub><br/>
  <sub><i>CubicLM — Your AI, your device, your rules.</i></sub>
</p>

<br/>

<br/>

<a href="https://star-history.com/#abir2afridi/CubicLM&Date">
  <img src="https://api.star-history.com/svg?repos=abir2afridi/CubicLM&type=Date" alt="Star History" width="600"/>
</a>

<sub><b>✨ Every feature, capability & detail from the original README is preserved — upgraded into an advanced, magazine-style layout ✨</b></sub>

<sub><b>✨ No information was removed — this is a full design upgrade with extensive new sections added ✨</b></sub>

</div>

<br/>

<sub>
  💡 <b>Pro tip:</b> Press <kbd>Ctrl</kbd> + <kbd>F</kbd> to search · <kbd>T</kbd> for the file tree · <kbd>Esc</kbd> to close dialogs
</sub>

</td>
</tr>
</table>

<br/>

</div>

CubicLM

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README