homaruscc 0.2.0

package/.env.example

@@ -0,0 +1,8 @@
+# HomarUScc environment variables
+# Copy this to ~/.homaruscc/.env and fill in your values
+
+# Required: Telegram bot token from @BotFather
+TELEGRAM_BOT_TOKEN=your-bot-token-here
+
+# Optional: API key for cloud embedding providers (not needed for Ollama)
+# EMBEDDING_API_KEY=your-api-key-here

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Ross
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,307 @@
+# HomarUScc
+
+**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.
+
+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.
+
+Built with [mini-spec](https://github.com/zot/mini-spec).
+
+## How It Works
+
+```
+Claude Code <-> MCP (stdio) <-> Proxy (mcp-proxy.ts)
+                                    |  auto-spawns + HTTP forwarding
+                                    v
+                              Backend (backend.ts)
+                                    |
+                                    +-- Telegram (long-polling adapter)
+                                    +-- Dashboard (Express + WebSocket SPA)
+                                    +-- Timer service (cron / interval / one-shot)
+                                    +-- Memory index (SQLite + vector + FTS + decay + MMR + dream scoring)
+                                    +-- Browser automation (Playwright)
+                                    +-- Identity manager (soul.md / user.md / state.md + journal)
+                                    +-- Session checkpoint (compaction resilience)
+                                    +-- Agent registry (background task dispatch)
+                                    +-- Skill plugins (hot-loadable)
+                                    +-- Tool registry (bash, fs, git, web, memory)
+```
+
+The proxy is thin and never restarts. The backend can be restarted (via `restart_backend` tool) for self-improvement without dropping the MCP connection.
+
+Events arrive from channels (Telegram messages, dashboard chat, timer fires) and flow into the event loop. HomarUScc sends MCP notifications to Claude Code, which reasons about them and calls MCP tools to respond.
+
+## Requirements
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
+- Node.js >= 22
+- (Optional) Ollama for local embeddings
+- (Optional) Playwright for browser automation
+
+## Installation
+
+### 1. Clone and build
+
+```bash
+git clone https://github.com/kcdjmaxx/HomarUScc.git
+cd HomarUScc
+npm install
+npm run build
+```
+
+### 2. Configure
+
+```bash
+mkdir -p ~/.homaruscc
+cp config.example.json ~/.homaruscc/config.json
+```
+
+Edit `~/.homaruscc/config.json` with your settings (see `config.example.json` for all options including default timers and browser config). Tokens use `${ENV_VAR}` syntax so secrets stay in your `.env` file:
+
+```bash
+cp .env.example ~/.homaruscc/.env
+# Edit ~/.homaruscc/.env with your actual tokens
+```
+
+### 3. Set up identity
+
+HomarUScc loads identity files from `~/.homaruscc/identity/` to shape your assistant's personality, what it knows about you, and its evolving self-knowledge.
+
+```bash
+mkdir -p ~/.homaruscc/identity
+cp identity.example/*.md ~/.homaruscc/identity/
+```
+
+Edit `soul.md` (agent personality) and `user.md` (what the agent knows about you) to make it yours. The starter kit includes templates for all five identity files. The agent updates them over time:
+
+| File | Purpose | Who writes it |
+|------|---------|---------------|
+| `soul.md` | Core identity, values, self-evolution | Human (core) + Agent (below Self-Evolution line) |
+| `user.md` | User context and preferences | Human |
+| `state.md` | Session mood, unresolved items, emotional continuity | Agent (end of each session) |
+| `preferences.md` | Emergent preferences discovered through experience | Agent (during reflection) |
+| `disagreements.md` | Times the agent pushed back or had a different opinion | Agent (when it happens) |
+
+Journal entries are written to `~/.homaruscc/journal/YYYY-MM-DD.md` during daily reflection.
+
+### Dream Cycle
+
+At 3am each night, the agent runs a three-phase dream cycle inspired by [neuroscience research on sleep functions](dreams.md):
+
+1. **Memory consolidation** — reviews recent memories, identifies what's important vs noise
+2. **Associative dreaming** — pulls random memories from different topics/periods and force-connects them, producing fuzzy, impressionistic fragments
+3. **Overfitting prevention** — challenges an established preference or belief to test its flexibility
+
+Dream output is deliberately stream-of-consciousness and stored in the unified memory index under `dreams/` with 0.5x weight (always ranks below waking memories) and a 7-day decay half-life (fades quickly). When dream fragments surface during waking interactions, the agent notes the origin explicitly.
+
+A morning digest summarizes interesting dream fragments via Telegram.
+
+The waking personality loop and dream cycle run on different timescales but feed into each other:
+
+```
+                WAKING LOOP                          DREAM CYCLE (3am)
+                ==========                           =================
+
+        ┌─→ Experience ──────────────────────────→ Raw material for dreams
+        │       |                                         |
+        │       v                                         v
+        │   Memory ←──────────── Memory Consolidation ────┘
+        │       |                (re-rank, strengthen,     |
+        │       |                 let weak ones decay)     |
+        │       v                                         v
+        │   Reflection ←──────── Emotional Processing ────┘
+        │       |                (revisit charged moments  |
+        │       |                 from new angles)         |
+        │       v                                         v
+        │   Self-knowledge ←──── Overfitting Prevention ──┘
+        │       |                (challenge established    |
+        │       |                 patterns/preferences)    |
+        │       v                                         v
+        │   Identity ←────────── Associative Dreaming ────┘
+        │   evolution            (novel connections feed
+        │       |                 into convictions,
+        │       v                 soul.md evolution)
+        └── Changed
+            behavior
+```
+
+The waking loop is **fast and reactive** — every interaction triggers observe, reflect, learn, evolve, act differently. The dream cycle is **slow and integrative** — once per night, processing the accumulated day into deeper patterns. This dual-timescale architecture mirrors how human memory consolidation works: waking learning is specific, sleep consolidation is general.
+
+### 4. Add to Claude Code
+
+Register HomarUScc as an MCP server in `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "homaruscc": {
+      "command": "node",
+      "args": ["/absolute/path/to/HomarUScc/dist/mcp-proxy.js"],
+      "env": {
+        "HOMARUSCC_CONFIG": "~/.homaruscc/config.json"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code. HomarUScc's tools will appear automatically. The proxy auto-spawns the backend process — no manual startup needed.
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `telegram_send` | Send a message to a Telegram chat |
+| `telegram_read` | Read recent incoming messages |
+| `memory_search` | Hybrid vector + full-text search over stored content |
+| `memory_store` | Store and index content for later retrieval |
+| `timer_schedule` | Schedule cron, interval, or one-shot timers |
+| `timer_cancel` | Cancel a scheduled timer |
+| `dashboard_send` | Send a message to the web dashboard |
+| `get_status` | System status (channels, memory, timers, queue) |
+| `get_events` | Recent event history |
+| `wait_for_event` | Long-poll for events (blocks until something happens) |
+| `browser_navigate` | Navigate to a URL |
+| `browser_snapshot` | Get the accessibility tree of the current page |
+| `browser_screenshot` | Take a screenshot (base64 PNG) |
+| `browser_click` | Click an element by CSS selector |
+| `browser_type` | Type into an input by CSS selector |
+| `browser_evaluate` | Execute JavaScript in the page |
+| `browser_content` | Get page text content |
+| `run_tool` | Execute any registered tool (bash, read, write, edit, glob, grep, git, web) |
+
+## MCP Resources
+
+| URI | Description |
+|-----|-------------|
+| `identity://soul` | Soul.md content |
+| `identity://user` | User.md content |
+| `identity://state` | State.md — agent mood, session continuity |
+| `config://current` | Current config (secrets redacted) |
+| `events://recent` | Recent event history |
+
+## Dashboard
+
+When enabled, the dashboard runs on `http://localhost:3120` with:
+
+- Chat interface (messages route through Claude Code via MCP)
+- Real-time event log via WebSocket
+- System status panel
+- Memory search browser
+
+### Dashboard Development
+
+```bash
+cd dashboard
+npm install
+npm run dev    # Dev server on :3121, proxies API to :3120
+```
+
+## Runtime Directories
+
+HomarUScc creates runtime data that's gitignored and stays local:
+
+| Directory | Purpose |
+|-----------|---------|
+| `user/context/` | Facts the assistant learns about you |
+| `user/corrections/` | Corrections you've made (so it doesn't repeat mistakes) |
+| `user/preferences/` | Your stated preferences |
+| `system/` | System-level learned knowledge |
+| `~/.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) |
+| `~/.homaruscc/browser-data/` | Persistent browser sessions |
+
+## Event Loop
+
+The `bin/event-loop` script provides a zero-token idle loop. It long-polls the dashboard HTTP API at the OS level — no Claude tokens are consumed while waiting. When events arrive, it returns control to Claude Code.
+
+```bash
+bash homaruscc/bin/event-loop
+```
+
+### Identity Digest
+
+Each wake delivers identity context so the agent stays in character. To avoid burning ~3K tokens on every event, the server uses two delivery modes:
+
+- **Normal wake** (~200 tokens) — a compressed digest: agent name, core behavioral rules, and last session mood. Enough for personality consistency without the full payload.
+- **Post-compaction wake** (~3K tokens) — full identity: `soul.md`, `user.md`, and `state.md`. Sent once after compaction when the original identity context has been compressed away.
+
+The `PreCompact` hook sets a flag on the backend. The next `/api/wait` response checks the flag and returns the appropriate format. The flag is consumed once — subsequent wakes return the digest until the next compaction.
+
+## Compaction Resilience
+
+Claude Code compresses conversation history when the context window fills up. Without mitigation, the post-compaction agent loses track of what it was doing. HomarUScc handles this with two mechanisms:
+
+**Session checkpoint** — Before compaction, the agent saves its current task context (topic, recent decisions, in-progress work, modified files) to `~/.homaruscc/checkpoint.json` via `POST /api/checkpoint`. After compaction, the post-compact context injection includes this checkpoint so the new instance knows exactly where things left off. The checkpoint is cleared at session end.
+
+**Delivery watermark** — The server tracks the timestamp of the last event delivered to Claude Code. After compaction, the event loop resumes from the watermark instead of replaying old events. This prevents the "bad loop" problem where a post-compaction agent re-handles messages it already responded to.
+
+Both are wired into the `PreCompact` Claude Code hook that calls `/api/pre-compact`. Add this 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"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## 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:
+
+1. Register the agent with `POST /api/agents` (returns 429 if at max capacity)
+2. Spawn a background Task agent via Claude Code's Task tool
+3. Return to the event loop immediately — stay responsive to messages
+4. When the agent completes, an `agent_completed` event flows through the event system
+5. Summarize results and send to the user
+
+Max concurrent agents is configurable via `agents.maxConcurrent` in config (default 3). The agent registry tracks running/completed/failed agents and includes them in post-compaction context so background work isn't lost across compaction boundaries.
+
+**Completion detection:** The backend polls output files of registered agents every 5 seconds. When it detects a completion marker (stable file mtime for 10+ seconds, or `"stop_reason":"end_turn"` in the output), it emits an `agent_completed` event that wakes the main event loop. No manual checking needed — results arrive as events.
+
+## 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.
+
+Key source files:
+
+| File | Purpose |
+|------|---------|
+| `src/homaruscc.ts` | Event loop orchestrator |
+| `src/mcp-proxy.ts` | MCP stdio proxy — auto-spawns backend, forwards tool calls over HTTP |
+| `src/backend.ts` | Standalone backend process (Telegram, timers, dashboard, memory) |
+| `src/mcp-server.ts` | Legacy single-process MCP server (unused in two-process mode) |
+| `src/mcp-tools.ts` | MCP tool definitions |
+| `src/mcp-resources.ts` | MCP resource definitions |
+| `src/config.ts` | Config loader with env var resolution and hot-reload |
+| `src/telegram-adapter.ts` | Telegram long-polling adapter |
+| `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/session-checkpoint.ts` | Save/restore task context across compaction |
+| `src/agent-registry.ts` | Track background agents with capacity limits |
+| `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/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 |
+
+## License
+
+MIT - see [LICENSE](LICENSE)

