Part of Brainplex — The intelligence layer for AI agents. npx brainplex init to install the full suite.

Cognitive immune system for OpenClaw — L2 semantic health checks with LLM analysis, tool exposure for agent queries, and Sitrep replacement.

Part of the Vainplex OpenClaw Plugin Suite.

Leuko operates as a two-tier hybrid system:

• Level 1 (L1 Daemon): Heuristic checks — file freshness, gateway alive, plugin loading, disk usage, service health. Runs every 15min, zero API cost. Included in this package.
• Level 2 (L2 Plugin): Cognitive checks — semantic analysis via LLM + deterministic correlation. Runs every 2h or on-demand.

  L1 Daemon (Node.js)        Plugin (L2)                    Agents
        │                         │                           │
  ┌─ 7 heuristic checks          │                           │
  ├─ Write daemon_checks[]        │                           │
  │  to leuko-status.json         │                           │
  │                    ┌──────────┘                           │
  │                    ├─ Read daemon_checks[]                │
  │                    ├─ Run CK-01..CK-06 (4 LLM + 2 det.) │
  │                    ├─ Write cognitive_checks[]            │
  │                    │                                      │
  │                    ├── leuko_status tool ─────────────────┤
  │                    ├── before_agent_start hook ───────────┤
  │                    └── /leuko command ───────────────────→│
  │                                                           │
  └── npx leuko-daemon [--watch] (standalone)                 │

The L1 daemon is a portable Node.js process that produces leuko-status.json — no Python, no NATS, no external dependencies required.

# Run once
npx @vainplex/openclaw-leuko daemon

# Watch mode (re-check every 15min)
npx @vainplex/openclaw-leuko daemon --watch

# Custom config
npx @vainplex/openclaw-leuko daemon --config /path/to/daemon-config.json

Or via the leuko-daemon binary after global install:

npm install -g @vainplex/openclaw-leuko
leuko-daemon --watch

Auto-discovers workspace by looking for .openclaw/ or AGENTS.md.

Optional JSON config file:

{
  "statusPath": "~/.openclaw/leuko-status.json",
  "workspace": "~/clawd",
  "watchIntervalMin": 15,
  "checks": {
    "file_freshness": {
      "targets": [
        { "name": "boot-context", "path": "~/clawd/BOOTSTRAP.md", "warnHours": 4, "critHours": 8 }
      ]
    },
    "service_health": {
      "endpoints": [
        { "name": "nats", "type": "tcp", "host": "localhost", "port": 4222, "timeoutMs": 3000 },
        { "name": "ollama", "type": "http", "url": "http://localhost:11434/api/tags", "timeoutMs": 3000 }
      ]
    },
    "disk_usage": { "warnPercent": 85, "critPercent": 95 }
  }
}

If no config is provided, freshness targets are auto-discovered from the workspace.

npm install @vainplex/openclaw-leuko

Add to openclaw.json:

{
  "plugins": {
    "entries": {
      "openclaw-leuko": { "enabled": true }
    }
  }
}

The plugin will auto-create a default config at ~/.openclaw/plugins/openclaw-leuko/config.json on first run.

• ok — All checks pass, no issues detected
• warn — Issues found that should be reviewed
• critical — Significant problems requiring attention

Agents can query system health:

leuko_status({ section: "summary" })
leuko_status({ section: "cognitive", severity_filter: "warn" })
leuko_status({ section: "recommendations" })

Sections: summary | daemon | cognitive | recommendations | all

/leuko              — Health summary
/leuko refresh      — Trigger immediate L2 check cycle
/leuko detail       — All checks with findings
/leuko config       — Active configuration

When system health is degraded, injects a one-liner into the agent's context:

⚕️ Leuko Health: WARN — 2 issues: goal_quality (3/9 vague goals), facts (stale 48h)

Configurable: only injected when issues exist, respects maxLength.

Full config lives at ~/.openclaw/plugins/openclaw-leuko/config.json:

{
  "enabled": true,
  "statusPath": "~/clawd/memory/leuko-status.json",
  "intervalMinutes": 120,
  "llm": {
    "primary": {
      "provider": "ollama",
      "model": "qwen3:14b",
      "baseUrl": "http://localhost:11434",
      "timeoutSec": 30
    },
    "fallback": {
      "provider": "litellm",
      "model": "gemini/gemini-2.0-flash-lite",
      "baseUrl": "http://localhost:4000",
      "timeoutSec": 30
    }
  },
  "checks": {
    "goal_quality": { "enabled": true, "usesLlm": true },
    "thread_health": { "enabled": true, "staleDays": 5 },
    "pipeline_correlation": { "enabled": true },
    "anomaly_detection": { "enabled": true },
    "bootstrap_integrity": { "enabled": true },
    "recommendations": { "enabled": true, "maxRecommendations": 5 }
  }
}

• Primary: ollama/qwen3:14b (local, $0.00/run)
• Fallback: gemini/gemini-2.0-flash-lite via LiteLLM (~$0.002/run)
• Budget: ≤ $0.05 per run (30x margin)
• Max 4 LLM calls per run (CK-01, CK-02, CK-05, CK-06)
• Fail-open: If LLM unavailable, severity defaults to ok with explanatory detail

This plugin replaces @vainplex/openclaw-sitrep. Sitrep's errors and custom collectors are adopted; systemd_timers, nats, goals, threads, and calendar collectors are either absorbed into cognitive checks or dropped (covered by L1).

npm install
npm run build          # TypeScript compilation
npm run test           # Run all tests
npm run test:coverage  # Coverage report (>80% lines)
npm run typecheck      # Type checking only

• TypeScript strict mode, noUncheckedIndexedAccess
• 0 any types
• ESM (type: module)
• 0 runtime dependencies (only node:* builtins)
• vitest for tests
• kebab-case filenames

MIT