New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Folder-tree templates that seed, restructure, and date-sort folders with undoable, plan-first moves.

version
1.0.0
GitHub stars
32
View on GitHub

What it does

  • Adds seed-tree, restructure-tree, sort-by-date, add-template, and setup skills for dated folder layouts
  • Covers month, year/month, year/month/day, flat DDMMYY, and current-and-past templates, plus custom ones in a private overlay
  • Plans every file move first, applies only on confirmation, and writes an undo log; name clashes get a suffix instead of overwriting
  • Designed for users who keep dated archives and want exiftool-based sorting by photo or document creation date

Dated folder-tree templates (months, year/month, year/month/day, flat DDMMYY, current-and-past): seed them, restructure existing trees into them, sort files by metadata date. Your own templates live in a private overlay.

Add marketplace

/plugin marketplace add danielrosehill/Claude-Code-Plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install folder-tree-templates@danielrosehill

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Add a folder-tree template

Load first

Run ${CLAUDE_PLUGIN_ROOT}/scripts/ftt.py where (needs uv). It reports the overlay folder and profile.env (DEFAULT_TEMPLATE, DATE_SOURCE). Use those as defaults. Every ftt.py command prints JSON.

New templates go to the user's overlay, <overlay>/templates/<name>.yaml, not into the plugin. Only a layout that is generic and useful to anyone belongs upstream in the plugin's templates/, and only when the user asks for that.

Template format

name: year-month-names            # kebab-case, the file name without .yaml
title: Year, then month name      # short human label
description: Four-digit year, then 01-Jan style month folders.
pattern: "{yyyy}/{mm}-{mon}"      # folder levels separated by /
seed: year                        # year | month: default range for seeding
triggers: [year month names]      # phrases that should pick it
notes: Optional caveats shown with the template.
example: ["2026/01-Jan", "2026/02-Feb"]

Tokens: {yyyy} 2026, {yy} 26, {mm} 01, {mon} Jan, {month} January, {dd} 01, {slot} current for the marker's current year, else {yy}. Any other text is literal (Q-{mm}, {yyyy} Photos). Each token at most once per folder level. Matching is case-insensitive when reading existing trees.

Steps

  1. Get the layout from the user, ideally as two or three example folder paths. Write the pattern from them, and check: does the leading level need a year? Does the order sort chronologically (name the trap if not)? Would seed: month be wiser because the template has a day level?
  2. Write the YAML to a temp file and run ftt.py validate <file>. Fix any errors. Show the user the sample; if shadows is set, the name overrides an existing template, so confirm or rename.
  3. Save to <overlay>/templates/<name>.yaml (create the folder if missing) and state the path.
  4. Confirm with ftt.py list that it appears with source: user. If the overlay is a git repository, commit just that file.

Data storage

  • Templates: built-ins in ${CLAUDE_PLUGIN_ROOT}/templates/, the user's own in <overlay>/templates/. A user template with the same name wins.
  • Each organised tree gets a .folder-tree.json marker at its root: template, pattern, current_year.
  • Undo logs: ${CLAUDE_PLUGIN_DATA}/logs/ (fallback <overlay>/cache/logs/).

Readme

Folder Tree Templates

Dated folder trees from templates. Create them where they're missing, move an existing tree from one layout to another, and file loose files by their metadata date. Built-in templates ship with the plugin; your own go in a private overlay.

Templates

TemplatePatternExample
months-numeric{mm}01 … 12
months-numbered-names{mm}-{mon}01-Jan … 12-Dec
months-short{mon}Jan … Dec
year-month{yy}/{mm}25/01
year-month-day{yy}/{mm}/{dd}26/01/01
year-monthname-day{yy}/{mon}/{dd}26/Jan/01
flat-ddmmyy{dd}{mm}{yy}010126 (1 Jan 2026)
current-and-past{slot}/{mm}current/01, 25/01

Tokens: {yyyy} {yy} {mm} {mon} {month} {dd} {slot} (current for the tree's current year, else {yy}). Other text is literal.

Skills

  • seed-tree: creates a template's folders for a year, a month or a date range. It only creates missing folders. It also covers the current-and-past year rollover.
  • restructure-tree: detects the layout an existing tree follows and converts it to another template (e.g. Jan/ → 25/01/). It plans first, applies on confirmation and can be undone.
  • sort-by-date: files loose files into a template using EXIF/QuickTime/PDF dates via exiftool, falling back to modified time. It plans first and can be undone.
  • add-template: writes a new template to your overlay and validates it.
  • setup: creates the overlay with a default template and date source.

Engine

scripts/ftt.py does the deterministic work and prints JSON. It needs uv (PyYAML is resolved inline); exiftool is optional.

ftt.py list | show NAME | validate FILE | where
ftt.py seed NAME TARGET [--year Y | --month YYYY-MM | --from D --to D] [--apply]
ftt.py detect TARGET
ftt.py convert TARGET --from A --to B [--year Y] [--apply]
ftt.py sort SRC --template NAME [--into DIR] [--source auto|exif|mtime] [--recursive] [--apply]
ftt.py rollover TARGET [--apply]
ftt.py undo LOG

Commands that move files only plan unless given --apply. Each applied run writes an undo log. Name clashes get (2) and nothing is overwritten. Each organised tree gets a .folder-tree.json marker recording its template and current year.

Your templates (overlay)

Your own templates are YAML files in <overlay>/templates/. A file there with the same name as a built-in replaces it. The overlay folder is the first of these that applies:

  1. $FOLDER_TREE_TEMPLATES_HOME
  2. $CLAUDE_USER_DATA/folder-tree-templates
  3. ~/.claude-user-data/folder-tree-templates (if ~/.claude-user-data exists)
  4. ${XDG_DATA_HOME:-~/.local/share}/claude-plugins/folder-tree-templates (if that root exists)
  5. otherwise ~/.claude-user-data/folder-tree-templates

profile.env there sets DEFAULT_TEMPLATE and DATE_SOURCE. Undo logs go to ${CLAUDE_PLUGIN_DATA}/logs/.

The template format is in skills/add-template/SKILL.md and docs/engine.md.

Installation

claude plugins marketplace add danielrosehill/Claude-Code-Plugins
claude plugins install folder-tree-templates@danielrosehill

License

MIT

Details

Marketplace
danielrosehill/Claude-Code-Plugins
Source
danielrosehill/Folder-Tree-Templates
Author
Daniel Rosehill
Category
Linux Sysadmin
License
MIT

More from danielrosehill/Claude-Code-Plugins

All 264

Similar to folder-tree-templates

More Development Tools