Skip to content

README.md

Latest commit

 

History

History
256 lines (174 loc) · 9.86 KB

README.md

File metadata and controls

256 lines (174 loc) · 9.86 KB
Raw

SaneClick

62 ready-to-use actions for your Finder right-click menu

GitHub stars License: PolyForm Shield Release macOS 14+ Listed on macOS apps list

⭐ Star this repo if it's useful! · Start a free 14-day trial · Buy SaneClick for $14.99 once · Keeps development alive

SaneClick Main Window

🔒 No spying · 💵 No subscription · 🛠️ Actively maintained

The Problem

Every time you right-click in Finder, you're stuck with Apple's limited context menu. Want to convert an image? Open in Terminal? Run a quick script? You have to leave Finder, open another app, navigate back to your file, and do it manually.

Why Can't You Fix It Yourself?

macOS has Services and Folder Actions, but they require Automator knowledge or AppleScript expertise. Most people give up before they start.

Why Alternatives Fail You

The "easy" solutions cost $10-15, require subscriptions, or haven't been updated since 2019. Some are abandonware. Others are overkill.

The Sane Solution

SaneClick gives you 62 ready-to-use actions — no scripting required. Browse by category, toggle on what you need, done.

  • Curated Library: 62 pre-built actions organized by category
  • One-Click Install: Toggle actions on/off instantly
  • Smart Filtering: Actions appear only for matching file types
  • Image and Media Tools: Convert, resize, strip metadata, OCR text, and handle common file chores from Finder
  • PDF and File Workflows: Merge PDFs, hash files, copy paths, create archives, and clean names without opening extra apps
  • Custom Scripts: Power users can write Bash, AppleScript, or Automator workflows
  • Categories: Essentials, Files & Folders, Images & Media, Coding, Advanced

Finder actions process selected files on your Mac. SaneClick does not upload file contents; update and license checks use the limited network requests described in PRIVACY.md.

Pay once. Keep every SaneClick action. No subscription.

Features

Feature Description
62 Pre-built Actions Copy paths, convert images, open in Terminal, OCR images, merge PDFs, and more
5 Categories Essentials, Files & Folders, Images & Media, Coding, Advanced
Smart Filtering Actions appear only for matching file types
Selection Count Filtering Show actions only for single files or multi-select (min/max)
Extension Match Modes "Any file matches" vs "All files must match"
One-Click Install Toggle actions on/off instantly
Custom Scripts Write Bash, AppleScript, or Automator workflows
Test Before Save Run scripts on real files with output preview before committing
Import/Export Share scripts as JSON (skip duplicates, update existing, or replace all)
Menu Bar Quick Access Status bar icon for quick settings, Finder restart, and updates
Extension Status Monitor Color-coded status (green/orange/red) with one-click Finder restart
App Visibility Show/hide the menu bar icon or Dock icon while always keeping one entry point visible

Requirements

  • macOS 14.0+
  • Apple Silicon (arm64) only
  • Xcode 16.0+ (for building from source)
  • XcodeGen (project generation; SaneMaster runs it for you)

Installation

Download

Download SaneClick — start with a free 14-day trial. After the trial, buy once for $14.99 to keep using the app.

Build from Source

Building from source? Consider buying SaneClick to support continued development.

# Clone the repository
git clone https://github.com/sane-apps/SaneClick.git
cd SaneClick

# Build + test (preferred)
./scripts/SaneMaster.rb verify

# Launch
./scripts/SaneMaster.rb launch

SaneMaster runs XcodeGen when needed; only run xcodegen generate manually if you add files and want to refresh immediately.

First Launch

On first launch, follow the setup screen to enable the Finder extension, then start the free 14-day trial or enter a license key. In the main window, use Browse Library to choose actions and Manage Folders to choose where SaneClick appears in Finder.

Enable the Extension

  1. Open SaneClick
  2. Go to System Settings > Privacy & Security > Extensions > Finder
  3. Enable SaneClick

