claude-code-hermit

Your own local Claude Tag.

Run an always-on Claude Code agent on your machine or server, for you or your team. Use it from your terminal or the Claude app via Remote Control, or connect Discord, Telegram, iMessage, or a custom Claude Code channel.

Give it ongoing responsibilities: maintain research, monitor systems, run routines, and follow up on unfinished work. Between requests, it checks those responsibilities, carries progress across sessions, and reaches you when something needs attention.

Run it on your Claude subscription and extend it with your own MCP servers, skills, and plugins.

Set up

Choose one installation method below. Run it from the folder where you want your agent, empty or existing. Uses your Claude subscription on Linux, macOS, or Windows via WSL2. See prerequisites.

With Claude Code 2.1.271+ and Bun 1.3+ installed:

claude plugin marketplace add gtapps/claude-code-hermit
claude plugin install claude-code-hermit@claude-code-hermit --scope local
claude "/claude-code-hermit:hatch"

Prepares Claude Code, Bun, and tmux, installs the plugin, and launches setup:

curl -fsSL https://gtapps.github.io/claude-code-hermit/install.sh | bash

Both options install Hermit for this folder. Hatch guides you through the agent’s purpose and preferences, then shows how to start it. Choose Quick for defaults you can adjust later.

Keep it running

After setup, follow the printed next steps to start your agent.

On your machine

Run in a persistent tmux session:

.claude-code-hermit/bin/hermit-start

Requires tmux. The watchdog recovers failed sessions while your machine stays on. Claude Code's /sandbox is recommended for unattended use. To connect a chat, run /claude-code-hermit:channel-setup as directed by the setup handoff.

Host setup and operations

In Docker

Run the guided setup in Claude Code:

/claude-code-hermit:docker-setup

Builds and starts the container, then walks you through authentication and channel pairing. Requires Docker Compose v2.

Docker setup

Customize the container. Ask the agent to add tools, packages, or services to its Docker setup. For example: “Add ffmpeg to the container.”

Optional Docker security controls cover local-network access, DNS policy, resource limits, and plugin installation auditing.

What the plugin adds

• Continuity. Persistent working state and archived session handoffs carry progress across compaction and restarts. An external watchdog recovers failed sessions, while context management keeps long-running sessions manageable.

• Proactive work. Heartbeats regularly check the responsibilities you give the agent. Routines run scheduled work, and watches surface changes. Together, they let the agent follow up without waiting for another request.

• Work through chat. Assign work and receive results in your connected chat. Longer assignments get threaded progress updates, with a separate reply when the agent needs a decision. Assignments can also carry a persistent task record with requester, due date, result confirmation, and a dashboard view by person.

• Token efficiency. With Claude Code’s Monitor, heartbeat checks and optional routine prechecks run outside the model. Quiet checks and skipped routines use no model tokens; eligible routines due together can share a wake.

• Lasting knowledge. Turn source material in raw/ into maintained knowledge in compiled/, alongside Claude Code's auto memory. /recall searches past sessions, knowledge, proposals, and captured channel conversations.

• Learning from experience. The agent reviews evidence from its work and operation, saves useful lessons, and verifies proposed behavior changes before bringing them to you for approval.

• Control and visibility. Track progress, proposals, and usage through the dashboard. Pause is enforced at the tool boundary, and optional usage caps can alert you or pause further work.

Part of your project channel. With passive mode, the agent saves incoming group messages to look back on later, and wakes when someone you allow @mentions it. It also remembers instructions for that channel. For example: “When I ask for a status update, include blockers.”

Configure

Tune from a terminal with /hermit-settings, or change permitted settings from a trusted Discord or Telegram chat. Every write is validated and recorded in a redacted audit ledger; /hermit-settings history [setting] shows what changed. Some of the settings available:

