mrdulasolutions/box-onprem/box-drive-detect

/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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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>"
}

1. 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.
2. 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 <path> 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 <detected>, but your workspace config expects <expected>. 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.