Wolverine Node.js

Self-healing Node.js servers powered by an AI coding harness.

Wolverine watches your server process, catches crashes, diagnoses errors with AI, generates fixes, verifies them, and restarts — automatically. It also has a dashboard with a command interface where you can tell the agent to build features, and it will modify your server code directly.

Built on patterns from claw-code — the open-source Claude Code harness.

Quick Start

Install from npm

npm i wolverine-ai
cp node_modules/wolverine-ai/.env.example .env.local
# Edit .env.local — add your OPENAI_API_KEY
npx wolverine server/index.js

Or clone from GitHub

git clone https://github.com/bobbyswhip/Wolverine.git
cd Wolverine
npm install
cp .env.example .env.local
# Edit .env.local — add your OPENAI_API_KEY
npm start

Dashboard opens at http://localhost:PORT+1. Server runs on PORT.

Try a Demo

Demos copy a buggy server into server/, let wolverine fix it, then restore your original:

npm run demo:list            # See all demos
npm run demo:01              # Basic typo (ReferenceError)
npm run demo:02              # Multi-file import mismatch
npm run demo:03              # Syntax error (extra paren)
npm run demo:04              # Secret leak in error output
npm run demo:05              # External service down (human notification)
npm run demo:06              # JSON config typo
npm run demo:07              # null.toString() crash

Each demo:

1. Backs up your current server/ directory
2. Copies the buggy demo into server/
3. Runs wolverine — watch it detect, diagnose, fix, verify, and restart
4. Restores your original server/ when you press Ctrl+C

Architecture

wolverine/
├── server/                  ← YOUR server code (agent can edit)
│   ├── index.js             ← Entry point
│   ├── routes/              ← Route modules
│   └── config/settings.json ← All settings (models, cluster, telemetry, limits)
├── src/
│   ├── core/                ← Wolverine engine
│   │   ├── wolverine.js     ← Heal pipeline + goal loop
│   │   ├── runner.js        ← Process manager (PM2-like)
│   │   ├── ai-client.js     ← OpenAI client (Chat + Responses API)
│   │   ├── models.js        ← 10-model configuration system
│   │   ├── verifier.js      ← Fix verification (syntax + boot probe)
│   │   ├── error-parser.js  ← Stack trace parsing + error classification
│   │   ├── error-hook.js   ← Auto-injected into child (IPC error reporting)
│   │   ├── patcher.js       ← File patching with sandbox
│   │   ├── health-monitor.js← PM2-style health checks
│   │   ├── config.js        ← Config loader (settings.json + env)
│   │   ├── system-info.js   ← Machine detection (cores, RAM, cloud, containers)
│   │   └── cluster-manager.js← Auto-scaling worker management
│   ├── agent/               ← AI agent system
│   │   ├── agent-engine.js  ← Multi-turn agent with 10 tools
│   │   ├── goal-loop.js     ← Goal-driven repair loop
│   │   ├── research-agent.js← Deep research + learning from failures
│   │   └── sub-agents.js    ← 7 specialized sub-agents (explore/plan/fix/verify/...)
│   ├── security/            ← Security stack
│   │   ├── sandbox.js       ← Directory-locked file access
│   │   ├── secret-redactor.js← Env value → key name replacement
│   │   ├── injection-detector.js ← AI-powered prompt injection scan
│   │   ├── rate-limiter.js  ← Error explosion protection
│   │   └── admin-auth.js    ← Dashboard admin authentication
│   ├── brain/               ← Semantic memory
│   │   ├── brain.js         ← Vector store + function map + learning
│   │   ├── vector-store.js  ← In-memory cosine similarity search
│   │   ├── embedder.js      ← Embedding + text compaction pipeline
│   │   └── function-map.js  ← Live project scanner
│   ├── backup/              ← Smart backup system
│   │   └── backup-manager.js← Full server/ snapshots with retention
│   ├── logger/              ← Observability
│   │   ├── event-logger.js  ← Structured event bus + JSONL persistence
│   │   ├── token-tracker.js ← Token usage + USD cost tracking
│   │   ├── repair-history.js← Error/resolution audit trail
│   │   └── pricing.js       ← Model cost calculations
│   ├── monitor/             ← Performance + process management
│   │   ├── perf-monitor.js  ← Endpoint response times + spam detection
│   │   ├── process-monitor.js← Memory/CPU/heartbeat + leak detection
│   │   ├── route-prober.js  ← Auto-discovers and tests all routes
│   │   └── error-monitor.js ← Caught 500 error detection (no-crash healing)
│   ├── dashboard/           ← Web UI
│   │   └── server.js        ← Real-time dashboard + command interface
│   ├── notifications/       ← Alerts
│   │   └── notifier.js      ← Human-required error detection
│   ├── mcp/                 ← External tools
│   │   ├── mcp-client.js    ← MCP protocol client (stdio + HTTP)
│   │   ├── mcp-registry.js  ← Server discovery + tool registration
│   │   └── mcp-security.js  ← Allowlists + injection scan on MCP results
│   ├── skills/              ← Reusable capabilities
│   │   ├── skill-registry.js← Auto-discovery + prompt injection
│   │   └── sql.js           ← Cluster-safe SQL + injection prevention
│   └── platform/            ← Fleet telemetry
│       ├── telemetry.js     ← Collects heartbeat data from all subsystems
│       ├── heartbeat.js     ← Sends heartbeats to platform backend
│       ├── register.js      ← Auto-registration on first run
│       └── queue.js         ← Offline queue with replay
├── bin/wolverine.js         ← CLI entry point (cluster-aware)
├── tests/                   ← Test suite
└── .wolverine/              ← Runtime state (gitignored)
    ├── brain/               ← Vector store persistence
    ├── events/              ← Event log (JSONL)
    ├── backups/             ← Server snapshots
    ├── usage.json           ← Token usage aggregates
    ├── usage-history.jsonl  ← Full token usage timeline
    ├── repair-history.json  ← Error/resolution audit trail
    └── mcp.json             ← MCP server configuration

