homaruscc 0.4.0 → 0.5.0

package/README.md

@@ -2,6 +2,8 @@
 
 **An MCP server that gives Claude Code a body** — messaging, memory, identity, timers, browser automation, and tools. Claude Code is the brain. HomarUScc is the nervous system.
 
+[kcdjmaxx.com/homaruscc](https://kcdjmaxx.com/homaruscc/)
+
 Most MCP servers add capabilities. HomarUScc adds _continuity_. It gives the agent persistent identity (who it is across sessions), evolving memory (what it's learned), and zero-token idle (it costs nothing when nobody's talking to it). The agent wakes on events, reasons, responds, reflects, and goes back to sleep.
 
 The result is an agent that remembers yesterday's conversation, carries forward its own preferences and opinions, writes a daily journal, dreams overnight, and can modify its own personality file as it develops. Not a chatbot that resets every session — a persistent presence that grows over time.
@@ -24,6 +26,7 @@ Claude Code <-> MCP (stdio) <-> Proxy (mcp-proxy.ts)
                                     +-- Identity manager (soul.md / user.md / state.md + journal)
                                     +-- Session checkpoint (compaction resilience)
                                     +-- Agent registry (background task dispatch)
+                                    +-- Plugin loader (backend plugins from dist/plugins/)
                                     +-- Skill plugins (hot-loadable)
                                     +-- Tool registry (bash, fs, git, web, memory)
 ```
@@ -171,6 +174,9 @@ Restart Claude Code. HomarUScc's tools will appear automatically. The proxy auto
 | `browser_type` | Type into an input by CSS selector |
 | `browser_evaluate` | Execute JavaScript in the page |
 | `browser_content` | Get page text content |
+| `crm_search` | Fuzzy CRM contact search with Levenshtein matching |
+| `calendar_today` | Fetch today's calendar events from Zoho Calendar |
+| `session_extract` | Analyze Claude Code transcripts for insights and patterns |
 | `run_tool` | Execute any registered tool (bash, read, write, edit, glob, grep, git, web) |
 
 ## MCP Resources
@@ -196,16 +202,61 @@ When enabled, the dashboard runs on `http://localhost:3120` with:
 
 The dashboard is responsive — on mobile devices the sidebar collapses into a hamburger menu. Accessible remotely over Tailscale at `http://<your-tailscale-ip>:3120`.
 
-### Apps Platform (planned)
+### Plugin System
+
+HomarUScc supports two kinds of extensibility:
+
+**Simple apps** — lightweight data apps with JSON storage and optional HTML UI. Live at `~/.homaruscc/apps/{slug}/` with a `manifest.json`, optional `index.html`, and `data.json`. Hooks (`read`, `write`, `describe`) are exposed via the `app_invoke` MCP tool.
+
+**Backend plugins** — full-featured plugins with their own database, Express routes, and MCP tools. Plugin source lives in `src/plugins/<slug>/` (gitignored, per-user) and compiles with the project to `dist/plugins/<slug>/`. At startup, the plugin loader discovers compiled plugins, initializes them with a data directory, and mounts their routes and tools.
+
+```
+~/.homaruscc/apps/<slug>/
+├── manifest.json       # { "type": "plugin", "name": "...", ... }
+├── collection.sqlite   # Plugin's own database (example)
+└── ...                 # Plugin data files
+
+src/plugins/<slug>/     # Source (gitignored, compiles to dist/plugins/)
+├── index.ts            # Exports: init(), routes(), tools(), shutdown()
+├── store.ts            # Plugin's data layer
+└── ...
+
+dashboard/src/plugins/  # Frontend components (gitignored)
+└── <slug>.tsx          # Auto-discovered via import.meta.glob
+```
+
+Plugin backend interface:
+```typescript
+export function init(dataDir: string): void;          // Called at startup
+export function routes?(router: Router): void;        // Express routes mounted at /api/plugins/<slug>/
+export function tools?(): PluginToolDef[];             // MCP tools registered alongside core tools
+export function shutdown?(): void;                     // Cleanup on stop
+```
 
-The dashboard supports a pluggable apps system. The agent can build mini web apps on request (budget trackers, reading lists, dashboards) that live inside the dashboard UI:
+Plugin frontend components register themselves using `registerSkill()` with a `surface` field that controls where they appear:
+
+```typescript
+import { registerSkill } from "../skills-registry";
+import MyPluginView from "./my-plugin-view";
+
+registerSkill({
+  id: "my-plugin",
+  name: "My Plugin",
+  icon: "#",
+  surface: "sidebar",   // "sidebar" | "apps" | "headless"
+  order: 100,
+  core: false,
+  component: MyPluginView,
+});
+```
 
-- Apps live at `~/.homaruscc/apps/{slug}/` with a manifest, React component, and JSON data store
-- Each app declares hooks (`read`, `write`, `describe`) exposed via a single `app_invoke` MCP tool
-- The agent can query and update app state through hooks — "what's on my reading list?" triggers `app_invoke(slug=reading-list, hook=describe)`
-- Apps are created by the agent via filesystem tools and auto-discovered on manifest scan
+| Surface | Where it renders | Required fields |
+|---------|-----------------|-----------------|
+| `sidebar` | Own tab in the sidebar (like Chat, Events, Records) | `component` |
+| `apps` | Card in the Apps grid panel | `url`, `description` |
+| `headless` | No UI — tools and timers only | `tools`, `timers` |
 
-See `specs/apps-platform.md` and `design/crc-App*.md` for the full design.
+Plugins are personal — they don't ship with the repo. When someone clones HomarUScc, they get a clean core. The agent builds plugins on request and they live entirely in user-space.
 
 ### Dashboard Development
 
@@ -229,6 +280,7 @@ HomarUScc creates runtime data that's gitignored and stays local. All user data
 | `local/dreams/` | Dream cycle output (nightly, stored at 0.5x weight) |
 | `local/research/` | Research notes stored by memory system |
 | `local/docs/` | Private documents (outreach drafts, session notes, etc.) |
+| `~/.homaruscc/apps/` | App and plugin data directories (per-user) |
 | `~/.homaruscc/memory/` | Vector + FTS search index (SQLite) |
 | `~/.homaruscc/identity/` | Agent identity files (soul, user, state, preferences, disagreements) |
 | `~/.homaruscc/journal/` | Daily reflection journal entries (indexed by memory system) |
@@ -278,6 +330,42 @@ Both are wired into the `PreCompact` Claude Code hook that calls `/api/pre-compa
 }
 ```
 
+### Hook Configuration
+
+HomarUScc hooks into Claude Code's compaction lifecycle to preserve context. Add the following to your project's `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s http://127.0.0.1:3120/api/pre-compact"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s http://127.0.0.1:3120/api/post-compact"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- **PreCompact**: Flushes transcripts, triggers checkpoint save, and returns a prompt reminding Claude to persist important context before compaction
+- **SessionStart**: Returns post-compaction context including checkpoint data, active timers, and identity refresh
+
+These hooks are optional but strongly recommended for long sessions. Without them, the agent loses task context across compaction boundaries.
+
 ## Agent Dispatch
 
 For tasks that would consume significant context (research, multi-file processing, mini-spec workflows), the agent can dispatch work to background agents instead of doing it inline:
@@ -292,6 +380,20 @@ Max concurrent agents is configurable via `agents.maxConcurrent` in config (defa
 
 **Completion detection:** Agents signal completion by calling `POST /api/agents/:id/complete` with a result summary. This emits an `agent_completed` event that wakes the main event loop. A 30-minute timeout fallback catches agents that fail to call back. No polling needed — results arrive as events.
 
+## Passive Knowledge Capture
+
+HomarUScc continuously extracts structured knowledge from conversations without explicit user action.
+
+**FactExtractor** — Batches conversation turns and sends them to Claude Haiku for extraction of preferences, corrections, patterns, facts, and decisions. Results are stored in the memory index under structured key prefixes (`local/user/preferences/`, `local/user/corrections/`, etc.). Runs in the background during normal conversation.
+
+**SessionExtractor** — Analyzes Claude Code JSONL transcripts (the raw session logs) to extract architecture decisions, debugging solutions, and workflow patterns. Designed to feed the daily reflection timer with deeper insights than real-time extraction can capture.
+
+Both systems complement the agent's explicit reflection cycle (journal entries, prediction error logging, dream cycles) by capturing knowledge that would otherwise be lost between sessions.
+
+## Compaction Auto-Restart
+
+After a configurable number of context compactions (default 8), the event loop signals that a full restart is needed. This prevents degraded performance from accumulated compaction artifacts. The `/nuke` Telegram command provides a manual escape hatch that kills all Claude processes and starts a fresh session.
+
 ## Architecture
 
 HomarUScc is a fork of HomarUS with the agent loop, model router, and HTTP API removed. Claude Code handles all reasoning; HomarUScc just provides the I/O layer.
@@ -311,18 +413,42 @@ Key source files:
 | `src/dashboard-server.ts` | Express + WebSocket dashboard server |
 | `src/dashboard-adapter.ts` | Dashboard channel adapter |
 | `src/memory-index.ts` | SQLite + sqlite-vec hybrid search with dream-aware scoring |
-| `src/compaction-manager.ts` | Auto-flush memory before context compaction |
+| `src/fact-extractor.ts` | Passive fact extraction from conversations via Haiku |
+| `src/session-extractor.ts` | Session transcript analysis for architecture insights |
+| `src/telegram-command-handler.ts` | Telegram slash commands (/ping, /status, /restart, /nuke) |
+| `src/compaction-manager.ts` | Auto-flush memory before context compaction, auto-restart after threshold |
 | `src/session-checkpoint.ts` | Save/restore task context across compaction |
 | `src/agent-registry.ts` | Track background agents with callback completion and timeout fallback |
 | `src/transcript-logger.ts` | Session transcript capture and indexing |
 | `src/identity-manager.ts` | Identity loader (soul.md, user.md, state.md) |
 | `src/timer-service.ts` | Cron, interval, and one-shot timers |
 | `src/browser-service.ts` | Playwright browser automation |
+| `src/plugin-loader.ts` | Backend plugin discovery, loading, and mounting |
 | `src/skill-manager.ts` | Hot-loadable skill plugins |
 | `src/tool-registry.ts` | Tool registration and policy enforcement |
 | `src/tools/` | Built-in tools (bash, fs, git, web, memory) |
 | `dashboard/` | React + Vite SPA |
 
+## Publishing to npm
+
+```bash
+# 1. Bump version in package.json
+npm version patch   # or minor/major
+
+# 2. Build everything
+npm run build
+cd dashboard && npm run build && cd ..
+
+# 3. Login (if not already)
+npm login
+
+# 4. Publish (dry run first)
+npm publish --dry-run
+npm publish
+```
+
+The `files` array in package.json controls what gets published: `dist/`, `dashboard/dist/`, `bin/`, `identity.example/`, config/env examples, README, and LICENSE. Source files, specs, design docs, and tests are excluded via `.npmignore`.
+
 ## License
 
 MIT - see [LICENSE](LICENSE)

package/bin/event-loop

@@ -49,7 +49,13 @@ while true; do
       cat /tmp/homaruscc-wait-response.json
       echo ""
       echo "---"
-      echo "Event loop paused. Handle the events above, then restart: bash \"\$PWD/bin/event-loop\""
+      # Check if backend is signaling auto-restart due to high compaction count
+      if command -v jq &>/dev/null && jq -e '.shouldRestart' /tmp/homaruscc-wait-response.json &>/dev/null; then
+        echo "⚠️ COMPACTION LIMIT REACHED — Auto-restart required."
+        echo "Handle the events above, save state, then run: bash \"\$PWD/bin/restart-claude\""
+      else
+        echo "Event loop paused. Handle the events above, then restart: bash \"\$PWD/bin/event-loop\""
+      fi
       exit 0
       ;;
     *)

package/bin/nuke-claude

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Nuclear restart — kill ALL claude processes system-wide, then start fresh
+# Called by the /nuke Telegram command when /restart fails
+# Env vars: HOMARUSCC_PROJECT_DIR, HOMARUSCC_CHAT_ID, HOMARUSCC_PORT
+
+set -euo pipefail
+
+PROJECT_DIR="${HOMARUSCC_PROJECT_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+PORT="${HOMARUSCC_PORT:-3120}"
+CHAT_ID="${HOMARUSCC_CHAT_ID:-}"
+SESSION_NAME="homaruscc"
+
+report() {
+  local success="$1"
+  local message="$2"
+  if [ -n "$CHAT_ID" ] && [ -n "$PORT" ]; then
+    curl -s -X POST "http://127.0.0.1:${PORT}/api/restart-result" \
+      -H "Content-Type: application/json" \
+      -d "{\"success\":${success},\"message\":\"${message}\"}" \
+      > /dev/null 2>&1 || true
+  fi
+}
+
+echo "[nuke] Starting nuclear restart..."
+
+# Ignore TERM/HUP/INT so we survive our own kill commands
+# (script name contains "claude" so pkill/pgrep match us)
+trap '' TERM HUP INT
+MY_PID=$$
+
+# Phase 1: Kill ALL tmux sessions
+for session in $(tmux list-sessions -F '#{session_name}' 2>/dev/null || true); do
+  echo "[nuke] Killing tmux session: $session"
+  tmux kill-session -t "$session" 2>/dev/null || true
+done
+sleep 1
+
+# Phase 2: Kill ALL claude processes (exclude ourselves)
+echo "[nuke] Killing all claude processes (excluding PID $MY_PID)..."
+for pid in $(pgrep -f "claude" 2>/dev/null || true); do
+  [ "$pid" = "$MY_PID" ] && continue
+  echo "[nuke] Killing PID $pid"
+  kill "$pid" 2>/dev/null || true
+done
+sleep 2
+
+# Phase 3: Kill any event-loop curl processes
+pkill -f "homaruscc-wait-response" 2>/dev/null || true
+
+# Phase 4: Verify everything is dead (exclude ourselves)
+REMAINING=0
+for pid in $(pgrep -f "claude" 2>/dev/null || true); do
+  [ "$pid" = "$MY_PID" ] && continue
+  REMAINING=$((REMAINING + 1))
+done
+if [ "$REMAINING" -gt 0 ]; then
+  echo "[nuke] $REMAINING claude processes still alive — force killing"
+  for pid in $(pgrep -f "claude" 2>/dev/null || true); do
+    [ "$pid" = "$MY_PID" ] && continue
+    kill -9 "$pid" 2>/dev/null || true
+  done
+  sleep 1
+fi
+
+# Restore signal handling
+trap - TERM HUP INT
+
+# Phase 5: Start fresh tmux session
+echo "[nuke] Starting fresh tmux session..."
+tmux new-session -d -s "$SESSION_NAME" -c "$PROJECT_DIR"
+
+if ! tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+  report "false" "Nuke: killed all processes but failed to create new tmux session"
+  exit 1
+fi
+
+tmux send-keys -t "$SESSION_NAME" 'claude --dangerously-skip-permissions "/homaruscc"' Enter
+
+report "true" "Nuke complete. All claude processes killed, fresh session started. Attach: tmux attach -t ${SESSION_NAME}"
+echo "[nuke] Done. Fresh session '${SESSION_NAME}' started."

package/bin/restart-claude

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Restart Claude Code in a tmux session with /homaruscc
+# Called by the /restart Telegram command (TelegramCommandHandler)
+# Env vars: HOMARUSCC_PROJECT_DIR, HOMARUSCC_CHAT_ID, HOMARUSCC_PORT
+
+set -euo pipefail
+
+PROJECT_DIR="${HOMARUSCC_PROJECT_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+PORT="${HOMARUSCC_PORT:-3120}"
+CHAT_ID="${HOMARUSCC_CHAT_ID:-}"
+SESSION_NAME="homaruscc"
+
+report() {
+  local success="$1"
+  local message="$2"
+  if [ -n "$CHAT_ID" ] && [ -n "$PORT" ]; then
+    curl -s -X POST "http://127.0.0.1:${PORT}/api/restart-result" \
+      -H "Content-Type: application/json" \
+      -d "{\"success\":${success},\"message\":\"${message}\"}" \
+      > /dev/null 2>&1 || true
+  fi
+}
+
+# Store chat ID for result callback
+if [ -n "$CHAT_ID" ] && [ -n "$PORT" ]; then
+  curl -s -X POST "http://127.0.0.1:${PORT}/api/restart-chat" \
+    -H "Content-Type: application/json" \
+    -d "{\"chatId\":\"${CHAT_ID}\"}" \
+    > /dev/null 2>&1 || true
+fi
+
+# Reset compaction counter so new session starts clean
+echo '{"count":0}' > "$HOME/.homaruscc/compaction-count.json"
+
+# Kill existing tmux session if it exists
+if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+  tmux kill-session -t "$SESSION_NAME"
+  sleep 1
+fi
+
+# Also kill any stray claude processes for this project
+# (in case claude was running outside tmux)
+pkill -f "claude.*$(basename "$PROJECT_DIR")" 2>/dev/null || true
+sleep 2
+
+# Start new tmux session — interactive claude inside it
+# Step 1: Create session with a shell
+tmux new-session -d -s "$SESSION_NAME" -c "$PROJECT_DIR"
+
+if ! tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+  report "false" "Failed to create tmux session"
+  exit 1
+fi
+
+# Step 2: Start claude with /homaruscc prompt passed directly
+tmux send-keys -t "$SESSION_NAME" 'claude --dangerously-skip-permissions "/homaruscc"' Enter
+
+report "true" "tmux session '${SESSION_NAME}' started with claude + /homaruscc. Attach: tmux attach -t ${SESSION_NAME}"

package/bin/setup

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# HomarUScc first-run setup
+# Creates ~/.homaruscc directory structure and launches the alignment interview
+# to generate identity files (soul.md, user.md, state.md, preferences.md, disagreements.md).
+
+set -euo pipefail
+
+HOMARUSCC_DIR="${HOMARUSCC_DIR:-$HOME/.homaruscc}"
+
+echo "=== HomarUScc Setup ==="
+echo ""
+
+# 1. Create directory structure
+dirs=(
+  "$HOMARUSCC_DIR"
+  "$HOMARUSCC_DIR/identity"
+  "$HOMARUSCC_DIR/journal"
+  "$HOMARUSCC_DIR/memory"
+  "$HOMARUSCC_DIR/secrets"
+)
+
+for dir in "${dirs[@]}"; do
+  if [ ! -d "$dir" ]; then
+    mkdir -p "$dir"
+    echo "Created $dir"
+  fi
+done
+
+# 2. Create config.json if it doesn't exist
+if [ ! -f "$HOMARUSCC_DIR/config.json" ]; then
+  cat > "$HOMARUSCC_DIR/config.json" << 'CONF'
+{
+  "channels": {
+    "telegram": {
+      "enabled": false,
+      "botToken": ""
+    }
+  },
+  "memory": {
+    "extraPaths": [
+      "~/.homaruscc/identity",
+      "~/.homaruscc/journal"
+    ]
+  },
+  "timers": {
+    "defaults": []
+  }
+}
+CONF
+  echo "Created $HOMARUSCC_DIR/config.json (edit to add Telegram bot token)"
+fi
+
+# 3. Create .env template if it doesn't exist
+if [ ! -f "$HOMARUSCC_DIR/.env" ]; then
+  cat > "$HOMARUSCC_DIR/.env" << 'ENV'
+# Telegram Bot Token (get from @BotFather)
+TELEGRAM_BOT_TOKEN=
+
+# Optional: Anthropic API key for phone/voice features
+# ANTHROPIC_API_KEY=
+ENV
+  echo "Created $HOMARUSCC_DIR/.env (edit to add tokens)"
+fi
+
+# 4. Check for identity files
+if [ -f "$HOMARUSCC_DIR/identity/soul.md" ]; then
+  echo ""
+  echo "Identity files already exist at $HOMARUSCC_DIR/identity/"
+  echo "Skipping alignment interview. Delete identity files to re-run."
+  echo ""
+  echo "Setup complete. Run: npx homaruscc"
+  exit 0
+fi
+
+# 5. Launch alignment interview
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+ALIGNMENT_DIR="$PROJECT_DIR/../alignment-generator"
+
+echo ""
+echo "Next step: Run the Alignment Interview to generate your identity files."
+echo "This is a browser-based questionnaire that maps your values and preferences"
+echo "into files your agent can use from day one."
+echo ""
+
+if [ -f "$ALIGNMENT_DIR/index.html" ]; then
+  echo "Opening alignment interview..."
+  echo "  1. Complete the interview (select 'HomarUScc' format)"
+  echo "  2. Download the identity kit"
+  echo "  3. Move the files to $HOMARUSCC_DIR/identity/"
+  echo ""
+  open "$ALIGNMENT_DIR/index.html" 2>/dev/null || echo "Open $ALIGNMENT_DIR/index.html in your browser"
+else
+  echo "Alignment interview not found at $ALIGNMENT_DIR"
+  echo "You can create identity files manually in $HOMARUSCC_DIR/identity/:"
+  echo "  soul.md      - Agent identity and values"
+  echo "  user.md      - About you (the human)"
+  echo "  state.md     - Session continuity"
+  echo "  preferences.md - Agent's emergent preferences"
+  echo "  disagreements.md - Times the agent pushed back"
+fi
+
+echo ""
+echo "After identity files are in place, run: npx homaruscc"