Initial public release of pdf-tools

Command-line tools for marked-up PDFs and scanned handwritten notes:
pdf-scrub, pdf-notes-md, scan-notes-md (Ollama by default, Claude on
request), scan-notes-index (per-page search metadata), and
scan-notes-stats.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZSvbNaLhgFuTm7wmkgbWs
This commit is contained in:
Eric Furst 2026-11-03 07:25:51 -05:00
commit e464871b69
29 changed files with 5296 additions and 0 deletions

52
scripts/batch-index.sh Executable file
View file

@ -0,0 +1,52 @@
#!/usr/bin/env bash
# batch-index.sh — run scan-notes-index on every transcribed PDF in a folder.
#
# usage: batch-index.sh <folder> [scan-notes-index options...]
#
# PDFs are taken newest first (reverse filename order, which is date order
# for date-prefixed names). A PDF without a <stem>.md transcript is skipped.
# Pages already indexed are kept, so the script can simply be rerun after an
# interruption. A failed PDF is reported and the batch moves on.
#
# Long runs belong in tmux: tmux new -s index 'batch-index.sh ~/notebooks'
set -uo pipefail
if [[ $# -lt 1 || ! -d "$1" ]]; then
echo "usage: $0 <folder> [scan-notes-index options...]" >&2
exit 64
fi
dir="$1"; shift
if command -v scan-notes-index >/dev/null 2>&1; then
run() { scan-notes-index "$@"; }
else
: "${PDF_TOOLS_DIR:?set PDF_TOOLS_DIR or install scan-notes-index}"
run() { (cd "$PDF_TOOLS_DIR" && uv run --quiet scan-notes-index "$@"); }
fi
pdfs=()
while IFS= read -r -d '' f; do pdfs+=("$f"); done \
< <(find "$dir" -type f -iname '*.pdf' -not -name '.*' -print0 | sort -rz)
total=${#pdfs[@]}
done_n=0; skipped=0; failed=()
start=$(date +%s)
for i in "${!pdfs[@]}"; do
pdf="${pdfs[$i]}"
echo "=== [$((i + 1))/$total] ${pdf#"$dir"/} ($(date '+%H:%M'))" >&2
if [[ ! -e "${pdf%.*}.md" ]]; then
echo "no transcript; skipping" >&2
skipped=$((skipped + 1))
continue
fi
if run "$@" "$pdf"; then
done_n=$((done_n + 1))
else
failed+=("${pdf#"$dir"/}")
fi
done
mins=$(( ($(date +%s) - start) / 60 ))
echo "=== finished in ${mins} min: $done_n indexed, $skipped skipped, ${#failed[@]} failed" >&2
for f in ${failed[@]+"${failed[@]}"}; do echo "failed: $f" >&2; done
[[ ${#failed[@]} -eq 0 ]]

56
scripts/batch-scan.sh Executable file
View file

@ -0,0 +1,56 @@
#!/usr/bin/env bash
# batch-scan.sh — transcribe every PDF in a folder with scan-notes-md.
#
# usage: batch-scan.sh <folder> [scan-notes-md options...]
#
# PDFs that already have a <stem>.md are skipped, and an interrupted PDF
# resumes from its last saved page, so the script can simply be rerun. A
# failed PDF is reported and the batch moves on to the next one. Extra
# options are passed to scan-notes-md; the default is --backend ollama, so
# nothing is sent to a cloud service unless you ask for it.
#
# Long runs belong in tmux: tmux new -s scan 'batch-scan.sh ~/notebooks'
set -uo pipefail
if [[ $# -lt 1 || ! -d "$1" ]]; then
echo "usage: $0 <folder> [scan-notes-md options...]" >&2
exit 64
fi
dir="$1"; shift
opts=("$@")
[[ ${#opts[@]} -eq 0 ]] && opts=(--backend ollama)
if command -v scan-notes-md >/dev/null 2>&1; then
run() { scan-notes-md "$@"; }
else
: "${PDF_TOOLS_DIR:?set PDF_TOOLS_DIR or install scan-notes-md}"
run() { (cd "$PDF_TOOLS_DIR" && uv run --quiet scan-notes-md "$@"); }
fi
pdfs=()
while IFS= read -r -d '' f; do pdfs+=("$f"); done \
< <(find "$dir" -type f -iname '*.pdf' -not -name '.*' -print0 | sort -z)
total=${#pdfs[@]}
done_n=0; skipped=0; failed=()
start=$(date +%s)
for i in "${!pdfs[@]}"; do
pdf="${pdfs[$i]}"
md="${pdf%.*}.md"
echo "=== [$((i + 1))/$total] ${pdf#"$dir"/} ($(date '+%H:%M'))" >&2
if [[ -e "$md" ]]; then
echo "already transcribed; skipping" >&2
skipped=$((skipped + 1))
continue
fi
if run "${opts[@]}" "$pdf"; then
done_n=$((done_n + 1))
else
failed+=("${pdf#"$dir"/}")
fi
done
mins=$(( ($(date +%s) - start) / 60 ))
echo "=== finished in ${mins} min: $done_n transcribed, $skipped skipped, ${#failed[@]} failed" >&2
for f in ${failed[@]+"${failed[@]}"}; do echo "failed: $f" >&2; done
[[ ${#failed[@]} -eq 0 ]]

18
scripts/pdf-notes-to-md.sh Executable file
View file

@ -0,0 +1,18 @@
#!/usr/bin/env bash
# pdf-notes-to-md.sh — extract PDF annotations to Markdown next to the PDF.
set -euo pipefail
if [[ $# -lt 1 ]]; then
echo "usage: $0 <pdf> [output.md]" >&2
exit 64
fi
IN="$1"
OUT="${2:-${IN%.pdf}.md}"
if command -v pdf-notes-md >/dev/null 2>&1; then
pdf-notes-md "$IN" -o "$OUT"
else
: "${PDF_TOOLS_DIR:?set PDF_TOOLS_DIR or install pdf-notes-md}"
(cd "$PDF_TOOLS_DIR" && uv run pdf-notes-md "$IN" -o "$OUT")
fi

19
scripts/scan-to-md.sh Executable file
View file

@ -0,0 +1,19 @@
#!/usr/bin/env bash
# scan-to-md.sh — transcribe scanned pages to Markdown.
#
# scan-notes-md itself decides the backend: scans in the confidential
# folders listed in ~/.config/pdf-tools/scan-notes.toml go to Ollama and
# their companion <stem>.md; everything else uses Claude.
set -euo pipefail
if [[ $# -lt 1 ]]; then
echo "usage: $0 <image-or-pdf> [more inputs...]" >&2
exit 64
fi
if command -v scan-notes-md >/dev/null 2>&1; then
scan-notes-md "$@"
else
: "${PDF_TOOLS_DIR:?set PDF_TOOLS_DIR or install scan-notes-md}"
(cd "$PDF_TOOLS_DIR" && uv run scan-notes-md "$@")
fi

49
scripts/scrub-and-mail.sh Executable file
View file

@ -0,0 +1,49 @@
#!/usr/bin/env bash
# scrub-and-mail.sh — scrub a PDF and open a new Mail.app message with it attached.
#
# Usage:
# scrub-and-mail.sh /path/to/file.pdf
#
# Designed to be called from a macOS Quick Action / Service / Shortcut
# with the selected PDF passed as $1.
set -euo pipefail
if [[ $# -lt 1 ]]; then
echo "usage: $0 <pdf>" >&2
exit 64
fi
IN="$1"
if [[ ! -f "$IN" ]]; then
echo "error: not a file: $IN" >&2
exit 1
fi
# Write the scrubbed copy to a temp dir so we don't pollute Dropbox.
TMPDIR_OUT="$(mktemp -d -t pdfscrub)"
BASENAME="$(basename "$IN" .pdf)"
OUT="$TMPDIR_OUT/${BASENAME}_clean.pdf"
# Resolve the CLI. Prefer the installed entry point; fall back to
# `uv run` from the project directory if you keep it ephemeral.
if command -v pdf-scrub >/dev/null 2>&1; then
pdf-scrub "$IN" -o "$OUT" >/dev/null
else
: "${PDF_TOOLS_DIR:?set PDF_TOOLS_DIR to the project path or install pdf-scrub}"
(cd "$PDF_TOOLS_DIR" && uv run pdf-scrub "$IN" -o "$OUT" >/dev/null)
fi
# Hand off to Mail.app. POSIX path -> HFS path for AppleScript's `file`.
osascript <<APPLESCRIPT
set theAttachment to POSIX file "$OUT"
tell application "Mail"
set theMessage to make new outgoing message with properties {visible:true, subject:"$BASENAME"}
tell theMessage
make new attachment with properties {file name:theAttachment} at after last paragraph
end tell
activate
end tell
APPLESCRIPT
echo "opened Mail with: $OUT" >&2