ship.md — Moving things in the real world, as easy as moving filesDownloadgithub
filesystem → real world<br>Moving things in the real world,<br>as easy as moving files.<br>ship.md watches your folders. Drag a file, run mv, or ask Hermes in plain English — and a courier is dispatched with a full audit trail.<br>Download SourceHow it works<br>Drag<br>drop files to courier
mv<br>in your shell
Prompt<br>hermes / codex
~/ship — Send skateboard home<br>$ mv eg1/office/skatebrd.txt eg1/home/<br>eg1/office/skatebrd.txt → eg1/home/skatebrd.txt
POSTapi.uber.com/v1/eats/deliveries/orders→ 202 accepted · courier dispatched
Tony<br>WhatsApp
“skatebrd.txt is on its way — eta 18 min”
drag & drop<br>Your Finder is the interface.<br>Drop a file into another folder and a courier is on its way. Nested paths keep semantic context.
Move skatebrd.txt from office/ → home/ ships it home<br>Drop tomatos.txt into italian/ restocks the kitchen<br>Every move writes a JSON event to the audit log
~/ship<br>NameDate Modified<br>eg1Today at 2:18 PM<br>homeToday at 2:18 PM<br>skatebrd.txtToday at 2:18 PM<br>officeToday at 2:18 PM<br>eg2Today at 2:18 PM<br>parentsToday at 2:18 PM<br>winter-clothes.txtToday at 2:18 PM<br>sisToday at 2:18 PM<br>eg3Today at 2:18 PM<br>cloudkitchenToday at 2:18 PM<br>italianToday at 2:18 PM<br>tomatos.txtToday at 2:18 PM<br>warehouseToday at 2:18 PM<br>laptop.jpgToday at 2:18 PM<br>ship.mdToday at 2:18 PM
how it works<br>Three ways to ship. One mental model.<br>Your filesystem already knows where things are. ship.md just makes the outside world catch up.
1. Model the world as folders<br>Each folder is a place — home, office, warehouse, cloud-kitchen. Nesting is meaning.
2. Files are things<br>skatebrd.txt, laptop.jpg, winter-clothes.txt. If it's in a folder, it's at that location.
3. Move to ship<br>Drag, mv, or ask Hermes. The watcher turns filesystem events into courier calls.
three ways to move<br>Use whatever interface you already know.<br>After installing the mac app, ship.md works with Finder, Terminal, and any coding harness that can touch files.
Drag & drop in Finder<br>Move files between folders the way you always have. ship.md watches the filesystem and turns every drop into a delivery event.<br>skatebrd.txt → home/
mv in your shell<br>Any mv, cp, or rsync that lands in a watched folder becomes a real-world move with an audit trail.<br>mv office/skatebrd.txt home/
Ask your coding harness<br>Hermes, Codex, Claude, Pi, Arc — any agent that can move files can now ship things. Same filesystem, same result.<br>move skateboard from home to office<br>HHermes<br>CCodex<br>CClaude<br>πPi<br>AArc
ship.md<br>Every folder can hold a ship.md<br>A tiny markdown manifest tells the watcher what lives there, who to notify, and where in the world it is. Context flows down the tree.
Inventory
Declare what belongs in this folder. Incoming files are matched against it.
Contacts
email · whatsapp · call — reached automatically on relevant events.<br>emailwhatsappcall
Context
location, area, google_pin. Inherited by all nested folders unless overridden.
Webhook
url · method · headers · params — fired on every matching event with folder context templated in.<br>POSTheadersparams
audit event · file_observedJSON<br>"event_id": "be2845cd-342e-4066-93b4-e79aa32d1da2",<br>"timestamp": "2026-07-12T08:27:29.028892+00:00",<br>"event_type": "file_observed",<br>"payload": {<br>"event_kind": "created",<br>"detected_via": "filesystem",<br>"folder_name": "incoming",<br>"location": "mumbai",<br>"file_name": "laptop.jpg",<br>"ship_contexts": [<br>"path": "/Users/bosky/ship/warehouse/ship.md",<br>"location": "delhi",<br>"inventory_items": ["laptop"],<br>"emails": ["ops@example.com"]<br>],<br>"movement_message":<br>"ship.md flow observed: laptop.jpg in incoming (location=mumbai)"
hermes / codex<br>Or just ask, in plain English.<br>Hermes plans, executes, and shows you the audit trail. Same result — a real move with receipts.
move my skateboard from home to office, and show the audit trail it created
skillmacos-file-routing-tray-apps0.0s<br>plan3 task(s)0.0s<br>execimport json, subprocess0.2s<br>plan update3/3 ✓0.0s
Hermes— Moved.<br>Current file state<br>· /Users/bosky/ship/eg1/home/skatebrd.txt: gone<br>· /Users/bosky/ship/eg1/office/skatebrd.txt: exists
planned_tools<br>"tool": "mv",<br>"from": ".../home/skatebrd.txt",<br>"to": ".../office/skatebrd.txt",<br>"reason": "ship.md inventory match"<br>},<br>"tool": "showToast",<br>"title": "ship.md moved",<br>"message": "skatebrd.txt: home → office"
self-host<br>self host or on-prem or managed portal<br>SQLite inventory, config, and audit log visibility for the watcher service. Runs on your machine.
DashboardInventoryLogsConfigAPI<br>Folders
Locations
Subscribers
Inventory rows
Inventory qty
Audit events<br>215
Paths<br>Root/Users/bosky/cp<br>Support~/Library/Application Support/ship-md<br>Vision modelanthropic/claude-sonnet-5<br>Latest eventship_updated · 09:48:01
Recent logs<br>› 2026-07-12T09:48:01Z ship_updated e2bd51ff…<br>› 2026-07-12T09:48:01Z ship_updated 9afbcaf2…<br>› 2026-07-12T09:48:01Z ship_updated 4ed600e9…<br>› 2026-07-12T09:48:01Z ship_updated 932f6cf8…<br>› 2026-07-12T09:48:01Z ship_updated 7f80a9fb…<br>› 2026-07-12T09:48:01Z...