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 ⚡

Connect to 23+ cloud providers ☁️ · Extend with Skills 🧩 · Built-in OpenAI-compatible API 🔌

_{Cloud AI}

_Localization

_On-Device

_Extensions

_{Multi-Platform}

_{Privacy First}

📱⚡ 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 🔌.

📥 Download · ✨ Features · 🤖 Models · 🛠️ Stack · 📂 Structure · 🚀 Setup · ⚙️ Config · ❓ FAQ · 🤝 Contribute

What is CubicLM?

💡 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.

🎁 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

Download — `v1.16.0`

🎉 Latest release · Build date: current · View full changelog →

Architecture	File	Size
Android _{arm64-v8a · modern phones}	`cubiclm-v1.16.0-arm64-v8a.apk`	67 MB
Android _{armeabi-v7a · older devices}	`cubiclm-v1.16.0-armeabi-v7a.apk`	21 MB
Android _{x86_64 · emulators, tablets}	`cubiclm-v1.16.0-x86_64.apk`	32 MB
Windows _{x64 · requires WebView2}	`cubiclm-v1.15.1-windows-x64.zip` _{unzip & run cubiclm.exe}	17 MB
Checksums _{SHA-256 verification}	`checksums.sha256`	—

🧭 Which Build Should I Choose?

Your Device	Recommended	Why
📱 Modern Android phone (2020+)	arm64-v8a	Best performance, full GPU acceleration, all models run
📱 Older / budget Android	armeabi-v7a	Smaller install, runs smaller quantized models
🖥️ Android emulator / Chromebook	x86_64	Native architecture for Intel/AMD chips
💻 Windows 10/11 PC	windows-x64	Cloud mode + Skills + MCP; optional local GGUF via llama-server sidecar when bundled (LiteRT/SD remain Android-first)
🌐 Any browser	Coming soon	Web is `dart:ffi`-blocked; tracked for future release

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

🧭 Navigation

_{Everything you need — organized into 3 zones · 23 sections · instant jump}

🗂️ Documentation Zones

_{🎯 Start here · Features · Models}

🎯 Introduction

Get to know CubicLM

🎯 What is CubicLM?
📥 Download — v1.12.0

✨ Core Features

What makes it powerful

🧠 Local AI Inference
🎛️ Inference Parameters
🚀 Startup & Onboarding
🌐 Web Access
🧠 Chat Context Memory
☁️ Cloud Providers

🤖 Model Catalog

18+ ready-to-run models

⚡ LiteRT-LM Models
🐫 GGUF Models
🎨 Image Generation
📊 Selection Guide

_{🧩 Power features · Integrations}

🧩 Extend & Integrate

Add new capabilities

🧩 Skills System
🔌 MCP Server
🔌 Built-in API

🌐 Build & Deploy

Create & ship apps

🌐 CubicWeb Builder
🖥️ Multi-Platform
🔄 Model Switcher

🩺 Monitor & Design

Debug & beautify

🩺 System Diagnostics
🎨 Theming & UX
🔮 Thinking Orbs

_{📖 Docs · Setup · Community}

🛠️ Technical Docs

Under the hood

🛠️ Tech Stack
📂 Project Structure
📋 Requirements

🚀 Build & Configure

From clone to release

🚀 Getting Started
⚙️ Configuration
🔐 Security & Privacy

💬 Help & Community

Support & contribution

❓ FAQ
🐛 Troubleshooting
🗺️ Roadmap
🤝 Contributing
💖 Acknowledgments
📄 License

Choose Your Path

_{Pick the journey that matches your goal}

🆕

First Time Here?

_{Get up and running in 5 minutes}

_{1️⃣ Download → 2️⃣ Install → 3️⃣ Chat}

🔍

Exploring Features?

_{See what CubicLM can do}

_{Local · Cloud · Vision · Image}

⚡

Power User?

_{Extend with Skills & MCP}

_{Tools · Automation · APIs}

👨‍💻

Developer?

_{Build from source}

_{Fork · Build · PR}

Features

Name: CubicLM
Author: CubicLM

_{Everything CubicLM can do — organized by capability}

🧠 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

