@cleocode/cleo 2026.3.26 → 2026.3.27

package/.claude-plugin/hooks/scripts/brain-worker.cjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+// CLEO Brain Observation Worker
+// HTTP server that receives hook events and stores observations via cleo CLI.
+// Designed as a background daemon — starts fast, handles errors silently.
+
+const http = require('node:http');
+const { execFileSync, execFile, fork } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const PORT = 37778;
+const PID_FILE = path.join(os.homedir(), '.cleo', 'brain-worker.pid');
+const LOG_FILE = path.join(os.homedir(), '.cleo', 'logs', 'brain-worker.log');
+const CLEO_BIN = path.join(os.homedir(), '.cleo', 'bin', 'cleo');
+
+// Tools to skip (too noisy or meta)
+const SKIP_TOOLS = new Set([
+  'ListMcpResourcesTool', 'SlashCommand', 'Skill', 'TodoWrite',
+  'AskUserQuestion', 'TaskList', 'TaskUpdate', 'TaskCreate',
+  'TeamCreate', 'SendMessage', 'ToolSearch',
+]);
+const SKIP_PREFIXES = ['mcp__cleo', 'mcp__claude-mem', 'mcp__plugin_claude-mem'];
+
+// --- Logging ---
+
+function ensureLogDir() {
+  const dir = path.dirname(LOG_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function log(msg) {
+  try {
+    ensureLogDir();
+    const ts = new Date().toISOString();
+    fs.appendFileSync(LOG_FILE, `[${ts}] ${msg}\n`);
+  } catch {
+    // Silent — never crash
+  }
+}
+
+// --- CLI helpers ---
+
+function cleoObserve(text, title) {
+  try {
+    const args = ['memory', 'observe', text];
+    if (title) {
+      args.push('--title', title);
+    }
+    execFileSync(CLEO_BIN, args, {
+      timeout: 10000,
+      stdio: 'ignore',
+      cwd: process.env.CLEO_PROJECT_DIR || process.cwd(),
+    });
+    return true;
+  } catch (err) {
+    log(`cleoObserve failed: ${err.message}`);
+    return false;
+  }
+}
+
+// --- Observation summarizer ---
+
+function summarizeTool(toolName, toolInput) {
+  const inp = toolInput || {};
+  switch (toolName) {
+    case 'Bash':
+      return `Ran: ${String(inp.command || '').slice(0, 120)}`;
+    case 'Write':
+      return `Wrote: ${inp.file_path || inp.path || 'unknown'}`;
+    case 'Edit':
+      return `Edited: ${inp.file_path || inp.path || 'unknown'}`;
+    case 'Read':
+      return `Read: ${inp.file_path || inp.path || 'unknown'}`;
+    case 'Glob':
+      return `Glob: ${String(inp.pattern || '').slice(0, 80)}`;
+    case 'Grep':
+      return `Grep: ${String(inp.pattern || '').slice(0, 60)} in ${String(inp.path || '.').slice(0, 60)}`;
+    case 'Agent':
+      return `Spawned agent: ${String(inp.prompt || inp.description || '').slice(0, 80)}`;
+    case 'WebFetch':
+      return `Fetched: ${String(inp.url || '').slice(0, 120)}`;
+    case 'WebSearch':
+      return `Searched: ${String(inp.query || '').slice(0, 80)}`;
+    default:
+      return `${toolName} called`;
+  }
+}
+
+function shouldSkip(toolName) {
+  if (SKIP_TOOLS.has(toolName)) return true;
+  for (const prefix of SKIP_PREFIXES) {
+    if (toolName.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+// --- Event handlers ---
+
+function handleObservation(data) {
+  const toolName = data.tool_name || 'unknown';
+  if (shouldSkip(toolName)) {
+    log(`Skipped noisy tool: ${toolName}`);
+    return;
+  }
+  const summary = summarizeTool(toolName, data.tool_input);
+  const title = `[hook] ${toolName}`;
+  log(`Observing: ${title} — ${summary}`);
+  cleoObserve(summary, title);
+}
+
+function handleSummarize(_data) {
+  log('Generating session summary...');
+  // Best-effort session summary: capture what we can from cleo
+  let sessionInfo = 'Claude Code session ended';
+  try {
+    const raw = execFileSync(CLEO_BIN, ['session', 'status', '--json'], {
+      timeout: 10000,
+      encoding: 'utf8',
+      cwd: process.env.CLEO_PROJECT_DIR || process.cwd(),
+    });
+    const parsed = JSON.parse(raw);
+    const s = parsed?.result?.session || parsed?.session || {};
+    if (s.scope || s.currentTask) {
+      sessionInfo = `Session ended: ${s.scope || 'unknown'} scope, task: ${s.currentTask || 'none'}`;
+    }
+  } catch {
+    // Use default
+  }
+  cleoObserve(sessionInfo, '[hook] session-end');
+}
+
+function handleSessionInit(_data) {
+  log('Session init received (no-op).');
+  // No-op for now — placeholder for future context injection
+}
+
+// --- HTTP Server ---
+
+function createServer() {
+  return http.createServer((req, res) => {
+    if (req.method === 'POST' && req.url === '/hook') {
+      let body = '';
+      req.on('data', (chunk) => { body += chunk; });
+      req.on('end', () => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end('{"ok":true}');
+
+        // Process async after responding
+        try {
+          const payload = JSON.parse(body);
+          const event = payload.event;
+          const data = typeof payload.data === 'string' ? JSON.parse(payload.data) : (payload.data || {});
+
+          switch (event) {
+            case 'observation':
+              handleObservation(data);
+              break;
+            case 'summarize':
+              handleSummarize(data);
+              break;
+            case 'session-init':
+              handleSessionInit(data);
+              break;
+            default:
+              log(`Unknown event: ${event}`);
+          }
+        } catch (err) {
+          log(`Error processing hook: ${err.message}`);
+        }
+      });
+    } else if (req.method === 'GET' && req.url === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, pid: process.pid, uptime: process.uptime() }));
+    } else {
+      res.writeHead(404);
+      res.end('Not found');
+    }
+  });
+}
+
+// --- PID management ---
+
+function readPid() {
+  try {
+    const pid = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10);
+    if (isNaN(pid)) return null;
+    return pid;
+  } catch {
+    return null;
+  }
+}
+
+function isRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function writePid(pid) {
+  const dir = path.dirname(PID_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(PID_FILE, String(pid));
+}
+
+function removePid() {
+  try {
+    fs.unlinkSync(PID_FILE);
+  } catch {
+    // Ignore
+  }
+}
+
+// --- Commands ---
+
+function startCommand() {
+  // Check if already running
+  const existingPid = readPid();
+  if (existingPid && isRunning(existingPid)) {
+    console.log(`Brain worker already running (PID ${existingPid})`);
+    process.exit(0);
+  }
+
+  // Also check if port is already in use
+  const net = require('node:net');
+  const probe = net.createServer();
+  probe.once('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+      console.log(`Port ${PORT} already in use — worker likely running`);
+      process.exit(0);
+    }
+  });
+  probe.once('listening', () => {
+    probe.close(() => {
+      // Port free — daemonize
+      daemonize();
+    });
+  });
+  probe.listen(PORT, '127.0.0.1');
+}
+
+function daemonize() {
+  // Fork a detached child that runs the server
+  const child = fork(__filename, ['--serve'], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, CLEO_PROJECT_DIR: process.cwd() },
+  });
+  child.unref();
+  writePid(child.pid);
+  console.log(`Brain worker started (PID ${child.pid}, port ${PORT})`);
+  process.exit(0);
+}
+
+function serveCommand() {
+  // This runs in the daemonized child
+  writePid(process.pid);
+  log(`Brain worker starting on port ${PORT} (PID ${process.pid})`);
+
+  const server = createServer();
+  server.listen(PORT, '127.0.0.1', () => {
+    log(`Brain worker listening on 127.0.0.1:${PORT}`);
+  });
+
+  server.on('error', (err) => {
+    log(`Server error: ${err.message}`);
+    removePid();
+    process.exit(1);
+  });
+
+  // Graceful shutdown
+  const shutdown = () => {
+    log('Brain worker shutting down...');
+    server.close();
+    removePid();
+    process.exit(0);
+  };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+}
+
+function stopCommand() {
+  const pid = readPid();
+  if (!pid) {
+    console.log('Brain worker not running (no PID file)');
+    process.exit(0);
+  }
+  if (!isRunning(pid)) {
+    console.log(`Brain worker not running (stale PID ${pid})`);
+    removePid();
+    process.exit(0);
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+    console.log(`Brain worker stopped (PID ${pid})`);
+  } catch (err) {
+    console.log(`Failed to stop brain worker: ${err.message}`);
+  }
+  removePid();
+}
+
+function statusCommand() {
+  const pid = readPid();
+  if (pid && isRunning(pid)) {
+    console.log(`Brain worker running (PID ${pid}, port ${PORT})`);
+  } else {
+    console.log('Brain worker not running');
+    if (pid) removePid();
+  }
+}
+
+// --- Main ---
+
+const command = process.argv[2];
+switch (command) {
+  case 'start':
+    startCommand();
+    break;
+  case '--serve':
+    serveCommand();
+    break;
+  case 'stop':
+    stopCommand();
+    break;
+  case 'status':
+    statusCommand();
+    break;
+  default:
+    console.log('Usage: brain-worker.js <start|stop|status>');
+    process.exit(1);
+}

