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:
Teknium 2026-04-20 03:06:17 -07:00 committed by Teknium
parent 1386e277e5
commit a25c8c6a56
8 changed files with 184 additions and 92 deletions

View file

@ -1,4 +1,4 @@
# disk-guardian
# disk-cleanup
Auto-tracks and cleans up ephemeral files created during Hermes Agent
sessions — test scripts, temp outputs, cron logs, stale chrome profiles.
@ -31,19 +31,19 @@ Deletion rules (same as the original PR):
## Slash command
```
/disk-guardian status # breakdown + top-10 largest
/disk-guardian dry-run # preview without deleting
/disk-guardian quick # run safe cleanup now
/disk-guardian deep # quick + list items needing prompt
/disk-guardian track <path> <category> # manual tracking
/disk-guardian forget <path> # stop tracking
/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 prompt
/disk-cleanup track <path> <category> # manual tracking
/disk-cleanup forget <path> # stop tracking
```
## Safety
- `is_safe_path()` rejects anything outside `HERMES_HOME` or `/tmp/hermes-*`
- Windows mounts (`/mnt/c` etc.) are rejected
- The state directory `$HERMES_HOME/disk-guardian/` is itself excluded
- The state directory `$HERMES_HOME/disk-cleanup/` is itself excluded
- `$HERMES_HOME/logs/`, `memories/`, `sessions/`, `skills/`, `plugins/`,
and config files are never tracked
- Backup/restore is scoped to `tracked.json` — the plugin never touches

View file

@ -1,4 +1,4 @@
"""disk-guardian plugin — auto-cleanup of ephemeral Hermes session files.
"""disk-cleanup plugin — auto-cleanup of ephemeral Hermes session files.
Wires three behaviours:
@ -8,10 +8,10 @@ Wires three behaviours:
compliance required.
2. ``on_session_end`` hook when any test files were auto-tracked
during the just-finished turn, runs :func:`disk_guardian.quick` and
logs a single line to ``$HERMES_HOME/disk-guardian/cleanup.log``.
during the just-finished turn, runs :func:`disk_cleanup.quick` and
logs a single line to ``$HERMES_HOME/disk-cleanup/cleanup.log``.
3. ``/disk-guardian`` slash command manual ``status``, ``dry-run``,
3. ``/disk-cleanup`` slash command manual ``status``, ``dry-run``,
``quick``, ``deep``, ``track``, ``forget``.
Replaces PR #12212's skill-plus-script design: the agent no longer
@ -27,7 +27,7 @@ import threading
from pathlib import Path
from typing import Any, Dict, Optional, Set
from . import disk_guardian as dg
from . import disk_cleanup as dg
logger = logging.getLogger(__name__)
@ -178,7 +178,7 @@ def _on_session_end(
try:
summary = dg.quick()
except Exception as exc:
logger.debug("disk-guardian quick cleanup failed: %s", exc)
logger.debug("disk-cleanup quick cleanup failed: %s", exc)
return
if summary["deleted"] or summary["empty_dirs"]:
@ -193,7 +193,7 @@ def _on_session_end(
# ---------------------------------------------------------------------------
_HELP_TEXT = """\
/disk-guardian ephemeral-file cleanup
/disk-cleanup ephemeral-file cleanup
Subcommands:
status Per-category breakdown + top-10 largest
@ -212,7 +212,7 @@ Test files are auto-tracked on write_file / terminal and auto-cleaned at session
def _fmt_summary(summary: Dict[str, Any]) -> str:
base = (
f"[disk-guardian] Cleaned {summary['deleted']} files + "
f"[disk-cleanup] Cleaned {summary['deleted']} files + "
f"{summary['empty_dirs']} empty dirs, freed {dg.fmt_size(summary['freed'])}."
)
if summary.get("errors"):
@ -268,14 +268,14 @@ def _handle_slash(raw_args: str) -> Optional[str]:
for item in prompt_items:
lines.append(f" [{item['category']}] {item['path']}")
lines.append(
"\nRun `/disk-guardian forget <path>` to skip, or delete "
"\nRun `/disk-cleanup forget <path>` to skip, or delete "
"manually via terminal."
)
return "\n".join(lines)
if sub == "track":
if len(argv) < 3:
return "Usage: /disk-guardian track <path> <category>"
return "Usage: /disk-cleanup track <path> <category>"
path_arg = argv[1]
category = argv[2]
if category not in dg.ALLOWED_CATEGORIES:
@ -292,7 +292,7 @@ def _handle_slash(raw_args: str) -> Optional[str]:
if sub == "forget":
if len(argv) < 2:
return "Usage: /disk-guardian forget <path>"
return "Usage: /disk-cleanup forget <path>"
n = dg.forget(argv[1])
return (
f"Removed {n} tracking entr{'y' if n == 1 else 'ies'} for {argv[1]}."
@ -310,7 +310,7 @@ def register(ctx) -> None:
ctx.register_hook("post_tool_call", _on_post_tool_call)
ctx.register_hook("on_session_end", _on_session_end)
ctx.register_command(
"disk-guardian",
"disk-cleanup",
handler=_handle_slash,
description="Track and clean up ephemeral Hermes session files.",
)

View file

@ -1,4 +1,4 @@
"""disk_guardian — ephemeral file cleanup for Hermes Agent.
"""disk_cleanup — ephemeral file cleanup for Hermes Agent.
Library module wrapping the deterministic cleanup rules written by
@LVT382009 in PR #12212. The plugin ``__init__.py`` wires these
@ -47,7 +47,7 @@ logger = logging.getLogger(__name__)
def get_state_dir() -> Path:
"""State dir — separate from ``$HERMES_HOME/logs/``."""
return get_hermes_home() / "disk-guardian"
return get_hermes_home() / "disk-cleanup"
def get_tracked_file() -> Path:
@ -297,7 +297,7 @@ def quick() -> Dict[str, Any]:
hermes_home = get_hermes_home()
_PROTECTED_TOP_LEVEL = {
"logs", "memories", "sessions", "cron", "cronjobs",
"cache", "skills", "plugins", "disk-guardian", "optional-skills",
"cache", "skills", "plugins", "disk-cleanup", "optional-skills",
"hermes-agent", "backups", "profiles", ".worktrees",
}
empty_removed = 0
@ -475,7 +475,7 @@ def guess_category(path: Path) -> Optional[str]:
rel = path.resolve().relative_to(hermes_home)
top = rel.parts[0] if rel.parts else ""
if top in {
"disk-guardian", "logs", "memories", "sessions", "config.yaml",
"disk-cleanup", "logs", "memories", "sessions", "config.yaml",
"skills", "plugins", ".env", "USER.md", "MEMORY.md", "SOUL.md",
"auth.json", "hermes-agent",
}:

View file

@ -1,4 +1,4 @@
name: disk-guardian
name: disk-cleanup
version: 2.0.0
description: "Auto-track and clean up ephemeral files (test scripts, temp outputs, cron logs) created during Hermes sessions. Runs via plugin hooks — no agent action required."
author: "@LVT382009 (original), NousResearch (plugin port)"