👁️ 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 (Settings → 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

⚙️ Device Intelligence

Feature	Description
🎚️ Device-tier auto-configuration	Adjusts context size and max tokens based on detected RAM
📊 Device specification card	`Settings → 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 (Settings › Parameters)

🪄 Auto Tune _{(default ON)}

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.

Parameter	Range
Context window	1K → 1M tokens (LiteRT capped to 4K by hardware)
Output tokens	256 → 128K tokens
Warnings	Orange warnings past device's recommended limit — but values stay selectable

📊 Full Parameter Reference

Parameter	Behavior
🌡️ Inference temperature	Applied on every generation, local and cloud
🎯 Local sampling	Top-P / Top-K / repeat-penalty sliders (GGUF + LiteRT; cloud uses provider defaults)
🔄 Context window changes	Auto-reload the resident model after the slider settles
🎨 Image generation	Sampling steps and synthesis resolution (Auto mode scales by available RAM)
⚡ Compute backend	CPU / Vulkan / OpenCL toggle with automatic model reload

🛡️ 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

🚀 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

👋 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

⚙️ 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

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

Controlled by AppConstants.keyAutoLoadLastModel:

Setting	Behavior
`ON`	After chat UI idle (splash gone + `DeviceInfo` ready + `1200ms`), checks `isModelLoaded` resident, `90s` crash-loop guard, `80%` RAM guard, then `loadModel().timeout(90s)` off the UI frame
`OFF` (default)	Shows `Resume Session?` dialog after `520ms`

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

🌐 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

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

📏 Limits & Transparency

Constraint	Value
Links per message	3 max
Characters per page	~9K
Timeout per fetch	15s
Source display	✅ Tappable chips with favicon (Google S2) + domain + title
Failed fetches	❌ Not shown, but logged

[!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

Scope	Budget
Local	~60% of Context Size (~4 chars/token)
Cloud	48K-char budget

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

🛟 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 Settings › Parameters → Context Size if the device allows
Small 0.6B–1B models may still ask "which game?" on their own

🧠 Long-Term Memory (ROM, not RAM)

Chats persist in on-device Hive storage forever — but a 2K context window can't hold them. CubicLM auto-learns durable facts and recalls relevant past turns into each generation. 100% offline: no embeddings model, no online database.

Layer	How
📝 Auto-learn facts	"amar nam Abir" / "remember X" → fact box (EN + romanized Bangla patterns, max 2/turn, duplicates + contradictions auto-replaced). Review/edit/delete on the Memory page
🔍 Cross-chat recall	Each turn: keywords → recent visible chats scanned → isolate-scored → top 3 turns (300-char centered snippets, 1 per chat) injected before your question when budget allows. Archived/hidden chats excluded
🎯 Ranked injection	System prompt gets only query-relevant facts (600-char budget), not a dump
🧠 Proof chip	Assistant bubble shows Memory +N when past turns informed the answer; System Logs rows `New memory stored` / `Recalled N past turn(s)`

☁️ Cloud AI Providers

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

🔀 Aggregators / Gateways

Provider	Highlights
OpenRouter	Multi-provider gateway — hundreds of models, free tier
Hugging Face	Inference Providers router — dozens of upstream vendors
xKiro	Smart-routing gateway, free tier, all vendors
TokenRouter	Unified hub — 100+ vendor models
AgentRouter	Non-profit OpenAI gateway — Claude / GPT / Gemini / GLM
OrcaRouter	Cost-price gateway — `vendor/model` IDs, `orcarouter/auto`
APInex	One-key gateway — OpenAI / Anthropic / Gemini / DeepSeek / Kimi / Zhipu / xAI

🏢 First-Party Providers

Provider	Models
OpenAI	GPT-5.2, GPT-4o, etc.
Anthropic	Claude Sonnet 4
Google Gemini	Gemini 2.5 Flash
DeepSeek	deepseek-v4-flash
Z.AI	GLM-5.3 series + free GLM Flash models
xAI Grok	Grok-4, Grok-3, vision
Perplexity	Sonar — web-grounded answers

⚡ High-Speed Inference

Provider	Models
Groq	Ultra-fast LPU — Llama, Qwen, DeepSeek
Cerebras	Fastest inference — Llama, Qwen, GPT-OSS
Mistral AI	Large, Codestral, Pixtral
Together AI	Llama, DeepSeek, Qwen turbo
Fireworks AI	Production open-model hosting
NVIDIA NIM	Llama 3.1, etc.
Cohere	Command-A, Command-R, Aya

🎨 Special & Utilities

Feature	Details
Stability AI	SD3.5 Flash cloud image generation
Cloud usage estimates	Explore → Online header card: per-provider in/out tokens + calls (chars/4, no pricing table), resettable
Custom endpoints	OpenAI-compatible with multiple profile support

[!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.

Behavior	Detail
🎯 Derived from model IDs	Chips are computed from the fetched model list itself
🆕 Zero-config updates	When a new vendor appears on the aggregator, its chip shows on the next refresh — no app update needed
✨ Prettified names	Known vendor names/icons are styled; unknown ones fall back to capitalized IDs

🧩 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.

🔧 Architecture & Data Model — click to expand

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

📦 Starter Skills (real content, not placeholders)

Skill	Purpose	Trigger Heuristics
🌐 Bangla-English Translator	Bilingual Banglish handling	Bangla script detection
🔍 Code Reviewer	Flutter / Dart / Python / JS senior review	Code-block presence
⚡ On-Device Efficient Prompting	Concise, structured for 2K–8K contexts	Local model detection
📚 Study Helper — ELI12	Analogy + quiz format	"explain", "teach" keywords
✍️ Creative Writer	Stories / poems / scripts	Creative keywords

🎛️ Skills UI

📍 Access Points

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

📥 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

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 Settings › 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

🧠 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 Settings › 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

[!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.

Feature	Details
🌐 Expose local models	OpenAI-compatible API on port 8080
🔑 Optional API key authentication	Toggle on/off
🚦 Rate limit	120 POSTs/min/IP (429 response), in-memory request ring (see `/v1/server/capabilities`)
⚠️ Honest 400	for `/v1/embeddings` (no on-device embedding mode)
📋 Recent-request viewer	in Settings → Nodes (last 10, auto-refresh)
🔌 Compatibility	Works with any OpenAI-compatible client on your network

Example usage:

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 · Toolkit · Settings

Destination	Contents
🔍 Explore	Model Hub (Local / Online / Skills / MCP scopes)
🧰 Toolkit	Battle Arena + Slide Maker + CubicWeb Builder widget cards
⚙️ App Settings	Six tabs — General (theme, orbs, language, startup), Nodes (local API server), Config (diagnostics, hardware, inference mode, system prompt, Skills, Custom MCP Server), Parameters (local model & imaging parameters), Dev Tools (Strict RAM guard, Developer tools, Linux runtime), Data (backups, export/import, usage stats, System logs)

💬 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

Click to expand

🔔 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

📎 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

⚛️ 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 Settings › 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)

🖥️ 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

🌐 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

🪟 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

🤔 Why Flutter Windows, not Tauri?

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).

🧭 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

☁️ 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

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

🩺 System Diagnostics (Settings › 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

💾 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

🎨 Theming & UX Deep Dive

Click to explore the design system

🎨 Color Palette

Token	Value	Usage
`Dt.canvas`	`#F8F4ED`	Warm off-white canvas (matches native splash)
`Dt.accent`	`#FF4D00`	Primary orange accent (brand color)
`Dt.pill`	—	Pill-shaped buttons
`Dt.hairline`	—	Subtle 1px separators

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

📐 Breakpoints

Name	Width	Layout
`phone`	360px	Bottom nav
`tablet`	600px	Bottom nav
`laptop`	900px	Sidebar nav
`desktop`	1280px	Sidebar nav
`wide`	1920px	Sidebar nav + wider gutters

🔮 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

Animation	Duration
Splash shimmer dwell	`1380ms`
Splash fade-out	`760ms`
Toast spring (top)	OS-default
Streaming flush (short)	`150ms`
Streaming flush (long)	`300ms`
Onboarding page transition	OS-default
Undo-delete snackbar	`5000ms`

Supported Models

_{18+ curated models across 3 runtimes — all downloadable in-app}

⚡ 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

🛠️ Tech Stack

_{Technologies powering CubicLM}

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 GetX Translations with Hive persistence 90+ keys — `nav_`, `chat_`, `model_`, `nodes_`, `about_`, `settings_`, `onboarding_*` `fallbackLocale EN` App Settings + bottom nav + all 4 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`

📊 Dependency Highlights

Dependency	Purpose
`llama_flutter_android`	Custom plugin — llama.cpp FFI bindings for Android
`flutter_litert_lm`	Custom plugin — Google LiteRT-LM runtime bindings
`sd_flutter_android`	Custom plugin — Stable Diffusion inference
`dart_mcp ^0.5.2`	MCP client (labs.dart.dev)
`window_manager 0.4.3`	Windows desktop window sizing & positioning
`flutter_secure_storage`	Keystore / Keychain for MCP bearer tokens

📂 Project Structure

🗂️ Click to expand full directory tree

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
│   ├── cloud_provider_info.dart           # Cloud provider metadata (split from cloud_model_controller)
│   ├── folder_model.dart                  # Chat folder/label model
│   ├── notification_entry.dart            # Model-switch history entry
│   ├── preview_step.dart                  # Preview-pipeline step value type (split from agent_controller)
│   ├── 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/                           # Big controllers are split: main + `part` files (one per feature)
│   ├── agent_controller.dart              # Agent-IDE orchestrator (main: fields, lifecycle)
│   │   ├── agent_controller_workspace.dart  # console, assets, symbols, attachments, mentions
│   │   ├── agent_controller_chat.dart       # transcript, build steps, terminal buffer
│   │   ├── agent_controller_streaming.dart  # streaming merge, fidelity checks, file ops
│   │   ├── agent_controller_generation.dart # project generation, plan, repair
│   │   └── agent_controller_runtime.dart    # preview serve, dev server, terminal, CLI
│   ├── battle_arena_controller.dart       # Side-by-side model comparison
│   ├── chat_controller.dart               # Chat logic (main) + 7 part files
│   │   ├── chat_controller_sessions.dart    # sessions, folders, model pins
│   │   ├── chat_controller_messages.dart    # selection, revisions, compare, export
│   │   ├── chat_controller_generation.dart  # send pipeline, context budget, web, skills
│   │   ├── chat_controller_attachments.dart # image/photo/file picking, text extraction
│   │   ├── chat_controller_voice.dart       # TTS playback, voice mode, speech-to-text
│   │   ├── chat_controller_templates.dart   # prompt templates (built-ins + custom)
│   │   └── chat_controller_find.dart        # find-in-page + history search
│   ├── cloud_model_controller.dart        # Cloud selection (main) + 4 part files
│   │   ├── cloud_providers.dart             # registry, ordering, filters, pins, key verify
│   │   ├── cloud_models.dart                # per-provider models, custom profiles
│   │   ├── cloud_health.dart                # health probes, test-all, persistence
│   │   └── cloud_sync_parse.dart            # auto-sync + model-list sync/parse
│   ├── home_controller.dart               # Tab navigation, model resume (520ms delay, async file check, 90s crash guard)
│   ├── model_controller.dart              # Local models (main) + 4 part files
│   │   ├── model_catalog.dart               # OTA/bundled catalog + custom URL models
│   │   ├── model_downloads.dart             # downloads, pause/resume/cancel, delete
│   │   ├── model_loading.dart               # load + file validation (SafeTensors/LiteRT)
│   │   └── model_safety.dart                # RAM-guard confirmations + dialogs
│   ├── server_controller.dart             # Local API server
│   ├── settings_controller.dart           # Settings (main) + 5 part files
│   │   ├── settings_loading.dart            # startup load, migration, persistence
│   │   ├── settings_cloud.dart              # providers, API keys, sync, shared generation
│   │   ├── settings_browser.dart            # parameters, browser opts, bookmarks, defaults
│   │   ├── settings_media.dart              # SD/WebGPU, cameras, TTS/STT, vision, audio
│   │   └── settings_appearance.dart         # fonts, themes, lock, export, reset, dev tools
│   ├── 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 4 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                   # Node manager (Settings → Nodes tab)
│   ├── 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 (main) + 7 part files + markdown builders
│   │   ├── agent_ide_mentions.dart          # @-mention overlay + picker
│   │   ├── agent_ide_sheets.dart            # system prompt, assets, brand, voice sheets
│   │   ├── agent_ide_command.dart           # command palette, ask-bar, bottom meter
│   │   ├── agent_ide_panes.dart             # preview, dev-tools, terminal, status panes
│   │   ├── agent_ide_chat.dart              # chat pane, actions, templates
│   │   ├── agent_ide_dialogs.dart           # asset-gen + global-search dialogs, file tabs
│   │   ├── agent_ide_files.dart             # files pane, tree, console, editor
│   │   └── agent_ide_markdown.dart          # architecture/component markdown builders
│   ├── gallery_view.dart                  # Image gallery
│   ├── slide_deck_view.dart               # Slide Maker composer (main) + 3 part files
│   │   ├── slide_deck_sheets.dart           # style/plus/theme/translate/data/URL sheets
│   │   ├── slide_deck_browser.dart          # sorter, deck bar, carousel, slide cards
│   │   └── slide_deck_canvas.dart           # slide canvases + image controls
│   ├── 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
│   │   ├── browser_sheets.dart              # bottom sheets + dialogs (split from browser_view)
│   │   ├── browser_home.dart                # home-tab content (split from browser_view)
│   │   ├── 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 (main) + 3 part files
│   │   ├── chat_bubble_actions.dart         # action bar, branch picker, TTS controls
│   │   ├── chat_bubble_bars.dart            # context menu, artifact/recall/skills/source bars
│   │   └── chat_bubble_helpers.dart         # badges, time/cost formatting, text cleanup
│   ├── citation_chip.dart                 # Source citation chip (favicon + domain)
│   ├── citation_link_builder.dart         # Citation-link markdown builder (split from chat_bubble)
│   ├── 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 (main) + 3 part files
│   │   ├── model_switcher_widgets.dart      # rows, headers, scope toggle
│   │   ├── model_switcher_local.dart        # local-model tab
│   │   └── model_switcher_cloud.dart        # cloud-model tab
│   ├── 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

🧩 File-split convention (two-dev + AI workflow): files over ~500 lines are split into a small main + one part file per feature (part of + extension … on …), so two developers + AI agents can work without merge conflicts. Every part file carries a Contains: header listing its methods — check it before editing. Behavior stays identical: splits move code only, verified by flutter analyze (0 issues) + full test suite.

📋 Requirements

🎯 Minimum

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

🚀 Recommended

Requirement	Version
🐦 Flutter	`3.19+` (latest stable)
🤖 Android	Android 12+ (better Vulkan)
💾 Storage	20+ GB (multiple models)
🧠 RAM	8 GB+
🎮 GPU	Adreno 6xx+ / Mali G7x+

🔑 For Release Builds

Keystore configured at android/key.properties
See android/key.properties.example for template

🚀 Getting Started

1️⃣ Clone & Install

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

# Install dependencies
flutter pub get

# Verify Flutter setup
flutter doctor

2️⃣ Run

# 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

Copy android/key.properties.example → android/key.properties

Fill in your keystore credentials and path:

storePassword=your_store_password
keyPassword=your_key_password
keyAlias=your_key_alias
storeFile=/path/to/your/keystore.jks

🏗️ Build Commands

# 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

[!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 and docs/BUILD_AND_RUN.md

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

⚙️ Configuration

🔑 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 Settings → Nodes 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 Settings › Config → SKILLS (next to Global System Prompt).

Method	Details
✅ Enable / disable	Toggle built-ins
📁 Import → From file	`.md` via file picker
🐙 Browse Anthropic skills	Flat list from `anthropics/skills`, cached, rate-limit safe
🔗 From URL	Any raw markdown link, size/type checked

[!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 Settings › 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

🖥️ Settings › Config

🔍 Diagnostics
🧮 Hardware capabilities
🎯 Inference mode
🪄 Auto Tune (context/output limits)
📝 Global system prompt
🧩 Skills
🔌 Custom MCP Server

🎚️ Settings › Parameters

🎨 Local model parameters
🖼️ Synthetic imaging parameters

📱 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)

🔐 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

🛡️ What Stays On-Device

Data	Storage
💬 Chat history	Hive (encrypted at rest by OS)
🤖 Local models	App-private storage
🎨 Generated images	App-private storage
📝 Skills content	Hive `skillsBox` (plain text — never uploaded)
🔑 API keys	Hive (or secure storage for MCP tokens)
📊 Usage estimates	Hive JSON, per-provider aggregated

🔒 Secure Storage

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

🌐 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

[!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.

Frequently Asked Questions

🤔 Is CubicLM really free?

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.

📱 Will it work on my phone?

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

🔋 Does local inference drain my battery?

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 Settings → Config — faster + more efficient than CPU
Use cloud providers for long sessions when plugged in

🌐 Can I use CubicLM completely offline?

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.

💻 Why isn't there a macOS / Linux / iOS build?

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!

🔌 How do I use CubicLM as an API server for my homelab?

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

Example (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)

🧩 What's the difference between Skills and MCP?

Aspect	Skills 🧩	MCP 🔌
Type	Static prompt injection	Live tool calls
Network	None needed	Requires remote server
Works on local models	✅ Yes	❌ No (unreliable structured output)
Works on cloud models	✅ Yes	✅ Yes (OpenAI-compatible)
User confirmation	None	Ask-before-run dialog
Best for	Teaching the model how to respond	Giving the model live access to tools

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

🔄 How do I update CubicLM?

Android: Download the new APK from 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.

🐛 I found a bug — where do I report it?

Open an issue on GitHub Issues with:

Device info — copy from Settings → Config → Device Specification card
Reproduction steps
System Logs — Settings → Config → System Logs → Export → paste
Screenshot / video if visual

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

💰 Can I sponsor / support development?

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!

🐛 Troubleshooting

Symptom	Likely Cause	Fix
App crashes on model load	Model file corrupt or RAM insufficient	Check `Settings → Config → System Logs` for `ERROR [Model]`; re-download or try a smaller quant
"Restart recommended" after context change	RAM guard triggered	Lower Context Size or switch to a smaller model
Streaming jank on long answers	Large context + big model	Reduce Context Size, or use a smaller model
Cloud provider returns 401	Invalid / expired API key	Re-verify the key in Explore; some providers rotate free keys
MCP tools not appearing	Server unreachable / wrong transport	Test Connection in MCP config; check the URL scheme (http vs https)
Web Access returns nothing	Link timed out or blocked	Check System Logs for `[Web]` errors; some sites block scraping
Skills not injecting	Threshold not met	Check the skill's trigger keywords; only skills scoring >0.6 activate
Windows app won't launch	WebView2 missing	Install Microsoft Edge WebView2 Runtime
Windows build fails with ATL error	ATL headers not installed	Visual Studio Installer → Add `Microsoft.VisualStudio.Component.VC.ATL`
`RenderFlex overflow` on small screens	Known layout edge case	Logged as ERROR but harmless; already fixed for 360dp (see `chat_view.dart`)

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

🗺️ Roadmap

✅ Shipped (v1.12.0)

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

🚧 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
Windows update feed — windows/updater_config.json points at GitHub Releases + zip/checksum templates; signed silent install still needs MSIX/Inno cert
iOS feasibility study — Metal backend for llama.cpp

Mid-term

Voice mode — conversational polish beyond existing STT+TTS hands-free loop
Multi-modal local — more VLMs (LLaVA, Moondream)
Free web search in chat — Deep Search uses DuckDuckGo when no Perplexity key is set; Perplexity still preferred when keyed
Local embeddings (v1) — /v1/embeddings via on-device trigram-hash vectors (cubiclm-trigram-hash-v1); neural model swap planned
Encrypted auto-backups — optional AES-256 auto-backups with passphrase in device secure storage
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

🤝 Contributing

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

🛠️ Code Contributions

Fork the repo
Branch — git checkout -b feature/my-feature
Follow conventions:
- Dart: flutter analyze clean
- Kotlin: follow Android style
- Commit: Conventional Commits (feat:, fix:, docs:)
Test on Android + Windows if possible
PR with a clear description + screenshots

🌍 Translation Contributions

Adding a language is easy:

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

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

📜 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 template. Include:

Device info (from Settings → Config card)
Steps to reproduce
System Logs export
Screenshots if visual

Acknowledgments

CubicLM stands on the shoulders of giants:

Project	Role
🦙 llama.cpp	The inference engine that makes local LLMs possible on mobile
⚡ Google LiteRT-LM	On-device ML runtime for Android
🎨 Stable Diffusion	Image generation backbone
🐦 Flutter	Cross-platform UI framework
🧩 dart_mcp	MCP client for Dart
🎯 GetX	State management
🗄️ Hive	Fast local storage
🔥 Firebase	Crash reporting
🎨 Lucide Icons	Icon set
🤗 Hugging Face	Model hosting

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 for full text.

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

It helps others discover the project and keeps development going.

_{Built with ❤️ by Abir Afridi and contributors}
_{CubicLM — Your AI, your device, your rules.}

_{✨ Every feature, capability & detail from the original README is preserved — upgraded into an advanced, magazine-style layout ✨}

_{✨ No information was removed — this is a full design upgrade with extensive new sections added ✨}

_{💡 Pro tip: Press Ctrl + F to search · T for the file tree · Esc to close dialogs}

CubicLM

The Cross-Platform AI Chat Powerhouse

What is CubicLM?

💡 The Idea

🎁 What You Get

Download — v1.16.0

🧭 Which Build Should I Choose?

🧭 Navigation

🗂️ Documentation Zones

Choose Your Path

🆕

🔍

⚡

👨‍💻

Features

🧠 Local AI Inference

🦙 llama.cpp Engine

⚡ Google LiteRT-LM

🎨 Stable Diffusion 1.5

👁️ Vision Models

🎬 Streaming Generation

🔍 Device Intelligence

⚙️ Device Intelligence

🎛️ Inference Parameters (Settings › Parameters)

🪄 Auto Tune (default ON)

🎚️ Manual Mode

📊 Full Parameter Reference

🛡️ RAM Guard (new in v1.12.0)

🚀 Startup, Onboarding & Splash

🎬 Splash Screen

👋 First-Run Onboarding (new)

⚙️ Initialization Strategy

🌐 Web Access (independent chat)

🔧 How It Works

📏 Limits & Transparency

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

📦 History Storage

✂️ Token-Budget Trim

🛟 Safety Nets

🧾 Proof in Logs

💡 Tip for Code Follow-Ups

🧠 Long-Term Memory (ROM, not RAM)

☁️ Cloud AI Providers

🔀 Aggregators / Gateways

🏢 First-Party Providers

⚡ High-Speed Inference

🎨 Special & Utilities

🏷️ Auto-Detected Company Filter

🧩 Skills — Offline Instruction Extensions

📦 Starter Skills (real content, not placeholders)

🎛️ Skills UI

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

🔨 Implementation

🧠 LLM Wiring

🖥️ UI

🔌 Built-in OpenAI-Compatible API Server

🧩 Additional Features

🧭 Navigation

💬 Chat & Sessions

🎨 Visual & UX

🔔 Notifications & Background

📎 Input & Sharing

🔧 System

🌐 CubicWeb Builder (Toolkit) — v1.12.0

🎬 Build Experience

🖥️ Runtime

🚀 Deploy & Share

⚛️ Next.js Pipeline

🧑‍💻 Developer Tools

📊 Diagnostics & Cloud Tools

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

🤖 Android (primary, full)

🌐 Web (Flutter Web)

🪟 Windows Desktop

🧭 Architecture & Consistency

🔄 In-Chat Model Switcher

🩺 System Diagnostics (Settings › Config › System Logs)

💚 Health Dashboard

🔎 Filters

💾 Persistence & Export

Download — `v1.16.0`

🪄 Auto Tune _{(default ON)}

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