package/.claude-plugin/hooks/scripts/observe.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# PostToolUse: capture tool observations into CLEO brain.db
+# Best-effort — always exits 0 so it never blocks Claude Code
+set -euo pipefail
+
+CLEO_BIN="${HOME}/.cleo/bin/cleo"
+[ ! -x "$CLEO_BIN" ] && exit 0
+[ ! -d ".cleo" ] && exit 0
+
+# Read stdin (tool use JSON from Claude Code)
+INPUT=$(cat) || exit 0
+TOOL=$(echo "$INPUT" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('tool_name','unknown'))" 2>/dev/null || echo "unknown")
+
+# Only observe meaningful tools (skip trivial ones)
+case "$TOOL" in
+  Read|Write|Edit|Bash|Glob|Grep|Agent) ;;
+  *) exit 0 ;;
+esac
+
+# Extract a short summary
+SUMMARY=$(echo "$INPUT" | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+tool = d.get('tool_name', 'unknown')
+inp = d.get('tool_input', {})
+if tool == 'Bash':
+    print(f'Bash: {str(inp.get(\"command\",\"\"))[:80]}')
+elif tool in ('Read','Write','Edit'):
+    print(f'{tool}: {inp.get(\"file_path\",inp.get(\"path\",\"\"))[:80]}')
+elif tool == 'Grep':
+    print(f'Grep: {inp.get(\"pattern\",\"\")[:40]} in {inp.get(\"path\",\".\")[:40]}')
+elif tool == 'Glob':
+    print(f'Glob: {inp.get(\"pattern\",\"\")[:60]}')
+elif tool == 'Agent':
+    print(f'Agent: {str(inp.get(\"prompt\",\"\"))[:80]}')
+else:
+    print(f'{tool} called')
+" 2>/dev/null || echo "$TOOL called")
+
+"$CLEO_BIN" memory observe "$SUMMARY" --title "[hook] $TOOL" >/dev/null 2>&1 || true
+exit 0

package/.claude-plugin/hooks/scripts/session-start.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# SessionStart hook: Auto-bind CLEO session to Claude Code terminal
+# Part of CLEO universal subagent architecture (v0.70.0+)
+
+set -euo pipefail
+
+# Find cleo installation
+CLEO_DIR="${HOME}/.cleo"
+CLEO_BIN="${CLEO_DIR}/cleo"
+
+# Only proceed if cleo is installed
+if [[ ! -x "$CLEO_BIN" ]]; then
+    exit 0
+fi
+
+# Check if .cleo project directory exists
+if [[ ! -d ".cleo" ]]; then
+    exit 0
+fi
+
+# Check if there's a current session
+CURRENT_SESSION_FILE=".cleo/.current-session"
+if [[ ! -f "$CURRENT_SESSION_FILE" ]]; then
+    exit 0
+fi
+
+# Read current session ID
+SESSION_ID=$(cat "$CURRENT_SESSION_FILE" 2>/dev/null || echo "")
+if [[ -z "$SESSION_ID" ]]; then
+    exit 0
+fi
+
+# Verify session exists and is active
+SESSION_STATUS=$("$CLEO_BIN" session status --session "$SESSION_ID" --format json 2>/dev/null || echo "{}")
+IS_ACTIVE=$(echo "$SESSION_STATUS" | jq -r '.session.status // "unknown"' 2>/dev/null || echo "unknown")
+
+if [[ "$IS_ACTIVE" == "active" ]]; then
+    # Export session to environment for all subsequent commands
+    export CLEO_SESSION="$SESSION_ID"
+
+    # Write to a file that can be sourced by the shell
+    echo "export CLEO_SESSION=\"$SESSION_ID\"" > ".cleo/.session-env"
+
+    # Optional: Display session info (visible in terminal)
+    echo "✓ CLEO session bound: $SESSION_ID" >&2
+fi
+
+exit 0

package/.claude-plugin/hooks/scripts/stop.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Stop: save session summary to CLEO brain
+# Best-effort — always exits 0 so it never blocks Claude Code
+set -euo pipefail
+
+CLEO_BIN="${HOME}/.cleo/bin/cleo"
+[ ! -x "$CLEO_BIN" ] && exit 0
+[ ! -d ".cleo" ] && exit 0
+
+# Get current session info if available
+SESSION_INFO=$("$CLEO_BIN" session status --json 2>/dev/null | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+r = d.get('result', {})
+s = r.get('session', {})
+if s:
+    print(f'Session ended: {s.get(\"scope\",\"unknown\")} scope, task: {s.get(\"currentTask\",\"none\")}')
+else:
+    print('Session ended')
+" 2>/dev/null || echo "Claude Code session ended")
+
+"$CLEO_BIN" memory observe "$SESSION_INFO" --title "[hook] session-end" >/dev/null 2>&1 || true
+exit 0

package/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "cleo",
+  "version": "0.70.1",
+  "description": "CLEO task management system with custom agents for LLM-driven development workflows",
+  "author": {
+    "name": "CLEO",
+    "url": "https://github.com/kryptobaseddev/cleo"
+  },
+  "capabilities": {
+    "task_management": true,
+    "multi_session": true,
+    "orchestration": true
+  },
+  "hooks": {
+    "enabled": true,
+    "directory": "hooks",
+    "manifest": "hooks/hooks.json"
+  },
+  "metadata": {
+    "schema_version": "1.0.0",
+    "min_claude_version": "1.0.0",
+    "license": "MIT"
+  }
+}