Get current disk space on the boot volume.

Returns total, used, and free disk space with human-readable sizes. Use this to check if disk pressure exists before deciding to clean.

Returns: str: JSON with total, free, used space and percentages. { "total": "500.1 GB", "free": "23.4 GB", "used": "476.7 GB", "free_gb": 23.4, "used_percent": 95.3 }

Scan macOS cache directories and report their sizes.

Scans developer tool caches (Xcode, Homebrew, npm, pip, Docker, etc.) and reports the size of each. Results are sorted by size (largest first).

Use this to understand what's consuming disk space before cleaning.

Args: params: Optional filters — specific category slugs or minimum size.

Returns: str: JSON array of cache categories with sizes, sorted largest first. [ { "slug": "xcode_derived_data", "name": "Xcode DerivedData", "size_bytes": 15032000000, "size_human": "15.0 GB", "item_count": 4230, "risk_level": "safe", "description": "Build artifacts...", "rebuild_note": "Xcode rebuilds on next build" } ]

Clear specific cache categories to free disk space.

Removes the contents of the specified cache directories. The directories themselves are preserved — only their contents are deleted. All cleared caches will regenerate automatically when their respective tools are used.

IMPORTANT: Use cacheout_scan_caches first to see sizes, then pass the slugs of categories you want to clear. Use dry_run=true to preview.

Args: params: Categories to clear and whether to dry-run.

Returns: str: JSON report of what was cleaned and total space freed. { "total_freed": "12.3 GB", "total_freed_bytes": 13204889600, "dry_run": false, "results": [ { "slug": "xcode_derived_data", "name": "Xcode DerivedData", "bytes_freed": 8500000000, "freed_human": "8.5 GB", "success": true, "error": null } ] }

Intelligently free disk space by clearing caches in priority order.

This is the PRIMARY tool for agents managing disk pressure. Specify how many GB you need freed, and the server clears the safest caches first:

1. Build artifacts (Xcode DerivedData) — always regenerates

2. Package manager caches (Homebrew, npm, pip) — re-downloads as needed

3. Browser caches — rebuilds on browsing

4. Docker (only if include_caution=true) — destructive, last resort

The server stops as soon as the target is met. Use dry_run=true to preview which categories would be cleaned and how much space would be freed.

Typical use: An agent detects low disk space (or needs room for swap/builds) and calls smart_clean(target_gb=10.0) to free 10 GB immediately.

Args: params: Target GB to free, dry_run flag, and caution inclusion.

Returns: str: JSON report with before/after disk state and what was cleaned. { "target_gb": 10.0, "target_met": true, "total_freed_human": "12.3 GB", "dry_run": false, "disk_before": {"free_gb": 5.2, ...}, "disk_after": {"free_gb": 17.5, ...}, "cleaned": [...], "skipped": [...] }

Get cacheout-mcp server status, mode, and available categories.

Returns the execution mode (standalone or app), the Cacheout binary path if in app mode, and a list of all available cache category slugs.

Use this to verify the server is running and understand its capabilities.

Returns: str: JSON with mode, binary path, and category list.

Get current system memory statistics on macOS.

Returns physical RAM breakdown (free, active, inactive, wired, compressed), swap usage, compressor ratio, memory pressure level, and an actionable memory tier classification.

Use this to check memory health before builds, heavy tasks, or when investigating performance issues. The memory_tier field provides a quick assessment: abundant > comfortable > moderate > constrained > critical.

In app mode, delegates to CacheOut CLI. In standalone mode, reads sysctl values directly (no CacheOut.app needed).

Returns: str: JSON with memory statistics. { "total_physical_mb": 8192.0, "free_mb": 512.3, "active_mb": 3200.1, "inactive_mb": 1024.5, "wired_mb": 2048.7, "compressed_mb": 800.2, "compressor_ratio": 2.5, "swap_used_mb": 256.0, "pressure_level": 1, "memory_tier": "moderate", "estimated_available_mb": 1536.8, "mode": "standalone" }

Get top processes by memory usage on macOS.

Returns a ranked list of the top N processes sorted by memory consumption. In standalone mode, uses RSS from ps (labeled as an estimate). In app mode, uses physical footprint from the Cacheout CLI.

Sort keys are mode-dependent:

• standalone: 'rss' (default)

• app: 'phys_footprint' (default)

The capabilities map in the response shows which sort keys are available. sort_by_pageins is gated to false in all modes this phase.