Troubleshooting

Check extension status in Settings > General:

  • Green = Active and working
  • Orange = Enabled but Finder needs restart (use the "Restart Finder" button)
  • Red = Disabled — enable in System Settings

Usage

  1. Choose Built-In Actions: Open Browse Library, then enable the actions you want.
  2. Write a Custom Action: Expand More Options in the main sidebar and choose Write Custom Action.
  3. Configure: Set the name, type (Bash, AppleScript, or Automator), content, icon, and file filters.
  4. Test: Use Test to select files and preview output or errors before saving.
  5. Manage Custom Actions: Use Manage Custom Actions in the sidebar after you create one.
  6. Use in Finder: Right-click a file in a monitored folder and choose a SaneClick action.

Script Variables

Type Variables
Bash $1, $2, etc. for file paths, or $@ for all
AppleScript item 1 of argv to access paths
Automator File paths via standard input

Architecture

See ARCHITECTURE.md for the full system overview and state machines.

SaneClick/
├── SaneClick/              # Host app (settings UI)
│   ├── Models/              # Script, Category models
│   ├── Services/            # ScriptExecutor, ScriptStore
│   ├── Views/               # SwiftUI views
│   └── Theme/               # Brand colors
├── SaneClickExtension/     # Finder Sync Extension
│   └── FinderSync.swift     # Context menu provider
├── Tests/                   # Unit tests
└── docs/                    # Website

Documentation

Document Purpose
README.md Product overview and doc map
ARCHITECTURE.md System design and state machines
DEVELOPMENT.md Build, test, and workflow SOP
PRIVACY.md Privacy practices and limited network behavior
SECURITY.md Security policy and vulnerability reporting
docs/ Public website and guide pages

Our Promise

"For God has not given us a spirit of fear, but of power and of love and of a sound mind." — 2 Timothy 1:7

Pillar Meaning
⚡ Power Your files stay on your device. No cloud account, no personal-content upload.
❤️ Love Built to serve you. No dark patterns or manipulation.
🧠 Sound Mind Calm, focused design. Does one thing well.

Contributing

Before opening a PR:

  1. ⭐ Star the repo (if you haven't already)
  2. Read CONTRIBUTING.md
  3. Open an issue first to discuss major changes

Support

⭐ Star the repo if SaneClick helps you. Stars help others discover quality software.

Stars help SaneClick stay visible to people looking for a maintained Finder utility.

License

PolyForm Shield 1.0.0 — free for any use except building a competing product. See LICENSE for details.

Part of the Sane Apps family.

Third-Party Notices

Third-party open-source attributions are documented in THIRD_PARTY_NOTICES.md.

Become a Contributor (Even if You Don't Code)

Are you tired of waiting on the dev to get around to fixing your problem?
Do you have a great idea that could help everyone in the community, but think you can't do anything about it because you're not a coder?

Good news: you actually can.

Copy and paste this into Claude or Codex, then describe your bug or idea:

I want to contribute to this repo, but I'm not a coder.

Repository:
https://github.com/sane-apps/SaneClick

Bug or idea:
[Describe your bug or idea here in plain English]

Please do this for me:
1) Understand and reproduce the issue (or understand the feature request).
2) Make the smallest safe fix.
3) Open a pull request to https://github.com/sane-apps/SaneClick
4) Give me the pull request link.
5) Open a GitHub issue in https://github.com/sane-apps/SaneClick/issues/new?template=bug_report.md that includes:
   - the pull request link
   - a short summary of what changed and why
6) Also give me the exact issue link.

Important:
- Keep it focused on this one issue/idea.
- Do not make unrelated changes.

If needed, you can also just email the pull request link to hi@saneapps.com.

I review and test every pull request before merge.

If your PR is merged, I will publicly give you credit, and you'll have the satisfaction of knowing you helped ship a fix for everyone.