hermes-agent/website/docs/user-guide/features/built-in-plugins.md

sidebar_position	sidebar_label	title	description
12	Built-in Plugins	Built-in Plugins	Plugins shipped with Hermes Agent that run automatically via lifecycle hooks — disk-cleanup and friends

Built-in Plugins

Hermes ships a small set of plugins bundled with the repository. They live under <repo>/plugins/<name>/ and load automatically alongside user-installed plugins in ~/.hermes/plugins/. They use the same plugin surface as third-party plugins — hooks, tools, slash commands — just maintained in-tree.

See the Plugins page for the general plugin system, and Build a Hermes Plugin to write your own.

How discovery works

The PluginManager scans four sources, in order:

1. Bundled — <repo>/plugins/<name>/ (what this page documents)
2. User — ~/.hermes/plugins/<name>/
3. Project — ./.hermes/plugins/<name>/ (requires HERMES_ENABLE_PROJECT_PLUGINS=1)
4. Pip entry points — hermes_agent.plugins

On name collision, later sources win — a user plugin named disk-cleanup would replace the bundled one.

plugins/memory/ and plugins/context_engine/ are deliberately excluded from bundled scanning. Those directories use their own discovery paths because memory providers and context engines are single-select providers configured through hermes memory setup / context.engine in config.

Bundled plugins respect the same disable mechanism as any other plugin:

# ~/.hermes/config.yaml
plugins:
  disabled:
    - disk-cleanup

Or suppress every bundled plugin at once with an env var:

HERMES_DISABLE_BUNDLED_PLUGINS=1 hermes chat

The test suite sets HERMES_DISABLE_BUNDLED_PLUGINS=1 in its hermetic fixture — tests that exercise bundled discovery clear it explicitly.

Currently shipped

disk-cleanup

Auto-tracks and removes ephemeral files created during sessions — test scripts, temp outputs, cron logs, stale chrome profiles — without requiring the agent to remember to call a tool.

How it works:

Hook	Behaviour
post_tool_call	When write_file / terminal / patch creates a file matching test_*, tmp_*, or *.test.* inside HERMES_HOME or /tmp/hermes-*, track it silently as test / temp / cron-output.
on_session_end	If any test files were auto-tracked during the turn, run the safe quick cleanup and log a one-line summary. Stays silent otherwise.

Deletion rules:

Category	Threshold	Confirmation
test	every session end	Never
temp	>7 days since tracked	Never
cron-output	>14 days since tracked	Never
empty dirs under HERMES_HOME	always	Never
research	>30 days, beyond 10 newest	Always (deep only)
chrome-profile	>14 days since tracked	Always (deep only)
files >500 MB	never auto	Always (deep only)

Slash command — /disk-cleanup available in both CLI and gateway sessions:

/disk-cleanup status                     # breakdown + top-10 largest
/disk-cleanup dry-run                    # preview without deleting
/disk-cleanup quick                      # run safe cleanup now
/disk-cleanup deep                       # quick + list items needing confirmation
/disk-cleanup track <path> <category>    # manual tracking
/disk-cleanup forget <path>              # stop tracking (does not delete)

State — everything lives at $HERMES_HOME/disk-cleanup/:

File	Contents
tracked.json	Tracked paths with category, size, and timestamp
tracked.json.bak	Atomic-write backup of the above
cleanup.log	Append-only audit trail of every track / skip / reject / delete

Safety — cleanup only ever touches paths under HERMES_HOME or /tmp/hermes-*. Windows mounts (/mnt/c/...) are rejected. Well-known top-level state dirs (logs/, memories/, sessions/, cron/, cache/, skills/, plugins/, disk-cleanup/ itself) are never removed even when empty — a fresh install does not get gutted on first session end.

To turn it off without uninstalling:

# ~/.hermes/config.yaml
plugins:
  disabled:
    - disk-cleanup

Adding a bundled plugin

Bundled plugins are written exactly like any other Hermes plugin — see Build a Hermes Plugin. The only differences are:

• Directory lives at <repo>/plugins/<name>/ instead of ~/.hermes/plugins/<name>/
• Manifest source is reported as bundled in hermes plugins list
• User plugins with the same name override the bundled version

A plugin is a good candidate for bundling when:

• It has no optional dependencies (or they're already pip install .[all] deps)
• The behaviour benefits most users and is opt-out rather than opt-in
• The logic ties into lifecycle hooks that the agent would otherwise have to remember to invoke
• It complements a core capability without expanding the model-visible tool surface

Counter-examples — things that should stay as user-installable plugins, not bundled: third-party integrations with API keys, niche workflows, large dependency trees, anything that would meaningfully change agent behaviour by default.