convez.ai
Agente
gtapps

claude-code-hermit

gtapps/claude-code-hermit

Ver no GitHub
BomPluginScore · de 0 a 100

Turn Claude Code into an Always-on Personal AI assistant

Instalação

$npx convez-ai gtapps/claude-code-hermit

1 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

Estrelas
85
Forks
16
Acompanhando
1
Saúde
57%
Último commit
há 1 dia
Versão
hermitd--v1.4.35
Issues abertas
14
Contribuidores
6

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 /loop behind a filesystem-only precheck so it stops paying the model every tick, sweeping your checklist for zero tokens.
  • Routines wrap CronCreate jobs 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.
  • /watch wraps Monitor streams 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. /recall searches both.
  • Task snapshots persist native Tasks past session end, so the plan survives archives.
  • Profile-gated guardrails scope deny patterns + sandbox per 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-judge confirms the cited evidence actually exists in the session reports, so a proposal can't certify itself.
  • proposal-triage deduplicates against open proposals, cross-checks your MEMORY.md and OPERATOR.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-tmux for sessions, routines, heartbeat, and the learning loop without 24/7 autonomy. Run /claude-code-hermit:channel-setup first 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 (timezone defaults UTC), plus how much it does before asking (conservative / balanced / autonomous).
  • channels — channels.<discord|telegram|imessage> with per-channel enabled (default true) + allowed_users, and channels.primary for outbound pings.
  • permission_mode, AGENT_HOOK_PROFILE — how freely the unattended agent acts (default auto; hook profiles minimal / standard / strict).
  • push_notifications, model, quality_gate.tier — notifications (default true), model override, and cleanup spend (budget / balanced / quality).
  • heartbeat.every, active_hours, idle_behavior — idle cadence (default 2h), active window (default 08:00–23:00), and what it does when idle (wait / discover).
  • Routines & watches — managed by /hermit-routines and /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 frontmatter cost_usd.
  • Per-day rollup in cost-summary.md, regenerated on every cost-tracker tick.
  • Morning brief (when scheduled as a routine) reads cost-summary.md and 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


Credits

License

MIT

Ver o original no GitHub

Bom para

Relacionados