# 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.

[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.

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)
                                    +-- Plugin loader (backend plugins from dist/plugins/)
                                    +-- 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
npm run setup    # installs skills to .claude/skills/
```

### 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/` (or `~/.homarus/identity/`) to shape your assistant's personality, what it knows about you, and its evolving self-knowledge.

**Recommended: Run the alignment interview**

The `/align` command walks you through a structured 10-domain interview (~30-45 minutes) that maps your values, communication style, and boundaries into identity files. It's how a new agent learns who you are.

```
/align
```

The interview covers: communication style, decision-making, autonomy preferences, intellectual style, work philosophy, ethics, AI relationships, creative sensibility, conflict handling, and life goals. Progress auto-saves after each domain — if interrupted, `/align` picks up where you left off. On first boot, HomarUScc will suggest running `/align` automatically.

**Alternative: Manual setup**

```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 |
| `telegram_typing` | Send a typing indicator |
| `telegram_react` | React to a message with an emoji |
| `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 |
| `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

| 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
- CRM (People) — markdown-based contact manager with search, tags, connections, and linked document viewer
- Kanban — task board synced with the agent's task system

The dashboard is responsive — on mobile devices the sidebar collapses into a hamburger menu. Accessible remotely over Tailscale at `http://<your-tailscale-ip>:3120`.

### 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
```

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,
});
```

| 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` |

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

```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. All user data lives under `local/` (one gitignore line):

| Directory | Purpose |
|-----------|---------|
| `local/user/context/` | Facts the assistant learns about you |
| `local/user/corrections/` | Corrections you've made (so it doesn't repeat mistakes) |
| `local/user/preferences/` | Your stated preferences |
| `local/system/` | System-level learned knowledge |
| `local/crm/` | CRM contact files (markdown + YAML frontmatter, see `crm.example/`) |
| `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) |
| `~/.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, session texture, highlight snippets) 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. The `texture` field captures the session's conversational dynamic (e.g., "rapid shipping, playful, terse messages") and `highlights` preserves 2-3 raw exchange snippets that exemplify the vibe — restoring not just _what_ was happening but _how_ it felt.

**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.

**Liveness watchdog** — An out-of-band launchd agent (`com.homaruscc.watchdog`) polls the backend's `/api/queue-status` every 60 seconds and reads `lastWaitPollAt`. If the event loop hasn't polled `/api/wait` for 15 minutes (configurable via `POLL_AGE_THRESHOLD`), the watchdog assumes the Claude Code session is dead — compacted-and-stuck, OOM'd, panicked, or terminated by the harness — and runs `bin/restart-claude` to spawn a fresh tmux session that re-invokes `/homaruscc`. Identity rehydrates from `soul.md` + `state.md` on the new instance's first wake. The bash event loop blocks at the OS level (long-poll, zero tokens during idle), so `lastWaitPollAt` is the authoritative liveness signal — no in-process heartbeat code, no Claude-side cron, no token cost while alive. The watchdog only acts when poll-age exceeds the threshold; healthy idle sessions stay quiet.

Three of HomarUScc's subtler bugs lived here and are worth knowing about: (1) BSD `pgrep -af` doesn't print full args, so the alive-check uses `ps -Ao args= -ww | grep -E ^claude`; (2) macOS TCC blocks launchd from executing scripts inside `~/Library/Mobile Documents/iCloud Drive`, so the watchdog script lives at `~/.homaruscc/bin/watchdog`, not in the project directory; (3) `restart-claude` needs `HOMARUSCC_PROJECT_DIR` propagated through the plist's `EnvironmentVariables` so it can `cd` to the right location after spawn.

Install:
```bash
cp bin/watchdog ~/.homaruscc/bin/
cp bin/com.homaruscc.watchdog.example.plist ~/Library/LaunchAgents/com.homaruscc.watchdog.plist
# Edit ~/Library/LaunchAgents/com.homaruscc.watchdog.plist to replace YOURUSER paths
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.homaruscc.watchdog.plist
```

These mechanisms 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"
          }
        ]
      }
    ]
  }
}
```

### 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:

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:** 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.

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 (text, photos, documents, reactions, edits) |
| `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/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)