📸 picofall

picture of all — a fast, local, keyboard-driven photo sorter.

Blaze through a pile of photos and file each one into a folder with a single keypress.

">https://img.shields.io/badge/node-%3E%3D16-5b8cff">

---

Why

You just dumped 500 photos off a camera and now you have to sort them into Solo, Family, Friends, Ceremony… Dragging them one by one in Finder is misery. picofall shows you one photo at a time, full-screen, and you press a number key to file it. That's it. A few hundred photos take minutes, not hours.

• ⌨️ Keyboard-first — 1–9 files a photo into a category instantly.
• 🗂️ Real folders — photos are physically moved on disk into category folders. No database, no lock-in.
• ↩️ Undo — mis-file something? Press U and it goes right back where it was.
• 📥 Living inbox — keep dropping new photos into the folder; picofall picks them up automatically while you work.
• 🔒 100% local & private — nothing leaves your machine. No accounts, no cloud, no telemetry.
• 🪶 Zero dependencies — pure Node.js. Nothing to npm install.

Requirements

• Node.js ≥ 16
• macOS gets fast, cached thumbnails via the built-in sips tool. On Windows/Linux picofall falls back to serving the original image bytes (still works, just heavier).

Quick start

git clone https://github.com/abiekaputra/picofall.git
cd picofall

# sort a specific folder of photos
node server.js /path/to/your/photos

# …or just run it and drop photos into the ./photos folder it creates
npm start

Then open http://localhost:5178 in your browser.

Pointing it at a folder

picofall sorts one working directory. The subfolders inside it are your piles; you pick which are "sources" (to sort) and which are "categories" (destinations). Resolution order:

Priority	How	Example
1	CLI argument	node server.js ~/Pictures/2024
2	PICOFALL_DIR env var	PICOFALL_DIR=~/Pictures/2024 npm start
3	default	./photos (created automatically)

Change the port with PORT=8080 npm start.

How to use

1. Pick source folder(s) — the "raw" piles you want to sort through.
2. Choose categories — existing folders appear automatically; add new ones (they're created as real folders).
3. Start sorting — one photo at a time. Press the number next to a category to move it there.

Keyboard shortcuts

Key	Action
1–9	Move the current photo to that category
→ / Space	Skip (leave it, go to next)
←	Go back
U	Undo the last move
F	Toggle full-resolution view
N	Create a new category
R	Rescan the source folder for newly added photos

How it works

A tiny zero-dependency Node HTTP server (server.js) serves a single-file web UI (public/index.html). Sorting a photo hits POST /api/move, which physically relocates the file into the destination folder — never overwriting (name clashes get (1), (2), …). Every move is appended to a local moves.log.jsonl so you always have a record. Thumbnails are cached under .cache/.

All paths from the browser are resolved relative to the working directory and rejected if they try to escape it.

Safety

• Photos are moved, not copied or deleted — nothing is ever thrown away.
• Undo restores the exact original name and location.
• Runs only on localhost; it is not exposed to your network.

Contributing

Issues and PRs welcome. It's intentionally small and dependency-free — please keep it that way. 🙏

License

MIT © Abi Eka Putra Wulyono