# FAQ

---

## Does this work on Windows?

Only via WSL2. Clone your project inside WSL2 (`/home/you/project`), not on the Windows filesystem. Docker Desktop with WSL2 backend works for always-on mode.

---

## How does bash sandboxing work?

The sandbox isolates bash tool calls at the OS level — `sandbox-exec` on macOS (built in, nothing to install) and `bwrap` + `socat` on Linux/WSL2. The `/hatch` wizard enables it by default at the "standard" profile, which protects credential paths (`~/.aws`, `~/.ssh`, `~/.gnupg`) while leaving network unrestricted so tools like `gh`, `npm`, and `pip` work on first run.

If your tooling uses a custom certificate authority (e.g. `gcloud` with a MITM proxy), you may need `"enableWeakerNetworkIsolation": true` in your `sandbox` settings block — see the [Claude Code sandbox docs](https://code.claude.com/docs/en/settings#sandbox-settings).

Native Windows is not supported by hermit in general; use WSL2.

---

## Can I use this with multiple projects?

Yes. Each project gets its own `.claude-code-hermit/` state directory. Install the plugin per-project (`--scope project`). For always-on, each project runs its own Docker container or tmux session.

---

## What Claude model does it use?

Whatever model your Claude Code instance uses by default. Override with `/hermit-settings model` (e.g., `sonnet`, `opus`). The `session-mgr` sub-agent always runs on Sonnet for cost efficiency.

---

## How much does it cost to run?

Depends on usage. Key cost drivers:

- **Heartbeat interval** — 5m with Opus is expensive; 2h is the default and usually sufficient.
- **Autocompact threshold** — default 50% keeps context lean.
- **Thinking tokens** — capped at 10K by default.

Set a per-session budget with `/hermit-settings budget`. A typical interactive session costs $1-5. Always-on agents with 2h heartbeat (the default) are significantly cheaper than shorter intervals.

---

## What happens if my auth token expires?

The hermit stops responding. Re-run `claude /login` inside the container to refresh credentials:

```bash
.claude-code-hermit/bin/hermit-docker login
```

Then restart: `.claude-code-hermit/bin/hermit-docker restart`

---

## Can I use an API key instead of a subscription?

Yes. Set `ANTHROPIC_API_KEY` in `.env` and choose "apikey" during `/docker-setup`. You'll pay per-token instead of using your subscription quota.

---

## Can I use this without Docker?

Yes. Docker is recommended for always-on mode but not required. Use `hermit-start`/`hermit-stop` for bare tmux. For interactive-only use, just run `/claude-code-hermit:session` — no tmux or Docker needed.

---

## How do I move my hermit to another machine?

Run `/claude-code-hermit:migrate` on the source machine before you leave. It audits Git hygiene, classifies which ignored files are portable, assesses hermit state (OPERATOR.md, config.json, HEARTBEAT.md), and produces a `migration-manifest.txt` with a verification checklist.

The short version: `git clone` handles your tracked files. The manifest handles the small set of portable ignored files. `hatch` handles destination setup (it preserves OPERATOR.md and config.json on re-init). `.claude/` is machine-local — reinstall plugins and re-grant permissions on the destination.

For always-on Docker setups, see [Moving to a new host](always-on.md#moving-to-a-new-host).

---

## How do I reset everything and start over?

```bash
rm -rf .claude-code-hermit/
# Remove the "claude-code-hermit: Session Discipline" block from CLAUDE.md
# Then re-run:
/claude-code-hermit:hatch
```

Your proposals, session history, and config will be gone. OPERATOR.md can be regenerated by the wizard.

---

## Can the hermit modify OPERATOR.md?

By design, no. OPERATOR.md is human-curated — the hermit reads it but never writes to it. Deny patterns mechanically block `Edit` and `Write` to OPERATOR.md. Tell the hermit "update OPERATOR.md with [change]" and it will ask you to make the edit.

---

## What's the difference between a "hermit" and a "hermit plugin"?

- **Hermit** = the running assistant instance in your project — what you get after running `/hatch`.
- **claude-code-hermit** = the base plugin package that provides session management, proposals, heartbeat, and the learning loop.
- **Hermit plugin** = a third-party extension that adds domain-specific agents, skills, and hooks (e.g., `claude-code-dev-hermit` adds repo mapping, implementation, and code review agents). Layers on top of the core.

---

## What's the difference between heartbeat and monitor?

**Heartbeat** is the built-in periodic health check — runs every 2h by default, evaluates the `HEARTBEAT.md` checklist, and alerts you only when something needs attention. It's always-on infrastructure.

**Watch** (`/watch`) is a session-scoped background watcher you set up for specific concerns (e.g., "watch for CI failures every 5 minutes"). Watches are task-specific and stop when the session closes.

See [Skills Reference](skills.md) for the heartbeat/watch comparison table.

---

## How does memory work?

Hermit uses several layers of memory:

- **SHELL.md** — working memory for the current session (task, progress, blockers, findings)
- **Session reports** (`S-NNN-REPORT.md`) — archived summaries of past sessions
- **OPERATOR.md** — your persistent instructions, read at every session start
- **Claude Code memory** — cross-session learning that persists between conversations (the hermit reflects on its experience and saves what it learns)
- **Proposals** (`PROP-NNN.md`) — structured improvement recommendations with evidence

The hermit reflects on its own memory — not by scanning old reports. It notices patterns from what it remembers across sessions.

---

## What happens when my hermit is idle?

Depends on the `idle_behavior` setting in `config.json`:

- **`"wait"`** — checks for incoming tasks and channel messages only. Passive.
- **`"discover"`** (default) — also picks up accepted proposals from `NEXT-TASK.md`, runs reflection, picks idle tasks from `IDLE-TASKS.md`, and aligns priorities with OPERATOR.md. Active.

Both modes run the heartbeat if enabled. Change with `/hermit-settings idle`.

---

## What are scheduled checks?

Automatic invocations of skills on a cadence — either from installed plugins (e.g., `claude-md-management:claude-md-improver`) or from your own hermit. They run during idle reflection at configurable intervals and must conform to the [scheduled-check contract](../skills/reflect-scheduled-checks/SKILL.md) (idempotent, returns findings or nothing, no self-scheduling). Configure with `/hermit-settings scheduled-checks`. See [Config Reference](config-reference.md#scheduled_checks) for the schema.

---

## When should I run `/session-start`? *(interactive mode)*

`/session-start` front-loads context: it reads OPERATOR.md, scans recent `compiled/` artifacts, loads SHELL.md state, and registers config-declared watches. It's worth running when:

- Starting a focused work block on a project with active hermit state (recent compiled/ outputs, updated OPERATOR.md, open proposals).
- Returning after a gap — OPERATOR.md context fades across conversations; session-start reloads it explicitly.
- Working on a fresh hatch — baseline audits only fire on the first session-start after hatch.

Skip it for quick one-off tasks, sessions under ~5 minutes, or any time the upfront context load isn't justified by the length of the work.

**Always-on / Docker mode:** `hermit-start.py` handles initialization automatically at container start. You don't run `/session-start` manually in always-on mode.
