Notice: Claude Code 2.1.287 blocks plugins named claude*, so this project moved from claude-code-hermit to hermitd. How to migrate.

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.

Install the Claude Code plugin

With Claude Code 2.1.287+ and Bun 1.3+ installed:

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

Or use the bootstrap installer

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

curl -fsSL https://gtapps.github.io/hermitd/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:

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. 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