filesystem → real world

Moving things in the real world,
as easy as moving files.

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.

Self-host on GitHub See how it works

Drag

drop files to courier

in your shell

Prompt

hermes / codex

~/ship — Create Delivery

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

eg1/office/bike.txt → eg1/home/bike.txt

POSThttps://api.uber.com/v1/eats/deliveries/orders

→ 202 accepted · courier dispatched · audit_id be2845cd…

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

bike.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 Hermes. The watcher turns filesystem events into courier calls.

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 bike.txt from office/ → home/ ships it home
Drop tomatos.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
bike.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
tomatos.txtToday at 2:18 PM
warehouseToday at 2:18 PM
laptop.jpgToday at 2:18 PM
ship.mdToday at 2:18 PM

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.

warehouse/ship.md

# Warehouse ship.md

## Inventory
- laptop

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

## Context
- location:   delhi
- area:       Warehouse Area
- google_pin: https://maps.google.com/?q=warehouse

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.

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)"
  }
}

hermes / codex

Or just ask, in plain English.

Hermes plans, executes, and shows you the audit trail. Same result — a real move with receipts.

move my bike 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

Hermes— Moved.

Current file state

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

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

planned_tools

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

self-host

ship.md admin 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: anthropic/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…

integrations

Wired into the Uber Delivery API.

When a movement resolves to a real-world dispatch, ship.md calls Create Delivery with the resolved context.

OAuth 2.0 bearer with the eats.deliveries scope
Delivery info, order details, and estimate ID resolved from ship.md context
Access may require written approval from Uber

POST/v1/eats/deliveries/orders

api.uber.com

Create Delivery

Schedules a delivery given the delivery information, order details, and estimate ID.

Authorization: Bearer ****

Scope: eats.deliveries

Idempotency-Key: be2845cd-…

Moving things in the real world,as easy as moving files.