LL Agent

Your Photos. Your Machine. Your Rules.

LL Agent is the AI bridge for LocalLens — a privacy-first photo organizer that runs 100% on your computer. Connect it to Claude Desktop (or any MCP-compatible AI) and organize, search, and manage your entire photo library using plain English.

Zero data leaves your machine. Not even metadata.

🎉 Used LL Agent during the free preview? You keep every Pro feature free, permanently — no key, nothing to do. Not a trial ending — a thank-you for being here early. New here? The Free tools are free forever; Pro is a yearly or monthly plan: locallensmcp.vercel.app/pricing.

---

What you can do

Say this…	What happens
"Sort my vacation photos by location"	Organized into folders by city/state in seconds
"Find all photos of Mom from last Christmas"	Face recognition + date filtering, no upload needed
"Find duplicate photos in my Downloads"	Reclaims gigabytes, with a safe dry-run preview
"Watch my camera roll and auto-sort new photos"	Real-time folder monitoring, organizes on arrival
"What can LocalLens do?"	Interactive feature guide, right in the chat

---

Quick Install ⇣

macOS (Homebrew) — Recommended

brew install ashesbloom/locallens/locallens-agent

Homebrew handles Gatekeeper automatically — no extra steps needed!

macOS (Manual DMG)

1. Download the .dmg from Releases
2. Drag LocalLens Agent.app to Applications
3. Fix Gatekeeper (required for unsigned apps):
   • The DMG includes a Fix LocalLens Agent.command file. Double-click it.
   • If macOS blocks double-click, run in terminal: bash ~/Downloads/Fix\ LocalLens\ Agent.command
   • Or run manually in terminal:

     xattr -cr "/Applications/LocalLens Agent.app" && codesign --force --deep --sign - "/Applications/LocalLens Agent.app"

---

Prerequisites

1. LocalLens app must be installed and running → Download
2. Claude Desktop (or any MCP-compatible client)

---

Installation

Option 1 — Download Binary (Recommended)

Download the latest release for your platform from the Releases page:

Platform	File
macOS (Apple Silicon)	locallens-mcp-vX.Y.Z-macos-arm64.zip
macOS (Intel)	locallens-mcp-vX.Y.Z-macos-x86_64.zip
Windows	locallens-mcp-vX.Y.Z-windows-x86_64.zip
Linux	locallens-mcp-vX.Y.Z-linux-x86_64.tar.gz

Extract the archive, then run the one-time connector setup:

./locallens-mcp --setup-claude

(Windows: .\\locallens-mcp.exe --setup-claude)

Note

On macOS the binary is unsigned. If the OS warns that the developer cannot be verified, allow it in System Settings → Privacy & Security, or clear the quarantine flag:

xattr -dr com.apple.quarantine locallens-mcp

Option 2 — macOS Menu Bar Agent (Tray App)

For a point-and-click experience on macOS, download the LocalLens Agent DMG from the Releases page:

Platform	File
macOS (Apple Silicon)	locallens-agent-vX.Y.Z-macos-arm64.dmg
macOS (Intel)	locallens-agent-vX.Y.Z-macos-x86_64.dmg

Open the DMG, drag LocalLens Agent to Applications, and launch it. A menu bar icon (LL) will appear. From there you can:

• Connect / disconnect from Claude Desktop with one click
• Start and stop the LocalLens backend
• Check for updates
• Copy custom instructions for Claude

Option 3 — Install from Source (Python Developers)

Requires Python 3.10+:

git clone https://github.com/ashesbloom/locallens_mcp_agent.git
cd locallens_mcp_agent
pip install -e .

---

Connect to Claude Desktop

Automatic (Recommended)

Run once after installing:

locallens-mcp --setup-claude

Then restart Claude Desktop. LocalLens tools appear in the tool panel automatically.

To check status or disconnect later:

locallens-mcp --claude-status   # print connection state as JSON
locallens-mcp --remove-claude   # remove LocalLens from Claude's config

Manual

Add the following to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "locallens": {
      "command": "locallens-mcp"
    }
  }
}

Restart Claude Desktop. LocalLens tools will appear in Claude's tool panel.

See claude_desktop_config.example.json for an annotated example.

