README
¶
MoonHub
[!NOTE] Acknowledgments
This project was inspired by the feature integration of TinyClaw and the lightweight design of PicoClaw, and continues to develop in its own unique direction.
Documentation Index (plugins, learning, compactor, SHIELD, memory, delegation, etc.): docs/README.md.
Introduction
A ready-to-use agent that's perfect for everyday users.
MoonHub is a local-first AI assistant designed for edge computing — Simple, Fast, Secure.
We believe AI shouldn't be the exclusive tool of tech experts. MoonHub is built for everyday users — no technical background required, just plug and play. Currently adapted for Linux, it runs perfectly on Raspberry Pi, industrial gateways, and various embedded devices.
Design Philosophy
| Principle | Description |
|---|---|
| Simple | Zero learning curve. Works out of the box, as easy as any home appliance. |
| Fast | Ultra-lightweight. <10MB memory, 1-second cold start, millisecond response. |
| Secure | Local-first. Your data never leaves the device — privacy entirely in your hands. |
Core Features
🤖 Agent Collaboration Engine
You're the commander, and the Agent team serves you. Each Agent has its own responsibilities — they communicate with each other, collaborate proactively, and seek your approval at critical decision points. This isn't a simple Q&A bot, but an intelligent team that truly understands context and autonomously drives tasks forward.
🎨 Dynamic UI Generation
Say goodbye to traditional Agents that "only output text." MoonHub can generate visual interactive interfaces in real-time based on your needs — financial dashboards, task managers, data visualizations — everything adapts on demand. You describe the idea, the Agent builds it for you.
📱 Dedicated Application
Users interact with the device through a dedicated app. Currently provided as a PWA for quick installation and offline use; native mobile apps are coming soon to cover more platforms and use cases.
Infinite Possibilities
MoonHub is deeply rooted in edge computing scenarios, maintaining extreme lightweight (<10MB memory) while delivering smooth experience and complete functionality. While the project has a clear core roadmap, its architecture is designed to fully support secondary development for diverse edge scenarios—whether smart agriculture, industrial IoT, intelligent retail, or home automation, you can rapidly build your own intelligent solutions on top of MoonHub.
| Scenario | Description |
|---|---|
| Smart Irrigation | Connect soil moisture and weather sensors. The Agent dynamically adjusts irrigation strategies based on real-time data for precision water-saving agriculture. |
| Industrial Monitoring | Deploy in production workshops for real-time equipment status collection, predictive maintenance alerts, and visualized operation dashboards. |
| Smart Retail | Connect foot traffic counters and inventory sensors to automatically generate restocking suggestions and sales analysis reports for business decisions. |
| Energy Management | Interface with smart meters and solar inverters to optimize power consumption strategies in real-time and generate energy reports. |
| Smart CRM | Integrate customer data and communication records. AI analyzes customer profiles and automatically generates follow-up reminders and sales opportunity insights. |
| Intelligent Ops | Connect server and application monitoring data. AI identifies anomaly patterns, triggers automatic alerts, and generates fault diagnosis reports. |
| Smart Security | Interface with cameras and door/window sensors. AI detects abnormal behaviors, pushes real-time alerts, and generates security logs. |
| Smart Aquaculture | Connect water quality sensors and feeding equipment. Real-time monitoring of aquaculture environment with automatic feeding adjustment and growth analysis reports. |
| Smart Classroom | Connect attendance devices and interactive displays. Automatically record attendance and assist teachers in generating personalized learning reports. |
| Smart E-commerce | Interface with order, inventory, and logistics systems. AI analyzes sales trends and automatically generates restocking suggestions and marketing strategies. |
Your imagination is MoonHub's only boundary.
Quick Start
- Power On — Device automatically creates a WiFi hotspot (
MoonHub-XXXX) - Configure Network — Connect to the hotspot, access the setup page, configure WiFi and set authorization code
- Install PWA — After configuration, follow the guide to install the PWA app
- Start Using — PWA automatically scans for local devices, enter the authorization code to start chatting, managing, and configuring
Features
Implemented
- Adaptive Memory — 3-layer memory system (episodic, semantic FTS5, temporal decay) that learns what to remember and forget over time.
- Self-Improving — Behavioral pattern detection system that learns from user feedback, tracks tool usage preferences, and evolves patterns over time.
- Plugin Architecture — Channels, providers, and tools are all plugins. The core stays tiny — everything else is extensible.
- Context Compactor — 4-layer context compaction pipeline (rules, dedup, LLM summary, L0/L1/L2 tiers) integrated in the agent loop; see
docs/implementation/compactor-status.mdandpkg/compactor/docs/. - SHIELD.md Anti-Malware — Runtime threat evaluation engine with YAML threat parsing, pattern matching, approval workflow, and 8 built-in threats; see
docs/implementation/shield-status.mdandpkg/shield/docs/. - Delegation System — Sub-agent orchestration (non-blocking and background tasks, template reuse, adaptive timeouts, SQLite persistence, Intercom pub/sub). Opt-in via
delegation.enabledinconfig.json(default off); seepkg/delegation/docs/README.md,pkg/delegation/docs/CONFIG.md, anddocs/implementation/delegation-status.md. - Inter-Agent Comms (Intercom) — In-process pub/sub for delegation-time signals: subscribe per topic (
On), catch-all viaOnAny, bounded per-topic retention withRecent/RecentAll; seepkg/delegation/intercom.goand the Intercom section indocs/implementation/delegation-status.md. - Smart Router V2 — 4-tier model routing system (simple/moderate/complex/reasoning) with rule-based scoring, feature extraction, and privacy-safe metrics. Routes simple queries to cheap models and complex ones to powerful models; see
pkg/routing/docs/README.mdanddocs/implementation/routing-status.md. - Device Provisioning — Zero-config WiFi setup (hotspot, scan/connect, diagnostics, automatic and manual recovery, factory reset, auth code, SSE). Opt-in on the web launcher via
MOONHUB_PROVISIONING_ENABLED=1; includes React provisioning wizard and optional PWA offline cache for that flow. Seepkg/provisioning/docs/README.md,pkg/provisioning/docs/CONFIG.md, anddocs/implementation/provisioning-status.md.
Planned
- PWA Frontend — Full user-facing PWA for device discovery, pairing, and day-to-day interaction beyond the provisioning wizard
- Dynamic UI Generation — Real-time visual component generation based on user needs (dashboards, task managers, data visualizations)
- Native APP — Native mobile applications for iOS and Android platforms
Completed (click to expand)
Self-Improving — Behavioral pattern detection that makes the agent better with every interaction. It grows with you.→ ImplementedPlugin Architecture — Channels, providers, and tools are all plugins. The core stays tiny — everything else is extensible.→ ImplementedContext Compactor — 4-layer context compaction pipeline with rule-based pre-compression, deduplication, LLM summarization, and tiered summaries.→ ImplementedSHIELD.md Anti-Malware — Runtime SHIELD.md enforcement engine with threat parsing, pattern matching, and built-in anti-malware protection.→ ImplementedDelegation System — Autonomous sub-agent orchestration with self-improving role templates, blackboard collaboration, and adaptive timeouts.→ Implemented (opt-in; seepkg/delegation/docs/anddocs/implementation/delegation-status.md)Smart Routing — 4-tier query classifier that routes simple queries to cheap models and complex ones to powerful ones, cutting LLM costs.→ Implemented (seepkg/routing/docs/anddocs/implementation/routing-status.md)Inter-Agent Comms — Lightweight pub/sub event bus for real-time inter-agent communication with wildcard subscriptions and bounded history.→ Implemented (delegation Intercom inpkg/delegation/intercom.go; enabled with delegation)Device Provisioning — Zero-config WiFi setup, recovery, factory reset, provisioning UI.→ Implemented (launcher opt-in; seepkg/provisioning/docs/README.mdanddocs/implementation/provisioning-status.md)
Changelog
2026-03-22 — Device provisioning documentation flow
Summary
Repository documentation now follows the same package docs → implementation status pattern as routing, delegation, and compactor: English pkg/provisioning/docs/, Chinese deep-dive in docs/implementation/provisioning-status.md, and cross-links from the doc index, web guide, and CLAUDE.md.
Documentation
pkg/provisioning/docs/README.md— Scope, source map, integration table (web API, launcher, frontend)pkg/provisioning/docs/CONFIG.md— Environment variables,provisioning.json, persisted keys, HTTP/SSE and browser token notesdocs/implementation/provisioning-status.md— Reading-order header linking the above; existing API and UI reference retaineddocs/README.md— Subsystem table, first-time reading step 6,docs/implementation/row,pkg/overview entryweb/README.md— Optional provisioning subsection (paths + doc flow)CLAUDE.md—provisioning/package note, launcher env vars, doc linksREADME.md/README_CN.md— Device Provisioning listed under Implemented with doc links
2026-03-21 — Smart Router V2 (4-Tier Model Routing)
Summary
4-tier model routing system with rule-based classification, replacing the original 2-tier (light/heavy) system. Automatically selects the appropriate LLM based on message complexity.
New Features
Smart Router V2 (pkg/routing/)
- 4-Tier Classification — simple, moderate, complex, reasoning tiers with configurable boundaries
- Rule-Based Scoring — Sub-microsecond classification using structural features (no API calls)
- Feature Extraction — Token estimate, code blocks, tool calls, conversation depth, attachments
- Attachment Hard Gate — Multi-modal inputs automatically route to reasoning tier
- Confidence Scoring — Sigmoid-based confidence calculation for each classification
- Signal Tracing — Every decision includes explainable signals for debugging
- Privacy-Safe Metrics — Aggregate statistics without storing message content
- Decision Recorder — Ring buffer for recent decisions with tier filtering
- HTTP Endpoints —
/metrics,/routing/decisions,/routing/stats - Backward Compatible — Falls back to 2-tier mode when
light_modelis configured
Documentation
pkg/routing/docs/README.md— Overview, architecture, quick startpkg/routing/docs/CONFIG.md— Configuration options, tier mapping, custom boundariespkg/routing/docs/FEATURES.md— Feature extraction, scoring weights, examplespkg/routing/docs/METRICS.md— Metrics collection, decision recorder, HTTP endpointsdocs/implementation/routing-status.md— Full implementation statusdocs/README.md— Repository documentation index (updated)
Technical Details
- Score range: [-1.0, 1.0] with negative scores for simple messages
- Default boundaries: simple [-1, -0.05), moderate [-0.05, 0.15), complex [0.15, 0.35), reasoning [0.35, 1.0]
- Weights: short message (-0.10), code block (+0.40), long message (+0.35), attachment (1.0 hard gate)
- 42 unit tests, all passing
Files Changed
pkg/routing/— Core implementation (tier, classifier, router, features, metrics, recorder)pkg/routing/docs/— New documentation directory (README, CONFIG, FEATURES, METRICS)pkg/config/config.go— RoutingConfig with TierMapping and TierBoundariesConfigpkg/agent/instance.go— RouterV2, TierCandidates fields and initializationpkg/agent/loop.go— Updated selectCandidates for 4-tier routingpkg/health/server.go— HTTP endpoints for metrics and decisionsdocs/README.md— Updated Smart Router section with full documentation links
2026-03-21 — Delegation System (sub-agent orchestration)
Summary
Sub-agent delegation with autonomous workflows: eight tools, SQLite store, session queue, background task injection in the agent loop, and DelegationUserID on tool execution context.
Documentation
pkg/delegation/docs/README.md,pkg/delegation/docs/CONFIG.md— Package-level docs (flow + config)docs/implementation/delegation-status.md— Deep implementation referencedocs/README.md— Repository index (delegation subsystem table)
Code (high level)
pkg/delegation/— Core implementationpkg/agent/delegation_integration.go,pkg/agent/instance.go,pkg/agent/loop.go— Runtime wiringpkg/config/config.go,pkg/config/defaults.go—DelegationConfig
2026-03-21 — SHIELD.md Anti-Malware Implementation
New Features
SHIELD.md Anti-Malware System (pkg/shield/)
A runtime threat evaluation engine:
- Threat Parser — YAML-formatted SHIELD.md parser with support for threat definitions, directives, and metadata
- Pattern Matcher — Condition syntax support for tool calls, file paths, network egress, skill operations
- Enforcement Actions — Three action types:
block,require_approval,logwith priority-based resolution - Approval Workflow —
/approveand/rejectcommands for user-confirmed actions with 5-minute timeout - Tool Integration — Shield evaluation integrated into
web_fetchandinstall_skilltools - Default Threats — 8 built-in threats covering SQL injection, command injection, path traversal, credential access, etc.
Technical Details
- Confidence threshold (0.85) with severity override for critical threats
- Action priority:
block>require_approval>log - Context-based approval bypass to prevent double-evaluation
- Comprehensive unit tests (31 tests, 100% pass rate)
Files Changed
pkg/shield/— New package (11 core files + 5 test files)pkg/agent/instance.go— Shield and ApprovalManager initializationpkg/agent/loop.go— Shield evaluation in tool execution flowpkg/commands/cmd_approve.go— Approve/reject command handlerspkg/tools/web.go— Shield integration for network egresspkg/tools/skills_install.go— Shield integration for skill installationdocs/implementation/shield-status.md— Implementation status
2026-03-20 — Context Compactor & documentation flow
Features
- Context Compactor (
pkg/compactor/) — Four-layer pipeline (rule-based pre-compression, deduplication, LLM summary, L0/L1/L2 tiers) integrated into Agent; seecompactorconfig andpkg/compactor/docs/CONFIG.md.
Documentation
- Added repository documentation entry
docs/README.md, distinguishing "package docs" fromdocs/implementation/*-status.mdconsistent withpkg/learning/docs. - Added
pkg/compactor/docs/(README + CONFIG). - Fixed link to
plugin-architecture-status.mdpointing to actual filedocs/implementation/plugin-status.md.
2025-03-20 — Plugin Architecture Implementation
New Features
Plugin Architecture System (pkg/framework/, pkg/plugins/)
A comprehensive plugin system that makes channels, providers, and tools all extensible plugins:
- Core Framework — Plugin types, interfaces (Channel/Provider/Tool), registry system, and lifecycle manager
- Channel Plugins — 16 channel plugins migrated (Telegram, Discord, Slack, Matrix, Feishu, QQ, DingTalk, LINE, OneBot, WeCom, WeCom App, WeCom AIBot, Pico, IRC, MaixCam, WhatsApp)
- Provider Plugins — 8 provider plugins migrated (OpenAI Compat, OpenAI OAuth, Anthropic, Anthropic Messages, Antigravity, Claude CLI, Codex CLI, GitHub Copilot)
- Tool Plugins — Web tools (web_search, web_fetch) and message tool migrated to plugin system
- Plugin Resolver — Provider factory now supports plugin-first resolution with built-in fallback
Technical Improvements
- Added
SetPluginProviderResolverfor provider plugin integration - Added
NewAgentLoopWithPluginToolsfor tool plugin merging - Added
MergeFrommethod to ToolRegistry for combining plugin tools - Added
InitializeToolsOnlyto plugin manager for early tool initialization - Updated channel manager to use plugin system for initialization
- Removed legacy factory pattern code from channel registry
Files Changed
pkg/framework/— New package (7 core files)pkg/plugins/channels/— 16 channel pluginspkg/plugins/providers/— 8 provider pluginspkg/plugins/tools/— 2 tool pluginspkg/plugins/docs/— Plugin documentationcmd/moonhub/internal/gateway/helpers.go— Plugin imports and initializationpkg/agent/loop.go— Plugin tool integrationpkg/channels/manager.go— Plugin-based channel initializationpkg/providers/factory_provider.go— Plugin resolver supportpkg/tools/registry.go— MergeFrom methoddocs/implementation/plugin-status.md— Implementation status
2025-03-19 — Self-Improving System Implementation
New Features
Self-Improving Behavioral Pattern Detection System (pkg/learning/)
A comprehensive learning system that makes the agent better with every interaction:
- Pattern Detector — Multi-layer signal detection using regex patterns, semantic keyword analysis, and conversation flow analysis. Supports both English and Chinese feedback detection.
- Tool Tracker — Tracks tool usage statistics including success rates, user acceptance/rejection, duration metrics (avg, P50, P95), and preference scoring.
- Behavioral Scorer — Multi-dimensional scoring system measuring response quality, tool efficiency, context relevance, correction rate, and adaptation speed.
- Pattern Evolution — Ebbinghaus-inspired decay algorithm, pattern merging, pruning of stale patterns, and contradiction detection.
- Proactive Suggestions — Generates optimization suggestions based on detected patterns and behavioral trends.
- Agent Integration — Seamless integration with the agent loop for automatic learning during conversations.
Technical Improvements
- Added FTS5 full-text search for pattern queries with proper special character escaping
- Implemented proper JSON error handling throughout the persistence layer
- Fixed SQL parameter mismatches in tool usage tracking
- Added comprehensive unit tests (43 tests, 100% pass rate)
- Updated golangci-lint configuration to v2 format
Bug Fixes
- Fixed
GetAllPatterns(),GetPatternsByCategory(),GetToolUsagePatterns()returning nil instead of empty slices - Fixed
deduplicateSignals()returning nil instead of empty slice - Fixed
RecordUserAcceptance()not incrementingUserAcceptedCallscounter - Fixed
calculatePreference()using wrong metric (success rate instead of acceptance rate) - Removed premature
breakstatements in pattern detection loops to capture all matching signals
Files Changed
pkg/learning/— New package (14 files, ~3000 lines)pkg/agent/loop.go— Learning integration in agent looppkg/agent/context.go— Learning context injectionpkg/agent/memory.go— Memory-learning bridgepkg/config/config.go— Learning configuration options.golangci.yaml— Updated to v2 format
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
moonhub
command
|
|
|
moonhub-launcher-tui
command
|
|
|
pkg
|
|
|
agent
Package agent provides the agent loop and integration for MoonHub
|
Package agent provides the agent loop and integration for MoonHub |
|
constants
Package constants provides shared constants across the codebase.
|
Package constants provides shared constants across the codebase. |
|
delegation
Package delegation implements the sub-agent delegation system with intercom.
|
Package delegation implements the sub-agent delegation system with intercom. |
|
fileutil
Package fileutil provides file manipulation utilities.
|
Package fileutil provides file manipulation utilities. |
|
identity
Package identity provides unified user identity utilities for MoonHub.
|
Package identity provides unified user identity utilities for MoonHub. |
|
provisioning
Package provisioning provides device provisioning and network management for MoonHub devices, enabling "plug-and-play" zero-configuration setup.
|
Package provisioning provides device provisioning and network management for MoonHub devices, enabling "plug-and-play" zero-configuration setup. |
|
routing
Package routing provides intelligent model routing based on message complexity.
|
Package routing provides intelligent model routing based on message complexity. |
|
shield
Package shield provides runtime threat evaluation and enforcement for MoonHub.
|
Package shield provides runtime threat evaluation and enforcement for MoonHub. |
|
utils
Package utils provides shared, reusable algorithms.
|
Package utils provides shared, reusable algorithms. |
|
web
|
|
|
backend
command
|
|
Click to show internal directories.
Click to hide internal directories.