Key	Default / options (default bold)
agent_name	your assistant's name
operator_profile	primary-chat audience: technical / non-technical
timezone	detected during setup; fallback UTC
language	detected during setup; fallback en
escalation	how much it does before asking: conservative / balanced / autonomous
model	session model: sonnet
permission_mode	how freely the unattended agent acts: auto
AGENT_HOOK_PROFILE	guardrail profile: minimal / standard (interactive) / strict (always-on)
channels	Discord / Telegram / iMessage / third-party channel plugins (+ allowed_users)
channels.primary	which channel gets outbound pings
channels.<name>.maintainer_channel_id	optional separate chat for technical alerts, diagnostics, and usage details
push_notifications	native/mobile push on alerts: true
remote	remote control; false also requires approval for cross-machine peer messages; true
ask_gate	route unattended questions to a paired channel: true
budget	optional daily / weekly / monthly caps; alert or binding pause action
artifacts	dashboard / proposals / weekly review: all enabled
heartbeat.enabled	timed idle sweeps: true
heartbeat.every	idle sweep cadence: 30m
heartbeat.active_hours	active window: 08:00–23:00
routines	persistent routines managed via /hermit-routines
monitors	persistent background watches managed via /watch
scheduled_checks	session-triggered skills at task completion
reflection.graduation_min_sessions	proposal recurrence bar: 1
quality_gate.tier	post-change cleanup spend: budget / balanced / quality
knowledge.compiled_budget_chars	fresh/resumed startup catalog budget: 2500
knowledge.raw_retention_days	raw/ retention: 14
knowledge.working_set_warn	warn above N compiled docs: 20
auto_session	auto-start session on boot: true
boot_skill / shutdown_skill	custom boot / teardown skill
context_hygiene.clear	safe-boundary context clear: enabled, quiet 1h, max age 24h, minimum 20,000 tokens
context_hygiene.compact	compact long-running active context: enabled, 100000 compactible tokens / 4h cooldown
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE	auto-compact at % of context: 65
MAX_THINKING_TOKENS	thinking-token cap per turn: 10000
watchdog.scheduler_enabled	OS scheduler for the watchdog tick: true on tmux always-on (auto-installed at boot); false or hermit-watchdog uninstall opts out
watchdog.enabled	recovery/restart tier: false until first scheduler registration (or /docker-setup); hygiene still runs

Full schema in the Config Reference

Observe

Artifacts. The agent uses Claude Code Artifacts to provide an interactive dashboard and custom pages generated on demand that you can view, interact with, and share. Ask it to build your own personalized agent dashboard.

Ask for an update from your terminal or connected chat:

Command	What it gives you
/brief	Current status and a summary of recent work.
/recall	Search past sessions, knowledge, proposals, and captured conversations.
/hermit-health	Alerts, routines, channels, blockers, and recent learnings.
/hermit-doctor	Diagnostics for the installation, runtime, scheduling, credentials, and permissions.
/hermit-evolution	Cost trends, proposal activity, routines, and what the agent has produced over time.
/cost-reflect	A breakdown of usage by token type, session, and what triggered the work.
/hermit-dashboard-design	A dashboard designed around what your agent actually tracks.

Learning loop

The agent reviews evidence from its work and operation. Durable lessons go to memory; non-trivial ideas that would change its behavior are verified, deduplicated, and brought to you for approval.

Work produces evidence
          │
          ▼
Reflect when due
          │
          ▼
Verify and deduplicate
          │
     ┌────┴────┐
     ▼         ▼
Remember    Propose
a lesson    a change
                 │
                 ▼
           You approve?
              │     │
             no    yes
              │     │
         No change  Implement
                        │
                        ▼
                  Verify result
                        │
                        ▼
                  Future evidence

Reflection runs at eligible task or session pauses, daily, and after routines configured to reflect. Approved changes can start now, become a task, or be left for manual implementation. Proposals are resolved when verification passes or later evidence shows the problem is gone.

Follow-up verification. The agent checks whether a fix or prediction held up over time. For example: “/later check tomorrow whether those errors have returned.”

New ways to help. The agent proposes new capabilities based on your work and the tools available to it. For example: “What else could you be doing for me?”

Cost

Quiet heartbeat checks, skipped routines, and passive chat capture use no model tokens. Work, evaluations, and replies consume usage; context management keeps conversation history bounded.