package/bin/event-loop

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Zero-token event loop for HomarUScc
+# Long-polls the dashboard HTTP API — blocks at OS level, zero Claude tokens while idle.
+# Returns to Claude only when real events arrive.
+#
+# The server maintains a delivery watermark — events already delivered via /api/wait
+# are never re-delivered. This survives context compaction without client-side state.
+
+set -euo pipefail
+
+# Read dashboard port from config, default 3120
+CONFIG="$HOME/.homaruscc/config.json"
+if [[ -f "$CONFIG" ]] && command -v jq &>/dev/null; then
+  PORT=$(jq -r '.dashboard.port // 3120' "$CONFIG" 2>/dev/null || echo 3120)
+else
+  PORT=3120
+fi
+
+BASE="http://127.0.0.1:${PORT}"
+TIMEOUT=120
+
+# Prevent duplicate listeners
+PIDFILE="/tmp/homaruscc-event-loop.pid"
+if [[ -f "$PIDFILE" ]]; then
+  OLD_PID=$(cat "$PIDFILE" 2>/dev/null || true)
+  if [[ -n "$OLD_PID" ]] && kill -0 "$OLD_PID" 2>/dev/null; then
+    echo "Killing previous event-loop (PID $OLD_PID)"
+    kill "$OLD_PID" 2>/dev/null || true
+    sleep 0.5
+  fi
+fi
+echo $$ > "$PIDFILE"
+trap 'rm -f "$PIDFILE"' EXIT
+
+while true; do
+  HTTP_CODE=$(curl -s -o /tmp/homaruscc-wait-response.json -w "%{http_code}" \
+    "${BASE}/api/wait?timeout=${TIMEOUT}" 2>/dev/null) || {
+    echo "ERROR: curl failed — is the HomarUScc dashboard running on port ${PORT}?"
+    exit 1
+  }
+
+  case "$HTTP_CODE" in
+    204)
+      # Timeout, no events — loop again (zero tokens)
+      continue
+      ;;
+    200)
+      # Events arrived — print and return to Claude
+      cat /tmp/homaruscc-wait-response.json
+      echo ""
+      echo "---"
+      echo "Event loop paused. Handle the events above, then restart: bash \"\$PWD/bin/event-loop\""
+      exit 0
+      ;;
+    *)
+      echo "ERROR: Unexpected HTTP ${HTTP_CODE} from /api/wait"
+      exit 1
+      ;;
+  esac
+done

