flowsquire

FlowSquire

A local-first automation platform for organizing files on your computer. No cloud, no AI, no subscriptions — just simple WHEN → DO workflows.

Getting Started in 2 Minutes

npm install -g flowsquire
flowsquire init      # 30 sec setup wizard
flowsquire start     # Drop a file in ~/Downloads

That's it. Your files organize themselves.

Features

• File Watching: Automatically organize files as they appear
• Smart PDF Workflow: Sort PDFs by keywords (invoice, bank, notes, etc.) with automatic compression
• Downloads Organizer: Sort images, videos, music, archives, documents, installers, and code files
• Screenshot Organizer: Organize screenshots by app, website domain, and date (macOS)
• Priority-Based Rules: Higher priority rules execute first
• Dry-Run Mode: Preview actions before executing
• PDF Compression: Automatically compress large PDFs (configurable threshold, default: 8MB)
• Interactive Setup: Guided wizard for first-time configuration

Installation

npm install -g flowsquire

Prerequisites

Ghostscript (required for PDF compression):

# macOS
brew install ghostscript

# Ubuntu/Debian
sudo apt-get install ghostscript

# Windows
# Download from https://www.ghostscript.com/download/gsdnld.html

Note: Without Ghostscript, PDF compression will fail, but all other features work normally.

Quick Start

# Run interactive setup wizard
flowsquire init

# Start the file watcher
flowsquire start

# Or with dry-run (preview only)
flowsquire start --dry-run

Interactive Setup

During flowsquire init, you'll be asked:

• Watch folder — Where to watch for new files (default: ~/Downloads)
• Documents folder — Where to organize documents (default: ~/Documents)
• Screenshots folder — Where screenshots are saved (default: ~/Downloads/Screenshots)
• Downloads organizer mode:
  • nested — Organize inside Downloads subfolders (Images/, Videos/, etc.)
  • system — Move to system folders (Pictures/, Movies/, Music/, etc.)
• PDF compression threshold — Size in MB above which PDFs are compressed (default: 8)
• Screenshot organizer mode:
  • metadata — Organize by App/Domain (macOS only)
  • by-app — Organize by App name only
  • by-date — Organize by date (works on all platforms)

Templates

PDF Workflow (6 rules)

Automatically organizes PDFs based on filename and size:

Priority	Rule	Condition	Nested Mode Destination	System Mode Destination
500	Large PDF Compression	> threshold (default: 8MB)	~/Downloads/PDFs/{category}/Compressed/	~/Documents/PDFs/{category}/Compressed/
450	arXiv Research Papers	YYMM.NNNNN format	~/Downloads/PDFs/Research(arXiv)/	~/Documents/PDFs/Research(arXiv)/
400	Invoice Organizer	invoice, bill, payment, receipt, tax	~/Downloads/PDFs/Invoices/	~/Documents/PDFs/Invoices/
300	Bank Statement	bank, statement, transaction, finance, credit, debit	~/Downloads/PDFs/Finance/	~/Documents/PDFs/Finance/
200	Study Notes	notes, note, lecture, study, class, course, assignment, homework, exam	~/Downloads/PDFs/Study/	~/Documents/PDFs/Study/
100	Default	any PDF	~/Downloads/PDFs/Unsorted/	~/Documents/PDFs/Unsorted/

Features:

• Cross-platform Ghostscript support (macOS/Linux: gs, Windows: gswin64c)
• Quality levels: screen (low), ebook (medium), printer (high)
• Preserves original filenames
• Configurable compression threshold (set during flowsquire init)

Smart Compression: Large PDFs exceeding your configured threshold are automatically categorized before compression:

• Original file → PDFs/{category}/
• Compressed copy → PDFs/{category}/Compressed/

arXiv Research Papers: Academic papers from arXiv.org are automatically detected by their standardized filename format:

• New format (2015+): YYMM.NNNNN (e.g., 2601.16163.pdf)
• Old format (2007-2014): YYMM.NNNN (e.g., 0706.0001.pdf)
• Versioned: YYMM.NNNNNvV (e.g., 2601.16163v1.pdf)

Example: 2601.16163v1.pdf → PDFs/Research(arXiv)/2601.16163v1.pdf

Note: Currently only arXiv papers are auto-detected for the Research category. Support for other academic paper sources (DOI-based filenames, keywords like "paper", "journal", "conference") is planned for future releases.

Categories detected from filename:

• Invoices: invoice, bill, receipt, rechnung, facture, factura, fattura, fatura, factuur, счет, 发票, 請求書, 세금계산서, فاتورة
• Finance: bank, statement, transaction, kontoauszug, banque, banco, banca, банк, 银行, 銀行, 은행, بنك
• Study: notes, lecture, study, assignment, homework, exam, notizen, vorlesung, cours, notas, заметки, 笔记, ノート, 노트, ملاحظات
• Unsorted: Everything else

Multilingual Support:
FlowSquire automatically detects PDF categories in 12 languages: English, German, French, Spanish, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Korean, and Arabic. Files like Rechnung_2026.pdf, ACME銀行_statement.pdf, or 发票_2026.pdf are automatically sorted into the correct category.

Example: invoice_large.pdf (10MB) → PDFs/Invoices/invoice_large.pdf + PDFs/Invoices/Compressed/invoice_large_compressed.pdf

Downloads Organizer (7 rules)

Sorts non-PDF files by type:

Type	Extensions	Nested Mode Destination	System Mode Destination
Images	jpg, jpeg, png, gif, webp, svg	~/Downloads/Images/	~/Pictures/Downloads/
Videos	mp4, mov, avi, mkv	~/Downloads/Videos/	~/Movies/
Music	mp3, wav, flac, aac	~/Downloads/Music/	~/Music/
Archives	zip, rar, 7z, tar, gz	~/Downloads/Archives/	~/Documents/Archives/
Documents	doc, docx, txt, rtf, xls, xlsx, ppt, pptx	~/Downloads/Documents/	~/Documents/Documents/
Installers	dmg, pkg, exe, msi	~/Downloads/Installers/	~/Documents/Installers/
Code	js, ts, jsx, tsx, py, rb, go, rs, java, cpp, c, h	~/Downloads/Code/	~/Documents/Code/

Screenshot Organizer

Organizes screenshots based on your chosen mode:

Metadata Mode (macOS only, requires Accessibility permissions):

• Organizes by: AppName/Domain/{filename}_{date}_{time}.png
• Example: Google Chrome/aistudio.google.com/SCR-2026-02-01_16-41.png
• Captures: foreground app, browser URL, window title

By App Mode:

• Organizes by: AppName/{filename}.png
• Example: Google Chrome/SCR-20260201-ornd.png

By Date Mode (works on all platforms):

• Organizes by: Year/Month/{filename}.png
• Example: 2026/February/SCR-20260201-ornd.png

Note: On non-macOS platforms, metadata mode falls back to by-date automatically.

CLI Commands

flowsquire init                          # Interactive setup wizard
flowsquire start                         # Start file watcher
flowsquire start --dry-run               # Preview mode (no actual changes)
flowsquire rules                         # List all rules
flowsquire config                        # Show all configured paths and settings
flowsquire config --<key> <value>        # Set a config value
flowsquire config --<key>                # Get a config value

Config Options

Path Settings:

• --downloads <path> — Watch folder for new files
• --documents <path> — Documents organization folder
• --screenshots <path> — Screenshots folder
• --pictures <path> — Pictures folder
• --videos <path> — Videos/Movies folder
• --music <path> — Music folder

Mode Settings:

• --downloads-mode <nested|system> — Downloads organizer mode
• --screenshot-mode <metadata|by-app|by-date> — Screenshot organizer mode
• --pdf-compression-threshold-mb <number> — PDF compression threshold in MB

Examples:

flowsquire config --downloads ~/Downloads
flowsquire config --downloads-mode system
flowsquire config --screenshot-mode by-date
flowsquire config --pdf-compression-threshold-mb 12

Note: After changing modes, delete rules and re-run flowsquire init to regenerate rules.

Rule Structure

Rules are stored in .flowsquire/rules.json:

{
  "id": "...",
  "name": "My Rule",
  "enabled": true,
  "priority": 100,
  "tags": ["pdf", "invoice"],
  "trigger": {
    "type": "file_created",
    "config": { "folder": "/Users/me/Downloads" }
  },
  "conditions": [
    { "type": "extension", "operator": "equals", "value": "pdf" },
    { "type": "name_contains", "operator": "equals", "value": "invoice" }
  ],
  "actions": [
    {
      "type": "move",
      "config": {
        "destination": "/Users/me/Documents/Invoices",
        "pattern": "{filename}_{YYYY}-{MM}-{DD}",
        "createDirs": true
      }
    }
  ]
}

Condition Types

• extension — File extension (e.g., "pdf", "jpg")
• name_contains — Filename contains text (case-insensitive)
• name_starts_with — Filename starts with text
• name_ends_with — Filename ends with text
• size_greater_than_mb — File size in MB

Action Types

• move — Move file to destination
• copy — Copy file to destination
• rename — Rename file
• compress — Compress PDF (requires Ghostscript)

Pattern Placeholders

Date/Time:

• {filename} — Original filename without extension
• {YYYY} — Year (2026)
• {MM} — Month number (01-12)
• {Month} — Month name (January, February, etc.)
• {DD} — Day (01-31)
• {HH} — Hour (00-23)
• {mm} — Minute (00-59)
• {ss} — Second (00-59)

Screenshot Metadata (macOS only):

• {app} — Foreground application name (e.g., "Google Chrome")
• {domain} — Website domain (e.g., "github.com")

Development

# Clone repo
git clone [e-mail]:miit-daga/flowsquire.git
cd flowsquire

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode
npm run dev

# Test
npm test

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   CLI       │────▶│  File Watcher│────▶│  Rule Engine│
│  (cli.ts)   │     │  (chokidar)  │     │             │
└─────────────┘     └──────────────┘     └──────┬──────┘
                                                 │
                        ┌──────────────┐        │
                        │   Actions    │◀───────┘
                        │ (move/copy/  │
                        │  compress)   │
                        └──────────────┘

License

MIT

Philosophy

Your computer should work for you. Not the other way around.