hermitd

<a href="https://hermitd.dev"><img src="https://img.shields.io/badge/website-hermitd.dev-black.svg" alt="Website" /></a> <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a> <a href="https://code.claude.com/docs/en/plugins"><img src="https://img.shields.io/badge/Claude%20Code-plugin-orange.svg" alt="Claude Code Plugin" /></a> <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.4.11-green.svg" alt="Version 1.4.11" /></a> <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/gtapps/hermitd/_gh_traffic_stats/.github/badges/clones.json" alt="Downloads" /> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome" /> <a href="https://discord.gg/54sJqAxhUh"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Join" /></a>

Like Claude Tag, but local.

Run an always-on Claude Code agent on your own machine, for you or your team. Start sessions from your chat in any project it can reach, on the model and effort you choose, and steer them through the agent or take over in the Claude app or CLI.

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.

It's Claude Code. hermitd is a plugin for the official Claude Code CLI, which runs as Anthropic ships it. New Claude models, features, and fixes work as soon as Claude Code supports them.

Coming from claude-code-hermit? See how to migrate.

<img src="assets/cover.png" alt="Always-on Claude Code agent" />

<a id="quick-start"></a>

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.292+ and Bun 1.4+ installed:

claude plugin install hermitd --marketplace gtapps/hermitd --scope local
claude "/hermitd:hatch"

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

curl -fsSL https://gtapps.github.io/hermitd/install.sh | bash

Both options set up the agent in 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:

hermitd 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 /hermitd:channel-setup as directed by the setup handoff.

Host setup and operations

In Docker

Run the guided setup in Claude Code:

/hermitd: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.

<a id="configure-it"></a>

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: dashboard and proposals 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 hermitd-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.

Ask it from your chat

Ask	What it does
“Start X in ~/code/api on Opus at high effort, in its own worktree.”	Starts a session in any project, on your model and effort.
“Tell me when my session in ~/code/web finishes.”	Watches your other Claude Code sessions.
!pause · !snooze 2h · !model sonnet · !effort high	Claude Code controls, straight from chat.
“/later check tomorrow whether those errors have returned.”	Checks whether a fix held up over time.
“When I ask for a status update, include blockers.”	Remembers instructions for that channel.
“What else could you be doing for me?”	Proposes new capabilities from your work and its tools.

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.

event: a file, a log line, a webhook, a schedule
   │
   ▼
precheck (plain script, no model tokens)
   │
   ├── nothing changed ──▶ back to sleep
   │
   ▼ something to do
Claude Code turn on your machine
   │
   ├── needs a decision ──▶ asks you in chat
   │
   ▼
result in your chat  +  usage recorded

• See what drives usage. Token usage is recorded per call, including the model, input/output/cache split, and whether work came from a routine, heartbeat, channel, or another source. Session and daily totals feed the dashboard, weekly review, and /cost-reflect.
• Set limits. Optional daily, weekly, and monthly caps can alert you or enforce a pause until the exceeded budget window resets. Under Claude subscription billing, dollar figures are usage estimates rather than additional per-token charges.
• Choose where to spend. Set the session model and optionally assign a different model to individual routines. Routine models run in isolated subagents, so use them for work that can return a concise result.

See budgets and routine scheduling for configuration and scheduler fallback behavior.

Remote work

Reach the running agent through your connected channels or Claude Code Remote Control. You can also start separate sessions for additional work:

• Background sessions with follow-up. Through /spawn-session, the agent launches a local Claude Code helper in the project, or in another folder with --cwd, and relays its status when it becomes idle. Claude Code isolates the helper's edits in a Git worktree unless the project sets worktree.bgIsolation to none; pass --worktree to give it one from the start. Set the helper’s model and effort with options such as --model sonnet --effort high.
• Local Remote Control gate. Through /rc-gate, the agent manages a Remote Control server on your machine or server. While the gate is open, you can spawn new Claude Code sessions from the Claude app, using your local files and tools. Each session gets its own Git worktree, while the agent keeps running.

