claude-code-hermit CLAUDE.md

claude-code-hermit (monorepo)

This repo is a multi-plugin Claude Code marketplace. Seven plugins ship from plugins/<slug>/: claude-code-hermit (core), claude-code-dev-hermit, claude-code-homeassistant-hermit, claude-code-fitness-hermit, hermit-scribe, laravel-forge-hermit, feed-hermit. Each plugin has its own CLAUDE.md, CHANGELOG.md, and tests/ — read those for plugin-specific context.

The top-level .claude-plugin/marketplace.json is the only marketplace. The README at the repo root is the canonical hermit pitch.

Always launch Claude Code from this repo's root, not from inside a plugin dir. Auto-memory is keyed by CWD, and plugin dirs contain their own .claude-plugin/ (launching there can load the plugin under test as the project plugin). Per-plugin CLAUDE.md files load on demand when you touch their files.

Conventions

• Per-plugin paths: every plugin lives at plugins/<slug>/. Tests, scripts, skills, agents, hooks, state-templates, docs, CHANGELOG, CLAUDE.md all live inside that dir.
• Tests run from inside the plugin dir: core and HA are pure bun test (auto-discovers tests/*.test.ts; HA keeps Python only as a test fixture, nothing shipped runs it); dev/fitness/scribe/forge use bash tests/run-all.sh (forge also needs a composer/PHP step). Helpers use CWD-relative paths and break if invoked from repo root.
• Tag format: <slug>--v<X.Y.Z> (double-dash, e.g. claude-code-hermit--v1.0.20).
• Independent versioning: each plugin's plugin.json bumps on its own cadence. Domain plugins declare core compat via required_core_version: ">=X.Y.Z" (semver range, not pin).
• Dependency fields: required_core_version and requires live in .claude-plugin/hermit-meta.json (hermit-internal, validator-invisible). dependencies is the native Claude Code resolver field in plugin.json. required_core_version is authoritative — read by plugins/claude-code-hermit/scripts/doctor-check.ts from hermit-meta.json. requires mirrors it for documentation. Update all three when the core version requirement changes. All hermit-internal manifest extensions (hermit.*, etc.) belong in hermit-meta.json. When a domain hatch depends on new core runtime behavior, bump required_core_version to the first compatible core version.
• CC-version-gated work bumps the floor, never shims around it. When a fix or feature depends on Claude Code CLI behavior introduced at a specific version (a new tool, hook payload shape, flag, or harness fix), bump that plugin's min_claude_code_version in .claude-plugin/hermit-meta.json to the version that introduces it — don't write feature-detection, version branches, or fallback code paths to keep the change working on older CC. The floor is the contract (enforced at hermit-evolve Step 0); raise it instead of carrying legacy compatibility code.
• Marketplace.json bumps: only the matching plugin's entry. The release skill takes a slug arg: /release <plugin-slug>.
• Dependency direction is one-way: domain plugins depend on core; core never depends on them. plugins/claude-code-hermit/ must not import a sibling, hardcode a sibling slug in logic, or branch on one being installed — it discovers siblings generically (sibling-scan + name-contains-hermit) and consumes only what they declare (hermit-meta.json hermit.*). Naming a plugin as an example in prose, docs, or a recommendation list is fine; conditioning behavior on it is not. Reverse direction too: siblings can't import core — shared logic ships as a hermit-run verb behind a required_core_version floor.
• Ship mechanism, not policy (all plugins): contracts stay strict, content stays loose — an installed hermit belongs to its operator, give skills data + goal + voice and let the model compose (don't hardcode content or operator-workflow opinions), and anything operator-editable must survive hermit-evolve. Contract list and extension points: plugins/claude-code-hermit/CLAUDE.md § Authorship layers.
• Ship standard: default-on, research preview. A new feature ships enabled by default, not behind an opt-in toggle defaulted off — treat it as a research preview to iterate on from real usage, not something held back by a conservative default. Default off only when the feature needs an operator-supplied credential/config it can't have yet, costs real spend per invocation, or is destructive/irreversible.
• Token discipline (all plugins): hook stdout, skill-driven Reads, and helper-script output are injected into the operator's context — print verdict-sized digests, and never have a skill Read an unbounded surface (JSONL event logs, DBs) directly; front it with a script that returns a bounded summary. The atom of cost is the API call, not the prompt: every tool call re-reads the full accumulated context from cache, so cache traffic is ≈85-90% of an always-on hermit's spend, measured live. Full pattern and examples: plugins/claude-code-hermit/CLAUDE.md § Development constraints. (This file is itself the costliest token surface in the repo — loaded every session and re-seeded into every subagent — so keep additions here terse.)