package/config.example.json

@@ -0,0 +1,55 @@
+{
+  "channels": {
+    "telegram": {
+      "token": "${TELEGRAM_BOT_TOKEN}",
+      "allowedChatIds": []
+    }
+  },
+  "memory": {
+    "embedding": {
+      "provider": "ollama",
+      "model": "nomic-embed-text",
+      "baseUrl": "http://127.0.0.1:11434/v1"
+    },
+    "extraPaths": []
+  },
+  "identity": {
+    "dir": "~/.homaruscc/identity"
+  },
+  "dashboard": {
+    "port": 3120,
+    "enabled": true
+  },
+  "timers": {
+    "enabled": true,
+    "defaults": [
+      {
+        "name": "morning-briefing",
+        "type": "cron",
+        "schedule": "0 9 * * *",
+        "timezone": "America/Chicago",
+        "prompt": "Good morning routine: 1) Search memory for user patterns and preferences. 2) Check recent events for anything unresolved. 3) Send a Telegram message with: a greeting, any pending items, and proactive suggestions."
+      },
+      {
+        "name": "evening-reflection",
+        "type": "cron",
+        "schedule": "0 21 * * *",
+        "timezone": "America/Chicago",
+        "prompt": "Daily reflection: 1) Review today's interactions. 2) Identify new user preferences, corrections, or patterns. 3) Store insights in memory. 4) Send a brief summary if there's something actionable for tomorrow."
+      },
+      {
+        "name": "nightly-dream",
+        "type": "cron",
+        "schedule": "0 3 * * *",
+        "timezone": "America/Chicago",
+        "prompt": "Dream cycle: 1) Memory consolidation — search recent topics, note what matters. 2) Associative dreaming — search diverse queries, force-connect results into impressionistic fragments. 3) Overfitting prevention — challenge one established belief. Store output as dreams/YYYY-MM-DD.md. Send a brief dream digest via Telegram."
+      }
+    ]
+  },
+  "browser": {
+    "enabled": false,
+    "headless": true,
+    "viewport": { "width": 1280, "height": 720 },
+    "timeout": 30000
+  }
+}