---

Free vs Pro

Free tools work for everyone. Pro tools need a license key — except for anyone who used LL Agent during the free preview, who keeps Pro free.

Free Tools

Available to everyone, no license required:

Tool	What it does
check_app_status	Check if LocalLens is running and healthy
get_stats	Library-wide statistics (photo count, locations, people)
get_job_progress	Poll the status of a running sort/find job
locallens_help	Interactive guide to features, topics, and workflows
get_enrolled_faces	List all enrolled people in the face recognition system
get_path_presets	Retrieve saved folder path presets
analyse_folder	Scan a folder: subfolder list, photo counts, locations, people
start_sorting	Sort photos by Date, Location, or People
start_find_group	Filter photos by person, location, and date — copy to a new folder
abort_job	Cancel a running sort or find job
open_folder	Open a folder in the system file browser
remember_paths	Save a folder path as a named preset for reuse
forget_paths	Remove a saved folder path preset
activate_pro_license	Activate a Pro license key
get_license_status	Check your current license tier
revoke_pro_license	Deactivate and remove the local Pro license

Pro Tools

Require an active Pro license (activate_pro_license), or a free-preview install:

Tool	What it does
add_face_enroll	Enroll one or more people for face recognition
find_duplicates	Detect duplicate photos in a folder
delete_duplicates	Safely remove duplicates (always dry-run first)
export_report	Generate a summary report of a folder's contents
schedule_auto_organize	Run an auto-sort sweep every N hours
create_active_folder	Watch a folder and organize new photos in real time
list_schedules	List all active schedules and folder watchers
manage_schedule	Pause, resume, or delete a schedule
open_scheduler_dashboard	Open the scheduler web dashboard
smart_album_suggestions	Album grouping suggestions (coming soon — not yet functional)

Quick comparison

Feature	Free	Pro
Folder analysis	✅	✅
Sort by date / location / people	✅	✅
Find & Group (filter by person + place + date)	✅	✅
Job progress & abort	✅	✅
Path memory (remember / forget)	✅	✅
See who is enrolled for face recognition	✅	✅
Batch face enrollment (add_face_enroll)	—	✅
Duplicate detection & cleanup	—	✅
Export reports	—	✅
Scheduled auto-organize (every N hours)	—	✅
Real-time folder watching	—	✅

Activating Pro

LL Agent Pro is a yearly or monthly subscription, sold through Dodo Payments as merchant of record (they handle payment and tax, and email your license key). There is no lifetime plan. To activate, either:

• In the app: click LL in the menu bar (on Windows, the system tray), choose Activate Pro…, and paste your key; or
• In Claude Desktop: say "activate my LL Agent license" followed by your key.

Activation needs the internet. A subscription then re-checks about once a week and keeps working for 14 days offline; a founding key never checks again. A key works on up to 3 of your machines. If you used LL Agent during the free preview, you don't need a key at all — Pro stays on for you.

---

Privacy

LL Agent is a strictly local server. It:

• Communicates exclusively with the LocalLens app on your machine via localhost
• Never sends photos, file paths, or metadata to any external server
• Discovers the LocalLens backend automatically via ~/.config/LocalLens/port.txt
• Stores the Pro license cache at ~/.config/LocalLens/mcp_license.json (local only)

License checks go to Dodo Payments' public license endpoint. They send the license key and an anonymous ID for this machine (a hash, so the key's 3 activations can be told apart) — never photos, file paths, metadata or your hostname. A non-expiring key (the free keys for founding users) makes exactly one network request, ever: activation. A subscription re-checks about once a week, and keeps working for 14 days past its last successful check if you are offline.

---

License

LL Agent is source-available under the Business Source License 1.1 (BUSL-1.1), © 2026 Mayank Pandey. You may read, fork and modify it, run it for testing, development and education, and use the Free-tier tools on your photos. Using Pro features on real photo libraries — personal or commercial — needs a license key, except for users who installed during the free preview, before paid plans launched. Using Pro in a copy whose license-key check was removed or bypassed is not licensed. Each version becomes Apache 2.0 on its Change Date. Summary: NOTICE.md. AI coding agents: see AGENTS.md.