kundol
A macOS-first CLI that plans, checks, and audits cleanup of developer caches, generated project files, and eligible startup items.
What it is
kundol is an open-source, macOS-first command-line tool for reviewing developer-machine storage, generated project artifacts, and user startup items. It also provides a read-only catalogue of optimisation rules and a path for requesting missing tools. There is no hosted application or dashboard.
Problem being solved
Developer caches and generated files can accumulate across tools and repositories, while startup items are easy to overlook. Broad cleanup scripts can remove the wrong target or hide the consequences of an action. The problem is to reclaim eligible space and simplify startup state without treating all disk usage as disposable.
How it solves the problem
- Scan published, scoped rules and print the exact targets, sizes where known, safety tiers, and proposed actions before selection.
- Require an explicit choice for review-tier targets; the force flag can select only safe, force-eligible suggestions.
- Re-probe target identity and repeat live path, symlink, marker, and activity checks immediately before applying a selected action.
- Report outcomes in a local SQLite action history and per-session audit logs. Eligible user LaunchAgents are disabled without deleting their plist files.
Technology used
Bun and TypeScript
The CLI runtime, strict source language, test runner, and release-bundle target.
Commander and Zod
Command registration and strict validation of the bundled optimisation registry.
JSON rule registry
Published rules define exact scopes, selectors, review tiers, live validators, and code-approved actions.
Bun SQLite and session logs
Local action, cancellation, and outcome history; these are not centralized usage analytics.
macOS launchctl
Disables eligible user LaunchAgents while leaving their plist files in place.
Bun tests and Docker sandbox
Regression tests use disposable roots; the first-run sandbox uses simulated targets without mounting host projects.
Analytics placeholder
Product signals
No published usage baseline
kundol records local audit outcomes, not centralized product telemetry. These placeholders require an explicit measurement and privacy decision before they can show aggregate results.
- Audited runs
- Pending evidence
- Verified actions
- Pending evidence
- Unsafe targets skipped
- Pending evidence
- CLI reliability
- Pending evidence
Simplified from the public repository
Basic system architecture
The command layer presents plans and collects selection; the registry engine and startup service own target checks and actions. The local audit boundary records attempts and outcomes.
01
Commander CLI
Registers optimise, read-only catalogue, and GitHub issue commands.
02
Bundled rule registry
Zod validates catalogue rules, scopes, selectors, safety tiers, and approved actions.
03
Probe and apply services
Identify precise targets, print a plan, recheck selected items, then apply eligible actions. Startup uses a dedicated service.
04
Local audit
Bun SQLite and session logs record scans, cancellations, attempts, outcomes, and errors.
Engineering decisions and limits
Constraints
- Only published, engine-ready rules with code-approved handlers are eligible for cleanup; proposed entries remain catalogue-only.
- Project scanning stays within a supplied workdir and skips symlinks, generated directories, and protected paths.
Trade-offs
- A conservative rule catalogue covers fewer targets than a generic disk sweeper, but keeps ownership and action semantics reviewable.
- Force mode is intentionally limited to safe targets; review targets cost an extra confirmation step.
Failure modes
- A target can change after the initial scan, so the engine rechecks identity and live validators before action.
- Owner-tool cache actions may trigger later re-downloads, and known target size does not prove command-side savings.
Rejected alternatives
- The public CLI does not run broad Docker prune or blanket temporary-file deletion without scoped ownership rules.
- Startup optimisation disables eligible user agents instead of deleting their plist files or mutating protected system entries.