# Lupable Disk Doctor

Automatic local disk monitoring and supported housekeeping for coding agents.
Linux preview · 0.3.1 · Python 3.9+ · no account · no telemetry.

## Install from your coding agent

Copy this request into Claude Code or Codex:

> Install Lupable Disk Doctor from https://lupable.com/plugins/disk-doctor/lupable-plugins-0.3.1.zip as a persistent user plugin for this harness. Inspect its README and lifecycle hooks first. Preserve unrelated settings. Explain its cleanup scope and help me complete the harness's one-time hook trust review. Do not install it as only a skill.

The agent downloads and extracts the plugin-only archive to a stable owned folder
under your home directory. No terminal commands are required from you.
Installation and hook trust are separate: review the hook authorization in your
harness and start a new session. A universal 30-second setup is not yet verified.

For the installing agent, after safely extracting to a persistent owned directory:

| Harness | Native installation |
| --- | --- |
| Claude Code | `claude plugin marketplace add /absolute/path/to/lupable-plugins`, then `claude plugin install lupable-disk-doctor@lupable-plugins --scope user` |
| Codex | `codex plugin marketplace add /absolute/path/to/lupable-plugins`, then `codex plugin add lupable-disk-doctor@lupable-plugins` |
| Cursor | Manifest and hook contract included; native installation is not release-verified. |

Keep the extracted directory for the local marketplace. Do not bypass hook trust,
overwrite unknown helpers, replace global settings or grant general deletion
authority. Public GitHub/marketplace listing is not yet available; the HTTPS
archive is the current distribution path.

## What happens automatically

Trusted SessionStart/Stop hooks install or upgrade the known helper, register the
current owned workspace for bounded metadata monitoring, enroll an existing
supported uv cache and configure one 15-minute user-cron job. A detached check
runs immediately. Routine housekeeping does not call an LLM, need an agent launch
wrapper, or require repeated cleanup requests.

A running cron daemon is required for checks after the agent closes; otherwise
lifecycle-only operation is reported. Configured scheduling is not proof of an
observed run.

**Trusting these hooks authorizes permanent deletion of unused native uv cache
entries and expired Disk Doctor-owned temporary folders.** uv may rebuild cached
environments or download dependencies later. Existing cleanup-off, category
revocation and pause choices are preserved.

| Disk buildup | Monitoring | Automatic cleanup |
| --- | --- | --- |
| Agent histories, logs, plugin downloads and runtime versions | Known local roots | No |
| Browser downloads and dependency caches | Known local roots | Only enrolled uv 0.12.2 native pruning |
| Dependencies, build/test outputs, docs and artifacts | Known folders in up to 20 observed workspaces | No |
| Disk Doctor-created temporary folders | Yes | Expired, unpinned, unlocked folders only |
| Arbitrary existing files, worktrees, Docker/cloud resources | Not a complete inventory | No |

Large does not mean disposable. This preview does **not** maintain every source
of agent disk buildup or redirect all agent artifacts into managed storage.
Tools must explicitly use the existing managed-temp API for that cleanup.

## Controls through your agent

Say “show Disk Doctor status”, “pause Disk Doctor” or “resume Disk Doctor”.
The included skill provides the controls; hooks/cron handle routine housekeeping.

| Helper control | Effect |
| --- | --- |
| `status`, `factors`, `report` | Inspect receipts and bounded metadata totals |
| `pause` | Persist pause and remove the owned cron entry |
| `schedule` | Resume owned scheduling: 15-minute checks for plugin users, hourly sweeps for legacy CLI users |
| `disable-cleanup` | Stop new deletion while retaining monitoring |
| `deny-cache-prune uv` | Revoke native cache permission |
| `keep NAME` / `release NAME` | Pin / unpin a managed temporary folder |
| `uninstall` | Pause and remove owned job/helper and matching skill files; retain data and receipts |

Pause before disabling/removing the harness plugin: cached files and its OS job
may remain. An already running action may finish after pause or revocation.
There is no recycle bin or restore guarantee.

## Safety and privacy

- No helper network requests or telemetry. Native uv pruning runs offline.
- Inventory reads metadata, not prompts/source/conversation bodies. Identity checks
  hash provider binaries and read a bounded cache marker.
- Unknown files, histories, credentials and worktrees are not enrolled for deletion.
  Symlinks, hardlinks, ownership/identity changes, special files, nested filesystems
  and incomplete preflights block managed cleanup.
- Only qualified uv 0.12.2 is supported. Binary/cache identity changes fail closed
  until re-enrollment. Native pruning is attempted at most daily, including failed
  or interrupted attempts. Provider lock contention is not reported as success.
- Reports contain local paths and hashes. Inspect before sharing. This is not a
  security boundary against hostile same-user processes or administrators.
- Partial totals are lower bounds. Growth requires complete comparable scans.
  Unlinked bytes do not guarantee physical reclaimed space. Native pruning times
  out after 20 seconds; scans and managed sweeps have entry/time budgets.

## Verification and limits

Automated tests cover cleanup boundaries, idempotency, locks, failed writes,
provider drift, revocation, pause, hooks and packaging. Real uv pruning and
live-use locking use disposable caches, not user data.

Native startup was verified with Codex CLI 0.163.0 and Claude Code 2.1.226 using
persistent plugins in disposable homes. An ordinary “Reply hello” request activates
housekeeping without a cleanup prompt. Tests use a non-serving model endpoint:
they prove hooks/receipts independently of model completion, not a complete
authenticated customer conversation. Codex's automated fixture bypasses trust
only for self-reviewed isolated hooks; user installation must review them.

Cursor is contract-tested only. Codex desktop, macOS and Windows are unverified
or unsupported. A real OS-cron fixture verifies housekeeping after the agent closes
and preserves unrelated jobs; this does not prove a customer's cron is running.
That acceptance fixture advances its own timestamps and uses a one-minute test
schedule with the actual generated command; it does not wait a full daily cycle.

## Standalone CLI compatibility

The legacy installer at https://lupable.com/plugins/disk-doctor/install.sh installs
the helper, not native plugin hooks. Inspect remote scripts first. Manual
`install --skills` is guidance-only, not automatic plugin installation.
Known unmodified releases support `--upgrade`; modified files are preserved.

For deliberately disposable scratch, `run --ttl-hours 24 -- COMMAND` sets
TMPDIR/TMP/TEMP and holds a cleanup lock until the foreground command exits.
Tools may ignore these variables. Detached jobs must not use expiring storage
after the foreground parent exits. Keep source, secrets and deliverables out.

## Development

```sh
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -q
python3 build_release.py
```

Release packaging is allowlisted. No core platform code, customer content or
private research is bundled. MIT licensed; provider source/binaries are not copied.