Inbox Ingestor

Drop a PDF in a folder. Get clean Markdown a few seconds later. Fully offline — no API key, no rate limits, no cloud dependency, no cost.

Why

If you use an LLM assistant (Claude, ChatGPT, etc.) with filesystem access as part of an Obsidian "second brain" workflow, you've probably hit this: PDFs are unreliable for these tools to read directly — broken tool calls, truncated extraction, or the assistant just asking you to paste the text in manually. Cloud-based conversion (Gemini, GPT-4V, etc.) fixes quality but adds API keys, rate limits, and billing setup for what should be a simple, boring, repeatable task.

This tool sidesteps all of it: a folder watcher that converts PDFs to Markdown locally, using pymupdf4llm. No network call, no key, no quota, no bill.

What it does — and doesn't do

Does: watches a folder, converts any .pdf that appears into a .md file with the same name, right next to it. Preserves headings and tables reasonably well for text-based PDFs.

Doesn't: file the note anywhere, categorize it, or make any decisions about your vault structure — that's a separate step, and honestly one your LLM assistant is much better suited for than a script. This tool solves the reading problem, not the organizing problem.

Won't work well on: scanned/image-only PDFs (no embedded text layer) — those need OCR, which this doesn't do. Text-based PDFs (the vast majority of papers, applications, reports) work well.

Setup

Works identically on macOS, Windows, and Linux — the watcher itself is pure Python.

pip install --upgrade pymupdf4llm watchdog

Then run it, pointing at whatever folder you want watched:

python3 pdf_inbox_watcher.py "/path/to/your/inbox"

Leave that terminal window open and it'll watch continuously. Drop a PDF in the folder, a .md file appears next to it within a couple seconds.

Running it in the background permanently

If you want it to survive reboots and start automatically, pick your OS below.

1. Edit com.inboxingestor.watcher.plist, replacing the two REPLACE_WITH_FULL_PATH_TO placeholders with your actual paths to the script and your inbox folder.
2. Move it into place and load it:

   mkdir -p ~/Library/LaunchAgents
   mv com.inboxingestor.watcher.plist ~/Library/LaunchAgents/
   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.inboxingestor.watcher.plist
   

   (launchctl load still works on some systems but is deprecated — if it fails with Input/output error, use bootstrap as shown above instead.)
3. Verify it's running:

   launchctl list | grep inboxingestor
   

   You should see an actual process ID (not -) in the output.

Common gotcha #1 — TCC / Full Disk Access: if your inbox folder is inside Desktop, Documents, or Downloads, macOS's privacy protections (TCC) will block the background process from reading it, even though it works fine when you run the script manually in Terminal. If you see Operation not permitted in the error log, go to System Settings → Privacy & Security → Full Disk Access and add your python3 binary.

Important: find the real binary, not a symlink — granting FDA to a symlink silently fails to take effect. Run which python3, then resolve it fully:

ls -l "$(which python3)"

If that shows it's a symlink (common with the Xcode Command Line Tools install, e.g. /usr/bin/python3 → /Library/Developer/CommandLineTools/usr/bin/python3, which is itself often another symlink into .../Python3.framework/Versions/X.Y/bin/python3), keep following the chain until you hit the actual file, and grant Full Disk Access to that path. It's also worth pointing the plist's ProgramArguments at this fully-resolved path directly, so there's no ambiguity about which binary launchd executes.

Common gotcha #2 — stale/quarantined plist: if you edited the .plist file with a tool other than a plain text editor or cat/shell redirect (e.g. some GUI tools or scripted writers), it may pick up a com.apple.provenance extended attribute that causes bootstrap to fail with Input/output error. Check with xattr -l ~/Library/LaunchAgents/com.inboxingestor.watcher.plist — if anything shows up, remove it with xattr -d com.apple.provenance ~/Library/LaunchAgents/com.inboxingestor.watcher.plist, or just rewrite the file with cat original.plist > ~/Library/LaunchAgents/com.inboxingestor.watcher.plist to strip it.

To stop it: launchctl bootout gui/$(id -u)/com.inboxingestor.watcher

1. Open Task Scheduler (search for it in the Start menu).
2. Create Task (not "Basic Task" — you want the full dialog for more control).
3. General tab: name it something like PDF Inbox Watcher. Check "Run whether user is logged on or not" if you want it fully background, or leave default for it to run only in your session.
4. Triggers tab → New: set to "At log on" so it starts automatically.
5. Actions tab → New:
   • Program/script: python (or the full path from where python in Command Prompt)
   • Add arguments: pdf_inbox_watcher.py "C:\path\to\your\inbox"
   • Start in: the folder where you saved pdf_inbox_watcher.py
6. Save. Right-click the task and choose Run to test it immediately.

Check Task Scheduler's history/log for the task to confirm it launched without errors.

1. Edit inbox-ingestor.service, replacing the placeholder paths with your actual paths to the script and inbox folder.
2. Install it as a user service:

   mkdir -p ~/.config/systemd/user
   cp inbox-ingestor.service ~/.config/systemd/user/
   systemctl --user daemon-reload
   systemctl --user enable --now inbox-ingestor.service
   

3. Check it's running:

   systemctl --user status inbox-ingestor.service
   

   Should show active (running).

To view logs: journalctl --user -u inbox-ingestor.service -f

Pairing with an LLM assistant (the actual point of this)

The watcher solves conversion. Filing/organizing the resulting notes is a separate, judgment-heavy step — that's where your LLM assistant comes in, if it has filesystem access to your vault (e.g. via an MCP filesystem server for Claude, or a similar plugin for other tools).

A simple pattern that works well:

1. Drop PDFs into your inbox folder throughout the week.
2. The watcher silently converts each to markdown as it lands.
3. Periodically, open a session with your assistant and say something like "process the inbox" — have it read each converted file, decide what kind of note it should become, and file it into the right place in your vault.

This tool is intentionally scoped to do the first two steps reliably and nothing else — the filing logic lives in whatever prompt/procedure doc you use with your assistant, since that's where judgment calls belong, not in a script.

License

MIT — do whatever you want with it, just give us an acknowledgement.

ChronoDyne Systems, Inc.

More Humane Than Human.