Ghost — Self-Healing Background Agent

Ghost is the invisible guardian of videoDJ.Studio. It runs silently in the background of the web and desktop DJ applications, monitoring for errors, performance issues, and state inconsistencies. When something goes wrong, Ghost fixes it automatically — and learns from every encounter.

What Ghost Does

• Monitors runtime errors, audio/video health, state consistency, performance, network issues, and IndexedDB integrity
• Fixes automatically using rules-based instant fixes (no LLM needed) for known problems like suspended AudioContext, stalled video, dropped WebSocket connections
• Diagnoses unknown errors by sending them to Ollama/Qwen 2.5 for analysis, receiving a diagnosis and suggested fix command
• Learns over time by storing every error pattern and fix result in a PostgreSQL knowledge base. When a fix achieves 90%+ success rate over 5+ occurrences, it gets promoted to a client-side rule for instant resolution
• Alerts you via Telegram bot (critical) and Resend email (critical + daily digest + weekly report) when it can't fix something after 3 attempts

Architecture

Ghost is a hybrid system with two components:

Ghost Client (lives inside the DJ app)

• Lightweight TypeScript module (web/app/lib/ghost.ts in the djstudio repo)
• Hooks into error boundaries, audio/video elements, Zustand store, network layer
• Applies instant rules-based fixes locally (no network needed)
• Ships telemetry to Ghost Server for unknown errors
• Receives fix commands from Ghost Server via WebSocket
• Accepts promoted rules (learned fixes pushed down from server)

Ghost Server (this repo — ghost.videodj.studio)

• Node.js + Fastify API deployed via Dokploy on KVM4
• Ingests telemetry from Ghost Client
• Searches knowledge base for matching patterns
• Calls Ollama/Qwen for LLM-powered diagnosis when pattern is new or unreliable
• Sends fix commands back to client via WebSocket
• Promotes high-success fixes to client-side rules
• Sends notifications via Resend (email) and Telegram Bot

Learning Loop

Error arrives → Search knowledge base
  ├── Known fix (>90% success) → Apply immediately
  ├── Low-confidence fix → Re-analyze with LLM → Try new fix → Update KB
  └── New error → LLM diagnosis → Send fix → Log result → Create KB entry

After 5+ occurrences at 90%+ success → Promote to client-side rule

Infrastructure

Service	Domain	Location
DJ App	app.videodj.studio	KVM4 via Dokploy
Ghost Server	ghost.videodj.studio	KVM4 via Dokploy
Admin Dashboard	admin.videodj.studio	KVM4 via Dokploy
Ollama + Qwen 2.5	localhost:11434	KVM4 (internal only)
PostgreSQL	internal	KVM4 (Docker volume)

Setup

# Clone
git clone https://github.com/flndrn-dev/ghost.git
cd ghost

# Install
npm install

# Configure
cp .env.example .env
# Edit .env with your database URL, Ollama URL, Resend key, Telegram bot token

# Development
npm run dev

# Production (Docker)
docker compose up -d

API Endpoints

Method	Path	Auth	Description
GET	/health	None	Heartbeat — status, uptime, connections, KB size
POST	/telemetry	API key	Ingest error/performance telemetry packet
POST	/telemetry/result	API key	Report whether a fix command worked
GET	/knowledge	API key	Browse knowledge base entries
GET	/knowledge/telemetry	API key	Telemetry log (filterable by severity)
GET	/knowledge/notifications	API key	Notification history
WS	/ws?sessionId=x&apiKey=x	API key	Real-time fix commands + promoted rules

Auth: Send x-ghost-api-key header with your GHOST_API_KEY value.

Knowledge Base Schema

Field	Description
error_pattern	Normalized error signature (line numbers stripped)
context_hash	Component + user action hash
fix_action	Human-readable fix description
fix_command_type	One of: state_patch, restart_subsystem, clear_cache, reload_component, retry_operation, notify_user
fix_command_payload	JSON payload sent to Ghost Client
success_rate	% of times this fix worked
times_seen	Total occurrences
llm_analysis	Qwen's diagnosis (cached)
auto_promoted	Whether this fix has been pushed to client-side rules

Notifications

Trigger	Telegram	Email
Critical failure (3 failed attempts)	Yes	Yes
Daily digest (24h summary)	No	Yes
Weekly report (trends)	No	Yes

Environment Variables

See .env.example for all configuration options.

Related

• DJ App: github.com/flndrn-dev/djstudio — the main videoDJ.Studio application
• Design Spec: GHOST.md in the djstudio repo — full architecture and design decisions
• Admin Dashboard: Separate repo (admin.videodj.studio) — monitoring UI for Ghost, Linus, and system health

Tech Stack

• Node.js 20 + Fastify
• PostgreSQL 16
• Ollama + Qwen 2.5 Coder 7B
• Resend (email) + Telegram Bot API
• Docker + Dokploy
• TypeScript