doctopus
A native macOS document manager: point it at a folder and it OCRs, indexes, tags and files what is inside — without moving anything you did not ask it to.
It takes the organizational ideas of Paperless-ngx and builds them on what macOS already offers: Continuity Camera, Vision OCR, Finder aliases, SQLite, and Apple's on-device Foundation models. Documents stay in ordinary folders that Finder can read with the app closed, and each folder carries its own index, so a library is self-contained and moves with it.
No third-party dependencies.
- Scan a stack of documents straight from an iPhone or iPad without coming back to the Mac in between.
- Search every word in the archive, including the text OCR found in scans.
- File by rules or by what a model read, with everything it proposed reviewable before it counts.
- Never surprised — nothing already in the library moves, is renamed or is deleted without an explicit action.
Installation
With Homebrew, on an Apple silicon Mac with macOS 15 or later:
brew install --cask jansim/tools/doctopus
This installs the latest release into /Applications. The cask always points
at the newest release, so a plain brew upgrade does not notice new ones;
brew upgrade --greedy doctopus fetches it. Releases are ad-hoc signed, not
notarized: the cask removes the quarantine flag so macOS will open the app.
Without Homebrew, download Doctopus.zip from the
latest release, unzip it
and move Doctopus.app to /Applications. macOS will refuse to open it at
first; allow it under System Settings › Privacy & Security › Open Anyway, or
run xattr -dr com.apple.quarantine /Applications/Doctopus.app. Or build it
yourself, see Building.
Building
Requires Xcode 26, for the macOS 26 SDK. Runs on macOS 15 or later.
Scripts/build.sh && open build/Doctopus.app
The script compiles the SwiftPM executable, assembles build/Doctopus.app,
compiles Resources/doctopus.icon with actool — emitting both a layered
Assets.car for macOS 26 and a legacy .icns used on macOS 15 — and ad-hoc
signs the bundle.
Two check suites are built into the binary and run against a generated demo
library — --selftest for the ingest pipeline, --uitest for the panes. Both
run in CI on every push; Testing has the commands.
Pushing a tag such as v1.1 builds the app with that version, runs the
pipeline checks and publishes it as Doctopus.zip in a GitHub release.
Technotes
| Architecture | How the source is layered, and what a library is |
| Storage | The library.doctopus container and the SQLite schema |
| File safety | Exactly what Doctopus will and will not touch on its own |
| Ingestion | Scanning, routing, OCR, optimization, naming |
| Intelligence | The on-device and API model backends |
| Interface | The three panes, review, keyboard |
| Testing | The demo library and the two check suites |
| Coding guidelines | Conventions this codebase holds to |
