The first native macOS desktop app for Inco AI's Splash local inference engine
El primer app de escritorio nativo de macOS para el motor de inferencia local Splash de Inco AI
🕹️ Servidor de Inferencia Local y Lanzadores de Agentes (Claude Cowork, Claude Code, OpenCode, Codex, Hermes)
Hasta ahora, Splash solo podía operarse desde la línea de comandos. Splash Monitor transforma esa experiencia en una suite visual completa para macOS: monitoreo de métricas en tiempo real, gestión de modelos de Hugging Face con un solo clic, y lanzadores de agentes de código — todo desde un ícono en la barra de menú o una ventana de escritorio nativa.
|
|
|
|
|
|
Cada módulo de Splash Monitor está optimizado para la experiencia nativa de macOS en Apple Silicon:
Módulo de Control del Servidor: Inicia y detiene el servidor Splash en un solo clic, cambia el modelo en caliente, configura el puerto y lanza agentes autónomos: Claude Cowork (activación de app nativa con aliases para evitar errores 404), Claude Code CLI, OpenCode, Codex y Hermes.
Módulo de Rendimiento en Tiempo Real: Monitorea velocidades de generación de tokens (DECODE y PREFILL en tok/s), ratio de acierto y reutilización de KV Cache, aceptación especulativa DFlash 2, latencias TTFT/ITL y uso de memoria unificada Metal (M3/M4/M5).
Módulo de Clientes Conectados: Inspección automática de conexiones TCP activas contra el puerto de inferencia, reconociendo clientes como Claude Desktop / Cowork, Cursor IDE, VS Code y Chatbots con sus íconos nativos y estado de transmisión.
Módulo de Guía de Conexión: Pasos y comandos de un clic para configurar el Gateway local en Claude Desktop, Cursor IDE, VS Code (Cline/Continue), Chatbox y scripts Python (OpenAI SDK / LangChain).
Módulo de Modelos: Control de modelos locales en disco con espacio utilizado, cambio en caliente y exploración del catálogo de Hugging Face con soporte para variantes GGUF y modo --language-only para modelos Coder.
Módulo de Test y Diagnóstico: Suite completa de verificación en un clic con Smoke Test (salud del servidor, disponibilidad Metal, plantilla Jinja, OpenAI Chat, Anthropic Messages y llamadas a herramientas/JSON), Benchmarking de velocidad con cálculo del factor de aceleración del KV Cache y Playground interactivo de inferencia local.
Módulo de Ajustes: Selector de idioma (Español Dominicano 🇩🇴 / English 🇬🇧 / macOS automático), configuración del ícono en la barra de menú superior de macOS y frecuencia de refresco.
Módulo Informativo: Información de versión (v1.0.6-beta), arquitectura nativa en Swift 6 y Metal, licencia abierta MIT y créditos de autoría de Joan Gregorio Pérez (JMGREP Developers).
Splash Monitor es un monitor gráfico para el motor de inferencia local Splash de Inco AI. Antes de instalar Splash Monitor, necesitas tener Splash funcionando en tu Mac.
Instala Splash desde el repositorio oficial de Inco AI:
# Agregar el tap oficial de Inco AI e instalar Splash
brew install incoai/tap/splash📋 Requisitos del motor Splash (según incoai/splash):
- Mac con Apple Silicon M3 o posterior
- macOS 26.4 (Tahoe) o posterior
- 36 GB de memoria unificada (48 GB o más recomendado)
Los modelos se descargan automáticamente en el primer uso. Consulta los modelos disponibles en huggingface.co/incoai.
Una vez que Splash esté instalado y funcionando, instala Splash Monitor:
La forma nativa y recomendada en macOS. Al instalar mediante Homebrew, macOS no aplica cuarentena de navegador y la app abre de inmediato:
brew install --cask hometrix/tap/splash-monitor
⚠️ Comprueba la versión que instala el cask. El cask del tap es un fichero aparte (hometrix/homebrew-tap) y puede quedarse atrás respecto a las publicaciones de este repositorio: en la auditoría de la v1.0.2-beta el cask seguía sirviendo la 1.0.0-beta. Verifica conbrew info --cask splash-monitoroSplash Monitor.app/Contents/Info.plist. Si el cask está atrasado, usa la Opción B o C, que siempre apuntan a la última publicación.
La forma más rápida si no deseas usar Homebrew tap:
curl -fsSL https://raw.githubusercontent.com/hometrix/SplashMonitor/main/scripts/install.sh | bash⚡️ Este comando consulta la última publicación en GitHub, descarga el DMG oficial, verifica su suma SHA-256 contra el fichero
SHA256SUMSpublicado y aborta si no coincide, lo monta, copia la app a/Applicationsy la abre automáticamente. Fija una versión concreta conSPLASH_MONITOR_TAG=v1.0.6-beta.
-
Descarga el instalador oficial: 👉 SplashMonitor-1.0.6-beta.dmg
Y su suma de verificación: SHA256SUMS
shasum -a 256 -c SHA256SUMS # debe imprimir "OK" -
Haz doble clic en el
.dmgdescargado y arrastra Splash Monitor a Aplicaciones.
🛡️ Si macOS muestra: "Apple no ha podido verificar que no contenga software malicioso...": Este aviso lo impone macOS a todas las apps de código abierto sin licencia de pago de Apple. Para abrirla:
- Ve a Ajustes del Sistema en tu Mac.
- Haz clic en Privacidad y seguridad (en la barra lateral) y baja hasta Seguridad.
- Pulsa el botón "Abrir de todas formas" (Open Anyway).
O por Terminal (1 segundo):
xattr -d com.apple.quarantine ~/Downloads/SplashMonitor*.dmg
Requisitos:
| Requisito | Versión Mínima |
|---|---|
| Mac | Apple Silicon (M3, M4, M5) |
| macOS | 13.0 o superior |
| Xcode | 15+ o Swift 6.0 Toolchain |
| Splash Engine | incoai/tap/splash |
# 1. Clonar el repositorio
gh repo clone hometrix/SplashMonitor
cd SplashMonitor
# 2. Ejecutar la batería de pruebas (64 pruebas, sin red ni motor real)
swift test
# 3. Compilar la app y generar el bundle .app
./scripts/build_app.sh
# 4. (Opcional) Generar el instalador DMG comprimido + SHA256SUMS
./scripts/create_dmg.sh
# 5. Iniciar la aplicación
open "Splash Monitor.app"🔢 Versión única.
Sources/SplashMonitor/Services/Version.swiftes la única fuente de la versión, el identificador de paquete y el número de compilación. Los tres scripts los extraen de ahí consed: no hay que editar la versión en varios sitios (antes se declaraba en cinco lugares y ya habían divergido entre sí).
swift test # 64 pruebas
swift test --filter PollingTests # solo una suite
swift test --filter VersionTests/testPatchTenIsNewerThanPatchTwo # una pruebaLas pruebas son herméticas por diseño: usan un transporte de estado simulado, un
terminador de procesos simulado, un directorio temporal propio y bootstrapNetwork: false
(sin tráfico a Hugging Face ni a GitHub). Ninguna prueba envía señales a procesos reales
ni escribe en tu ~/.zshrc. Cubren, entre otras cosas:
| Suite | Qué protege |
|---|---|
VersionTests |
Orden semántico de versiones y unicidad de la versión del producto |
ModelIDValidatorTests |
Rechazo de identificadores de modelo con inyección de shell y rutas .. |
ProcessIntrospectionTests |
Que nunca se señalice a un cliente conectado, solo a escuchas del motor |
ServeLockTests |
Lectura de serve-<puerto>.lock, bloqueos vacíos, corruptos y huérfanos |
ShellEnvironmentTests |
Contenido del entorno, reversión exacta del ~/.zshrc y consentimiento |
ModelSizeCacheTests |
Que el sondeo no vuelva a recorrer el árbol de modelos en cada ciclo |
PollingTests |
Que el panel siga detectando el motor tras detenerlo o arrancarlo tarde |
ClientTerminationPolicyTests |
Que no se termine un PID reciclado ni la propia app |
StatusModelTests |
Contrato real de /status del motor y tolerancia a claves nuevas |
SplashMonitor/
├── Package.swift # Manifiesto Swift Package Manager
├── LICENSE # Licencia MIT
├── CONTRIBUTING.md # Guías de contribución (bilingüe)
├── SECURITY.md # Política de divulgación responsable
├── CODE_OF_CONDUCT.md # Código de Conducta Contributor Covenant v2.1
├── README.md # Documentación técnica bilingüe
├── Resources/
│ ├── AppIcon.icns # Bundle de icono multi-resolución
│ └── AppIcon.iconset/ # Assets de icono estándar y Retina
├── scripts/
│ ├── build_app.sh # Build Release + empaquetado .app
│ └── create_dmg.sh # Empaquetado DMG vía hdiutil
└── Sources/
└── SplashMonitor/
├── SplashMonitorApp.swift # Entry point (WindowGroup + MenuBarExtra)
├── Models/
│ └── SplashStatus.swift # Structs Codable para /status y HF API
├── Services/
│ ├── SplashService.swift # Singleton (polling, procesos, servidor)
│ └── LocalizationService.swift # Detección dinámica del idioma
└── Views/
├── MainWindowView.swift # NavigationSplitView de escritorio
├── MenuBarView.swift # Popover interactivo del menú superior
├── TokenMetricsView.swift # Sparkline, tarjetas de velocidad, gauge
├── ModelManagerView.swift # Modelos locales + catálogo HF
├── ServerControlView.swift # Selector, controles, lanzadores
├── AboutView.swift # Créditos e info de versión
├── AppIconView.swift # Renderizado del icono de la app
└── DominicanEmblem.swift # Emblema patrio dominicano
| Componente | Tecnología |
|---|---|
| Lenguaje | Swift 6 |
| UI Framework | SwiftUI |
| Package Manager | Swift Package Manager |
| Plataforma | macOS 13.0+ (Apple Silicon) |
| Motor de Inferencia | Inco AI Splash |
| Catálogo de Modelos | Hugging Face API |
| Icono | Custom 3D liquid droplet (SF Symbols + Canvas) |
| Empaquetado | hdiutil (DMG nativo de macOS) |
¡Las contribuciones son bienvenidas! Consulta nuestras guías antes de participar:
| Documento | Descripción |
|---|---|
| 📋 Guía de Contribución | Flujo de trabajo, convenciones de código y estructura del proyecto |
| 🔒 Política de Seguridad | Divulgación responsable de vulnerabilidades |
| 📜 Código de Conducta | Contributor Covenant v2.1 |
|
Joan Gregorio Pérez Software Engineer · JMGREP Developers 🇩🇴 República Dominicana GitHub |
Agradecimientos especiales:
- Inco AI — Motor de inferencia Splash
- Hugging Face — Catálogo de modelos
Si Splash Monitor te resulta útil para tus flujos de trabajo de IA local y desarrollo con agentes, ¡considera apoyar su desarrollo continuo invitándome a un café! Cada aporte ayuda a mantener el proyecto actualizado, probado y optimizado para Apple Silicon.
Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para los términos completos.
MIT License — Copyright (c) 2026 JMGREP Developers / Joan Gregorio Pérez
Splash Monitor es una aplicación independiente que interactúa con componentes de terceros. A continuación se detallan las licencias de cada dependencia:
| Componente | Licencia | Repositorio |
|---|---|---|
| Splash Monitor | MIT | hometrix/SplashMonitor |
| Splash Engine | Apache-2.0 | incoai/splash |
| Modelo Qwen3.8-27B-Splash | Apache-2.0 | incoai/Qwen3.8-27B-Splash |
| Modelo Qwen3.6-35B-A3B-Splash | Apache-2.0 | incoai/Qwen3.6-35B-A3B-Splash |
| Qwen3.8-27B (base) | Apache-2.0 | Qwen/Qwen3.8-27B |
| Qwen3.6-35B-A3B (base) | Apache-2.0 | Qwen/Qwen3.6-35B-A3B |
⚠️ Aviso: Los pesos de los modelos mantienen sus propias licencias. Consulta cada repositorio en Hugging Face para los términos específicos.
ℹ️ Disclaimer: Splash Monitor es un proyecto independiente y no está afiliado, patrocinado ni respaldado por Inco AI. "Splash" es una marca de Inco AI. Este proyecto utiliza la API pública de Splash bajo los términos de la licencia Apache-2.0.
Until now, Splash could only be operated from the command line. Splash Monitor transforms that experience into a complete visual suite for macOS: real-time metrics monitoring, one-click Hugging Face model management, and code agent launchers — all from a menu bar icon or a native desktop window.
|
|
|
|
|
|
Every module of Splash Monitor is designed and optimized for a native Apple Silicon macOS experience:
Server Control Module: Start and stop the Splash server with one click, hot-swap models without restarting, configure custom listening ports, and launch autonomous coding agents: Claude Cowork (native AppKit launch with model aliases to prevent 404 errors), Claude Code CLI, OpenCode, Codex, and Hermes.
Real-Time Performance Module: Live token generation speed telemetry (DECODE and PREFILL in tok/s), KV Cache hit ratio and token reuse, DFlash 2 speculative decoding acceptance rates, TTFT/ITL latencies, and Apple Silicon Metal unified memory usage (M3/M4/M5).
Connected Clients Module: Automatic inspection of active TCP sockets against the inference port, recognizing clients such as Claude Desktop / Cowork, Cursor IDE, VS Code, and Chatbots with their native macOS application icons and stream state.
Connection Guide Module: Quick setup instructions and one-click copyable configuration snippets for Claude Desktop, Cursor IDE, VS Code (Cline/Continue), Chatbox, and Python scripts (OpenAI SDK / LangChain).
Model Management Module: Disk footprint inspection for local models, hot-swap deployment, and Hugging Face catalog exploration with support for GGUF variants and --language-only mode for Coder models.
Model Testing Module: Complete one-click verification suite with Smoke Testing (server health, Metal engine readiness, Jinja templates, OpenAI Chat, Anthropic Messages, and Tool Calling/JSON validation), Metal speed benchmarking with KV Cache speedup factor calculation, and an interactive local inference Playground.
Settings Module: Language selector (Dominican Spanish 🇩🇴 / English 🇬🇧 / macOS auto-sync), customizable macOS menu bar item display modes, and background polling interval controls.
About Module: Version information (v1.0.6-beta), native Swift 6 and Metal architecture details, MIT open-source license, and author credits for Joan Gregorio Pérez (JMGREP Developers).
Splash Monitor is a graphical monitor for Inco AI's Splash local inference engine. Before installing Splash Monitor, you need Splash running on your Mac.
Install Splash from the official Inco AI repository:
# Add the official Inco AI tap and install Splash
brew install incoai/tap/splash📋 Splash engine requirements (from incoai/splash):
- Mac with Apple Silicon M3 or newer
- macOS 26.4 (Tahoe) or later
- 36 GB of unified memory (48 GB or more recommended)
Models are downloaded automatically on first use. See available models at huggingface.co/incoai.
Once Splash is installed and running, install Splash Monitor:
The native macOS package manager method. When installed through Homebrew, macOS does not flag it with browser quarantine:
brew install --cask hometrix/tap/splash-monitor
⚠️ Check which version the cask installs. The tap cask is a separate file inhometrix/homebrew-tapand can lag behind this repository's releases: in the v1.0.2-beta audit the cask still served 1.0.0-beta. Verify withbrew info --cask splash-monitororSplash Monitor.app/Contents/Info.plist. If the cask is behind, use Option B or C, which always point at the latest release.
The quickest method without tapping:
curl -fsSL https://raw.githubusercontent.com/hometrix/SplashMonitor/main/scripts/install.sh | bash⚡️ This script resolves the latest release, downloads the official DMG, verifies its SHA-256 checksum against the published
SHA256SUMSfile (aborting on mismatch), mounts it, installs to/Applications, and opens the app automatically. Pin a specific version withSPLASH_MONITOR_TAG=v1.0.6-beta.
-
Download the official installer: 👉 SplashMonitor-1.0.6-beta.dmg
And its checksum file: SHA256SUMS
shasum -a 256 -c SHA256SUMS # must print "OK" -
Double-click the downloaded
.dmgand drag Splash Monitor to Applications.
🛡️ If macOS shows: "Apple cannot verify that this app is free of malware...": This is a standard Gatekeeper notice for independent open-source apps. To allow it:
- Open System Settings on your Mac.
- Go to Privacy & Security and scroll down to the Security section.
- Click "Open Anyway".
Or via Terminal (1 second):
xattr -d com.apple.quarantine ~/Downloads/SplashMonitor*.dmg
Requirements:
| Requirement | Minimum Version |
|---|---|
| Mac | Apple Silicon (M3, M4, M5) |
| macOS | 13.0 or later |
| Xcode | 15+ or Swift 6.0 Toolchain |
| Splash Engine | incoai/tap/splash |
# 1. Clone the repository
gh repo clone hometrix/SplashMonitor
cd SplashMonitor
# 2. Run the test suite (64 tests, no network, no real engine)
swift test
# 3. Build the release binary and bundle .app
./scripts/build_app.sh
# 4. (Optional) Create the compressed DMG installer + SHA256SUMS
./scripts/create_dmg.sh
# 5. Launch the application
open "Splash Monitor.app"🔢 Single source of truth for the version.
Sources/SplashMonitor/Services/Version.swiftholds the version, bundle identifier and build number, and all three scripts extract them withsed. Before, the version was declared in five places and had already diverged.
swift test # 64 tests
swift test --filter PollingTests # one suite
swift test --filter VersionTests/testPatchTenIsNewerThanPatchTwo # one testTests are hermetic by design: a stub status transport, a recording process terminator,
a private temp directory and bootstrapNetwork: false (no Hugging Face or GitHub
traffic). No test signals a real process or writes to your ~/.zshrc.
SplashMonitor/
├── Package.swift # Swift Package Manager manifest
├── LICENSE # MIT License
├── CONTRIBUTING.md # Contribution guidelines (bilingual)
├── SECURITY.md # Vulnerability disclosure policy
├── CODE_OF_CONDUCT.md # Contributor Covenant v2.1
├── README.md # Bilingual technical documentation
├── Resources/
│ ├── AppIcon.icns # Multi-resolution macOS icon bundle
│ └── AppIcon.iconset/ # Standard & Retina icon assets
├── scripts/
│ ├── build_app.sh # Release build + .app bundling
│ └── create_dmg.sh # DMG packaging via hdiutil
└── Sources/
└── SplashMonitor/
├── SplashMonitorApp.swift # Entry point (WindowGroup + MenuBarExtra)
├── Models/
│ └── SplashStatus.swift # Codable structs for /status & HF API
├── Services/
│ ├── SplashService.swift # Singleton (polling, processes, server)
│ └── LocalizationService.swift # Dynamic OS language detection
└── Views/
├── MainWindowView.swift # NavigationSplitView desktop window
├── MenuBarView.swift # Interactive menu bar popover
├── TokenMetricsView.swift # Sparkline, speed cards, memory gauge
├── ModelManagerView.swift # Local models + HF catalog explorer
├── ServerControlView.swift # Selector, controls, agent launchers
├── AboutView.swift # Author credits and version info
├── AppIconView.swift # App icon rendering component
└── DominicanEmblem.swift # Dominican Republic national emblem
| Component | Technology |
|---|---|
| Language | Swift 6 |
| UI Framework | SwiftUI |
| Package Manager | Swift Package Manager |
| Platform | macOS 13.0+ (Apple Silicon) |
| Inference Engine | Inco AI Splash |
| Model Catalog | Hugging Face API |
| Icon | Custom 3D liquid droplet (SF Symbols + Canvas) |
| Packaging | hdiutil (native macOS DMG) |
Contributions are welcome! Please read our guidelines before participating:
| Document | Description |
|---|---|
| 📋 Contributing Guide | Workflow, code conventions, and project structure |
| 🔒 Security Policy | Responsible vulnerability disclosure |
| 📜 Code of Conduct | Contributor Covenant v2.1 |
Si el puerto predeterminado 8000 está ocupado por otro servicio de tu Mac (como Uvicorn, Django, Docker o Node.js):
- Opción A (Automática): En el panel de control del servidor, pulsa el botón ✨ "Sugerir libre" para que Splash Monitor asigne automáticamente el siguiente puerto disponible (ej. 8001 o 8005).
- Opción B (Personalizada): Escribe manualmente el puerto que desees en el campo de texto. Splash Monitor utilizará su Bridge Launcher para ejecutar Splash en el puerto elegido sin errores.
- Opción C (Liberar puerto): Si intentas arrancar en un puerto ocupado, la app te mostrará qué proceso lo tiene tomado y te ofrecerá un botón para liberarlo con un solo clic.
Si al ejecutar splash claude en tu terminal ves el mensaje:
error: No ready Splash server. Run 'splash serve --model <HF_REPO_ID>' in another terminal first.
Asegúrate de que:
- El servidor Splash esté iniciado y con su modelo cargado (verás el estado en verde en Splash Monitor).
- Si ejecutaste el servidor en un puerto personalizado (distinto de 8000), lanza el agente directamente desde los botones de Splash Monitor para que la app configure automáticamente las variables de entorno de conexión (
ANTHROPIC_BASE_URL,SPLASH_PORT).
|
|
Joan Gregorio Pérez Software Engineer · JMGREP Developers 🇩🇴 Dominican Republic GitHub |
Special Thanks:
- Inco AI — Splash inference engine
- Hugging Face — Model catalog
If you find Splash Monitor valuable for your local AI workflows and autonomous coding agents, consider supporting its ongoing development by buying me a coffee! Every contribution helps keep the project updated, tested, and fine-tuned for Apple Silicon.
This project is licensed under the MIT License. See the LICENSE file for full terms.
MIT License — Copyright (c) 2026 JMGREP Developers / Joan Gregorio Pérez
Splash Monitor is an independent application that interfaces with third-party components. Below are the licenses for each dependency:
| Component | License | Repository |
|---|---|---|
| Splash Monitor | MIT | hometrix/SplashMonitor |
| Splash Engine | Apache-2.0 | incoai/splash |
| Qwen3.8-27B-Splash Model | Apache-2.0 | incoai/Qwen3.8-27B-Splash |
| Qwen3.6-35B-A3B-Splash Model | Apache-2.0 | incoai/Qwen3.6-35B-A3B-Splash |
| Qwen3.8-27B (base model) | Apache-2.0 | Qwen/Qwen3.8-27B |
| Qwen3.6-35B-A3B (base model) | Apache-2.0 | Qwen/Qwen3.6-35B-A3B |
⚠️ Note: Model weights retain their own licenses. Check each Hugging Face repository for specific terms.
ℹ️ Disclaimer: Splash Monitor is an independent project and is not affiliated with, sponsored by, or endorsed by Inco AI. "Splash" is a trademark of Inco AI. This project interfaces with the public Splash API under the terms of the Apache-2.0 license.
Made with ❤️ in the Dominican Republic 🇩🇴
