# open source · MIT · a plugin for the official Claude Code CLI

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.

               .-""""""-.
            .-'   .--.   '-.
           /    .'    '.    \
          ;    /  .--.  \    ;
          |   |  ( () )  |   |      o     o
          ;    \  '--'  /    ;       \   /
           \    '.____.'    /     ___)_(___
            '-._        _.-'-----'  (__)   \
                '------'   /_/  /_/  /_/ \__/

## set up

Choose one. Run it from the folder where you want your agent. Uses your Claude subscription.

A · you already run Claude Code

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

Claude Code 2.1.287+, Bun 1.3+

B · fresh machine

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

Prepares Claude Code, Bun and tmux, installs the plugin, starts setup.

hermitd start            # keep it running in tmux
/hermitd:docker-setup    # or in Docker

## how it runs

It's Claude Code.

hermitd is a plugin for the official Claude Code CLI, which runs as Anthropic ships it.

Grows with Claude Code.

New Claude models & features & fixes work as soon as Claude Code supports them.

## what the plugin adds

Give it ongoing responsibilities. Between requests, it checks them, carries progress across sessions, and reaches you when something needs attention.

proactive work

Heartbeats check its responsibilities, routines run scheduled work, and watches surface changes.

token efficiency

Heartbeat checks and routine prechecks run outside the model. Quiet checks and skipped routines use no model tokens. Give a routine its own model to spend less.

continuity

Progress survives compaction and restarts, and a watchdog recovers failed sessions. /recallsearches past sessions, knowledge and conversations.

work through chat

Assign work and get results in your chat through Claude Code channels, with threaded progress and a separate reply when it needs a decision. In group channels it listens quietly and wakes when someone you allow @mentions it.

control and visibility

Track progress, proposals and usage on the dashboard. Pause is enforced at the tool boundary; optional caps alert you or pause work.

your network

Local databases, SSH, LAN devices and Home Assistant are reachable because the agent runs where they are.

## how a wake works

Quiet checks use no model tokens.

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

work produces evidence
   │
   ▼
reflect when due  ──▶  verify and deduplicate
                               │
                ┌──────────────┴──────────────┐
                ▼                             ▼
        remember a lesson              propose a change
                                              │
                                  you approve? ── no ──▶ no change
                                              │ yes
                                              ▼
                                  implement, then verify the result

## learning loop

Learning from experience, with your approval.

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.

Proposals are resolved when verification passes or later evidence shows the problem is gone.

## ask it from your chat

“Start X in ~/code/api on Opus at high effort, in its own worktree.”
Sessions in any project, on your model and effort.
“Tell me when my session in ~/code/web finishes.”
It 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.”
It checks whether a fix held up over time.
“When I ask for a status update, include blockers.”
It remembers instructions for that channel.
“What else could you be doing for me?”
It proposes new capabilities from your work and its tools.

## which one fits

Claude Projects, Claude Tag, or hermitd

They work alongside each other. Pick by where your work lives.

Claude Projects

Your repos are on github.com and you like steering from Claude's apps. Cloud threads, or a thread on your computer through Remote Control. Pro and Max.

Claude Tag

Your team works in Slack. A shared @Claude with a sandbox per thread, nothing to host. Team and Enterprise.

Use hermitd when you want to run the agent yourself

on your machines and network, woken by your own events
in the chat you already use, through Claude Code channels: Discord, Telegram, iMessage, or one you build
hand it new work from your chat, like “start X on Opus at high effort”, and continue it in your terminal or the Claude app
ask it to keep an eye on your other Claude Code sessions on that machine, even ones you started yourself, and hear in chat when they finish
with your rules enforced: hooks, pause, budget caps, your own MCP servers, skills and plugins

Not for you if you don't want to keep a machine running. If nothing you need lives on your network, a hosted Claude product is simpler.

Anthropic product details as documented on 2026-10-06.

Community

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

Join the Discord GitHub