Agent Tools

Install Agent Tools

1. Open Cleer 1.2.0 or later.
2. Open Settings.
3. Find Command Line & Agent Tools (Beta).
4. Click Install Agent Tools.
5. Click Add Terminal Command if you want to run cleer from your shell.

Cleer creates the optional shell command at:

~/.local/bin/cleer

Cleer does not edit your shell profile. If your shell cannot find cleer, reopen the terminal or use the stable absolute path:

/Users/YOUR_NAME/Library/Application Support/Cleer/AgentTools/current/bin/cleer

Check the installation:

cleer version
cleer capabilities

version, capabilities, and MCP initialization work without activation. Scans and cleanup commands require an activated Cleer license.

Run scans from the CLI

Run a system status check:

cleer status

Scan a folder for its largest contents:

cleer scan analysis --path "$HOME/Downloads"

Find duplicate files:

cleer scan duplicates --path "$HOME/Documents"

Find build artifacts in development projects:

cleer scan projects --path "$HOME/Developer"

Run scans that use Cleer's standard locations:

cleer scan smart
cleer scan category
cleer scan installers
cleer scan uninstall

An iCloud scan requires a folder path that Cleer can access:

cleer scan icloud --path "$HOME/Library/Mobile Documents/com~apple~CloudDocs"

Use JSON Lines when a script or an Agent reads the result:

cleer scan analysis --path "$HOME/Downloads" --output jsonl

Each JSON Lines record is one versioned event. A scan ends with completed, cancelled, or failed.

Scans run in the foreground. Press Ctrl-C to cancel. Cleer does not keep CLI jobs after the process exits, so another CLI process cannot query or cancel an earlier job.

Prepare a cleanup plan

The CLI can prepare a reviewable cleanup plan without changing files:

cleer cleanup prepare \
  --scope analysis \
  --root "$HOME/Downloads" \
  --path "$HOME/Downloads/OldInstaller.dmg" \
  --output json

Valid scopes are smart, category, analysis, duplicates, projects, installers, uninstall, and icloud.

Use the returned plan ID to inspect the saved plan:

cleer cleanup show PLAN_ID --output json

Preparing or showing a plan does not delete files. Applying a plan requires a short-lived, one-use approval token from the Cleer UI approval broker. Agent Tools does not let a script or an Agent create this token. Use the Cleer app to review and approve cleanup.

Connect an MCP client

The easiest setup is in Cleer > Settings > Command Line & Agent Tools (Beta). Click the copy button for Cursor, Codex, or Claude Code, then paste the result into that tool's MCP configuration.

Use the stable current path in MCP configuration. Replace YOUR_NAME with your macOS account name.

Cursor

Add this server to your Cursor MCP configuration:

{
  "mcpServers": {
    "cleer": {
      "command": "/Users/YOUR_NAME/Library/Application Support/Cleer/AgentTools/current/bin/cleer",
      "args": ["mcp"]
    }
  }
}

Codex

Add this server to your Codex configuration:

[mcp_servers.cleer]
command = "/Users/YOUR_NAME/Library/Application Support/Cleer/AgentTools/current/bin/cleer"
args = ["mcp"]

Claude Code

Run this command:

claude mcp add --scope user cleer -- '/Users/YOUR_NAME/Library/Application Support/Cleer/AgentTools/current/bin/cleer' mcp

Restart the MCP client after you change its configuration.

Use the MCP tools

Cleer exposes these tools by default:

• cleer_capabilities returns the supported scan and protocol features.
• cleer_scan_start starts a read-only scan and returns a job ID.
• cleer_job_events returns scan events after an optional sequence number.
• cleer_job_cancel requests cancellation of a running scan.
• cleer_cleanup_prepare creates a reviewable cleanup plan without changing files.

The supported scan kinds are status, smart, category, analysis, duplicates, projects, installers, uninstall, and icloud. The analysis, duplicates, projects, and icloud kinds require an absolute path.

For an asynchronous scan, the MCP client follows this sequence:

1. Call cleer_scan_start and save the returned jobId.
2. Call cleer_job_events with that jobId.
3. Pass the last event sequence as afterSequence on the next call.
4. Stop when terminal is true.

cleer_cleanup_apply is hidden by default. Cleer exposes it only after a separately verified UI approval-broker gate. An MCP client cannot enable cleanup by changing its configuration alone.

macOS permissions

The terminal or MCP client needs permission to read every folder that you ask Cleer to scan. macOS may block Desktop, Documents, Downloads, Mail, iCloud Drive, or other protected locations.

If a scan reports authorization_required or file_system, grant the host app access in System Settings > Privacy & Security. Grant only the access that you need, then run the scan again.

Update or remove Agent Tools

Open Cleer > Settings > Command Line & Agent Tools (Beta).

• Click Check & Update to install the current compatible release.
• Click Uninstall to remove the managed Agent Tools files.

Cleer keeps Agent Tools separate from the main app. Removing Agent Tools does not remove Cleer or your license.

Troubleshooting

• If cleer is not found, click Add Terminal Command again or use the stable absolute path.
• If a command returns license_required, open Cleer and activate your license.
• If the MCP client shows no Cleer tools, confirm that the command path is absolute and that the argument is mcp. Restart the client after you save the configuration.
• If Agent Tools reports a missing or incompatible Worker, open Cleer and run Check & Update. Reinstall Agent Tools if the problem remains.