claude-code-hermit
gtapps/claude-code-hermit
Turn Claude Code into an Always-on Personal AI assistant
Instalação
npx convez-ai gtapps/claude-code-hermit1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
claude-code-hermit
Claude Code plugin that turns it into a 24/7 AI assistant. Self-learning, Pro-Active, Cost-aware, Observable, One Claude subscription, multiple hermits.
A hermit is a Claude Code session that doesn't end: It wires the native primitives (/loop, CronCreate, Channels, Monitor, Auto-memory, native Tasks, etc) into an always-on agent that keeps its own state, routines, and memory across restarts, and reaches you on Discord, Telegram, or the Claude app when something needs a decision. It runs on your existing subscription, and one subscription runs several hermits.
# Install
claude plugin marketplace add gtapps/claude-code-hermit
claude plugin install claude-code-hermit@claude-code-hermit --scope local
# Boot Claude Code and run the setup wizard
/claude-code-hermit:hatch
# Go always-on
/claude-code-hermit:docker-setup
One Claude subscription, multiple hermits — each with its own memory, cost history, and routines.
What you get
Just Claude Code everything is yours to shape: channels (Discord/Telegram), MCP servers, routines, watches, the heartbeat checklist. Hermit adds persistence, a learning loop, and a quick setup to wire everything.
- Heartbeat gates
/loopbehind a filesystem-only precheck so it stops paying the model every tick, sweeping your checklist for zero tokens. - Routines wrap
CronCreatejobs that expire in 7 days and fire in the machine's timezone: they self-rearm daily, run on your wall clock, and are managed by/hermit-routines. /watchwrapsMonitorstreams that die with the session: it auto-starts from config (or plain language) and routes findings to your notifications, silent when quiet.- Channels let you DM a session; the hermit agent acts on it ("accept PROP-014", "status") and pings you first when something needs a yes/no.
- Auto-memory + knowledge Two layers. Claude Code's native auto-memory holds operator facts and preferences (how to work with you); on top, the hermit adds a
raw/→compiled/knowledge base — domain outputs and living topic pages updated in place — re-injected as a catalog within a context budget at session start./recallsearches both. - Task snapshots persist native
Taskspast session end, so the plan survives archives. - Profile-gated guardrails scope
deny patterns + sandboxper profile, locking the unattended agent down harder than the one you're watching. - One runtime. Everything is TypeScript running on Bun — zero npm packages, zero Python, across the whole fleet. Install Bun, done.
Sessions self-manage. Daemons auto-archive at 12h idle and at midnight when you're away, so evidence reaches the learning loop without a manual close. An external watchdog restarts dead sessions, nudges wedged ones, re-arms missed schedules, and clears stale context after a midnight close — recovery never depends on the session being conscious.
It reaches you first. Notifications default to a native push (headless-friendly), or a Discord/Telegram DM you can reply to if you've paired a channel.
Cost scales with events, not time. Nothing wakes the model until something happens, so an idle hermit is effectively free.
Learning Loop
A hermit watches what keeps going wrong across sessions, proposes a fix, and asks you yes or no. It won't propose the same thing twice.
At natural pauses — session end, idle ticks, scheduled cadence — it reflects. Most reflections never reach the model: a precheck script gates whether any phase (compute, resolution check, cost spike, digest, newborn) is actually due. When one is, two subagents vet the candidate before it reaches you:
reflection-judgeconfirms the cited evidence actually exists in the session reports, so a proposal can't certify itself.proposal-triagededuplicates against open proposals, cross-checks yourMEMORY.mdandOPERATOR.md, and applies a three-condition bar.
Survivors land as a proposal you can act on from anywhere — including a DM:
/claude-code-hermit:proposal-list # see what it found
/claude-code-hermit:proposal-act accept PROP-003 # or just reply "accept PROP-003"
What it proposes: improvements, routines, new capabilities (skills, agents, heartbeat checks), guardrails (OPERATOR.md guidance you confirm), and bugs. When it catches itself repeating the same multi-step procedure across sessions, it drafts the skill and asks before installing. Accepted proposals can carry a measurable success signal and auto-resolve when met. You're the acceptance gate for every change. Raw session journals distill into compiled artifacts that reload next session — the raw/compiled pattern Karpathy described for his wiki-LLM.
Observable
On-demand skills — pullable from the Claude app, your terminal, or a DM:
/recall— full-text search over past sessions, compiled knowledge, and proposals ("what did I decide about X?")/hermit-brain— open loops, fragile zones, and key learnings from recent sessions/hermit-evolution— cost trend and behavior drift over weeks/hermit-health— alerts, routines, channels, heartbeat state/hermit-doctor— fifteen-check install diagnostic, from hook registration to heartbeat liveness/cost-reflect— structural cost audit: which token types and trigger sources drive spend/pulse— what it's doing right now/brief— summary of recent work
Quick Start
Prerequisites: Claude Code v2.1.172+, a Claude plan (Pro, Max, Teams, or Enterprise), and Bun 1.3+. Linux, macOS, and Windows via WSL2 — see FAQ.
1. Install
cd /path/to/your/project # or any folder — even an empty one
claude plugin marketplace add gtapps/claude-code-hermit
claude plugin install claude-code-hermit@claude-code-hermit --scope local
2. Initialize
claude /claude-code-hermit:hatch
The wizard sets up your agent's identity, scans your folder, generates OPERATOR.md, and offers Quick (4 questions) or Advanced (full wizard).
Just trying it? After
hatch, run.claude-code-hermit/bin/hermit-start --no-tmuxfor sessions, routines, heartbeat, and the learning loop without 24/7 autonomy. Run/claude-code-hermit:channel-setupfirst if you want Discord or Telegram.
3. Go Always-on
/claude-code-hermit:docker-setup
Generates the Docker scaffolding, builds the image, starts the container, and walks through auth and channel pairing. The container ships with the hardening baseline (cap_drop: ALL, no-new-privileges, pids_limit). Want stronger isolation? Run /docker-security for opt-in LAN containment + DNS allowlist + resource bounds.
See Always-On Setup for the full guide. Want always-on without Docker? See Always-On Operations for bare tmux.
Upgrading
claude plugin update claude-code-hermit@claude-code-hermit --scope local
/claude-code-hermit:hermit-evolve
Configure it
Set up interactively by /hatch, then tunable live with /hermit-settings (or just by asking the hermit). Principal config.json keys (default in bold, or noted inline) — full schema in the Config Reference:
agent_name,timezone,escalation— identity (timezonedefaultsUTC), plus how much it does before asking (conservative/balanced/autonomous).channels—channels.<discord|telegram|imessage>with per-channelenabled(defaulttrue) +allowed_users, andchannels.primaryfor outbound pings.permission_mode,AGENT_HOOK_PROFILE— how freely the unattended agent acts (defaultauto; hook profilesminimal/standard/strict).push_notifications,model,quality_gate.tier— notifications (defaulttrue), model override, and cleanup spend (budget/balanced/quality).heartbeat.every,active_hours,idle_behavior— idle cadence (default2h), active window (default08:00–23:00), and what it does when idle (wait/discover).- Routines & watches — managed by
/hermit-routinesand/watch; both default to none.
Cost & local-first
You run on your own Claude subscription — no daily caps, no per-runtime-hour billing — and every token is logged where you can see it.
- Per-call token usage logged to
.claude/cost-log.jsonl(model, input/output/cache split, USD estimate, and what triggered the turn — heartbeat, routine, or interactive). - Per-session running total in
.status.json; carried into archived session reports as frontmattercost_usd. - Per-day rollup in
cost-summary.md, regenerated on every cost-tracker tick. - Morning brief (when scheduled as a routine) reads
cost-summary.mdand includes yesterday's spend.
Because idle always-on cost is effectively zero, one Claude subscription can run several hermits at once.
Pre-built Hermits
Domain plugins you stack on top of any hermit you've hatched.
dev-hermit— For software builders. Safety layer for code-writing agents: push guard, branch discipline, gated PRs.homeassistant-hermit— For Home Assistant users. HA skills, safety hook, automation builder, zero-dependency CLI.fitness-hermit— Fitness focused. Strava MCP wiring, activity deep-dives, weekly-load routines.
Many operators run several hermits in parallel — one per domain. Each one is a /hatch away. They share nothing but the protocol; their memory, cost history, and routines are independent, and a single Claude subscription covers them all. See Creating Your Own Hermit.
Community
Join the claude-code-hermit Discord community for install help, always-on ops, plugin authoring, bug triage, and proposal/design discussion. Confirmed bugs and roadmap decisions should still move back to GitHub so they remain searchable and reviewable.
Documentation
- Always-On Operations
- Always-On Setup
- Architecture
- Config Reference
- Community Discord
- Creating Your Own Hermit
- Docker Security
- FAQ
- Getting Started
- Plugin Hermit Storage
- Recommended Plugins
- Security
- Skills Reference
- Testing
- Troubleshooting
- Upgrading
Credits
- OpenClaw — Inspiration for autonomous agent ergonomics
- Everything Claude Code — Hook patterns and lifecycle architecture
- Andrej Karpathy — Inspiration for the raw/compiled knowledge system