open source · macOS · single-file bash

🐚 limpet

Use an external drive as your primary storage on macOS — without it breaking when you unplug. Your folders cling to the drive, but survive every detach and re-attach themselves.

drive = primary auto local failover no kext · no daemon · no network

What people do

Mac storage is small and pricey — so you put your files on an external SSD.

Documents, Downloads, Desktop, whole project folders — moved onto a cheap fast drive, with symlinks pointing the way. The internal disk stays empty. It works beautifully.

Your Mac
folders (signposts)

points to →

External SSD
real files

The problem

Unplug the drive, and the signpost points to nothing.

Saves fail. Apps error. Desktop and Documents look empty. And a reboot can quietly recreate empty folders — splitting your files across two places. macOS has no built-in "work offline, sync later" for this.

Your Mac

broken ✕

unplugged

Why it matters

The drive is connected 99% of the time. It's the other 1% that hurts.

A bumped cable. An accidental eject. Grabbing the laptop and walking off. One small mistake shouldn't break your whole workflow — or risk your files.

✓Keep the internal drive empty — the whole point of going external.
✓…and never let a disconnect interrupt what you're doing.

The idea, in one line

Offline mode — for your drive.

Like a limpet clings to its rock yet detaches with the tide: your folders ride the SSD when it's there, and the instant it's gone they become normal local folders so you keep working. When the drive returns, your offline work moves back on — automatically.

connected → on the SSD unplugged → works locally back → merged up

1

How it works — the guard

A tiny watcher reacts to plug/unplug in under a second.

It rides a system hook that fires whenever any drive mounts or unmounts. Drive gone → it flips your folders to real local folders so saving never fails. It only checks the mountpoint and swaps local links, so it needs no special permissions.

launchd · WatchPaths /Volumes · no Full Disk Access required

2

How it works — the helper

When the drive's back, your offline work moves back onto it.

macOS won't let a silent background task write to an external drive (a security rule). So that step runs from your terminal, which is allowed — a tiny throttled hook that merges offline files back and refreshes an offline-readable copy of anything critical.

two layers that cover each other: one reacts instantly, one finishes the job

Safety by design

Built so it cannot lose data.

✓Verified copy before delete — every file is byte-checked before the original is removed.
✓Never overwrites — a name clash on merge keeps both copies.
✓No kernel extensions, no servers, no network — ~300 lines of bash you can read.
!Not a backup. limpet keeps you resilient to unplugs — it complements Time Machine, doesn't replace it.

The whole loop

Three states, fully automatic.

✓

Connected
files on the SSD

unplug

Working locally
saving still works

reconnect

✓

Synced back
offline work merged

You never touch any of it. It just happens.

Try it

Three commands.

# install
curl -fsSL https://raw.githubusercontent.com/notpritam/limpet/main/install.sh | bash

# set up — pick a drive + folders
limpet setup

# check anytime
limpet status

humans use the wizard · scripts & agents use --drive … --folders … --yes

Why it exists

Nothing off-the-shelf does this safely on a Mac.

The drive-pooling tools don't run on macOS; the ones that do break the instant the drive goes offline; sync apps double your storage and run a service. limpet is one auditable bash file — the most contained option. Open source, MIT.

github.com/notpritam/limpet contributions welcome