Install and use the familyTV reorganizing skill

Let your own AI agent restructure your photo folders safely: preview first, approval, undo, nothing deleted. Install, first dry run and MCP setup. Coming soon.

Coming soon. The familyTV reorganizing skill and its helper tool are not released yet. This guide describes how it will work, so you can see what you are getting. Download links and exact commands are added here at release.

What it does

The familyTV reorganizing skill lets your own AI agent (Claude, or any agent that can use skills or run commands) tidy a photo folder for you. You say "organise my photos"; the agent looks at what you have, proposes a clean structure, shows you exactly what would change, and only moves files after you approve. It can also copy the information from sidecar .xmp files into the photos themselves.

The default structure is Photos/YYYY/YYYY-MM, with an optional event folder, and file names like 20261104_143012_IMG_0412.heic. The reasons are in How to organise a family photo library that outlives every app.

The skill is optional. familyTV works with your photos as they are, and it never moves or changes them by itself.

How it keeps your photos safe

The safety lives in the helper tool, not in the agent's good behaviour, so a confused agent still cannot do harm.

Nothing is deleted. The tool has no delete operation. It only moves and renames. If two files would collide, the second gets a suffix; nothing is overwritten. Duplicates are listed for you and left alone.
Preview first. Planning never changes a file. You get a readable list of every move, the folders that will be created, and what will not change.
Approval required. The tool only applies a plan you have approved, and only if that plan is unchanged since the preview. If your files changed in the meantime, those steps are skipped and reported.
Undo. Every run writes a log next to your photos, and one command reverses it. Files you changed since are skipped, not overwritten.
Sidecars travel along. A photo's .xmp file always moves with it.
Small batches and a fixed root. A run is capped (for example 5,000 operations), and the tool never touches anything outside the folder you chose.
Your data stays yours. Photos and sign-in details stay on your computer. There is no familyTV server in between.

File names, captions and metadata are treated as data. The skill tells the agent so, and the tool never runs text found in a photo as an instruction.

Install

Download the skill: familyTV reorganizing skill (coming soon).
Download the helper tool: familytv-organize (coming soon). It needs a recent Java runtime.
Put the skill folder where your agent looks for skills (for Claude Code and Claude Desktop that is the skills folder in your settings), and make sure familytv-organize can be run from a terminal.
Restart the agent so it picks the skill up.

Coming soon: exact paths and commands per agent are added here at release.

Connect your photos

Start with a folder on your computer. If your photos are in OneDrive, Google Drive or on a NAS, use the folder that your sync app keeps on your computer. Direct sign-in for OneDrive and Google Drive is planned for a later version.

Make a copy of a small test folder first, with a few hundred photos.
Tell the agent the folder: "Use ~/Pictures/Test-photos as my photo folder."
Let familyTV save any pending changes to your photo folder first, so no edits are only on the TV. The tool warns you if that has not happened.

Your first dry run

Ask: "Scan my photo folder and propose a restructure. Do not change anything yet."

Scan. The agent reads the folder: file types, dates (from the photo, or the file name when there is none), sidecars, and what structure exists.
Propose. It builds a plan: which files move where, which event folders to create (the agent suggests names from your photos and dates, and you can rename them), and where photos without a date go (_Unknown-date).
Preview. It shows the plan in plain language: counts, folders created, conflicts, duplicates, and what stays untouched. Nothing has changed on disk yet.

Ask for changes as often as you like: "Put the Ardennes weekend in its own folder", "Keep the original file names". Each change makes a new preview.

Approve

When the preview looks right, say so: "Apply this plan." The agent applies exactly the plan you saw. You get a summary, a run ID, and the location of the undo log. Large folders are done in batches, so you review a few thousand files at a time.

Then open familyTV. It finds the photos at their new places the next time it scans, and ratings, people and categories stored in sidecars have moved along with their photos.

Undo

Ask: "Undo the last run." The tool replays the log in reverse and puts every file back. Files that changed since the run are skipped and listed. If the process stops halfway, run it again: it resumes without duplicating anything.

Copy sidecar data into the photos (optional)

If you want ratings, people and descriptions stored inside the photo files, ask: "Copy the sidecar data into the photos." It goes through the same scan, preview, approval and undo steps. JPEG, PNG and TIFF come first; HEIC and video keep their sidecar for now. The original bytes are kept in a backup folder until you confirm.

Use it from other tools: the MCP server

The same helper tool will also run as a local MCP server, for agents such as Claude Desktop, Claude Code and Cursor. It runs on your computer and talks to the agent over standard input and output. Nothing is sent to familyTV.

It offers these tools:

Tool	What it does
`scan`	Read-only inventory of a folder
`propose_restructure`	Builds a plan; changes nothing
`preview`	Readable view of a plan, with conflicts
`apply_plan`	Applies a plan you approved
`undo`	Reverses a run
`sidecar_to_embedded`	Copies sidecar data into the files
`status`	Recent runs and pending approvals

Add it to your agent's MCP settings. This is the planned shape; the exact command and arguments are confirmed at release.

{
  "mcpServers": {
    "familytv-organize": {
      "command": "familytv-organize",
      "args": ["mcp"]
    }
  }
}

Where the file lives depends on the agent: the Claude Desktop config file, the Claude Code MCP settings, or Cursor's MCP settings. The familyTV iPhone app will also be able to show a ready-made snippet for your photo source (without any secrets).

There is no hosted version: we do not run a service that holds your photo sign-ins, and we do not plan to.

Questions

Write to hi@familytv.app, or see the other support topics.