filesystem → real world

Moving a skateboard home in the real world,
as easy as moving files.

ship.md watches your folders. Drag a file, run mv, or ask an agent in plain English — and a courier is dispatched with a full audit trail.

Download Source How it works

~/ship — Send skateboard home

$ mv eg1/office/skatebrd.txt eg1/home/

eg1/office/skatebrd.txt → eg1/home/skatebrd.txt

POSTapi.uber.com/v1/eats/deliveries/orders→ 202 accepted · courier dispatched

Tony

“skatebrd.txt is on its way — eta 18 min”

drag & drop

Your Finder is the interface.

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
Drop eggs.txt into italian/ restocks the kitchen
Every move writes a JSON event to the audit log

~/ship

NameDate Modified

eg1Today at 2:18 PM
homeToday at 2:18 PM
skatebrd.txtToday at 2:18 PM
officeToday at 2:18 PM
eg2Today at 2:18 PM
parentsToday at 2:18 PM
winter-clothes.txtToday at 2:18 PM
sisToday at 2:18 PM
eg3Today at 2:18 PM
cloudkitchenToday at 2:18 PM
italianToday at 2:18 PM
eggs.txtToday at 2:18 PM
warehouseToday at 2:18 PM
laptop.jpgToday at 2:18 PM
ship.mdToday at 2:18 PM

how it works

Three ways to ship. One mental model.

Your filesystem already knows where things are. ship.md just makes the outside world catch up.

1. Model the world as folders

Each folder is a place — home, office, warehouse, cloud-kitchen. Nesting is meaning.

2. Files are things

skatebrd.txt, laptop.jpg, winter-clothes.txt. If it's in a folder, it's at that location.

3. Move to ship

Drag, mv, or ask an agent. The watcher turns filesystem events into courier calls.

three ways to move

Use whatever interface you already know.

After installing the mac app, ship.md works with Finder, Terminal, and any coding harness that can touch files.

Drag & drop in Finder

Move files between folders the way you always have. ship.md watches the filesystem and turns every drop into a delivery event.

skatebrd.txt → home/

mv in your shell

Any mv, cp, or rsync that lands in a watched folder becomes a real-world move with an audit trail.

mv office/skatebrd.txt home/

Ask your coding harness

agent, Codex, Claude, Pi, Arc — any agent that can move files can now ship things. Same filesystem, same result.

move skateboard from home to office

aagent

CCodex

CClaude

πPi

AArc

ship.md

Every folder can hold a ship.md

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.

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.

POSTheadersparams

audit event · file_observedJSON

{
  "event_id": "be2845cd-342e-4066-93b4-e79aa32d1da2",
  "timestamp": "2026-07-12T08:27:29.028892+00:00",
  "event_type": "file_observed",
  "payload": {
    "event_kind": "created",
    "detected_via": "filesystem",
    "folder_name": "incoming",
    "location": "mumbai",
    "file_name": "laptop.jpg",
    "ship_contexts": [
      {
        "path": "/Users/bosky/ship/warehouse/ship.md",
        "location": "delhi",
        "inventory_items": ["laptop"],
        "emails": ["ops@example.com"]
      }
    ],
    "movement_message":
      "ship.md flow observed: laptop.jpg in incoming (location=mumbai)"
  }
}

agent / codex

Or just ask, in plain English.

agent 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

plan3 task(s)0.0s

execimport json, subprocess0.2s

plan update3/3 ✓0.0s

agent— Moved.

Current file state

· /Users/bosky/ship/eg1/home/skatebrd.txt: gone

· /Users/bosky/ship/eg1/office/skatebrd.txt: exists

planned_tools

[
  {
    "tool": "mv",
    "from": ".../home/skatebrd.txt",
    "to":   ".../office/skatebrd.txt",
    "reason": "ship.md inventory match"
  },
  {
    "tool": "showToast",
    "title": "ship.md moved",
    "message": "skatebrd.txt: home → office"
  }
]

self-host

self host or on-prem or managed portal

SQLite inventory, config, and audit log visibility for the watcher service. Runs on your machine.

DashboardInventoryLogsConfigAPI

Folders

Locations

Subscribers

Inventory rows

Inventory qty

Audit events

215

Paths

Root: /Users/bosky/cp
Support: ~/Library/Application Support/ship-md
Vision model: claude-sonnet-5
Latest event: ship_updated · 09:48:01

Recent logs

› 2026-07-12T09:48:01Z ship_updated e2bd51ff…

› 2026-07-12T09:48:01Z ship_updated 9afbcaf2…

› 2026-07-12T09:48:01Z ship_updated 4ed600e9…

› 2026-07-12T09:48:01Z ship_updated 932f6cf8…

› 2026-07-12T09:48:01Z ship_updated 7f80a9fb…

› 2026-07-12T09:48:01Z ship_updated 3a2acad4…

add your own

Any webhook or logistics API.
Same ship.md

Click a provider to see the ship.md manifest ship.md generates. Same folder, different destination — swap the webhook, keep the audit trail.

25 skills, one manifest

bring your own

ship.mdcourier

## Inventory
- laptop

## Contacts
- email:    ops@example.com
- whatsapp: +15550001111

## Context
- location:   delhi
- provider:   Uber

## Webhook
- url:     https://api.uber.com/v1/customers/{customer_id}/deliveries
- method:  POST
- headers:
    Authorization: Bearer ${UBER_API_TOKEN}
    Content-Type:   application/json
- params:
    pickup_address: {{ context.area }}
    dropoff_address: {{ event.destination }}
    manifest_items: {{ inventory }}

endpoint

POST https://api.uber.com/v1/customers/{customer_id}/deliveries

auth

Bearer: ${UBER_API_TOKEN}

Drop url, method, headers in ship.md
Secrets stay in env — ${TOKEN} interpolated at dispatch
Works with any REST endpoint — courier, checkout, fulfillment, returns

Moving a skateboard home in the real world,as easy as moving files.