package/dist/agent-registry.d.ts

@@ -0,0 +1,38 @@
+import type { Event, Logger } from "./types.js";
+export type AgentStatus = "running" | "completed" | "failed";
+export interface AgentEntry {
+    id: string;
+    description: string;
+    status: AgentStatus;
+    startTime: number;
+    outputFile?: string;
+    result?: string;
+    error?: string;
+}
+export declare class AgentRegistry {
+    private agents;
+    private maxConcurrent;
+    private emitFn;
+    private logger;
+    private pollIntervalMs;
+    private pollTimer;
+    constructor(logger: Logger, maxConcurrent?: number, pollIntervalMs?: number);
+    setEmitter(fn: (event: Event) => void): void;
+    register(id: string, description: string, outputFile?: string): boolean;
+    getAll(): AgentEntry[];
+    get(id: string): AgentEntry | null;
+    complete(id: string, result: string): void;
+    fail(id: string, error: string): void;
+    cleanup(id: string): void;
+    getAvailableSlots(): number;
+    getActiveCount(): number;
+    startPolling(): void;
+    stopPolling(): void;
+    pollAgents(): void;
+    private checkAgentFile;
+    private readTail;
+    private extractSummary;
+    private resolve;
+    private emit;
+}
+//# sourceMappingURL=agent-registry.d.ts.map

package/dist/agent-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-registry.d.ts","sourceRoot":"","sources":["../src/agent-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE7D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAWD,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,MAAM,CAAyC;IACvD,OAAO,CAAC,MAAM,CAAS;IAEvB,OAAO,CAAC,cAAc,CAAS;IAE/B,OAAO,CAAC,SAAS,CAA+C;gBAEpD,MAAM,EAAE,MAAM,EAAE,aAAa,SAAI,EAAE,cAAc,SAAO;IAMpE,UAAU,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI;IAI5C,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO;IAmBvE,MAAM,IAAI,UAAU,EAAE;IAItB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAKlC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAY1C,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAYrC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIzB,iBAAiB,IAAI,MAAM;IAI3B,cAAc,IAAI,MAAM;IASxB,YAAY,IAAI,IAAI;IAWpB,WAAW,IAAI,IAAI;IASnB,UAAU,IAAI,IAAI;IAiBlB,OAAO,CAAC,cAAc;IAqCtB,OAAO,CAAC,QAAQ;IAoBhB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,IAAI;CAcb"}