How Self-Healing Works

Server crashes
  → Error parsed (file, line, message, errorType)
  → Error classified: missing_module | missing_file | permission | port_conflict | syntax | runtime
  → Secrets redacted from error output
  → Prompt injection scan (AUDIT_MODEL)
  → Human-required check (expired keys, service down → notify, don't waste tokens)
  → Rate limit check (error loop → exponential backoff)

Operational Fix (zero AI tokens):
  → "Cannot find module 'cors'" → npm install cors (instant, free)
  → ENOENT on config file → create missing file with defaults
  → EACCES/EPERM → chmod 755
  → If operational fix works → done. No AI needed.

Goal Loop (iterate until fixed or exhausted):
  Iteration 1: Fast path (CODING_MODEL, single file, ~1-2k tokens)
    → AI returns code changes AND/OR shell commands (npm install, mkdir, etc.)
    → Execute commands first, apply patches second
    → Verify (syntax check + boot probe) → Pass? Done.
  Iteration 2: Single agent (REASONING_MODEL, multi-file, 10 tools)
    → Agent has error pattern → fix strategy table
    → Uses bash_exec for npm install, chmod, config creation
    → Uses edit_file for code fixes
    → Verify → Pass? Done.
  Iteration 3: Sub-agents (explore → plan → fix)
    → Explorer finds relevant files (read-only)
    → Planner considers operational vs code fixes
    → Fixer has bash_exec + file tools (can npm install AND edit code)
    → Deep research (RESEARCH_MODEL) feeds into context
    → Each failure feeds into the next attempt

After fix:
  → Record to repair history (error, resolution, tokens, cost, mode)
  → Store in brain for future reference
  → Promote backup to stable after 30min uptime

Caught Error Healing (No-Crash)

Most production bugs don't crash the process — Fastify/Express catch them and return 500. Wolverine now detects these too:

Route returns 500 (process still alive)
  → Error hook reports to parent via IPC (auto-injected, zero user code changes)
  → ErrorMonitor tracks consecutive 500s per route
  → 3 failures in 30s → triggers heal pipeline (same as crash healing)
  → Fix applied → server restarted → route prober verifies fix

The error hook auto-patches Fastify and Express via --require preload. No middleware, no code changes to your server.

Agent Tool Harness

The AI agent has 10 built-in tools (ported from claw-code):

Blocked commands (from claw-code's destructiveCommandWarning): rm -rf /, git push --force, git reset --hard, npm publish, curl | bash, eval()

Protected paths — the agent can NEVER modify: src/, bin/, tests/, node_modules/, .env, package.json

Only files in server/ are editable.

Sub-Agents

For complex repairs, wolverine spawns specialized sub-agents that run in sequence or parallel:

Each sub-agent gets restricted tools — the explorer can't write files, the fixer can't search the web. This prevents agents from overstepping their role.

Workflows:

• exploreAndFix() — explore → plan → fix (sequential, 3 agents)
• spawnParallel() — run multiple agents concurrently (e.g., security + explore)

Dashboard

Real-time web UI at http://localhost:PORT+1:

Command Interface

Three routes (AI-classified per command):

Secured with WOLVERINE_ADMIN_KEY + IP allowlist (localhost + WOLVERINE_ADMIN_IPS).

10-Model Configuration

Every AI task has its own model slot. Customize in .env.local:

Reasoning models (o-series, gpt-5-nano) automatically get 4x token limits to accommodate chain-of-thought.

Security

Brain (Semantic Memory)

Vector database that gives wolverine long-term memory:

• Function Map — scans server/ on startup, indexes all routes, functions, classes, exports
• Error History — past errors with context for loop prevention
• Fix History — successful and failed repairs for learning
• Learnings — research findings, admin commands, patterns discovered
• Skill Knowledge — embedded docs for SQL skill, best practices, wolverine itself

Two-tier search for speed:

1. Keyword match (instant, 0ms) — catches most lookups
2. Semantic embedding search (API call) — only when keywords miss

Process Manager

Wolverine acts as a PM2-like process manager with AI-powered diagnostics:

The 📊 Analytics dashboard panel shows memory/CPU charts, route health status, and response time breakdowns — all updating in real-time.

Auto-Clustering

Wolverine detects your machine and forks the optimal number of workers:

wolverine server/index.js           # auto-detect: 20 cores → 10 workers
wolverine server/index.js --single  # force single worker (dev mode)
wolverine server/index.js --workers 4  # force 4 workers
wolverine --info                    # show system capabilities

System detection:

• CPU cores, model, speed
• Total/free RAM, disk space
• Platform (Linux, macOS, Windows)
• Container environment (Docker, Kubernetes)
• Cloud provider (AWS, GCP, Azure, Railway, Fly, Render, Heroku)

Scaling rules:

Workers auto-respawn on crash with exponential backoff (1s → 30s). Max 5 restarts per worker.

Configuration

.env.local                     ← Secrets only (API keys, admin key)
server/config/settings.json    ← Everything else (models, port, clustering, telemetry, limits)

settings.json is inside server/ so the agent can read and edit it. Config loader priority: env vars > settings.json > defaults.

Platform Telemetry

Every wolverine instance automatically broadcasts health data to the analytics platform. Zero config — telemetry is on by default.

Startup:
  📡 Registering with https://api.wolverinenode.xyz...
  📡 Registered: wlv_a8f3e9b1c4d7
  📡 https://api.wolverinenode.xyz (60s)

How it works:

• Auto-registers on first run, retries every 60s until platform responds
• Saves key to .wolverine/platform-key (survives restarts)
• Sends one ~2KB JSON POST every 60 seconds (5s timeout, non-blocking)
• Payload matches PLATFORM.md spec: instanceId, server, process, routes, repairs, usage (tokens/cost/calls + byCategory + byModel + byTool), brain, backups
• Platform analytics aggregates across all servers: total tokens/cost, breakdown by category (heal/chat/develop/security/classify/research/brain), by model, by tool
• Secrets redacted before sending
• Offline-resilient: queues up to 1440 heartbeats locally, drains on reconnect

Lightweight: 4 files, ~250 lines. No external dependencies. Key/version cached in memory. Response bodies drained immediately. No blocking, no delays.

Override: WOLVERINE_PLATFORM_URL=https://your-own-platform.com Opt out: WOLVERINE_TELEMETRY=false

See PLATFORM.md for the backend spec and TELEMETRY.md for the protocol.

Demos

All demos use the server/ directory pattern. Each demo:

1. Backs up your current server/
2. Copies a buggy Express server into server/
3. Runs wolverine — you watch it fix the bug in real-time
4. Restores your original server/ on Ctrl+C

Backup System

Full server/ directory snapshots with lifecycle management:

• Created before every repair attempt and every smart edit (with reason string)
• Created on graceful shutdown (createShutdownBackup())
• Includes all files: .js, .json, .sql, .db, .yaml, configs
• Status lifecycle: UNSTABLE → VERIFIED (fix passed) → STABLE (30min+ uptime)
• Retention: unstable/verified pruned after 7 days, stable keeps 1/day after 7 days
• Atomic writes prevent corruption on kill

Rollback & Recovery:

Dashboard endpoints (admin auth required):

• POST /api/backups/:id/rollback — rollback to specific backup
• POST /api/backups/:id/hotload — hot-load backup as current state
• POST /api/backups/undo — undo the last rollback

Skills

Auto-discovered from src/skills/. Each skill exports metadata for the registry:

SQL Skill (src/skills/sql.js)

• sqlGuard() — Express middleware blocking SQL injection (UNION, stacked queries, tautologies, timing attacks, etc.)
• SafeDB — Parameterized-only database wrapper (blocks string concatenation in queries)
• Auto-injected into agent prompts when building database features

Add new skills by creating a file in src/skills/ with SKILL_NAME, SKILL_DESCRIPTION, SKILL_KEYWORDS, SKILL_USAGE exports.

MCP Integration

Connect external tools via Model Context Protocol:

// .wolverine/mcp.json
{
  "servers": {
    "datadog": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@datadog/mcp-server"],
      "allowedTools": ["get_metrics", "list_monitors"],
      "enabled": true
    }
  }
}

Tools appear as mcp__datadog__get_metrics in the agent. All MCP data passes through the security stack (redaction, injection scan, rate limiting).

Usage Tracking

Every API call tracked with input/output tokens + USD cost:

• By Category: heal, develop, chat, security, classify, research, brain
• By Model: which model costs the most
• By Tool: call_endpoint, search_brain, etc.
• Timeline chart: color-coded SVG bar chart
• Persisted: .wolverine/usage-history.jsonl survives restarts
• Custom pricing: override in .wolverine/pricing.json

Notifications

Errors the AI can't fix trigger human alerts:

AI summary generated with CHAT_MODEL, secrets redacted, optional webhook delivery.

License

MIT