box-drive-detect

name	box-drive-detect
description	Probe the local Box Drive desktop-app mount to confirm the air-gapped backend is ready. Checks the mount path exists, is writable, Box Drive process is running, and reports the linked Box account email. Use when the user wants to verify Box Drive is set up, before running box-init for the first time, or when another skill needs the mount path. Never falls back to the network.
argument-hint	[--refresh]

/box-drive-detect

If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md.

Probe Box Drive desktop-app state. Caches result in workspace config (24 h TTL) so other skills don't re-probe each invocation.

Usage

/box-drive-detect [--refresh]

Examples:

• /box-drive-detect — return cached result if fresh, otherwise probe
• /box-drive-detect --refresh — force re-probe (use after toggling Box Drive on/off)

What to do

1. Look for the mount. macOS path candidates, in order:
   • ~/Library/CloudStorage/Box-Box/ (Box Drive 2.x / modern)
   • ~/Box/ (older Box Drive)
   • ~/Box Sync/ (deprecated Box Sync product)
   • Plus any path the user has declared in _box-memory.json.settings.box_drive_path_override
2. Verify writability. Touch a probe file at <mount>/.box-memory-probe. Delete it on success. Surface clear error if the touch fails — likely permissions or the mount isn't actually backed by Box Drive.
3. Confirm Box Drive process is running. On macOS, check via pgrep -i 'Box' or ps -ax | grep -iE 'box drive|box.app'. If Box Drive isn't running, files written locally won't sync until the user starts it — surface that clearly.
4. Read the linked Box account email (best-effort). Check Box Drive's local config: ~/Library/Application Support/Box/Box/box_users.db (SQLite — read the user_email column if accessible) or ~/Library/Application Support/Box/Box/ for a JSON config. If neither is accessible, ask the user to confirm which Box account they're signed into.
5. Estimate sync state. Box Drive maintains a sync queue. On macOS, look for indicators like Finder badges or status files (~/Library/Application Support/Box/Box/sync_status.json if it exists). If you can't determine state, report it as unknown — don't guess.
6. Build the result object:

{
  "backend": "local",
  "drive_path": "<absolute path>",
  "drive_writable": true,
  "drive_process_running": <true|false>,
  "drive_account_email": "<email or null>",
  "sync_state": "<idle|pending|offline|unknown>",
  "detected_at": "<ISO-8601 UTC>"
}

7. Cache in _box-memory.json.local_backend if a workspace exists. TTL 24 h — much shorter than the cloud variant's tier cache because Box Drive can be killed by the user at any time.
8. Report concisely:

Box Drive: detected at <path>
  Writable:           yes
  Process running:    yes
  Account:            <email>
  Sync state:         <state>
  Cached:             <ISO timestamp>

Hard rule — never fall back to the network

If any check fails (mount missing, not writable, Box Drive not running), surface a clean error and stop. Do NOT escalate to the Box API. Do NOT call any Box MCP tool. Do NOT auto-launch a different plugin.

Error messages should be actionable:

• No mount found → "No Box Drive mount detected. Install Box Drive (https://www.box.com/drive), sign in, and try again. If you don't want Box Drive locally, use the cloud variant: https://github.com/mrdulasolutions/BOX"
• Mount exists but not writable → "The mount at isn't writable. Check Box Drive is running and you're signed in with write access to your Box folder."
• Box Drive process not running → "Box Drive isn't running. Local writes will succeed but won't sync to Box cloud until Box Drive is started."
• Account email mismatch (if the user has declared an expected account and detected differs) → "Box Drive is signed in as , but your workspace config expects . Confirm which account before proceeding."

Cache invalidation triggers

Force a re-probe when:

• --refresh flag passed explicitly
• Cached detected_at is older than 24 h
• box-airgap-status detects a status change
• A user reports the previous detection was wrong

Don't

• Don't call Box's API. This plugin is air-gapped from the Box network by construction.
• Don't write the mount path to logs visible to the LLM provider. The path itself can leak account information.
• Don't guess sync_state if Box Drive doesn't expose it. Report unknown.
• Don't auto-launch Box Drive. Users do that themselves.