Both session-spawning paths require a Git workspace. Remote Control requires a Claude sign-in through /login on the machine running the agent.

Watch other sessions. Through Claude Code cross-session messaging, ask the agent to watch a local Claude Code session, including one you started interactively, and notify you when it next becomes idle.

Claude Code controls from chat. Use !model sonnet, !effort high, !advisor opus, !compact, !clear, !doctor (alias !checkup), and !permission-mode auto directly from your connected chat. Control the agent’s work with !pause, !resume, and !snooze 2h. Use /when-done-switch-to --model sonnet to switch automatically at the end of the current turn.

Extensions

Optional plugins that add domain tools and workflows to your agent.

• dev-hermit: Branch discipline, push guards, and gated PR workflows.
• homeassistant-hermit: Home Assistant tools, automation workflows, and safety checks.
• fitness-hermit: Strava integration, activity analysis, and training routines.
• hermitd-feed: Source curation, recurring briefs, and weekly synthesis.
• hermitd-laravel-forge: Laravel Forge deployments, logs, and server management.
• hermitd-scribe: GitHub issues and comments from proposals through a dedicated bot identity.

You can run separate agents for different responsibilities, each with its own working state, knowledge, and routines. See Creating Your Own Hermit.

External orchestration. Other agents and tools can check the agent’s status, health, and recent work through its MCP interface, and request a wake when needed.

Maintenance

Sign-in renewal from chat. When your agent’s Claude sign-in needs renewing, use /relogin from your connected chat. Open the link in your browser, sign in, and send the code back in chat.

Scheduled backups. Optional backups preserve the agent’s knowledge, session reports, settings, and Claude Code memory in Git, with an optional private remote copy. Backups run without model tokens.

Upgrading from claude-code-hermit

Claude Code 2.1.287 blocks plugins named claude*, so this project moved from claude-code-hermit to hermitd. Before migrating, update every registered agent in the Claude config directory to core 1.4.8 and stop all of them, including Docker agents. Run once on the host:

curl -fsSL https://gtapps.github.io/hermitd/migrate.sh | bash

The migration records every agent before replacing the marketplace, moves project state to .hermit/, refreshes launchers and permissions, and rebuilds Docker images. Customized managed files receive .bak copies. If interrupted, rerun the same command to resume. Disabled plugin installs are reported and are not reinstalled.

Follow the printed start command for each agent, then run /hermitd:hermit-evolve. Pending later commands that still use old paths are reported for re-arming.

Upgrading

Run hermitd update from the project folder, or hermitd update <name> from anywhere. Docker updates refresh the host core first, then the container.

hermitd list shows registered and discovered agents on this host, including stopped and missing projects. hermitd status [name] shows transport, execution and its age, open and waiting tasks, and the first runnable task. Both support --json. Listing never removes entries; hermitd prune removes missing projects.

Use hermitd start|stop|restart|attach [name] for lifecycle commands, hermitd pause [name] on|off|snooze <duration>|status, hermitd watchdog [name] run|install|uninstall, or hermitd run [name] <script> [args] for maintenance. Names match the project folder or agent name; with no name, the nearest project above the current folder is used.

See the Upgrade guide for details.

<a id="tips--tuning"></a>

Guides

• Configure: the Config Reference covers the full schema and tuning details.
• Use: Getting Started and the Owner's Guide cover everyday work, decisions, and controls.
• Automate: Routine Authoring covers schedules and prechecks. Channel configuration includes third-party channel plugins.
• Observe: Artifacts explains the dashboard, proposals, and weekly reviews.
• Maintain: Upgrading, Backup, Troubleshooting, and Uninstalling.
• Understand: Architecture, Security, and FAQ.

All documentation

Community

Join the Discord community for setup help and discussion. See CONTRIBUTING.md for reporting bugs or contributing.

Credits

Andrej Karpathy inspired the raw/ → compiled/ knowledge system.

License

MIT

Independent project, not affiliated with Anthropic.