MCP server that gives Claude Code a body — messaging, memory, identity, timers, browser automation, and dreams
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.
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.
git clone https://github.com/kcdjmaxx/HomarUScc.git
cd HomarUScc
npm install
npm run build
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:
cp .env.example ~/.homaruscc/.env
# Edit ~/.homaruscc/.env with your actual tokens
HomarUScc loads identity files from ~/.homaruscc/identity/ to shape your assistant's personality, what it knows about you, and its evolving self-knowledge.
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.
At 3am each night, the agent runs a three-phase dream cycle inspired by neuroscience research on sleep functions:
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.
Register HomarUScc as an MCP server in .claude/settings.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.
| 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) |
| 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 |
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.
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:
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:
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.
cd dashboard
npm install
npm run dev # Dev server on :3121, proxies API to :3120
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 |
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 homaruscc/bin/event-loop
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:
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.
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.
Both are wired into the PreCompact Claude Code hook that calls /api/pre-compact. Add this to your project's .claude/settings.local.json:
{
"hooks": {
"PreCompact": [
{
"hooks": [
{
"type": "command",
"command": "curl -s http://127.0.0.1:3120/api/pre-compact"
}
]
}
]
}
}
HomarUScc hooks into Claude Code's compaction lifecycle to preserve context. Add the following to your project's .claude/settings.local.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"
}
]
}
]
}
}
These hooks are optional but strongly recommended for long sessions. Without them, the agent loses task context across compaction boundaries.
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:
POST /api/agents (returns 429 if at max capacity)agent_completed event flows through the event systemMax 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.
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.
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.
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 |
# 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.
MIT - see LICENSE
FAQs
MCP server that gives Claude Code a body — messaging, memory, identity, timers, browser automation, and dreams
We found that homaruscc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.