mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-25 00:51:20 +00:00
docs(plugins): rename disk-guardian to disk-cleanup + bundled-plugins docs
The original name was cute but non-obvious; disk-cleanup says what it does. Plugin directory, script, state path, log lines, slash command, and test module all renamed. No user-visible state exists yet, so no migration path is needed. New website page "Built-in Plugins" documents the <repo>/plugins/<name>/ source, how discovery interacts with user/project plugins, the HERMES_DISABLE_BUNDLED_PLUGINS escape hatch, disk-cleanup's hook behaviour and deletion rules, and guidance on when a plugin belongs bundled vs. user-installable. Added to the Features → Core sidebar next to the main Plugins page, with a cross-reference from plugins.md.
This commit is contained in:
parent
1386e277e5
commit
a25c8c6a56
8 changed files with 184 additions and 92 deletions
114
website/docs/user-guide/features/built-in-plugins.md
Normal file
114
website/docs/user-guide/features/built-in-plugins.md
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
---
|
||||
sidebar_position: 12
|
||||
sidebar_label: "Built-in Plugins"
|
||||
title: "Built-in Plugins"
|
||||
description: "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](/docs/user-guide/features/plugins) page for the general plugin system, and [Build a Hermes Plugin](/docs/guides/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:
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
plugins:
|
||||
disabled:
|
||||
- disk-cleanup
|
||||
```
|
||||
|
||||
Or suppress every bundled plugin at once with an env var:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```yaml
|
||||
# ~/.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](/docs/guides/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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue