ship.md

Moving files in folders, move things in the real world. A mac file monitoring app, to rethink logistics. $ mv ship/clothes/spanish-jersey.png ship/office/

Comment

Inspiration

Everything you see around you was shipped there by someone. Every single thing.

I built ship.md as a standard and app—a macOS file monitor—around a slightly strange idea: the filesystem could be an interface to the physical world.

The original motivation was agents. Coding agents are already good at navigating folders, reading Markdown, and moving files. Giving them another proprietary logistics interface felt unnecessary.

With ship.md, anything capable of manipulating a filesystem can initiate a physical-world workflow. It also works without an agent: drag a file in Finder, use mv, or generate the event from another program.

What it does

Places are folders. Things are files. Moving a file means moving the corresponding physical thing.

For example:

~/ship/
├── home/
│   ├── ship.md
│   └── skateboard.txt
└── office/
    └── ship.md

Then:

mv ~/ship/home/skateboard.txt ~/ship/office/

ship.md observes the move, reads the location and routing context from the nearest ship.md files, writes an audit event, and invokes the configured delivery and notification actions.

A folder manifest can contain:

## Inventory
- skateboard

## Contacts
- email: me@example.com
- whatsapp: +1234567890

## Context
- location: home

## Webhook
- url: https://example.com/deliver
- method: POST

How we built it

The current version is an early macOS implementation written mostly in Python. It includes:

  • A local filesystem watcher
  • SQLite-backed inventory
  • A JSON audit trail
  • A small admin interface
  • Manifest-driven webhook adapters
  • A packaged macOS DMG

The courier integrations are ordinary API calls configured through manifests; there are no special partnerships hidden behind them.

The code and DMG are available at github.com/bosky101/ship.md.

Challenges we ran into

The hardest part is defining what a file move means in the physical world.

Does moving a file express intent, confirm dispatch, or represent completed delivery? Unlike digital files, physical objects cannot be moved instantly or rolled back with a keyboard shortcut.

That raises important questions around confirmation, failure handling, idempotency, permissions, and recovery from accidental moves. The abstraction is deliberately simple, but the real world behind it is not.

Another challenge was preserving the familiarity of ordinary filesystem operations while providing enough context, visibility, and safeguards for physical workflows.

Accomplishments that we're proud of

The basic loop works: a normal filesystem move can trigger an auditable physical-world workflow.

We built a system that agents, shell scripts, desktop users, and other programs can all operate through the same interface. There is no separate agent-only protocol to learn.

We also packaged the prototype as a macOS app with a local watcher, inventory database, audit trail, admin interface, configurable actions, and downloadable DMG.

What we learned

The filesystem is surprisingly expressive as a coordination interface. Folders naturally represent places, files represent things, and Markdown provides human-readable context and configuration.

We also learned that the simplicity of the interface shifts complexity elsewhere. Physical actions need stronger confirmation and state models than ordinary file operations.

The questions we are still exploring are:

  1. Is the filesystem a useful abstraction for logistics, or merely a fun demo?
  2. What confirmation or rollback model would make accidental file moves safe?
  3. Should a move represent intent, confirmed dispatch, or completed delivery?

There are many rough edges, but the mental model is simple enough to test—and hopefully simple enough for people to break in interesting ways.

What's next for ship.md

The next step is to test the model with real users and real workflows, improve safety around accidental moves, and define clearer lifecycle states for physical deliveries.

I have also put up a pricing page at shipmd.app for anyone interested in exploring the product as a customer and helping rethink logistics with me.

The broader goal is to bring the simplicity of files and prompting to a nontechnical audience.

Because, let’s face it: everything you see around you was shipped there by someone. Every single thing.

@boskykode

Built With

Share this project:

Updates