Can I use an external drive as primary storage on macOS?

Yes. limpet moves the home folders you pick (Documents, Downloads, Desktop, project folders) onto an external SSD and symlinks to them, so the external drive is your primary storage and the internal disk stays nearly empty.

What happens when I unplug the external drive?

A background guard detects the unplug within about a second and turns the affected folders back into real local folders, so saving keeps working with no errors. When the drive returns, limpet merges your offline work back onto it and never overwrites — a name clash keeps both copies.

Is limpet safe? Will I lose data?

limpet verifies a byte-for-byte copy before deleting any original, and keeps both files on a name clash. It uses no kernel extensions, no daemons and no network. It complements a backup such as Time Machine; it is not a replacement for one.

Yes. limpet is free and open source under the MIT license, installable with a single curl command on macOS.

Can limpet auto-organize my files?

Yes. limpet organize (added in v0.4) is an opt-in file organizer, off by default. When enabled it sorts idle files in the folders you choose into destinations by type or rule, only when a file is safe to move (aged, aged-idle, or quick), never overwrites on a name clash, and every move is reversible with limpet organize undo.

limpet — run your Mac off an external SSD, without it breaking when you unplug

The problem

Unplug the drive, and the signpost points to nothing.

You move your files to a cheap external SSD and symlink to them — perfect, until the cable slips. Then saves fail, the Desktop empties, and a reboot can quietly split your files across two places.

~/Documents → ✕ nothing

The fix

limpet fails over to local, then merges back.

The moment it's unplugged, each folder becomes a real local one — so every save keeps working. When the drive returns, your offline edits move back on, and a name clash keeps both.

~/Documents → local → merged

Feature by feature

Built to be boringly reliable.

Offline mode, for your drive. Everything below happens on its own — you never babysit a cable again.

Instant failover

A background guard rides a system hook that fires on any plug or unplug. Drive gone → your folder becomes a real local folder in under a second. Drive back → it re-links and merges. No permissions required.

connected

local · saves work

merged back

Verified before delete

Moving a folder onto the drive byte-checks every file before the original is ever removed. Fail the check, keep the original.

Never overwrites

A name clash on merge keeps both copies, timestamped. You cannot lose a version.

Contained by design

No kernel extensions, no daemons, no network. One file you can read.

Self-updating

Ships via GitHub Releases. limpet update, or opt into automatic.

You, or your agent

An interactive wizard for people; --drive --folders --yes for scripts & AI agents.

Under the hood

Two small pieces that cover each other.

That's the entire tool. One reacts instantly; one finishes the job macOS won't let a background task do.

01

The guard

A launchd agent watching /Volumes. It flips folders between symlink and real-local the moment a drive appears or vanishes. Only stats the mountpoint — so it needs no Full Disk Access.

instant · permissionless · always on

02

The helper

macOS blocks background tasks from writing to external volumes, so the merge-back runs from your terminal — which is allowed — via a tiny throttled hook. It also keeps an offline-readable mirror of anything critical.

merge-back · offline mirror · daily update check

Questions

The honest FAQ.

The stuff you'd actually ask before running your whole Mac off a cable.

Wait — is this safe? Will I lose files?

No. limpet byte-verifies every copy before it deletes the original, and if two files ever clash it keeps both, timestamped. It's ~1,300 lines of bash you can read over one coffee. (It's not a backup, though — keep your Time Machine.)

Are you rich enough for a Mac but not the storage upgrade?

Guilty. I bought the Mac, looked at the storage-upgrade price, quietly closed the tab, and bought a cheap external SSD instead. Then it kept breaking every time the cable slipped. So — limpet.

Who is this actually for?

Honestly? Me. It runs on my machine every day. I made it public because you're probably in the same boat — small internal disk, big external SSD. If it helps, star it or say hi.

Does it work with any drive and any folders?

Any external volume, and whatever home folders you pick — Documents, Downloads, Desktop, entire project directories. limpet link <path> moves anything else onto the drive too.

Can it auto-organize my Downloads too?

Yes — limpet organize (v0.4) is an opt-in file sorter, off by default. When you enable it, it moves only idle files — you choose the rule (aged, aged-idle or quick) and where each type goes — it never overwrites, and every move is undoable with limpet organize undo.

Do I have to babysit it?

No. A background guard plus a tiny terminal hook handle everything. Unplug, replug, reboot with the drive gone — it sorts itself out and merges your work back when the drive's home.

Get started

Two commands. You're protected.

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

# set up — pick a drive + folders limpet setup

Read the docs