claude-hermes

Claude Hermes

Fork of moazbuilds/claudeclaw. Rebuilt around a SQLite state engine, an envelope-based router, an auto-promoting skills pipeline, and a human-triggered, verify-gated self-evolution loop. The Telegram and Discord bridges are the only interfaces — no web dashboard.

🇨🇳 中文 README

Claude Hermes turns your Claude Code into a personal assistant that never sleeps. It runs as a background daemon, executes tasks on a schedule, responds on Telegram and Discord, transcribes voice commands, and learns new skills from your usage.

Why Hermes (vs. the Claw fork it grew out of)

	Hermes	Claw
Storage	bun:sqlite + FTS5, single state.db	flat JSON files
Sessions	scope-based router (dm, per-channel-user, per-thread, shared, workspace)	global + per-thread overrides
Skills	candidate → active with a rollback window (shadow on regression)	manual install only
Self-evolution	human-triggered, verify-gated: auto-commits on green, reverts on red	none
Model routing	agentic mode picks Opus for planning / Sonnet for implementation per message	single-model
Web dashboard	removed — talk to the daemon via Telegram/Discord/CLI	yes
Verify pipeline	typecheck + lint + unit + smoke + integration, all five must be green	manual

Install

Easiest path — install from the Claude Code plugin marketplace. Inside any Claude Code session, run:

/plugin marketplace add sypsyp97/claude-hermes
/plugin install claude-hermes@claude-hermes
/claude-hermes:start

The setup wizard walks you through model, heartbeat, Telegram, Discord, and security; the daemon then runs in the background. Bun is the only runtime dependency — start will offer to install it for you if it's missing.

If you previously ran the upstream Claw daemon in this workspace, the first start migrates .claude/claudeclaw/ → .claude/hermes/ once and then leaves the legacy directory untouched as a safety net.

Develop from source

git clone https://github.com/sypsyp97/claude-hermes.git
cd claude-hermes
bun install
bun run verify

Then point Claude Code at the working tree:

/plugin marketplace add /absolute/path/to/claude-hermes
/plugin install claude-hermes@claude-hermes

Features

Automation

• Heartbeat: periodic check-ins with configurable intervals, quiet hours, and editable prompts. The heartbeat prompt can be an inline string or a file path; edits take effect without restarting the daemon.
• Cron jobs: timezone-aware schedules for repeating or one-time tasks. Job files hot-reload every 30s — no daemon restart needed.
• Scaffolder (/claude-hermes:new): new job <name>, new skill <name>, or new prompt <name> writes a template file with sensible frontmatter so you don't hand-craft YAML. Runs as a CLI too: bun run src/index.ts new job my-job --schedule "0 9 * * *".
• Self-evolution (bun run scripts/evolve.ts): opt-in local tool that takes a task body (CLI arg or stdin or Discord/Telegram message), asks your local Claude to implement it, runs the full verify pipeline, and commits on green / git restores on red. Small-step, verify-gated, journal-everything discipline. Human-triggered, not a cron — the verify gate is the safety net.

Communication

• Telegram: text, image, and voice (whisper.cpp or any OpenAI-compatible STT endpoint).
• Discord: DMs, server mentions/replies, slash commands (/start, /reset), voice messages, image attachments, and reaction feedback.
• Time-aware messages: prefixes help the agent reason about delays and daily patterns.
• Real-time status sinks: task progress is streamed back to whoever triggered it — Discord reactions, Telegram typing indicators, or terminal lines — so long-running evolve runs or heartbeat turns aren't silent.

Discord channel policies

The daemon auto-routes channels by name:

• listen-* / ask-* — free-response mode; the bot replies without needing an @mention.
• deliver-* — delivery-only, no interactive replies (use for broadcasts).
• Server channels — default: per-channel-user memory, reply on mention/reply only.
• DMs — default: per-user memory, reply to every message.
• Manual override: per-channel channel_policies rows in SQLite win over the name-based default.

Multi-session threads (Discord)

• Independent thread sessions: each Discord thread gets its own Claude CLI session.
• Parallel processing: messages in different threads don't block each other.
• Auto-create: the first message in a new thread bootstraps a fresh session.
• Cleanup: thread sessions are dropped when the thread is deleted or archived.
• Backwards-compatible: DMs and main-channel messages keep using the global session.

See docs/MULTI_SESSION.md for the routing details.