Reclaim

A terminal data recovery toolkit for photos and video, with live dashboards.

Reclaim packages a complete recovery workflow into one menu driven CLI: image a failing card or SSD, carve back your photos, find and rebuild video clips, and sort everything by capture date. Each long running step shows a live block map so you can see progress, rate, and results. It was built while recovering a reformatted 128 GB SD card of Sony A7III RAW and 4K footage.

Supports macOS (Apple Silicon and Intel) and Linux. On Windows the file-based steps work too; image a disk from WSL2 (see Windows).

Golden rule: Reclaim never writes to your source. Every source device or image is opened read only, and recovered files go to a different location. When in doubt, image first and work from the copy.

Steps are independent and resumable. Scan for videos one day and carve them another. ddrescue and photorec resume from their map and session files. See docs/USAGE.md.

git clone https://github.com/hjanesh/reclaim
cd reclaim
./install.sh
python3 reclaim.py

Prefer a reclaim command on your PATH? Install it with pipx (or pip):

pipx install .        # then just run:  reclaim

• New Mac with nothing installed? Follow docs/SETUP-MACOS.md, a from zero guide (Xcode tools, Homebrew, git, then Reclaim).
• macOS uses Homebrew. Linux uses apt.
• install.sh installs ddrescue, photorec (from testdisk), ffmpeg, exiftool, and python3, and builds untrunc best effort. If untrunc does not build, complete clips still carve and broken video repair falls back to ffmpeg.

Every path prompt accepts three things:

• Type or paste a path.
• Press f to open a native file or folder picker (Finder on macOS, zenity or kdialog on Linux).
• Press b to go back to the menu.

Output prompts default to a folder inside the repo (output/photos, output/videos, and so on), which is git ignored. Press Enter to accept the default, or type/pick anywhere else.

The menu is the easy path, but every file-based step also runs as a subcommand, which is handy for scripting or repeat runs:

reclaim detect card.img 60                 # find MP4/MOV clips in the first 60 GB
reclaim recover card.img out/ --ref refs/  # carve + repair (refs = a clip or folder of clips)
reclaim organize recovered/ organized/     # dry-run; add --apply to move
reclaim rename recovered/ named/           # dry-run; add --apply to rename
reclaim verify recovered/ --dedup          # check files open; add --apply to move duplicates
reclaim disks                              # list attached drives

reclaim image and reclaim photos stay interactive (they need device selection, sudo, and the live dashboard). Running reclaim with no arguments opens the menu.

The file-based steps (recover from an image, detect, recover video, organize, rename, verify) run on Windows, and reclaim disks lists your drives. Imaging a physical card, though, relies on ddrescue, which is not native to Windows. The reliable route is WSL2: install Ubuntu under WSL, run ./install.sh there, attach the card to WSL with usbipd, and image it from Linux. Then work from the resulting image on either side.

1. Image the media first (option 1). This touches the card or SSD once; all further work reads the safe copy. Use a fast, direct USB-C or Thunderbolt port. Cheap or USB 2.0 cables cap throughput.
2. Recover photos (option 2) from the image.
3. Detect videos (option 3) to see how many clips survived and their state.
4. Recover videos (option 4). Complete clips carve cleanly. For broken ones, supply reference clips shot on the same camera in the same mode (a single file or a folder of references).
5. Organize (option 5) or Rename (option 6) to tidy the results.

The live dashboard is the source of truth. photorec and ddrescue are launched detached, with their own output written to a log file in the output folder (for example output/photos/photorec_run.log), so their text UI cannot interfere with the dashboard.

• Sources are opened read only in code. No repair, format, or fsck is run on your media.
• The tool refuses an output that equals, contains, or sits inside the source (one shared guard, lib/safety.py).
• Imaging refuses a destination on the same physical disk as the source (you can't image a card onto itself) and warns when the destination has less free space than the source.
• Best-effort steps that used to fail silently now record to a reclaim.log in the output folder, so there's an audit trail of what happened.
• SD cards generally do not support TRIM, so a quick or in camera format usually leaves the data intact, which is why recovery works. SSDs do support TRIM, so a reformatted SSD is often unrecoverable. Image it and check, but set expectations low.

See docs/SAFETY.md for the full philosophy and known gotchas.

reclaim.py            main menu + non-interactive CLI
install.sh            dependency installer (macOS and Linux)
lib/
  theme.py            shared UI (palette, panels, live redraw, prompts, picker)
  platform_utils.py   OS, disk listing, native picker, destination guards
  safety.py           the "never clobber the source" path guard
  runlog.py           append-only run log for the output folder
  manifest.py         recovery manifest + checksums
  mp4.py              MP4/MOV atom scan, carve, and clip cache
  ddwatch.py          ddrescue dashboard
  phrec_watch.py      photorec dashboard
  scan_mp4.py         video clip finder dashboard
  video_recover.py    carve and repair videos
  organize.py         relabel and date sort
  rename.py           restore original filenames
  verify.py           validate recovered media + de-dupe
docs/USAGE.md         step by step
docs/SAFETY.md        read only and imaging philosophy
docs/SETUP-MACOS.md   from zero macOS setup

Each lib/*.py also runs standalone, for example python3 lib/scan_mp4.py image.img 60.

Runtime is pure stdlib. Tests and linting use dev-only tools:

python3 -m venv .venv && .venv/bin/pip install pytest ruff
.venv/bin/pytest        # ~50 tests, no external tools or root needed
.venv/bin/ruff check .

The suite covers the risky pure logic (MP4 atom walk/carve/cache, the path-safety guard, the ANSI-aware width helpers, and filename reconstruction) against synthetic fixtures. CI (.github/workflows/ci.yml) runs both on every push and PR.

MIT, 2026 Hemanth Janesh. Contributions welcome.

Built on GNU ddrescue, TestDisk and PhotoRec, FFmpeg, ExifTool, and untrunc.