Args: params: top_n (default 10) and optional sort_by key.

Returns: str: JSON envelope with mode, capabilities, data (processes + sort info), partial.

Get macOS memory compressor health metrics.

Returns compressor ratio, compression/decompression rates (via dual-sample), thrashing detection, pressure level, and trend information.

Takes two samples ~1 second apart to compute instantaneous rates. Thrashing is flagged when decompression_rate > 100/sec AND > 2x compression_rate (aligned with CompressorTracker.swift thresholds).

Trend requires multiple invocations over time — a single call returns "unknown" with partial=true.

In standalone mode, reads vm_stat and sysctl directly. In app mode, delegates to --cli memory-stats.

Returns: str: JSON envelope with mode, capabilities, data (ratio, rates, thrashing), partial.

Execute a memory reclamation intervention on macOS.

IMPORTANT: Always call with confirm=false first to preview what will happen, then call again with confirm=true to execute.

Available interventions:

• purge: Flush the Unified Buffer Cache (UBC) to reclaim purgeable memory. Works in both standalone and app modes.

• trigger_pressure_warn: Manual pressure event (app only, not yet available)

• reduce_transparency: Toggle transparency setting (app only, not yet available)

• delete_sleepimage: Remove sleepimage file (app only, not yet available)

• cleanup_snapshots: Clean orphaned APFS snapshots (app only, not yet available)

• flush_compositor: Display mode toggle (app only, not yet available)

In standalone mode, only 'purge' is supported. In app mode, only 'purge' is currently wired; other interventions will unlock as the CLI surface grows.

The response always includes a capabilities map showing which interventions are available in the current mode.

Args: params: intervention_name, confirm flag, and optional target_pid.

Returns: str: JSON envelope with mode, capabilities, data, partial.

Get overall system health score with alerts.

Returns a health score (0-100, -1 if no data), the data source, and any active alerts from the daemon.

In socket mode (daemon running), fetches health data directly from the daemon's Unix socket for <1ms latency. In CLI/standalone mode, computes the health score locally using the canonical formula.

The health score formula: base = 100 critical pressure: -50, warn pressure: -25 swap penalty: min(50, swap_used_percent / 2) compressor penalty: min(30, max(0, (3.0 - ratio) * 10)) score = max(0, base - penalties)

Returns: str: JSON with score (Int, -1 if no data), source, and alerts array.

Configure the autopilot policy for the headless daemon.

Uses a validate-then-write flow:

1. Writes candidate config to autopilot.candidate.json (0600)

2. If daemon running: validates via socket; else validates locally

3. Invalid: deletes candidate, returns errors

4. Valid: atomically renames candidate to autopilot.json

5. If daemon: sends SIGHUP and polls for config generation increment

The local validator mirrors the daemon's shared validator exactly:

• version must be 1

• enabled must be boolean

• Rules: actions must be 'pressure-trigger' or 'reduce-transparency'

• Webhook (if present): url required, format = 'generic', timeout_s 1-60

• Telegram (if present): bot_token + chat_id required, timeout_s 1-60

Args: params: Config object to validate and apply.

Returns: str: JSON with success status, validation errors, and any warnings.

Check if the Cacheout watchdog has raised any disk/swap/memory alerts. This is a near-zero-cost check (reads a small JSON file). Use this at the start of tasks, before builds, or after errors — NOT on a polling loop. Returns null if no alert is active. If an alert exists, review it and take action with smart_clean, then call again with acknowledge=true to clear it.

Get predictive memory recommendations from the Cacheout engine.

Returns advisory recommendations about memory health, including compressor degradation, swap pressure, high-growth processes, Rosetta-translated processes, and agent memory pressure.

Mode-dependent behavior:

• socket: Full recommendations from daemon (all 7 types when conditions apply)

• app: Snapshot-only recommendations from CLI (no trend-based types)

• standalone: Basic recommendations from sysctl (compressor_low_ratio, swap_pressure only)

The partial flag in _meta indicates degraded results:

• Always true in app/standalone modes (no trend data)

• True in socket mode only when daemon's process scan was incomplete

Returns: str: JSON with recommendations array and _meta. { "recommendations": [ { "type": "compressor_low_ratio", "message": "Compression ratio 1.5 is below 2.0", "process": null, "pid": null, "impact_value": 1.5, "impact_unit": "ratio", "confidence": "low", "source": "standalone" } ], "_meta": { "mode": "standalone", "count": 1, "partial": true, "source": "standalone" } }