Custodian

Rule-driven file organization for Obsidian.

Custodian turns ordinary vault folders into smart folders. It evaluates an ordered JSON ruleset and moves matching files to static or metadata-driven destinations.

New installations start with an empty ruleset. Custodian does not move files until the user adds and enables a rule.

Install with BRAT

1. Install and enable BRAT in Obsidian.
2. Open BRAT settings and choose Add Beta Plugin.
3. Enter Giblicious/custodian.
4. Enable Custodian under Community plugins.

Custodian supports Obsidian on desktop and mobile.

Rule system

Rules run from top to bottom. The first matching rule owns the file. A rule can use nested all, any, and not groups.

Supported fields:

• Title, path, folder, and extension
• Tags
• YAML frontmatter, including dotted properties such as project.status
• File creation and modification dates

Supported comparisons:

• Exists and does not exist
• Equals and does not equal
• Contains, does not contain, starts with, and ends with
• Glob and regular expression
• Membership in a list
• Greater than and less than
• Before and after

String comparisons are case-insensitive by default. Set caseSensitive to true on a leaf condition when needed. Glob patterns use * as the wildcard.

Example:

{
  "version": 1,
  "rules": [
    {
      "id": "active-project-meetings",
      "name": "Active project meetings",
      "enabled": true,
      "destination": "Projects/{{property:project.name|Unassigned}}/Meetings/{{modified:year}}",
      "conflict": "suffix",
      "when": {
        "all": [
          { "field": "extension", "operator": "equals", "value": "md" },
          { "field": "tag", "operator": "equals", "value": "meeting" },
          {
            "any": [
              { "field": "frontmatter", "key": "status", "operator": "equals", "value": "active" },
              { "field": "folder", "operator": "starts-with", "value": "Projects/Active" }
            ]
          }
        ]
      }
    }
  ]
}

Set manualOnly to true to exclude a rule from automatic organization. Set conflict to skip or suffix. The suffix policy creates a numbered filename instead of overwriting an existing file.

Destination templates

Destinations support:

• {{year}}, {{month}}, and {{day}}
• {{title}} and {{extension}}
• {{property:key}}
• {{created:year}}, {{created:month}}, and {{created:day}}
• {{modified:year}}, {{modified:month}}, and {{modified:day}}

Add a fallback after |, such as {{property:project|Unassigned}}. Template values are sanitized into safe folder names.

Rule authoring prompt

Custodian settings include Copy authoring prompt. The prompt documents the exact supported schema and includes the current ruleset. Give it to an assistant with a description of the desired filing behavior, then paste the returned JSON into the ruleset editor.

Custodian validates the complete document before saving. Invalid JSON, duplicate rule IDs, unsupported fields or operators, malformed templates, unsafe paths, invalid regular expressions, and excessive nesting are rejected without replacing the saved ruleset.

Commands

• Preview file organization: list planned moves without changing the vault
• Organize all files now: apply all enabled rules, including manual-only rules
• Copy rule-authoring prompt: copy the schema and current ruleset

Safety

• Custodian never overwrites files.
• Excluded folders are never used as move sources.
• Automatic moves are serialized to avoid folder-creation races.
• Self-triggered file events are suppressed.
• Repeated automatic moves are stopped when overlapping rules cause a loop.
• Existing version 0.1.1 rules are migrated automatically.

Use the preview command before applying a new ruleset to a large vault. Keep a current backup or version history for the vault.

Privacy

Custodian works entirely inside Obsidian. It has no network requests, telemetry, accounts, advertising, or analytics. The authoring prompt is copied to the clipboard only; Custodian does not contact an assistant itself.

Development

npm install
npm run check

Create a numeric version tag matching manifest.json to publish the BRAT release assets.

License

MIT