Tidemark user guide

Contents

1. Getting started
2. Cleanup
3. Installed Apps
4. Disk Map
5. AI Tools
6. Servers
7. Ask AI
8. Terminal and shortcuts
9. Settings
10. Safeguards
11. CLI usage
12. Custom cleanup rules
13. Data locations and troubleshooting

Getting started

Tidemark is a free, open-source disk cleanup app. It finds the caches, dependencies, build artifacts, and AI models that pile up during development, along with apps you haven't used in a long time, and cleans them up safely. Scanning never deletes anything, and cleanup runs only after you confirm it.

Installation

1. Open Tidemark_<version>_aarch64.dmg and drag Tidemark.app to the Applications folder.
2. If macOS blocks the first launch because the developer can't be verified, Control-click the app in Finder and choose Open.
3. Requirements: Apple silicon Mac, macOS 11 or later.

Layout

On first launch, click Start Scan. The last scan results are saved and shown right away on the next launch, and the status line at the top shows when the scan was run.

Cleanup

In the Cleanup view, you pick items found by the scan and clean them up after confirming.

Scanning

• Rescan in the header scans everything again. Hover over a category in the sidebar to show a refresh icon that rescans only that category.
• While scanning, progress is shown, and you can stop with Cancel Scan.

AI tool and model cleanup

• Hugging Face checks HF_HUB_CACHE → HF_HOME/hub → XDG_CACHE_HOME/huggingface/hub → the default path and lists only models, datasets, and Spaces. Deleting a model folder may free very little shared storage; hf cache delete is recommended.
• Ollama honors OLLAMA_MODELS; use ollama rm <model> for individual models. LM Studio checks its home pointer, then ~/.lmstudio, then the legacy ~/.cache/lm-studio home for models.
• Claude Desktop and Windsurf caches and Whisper models have dedicated rules. General ~/.cache cleanup excludes the LM Studio and Hugging Face homes and Whisper, and sign-in tokens and keys are protected.

Browser caches and personal data cleanup

• Chrome, Edge, Brave, Arc, Firefox, Safari, Opera, and Vivaldi target cache folders only, without duplicating general app caches. Cookies, sign-ins, history, bookmarks, and extension data are preserved. Quit the browser when a running-process warning appears. Offline pages may need downloading again.
• Mail attachment download copies are Caution items. Mailboxes (~/Library/Mail) and server originals are preserved; save any edits to downloaded copies elsewhere first.
• iOS/iPadOS backups appear individually as Danger items and are excluded from safe-item selection. A backup may be your only copy for restoring a device; check for another backup, such as iCloud. Emptying the Trash makes recovery impossible.
• Inaccessible Safari, Mail, and device-backup paths are skipped. If needed, allow Full Disk Access in macOS settings and rescan.

Risk

A ⚠ mark next to an item is a warning (for example, a related program is running). Hover over it to see the details.

Filters and search

• Use the sidebar to filter by category, risk, and project idle time (30+ days, 90+ days, 180+ days).
• The search field above the list (⌘F) searches names and paths and highlights matching text. With multiple words, only items containing all of them remain. Press Esc to clear it.
• Select safe items selects only Safe items that have no warnings.

Detail panel

Click an item to open it on the right.

• Shows the description, how to restore (how it comes back after deletion), and the cleanup method (official command or direct deletion).
• You can expand the folder contents. Items that will be removed are tagged Delete.
• You can Show in Finder, open it in the built-in or an external terminal, Recalculate, or Ask AI.

Pre-check

For items cleaned with a command, such as unused Docker data, unavailable iOS simulators, and the Homebrew cache, Tidemark calculates in advance how much space will actually be freed. The list shows the estimated reclaimable space alongside the total size, like ~13.4 GB / 56.4 GB.

Git check

Project folders (node_modules, target, and so on) also show the state of their git repository.

• ✓ Merged / Kept on remote: the code is on the remote, so it's safe to clean.
• Check git: there are uncommitted changes or unpushed commits.
• Turn on Update remote info (git fetch) in the sidebar to fetch the latest remote branches before judging, starting with the next scan.

Cleaning up

1. Select items with the checkboxes next to them. The bottom bar shows the number selected and the estimated reclaimable space.
2. Turn on Move to Trash if you want. In that case, space is freed only after you empty the Trash. Old-file cleanups and command-based items are deleted right away.
3. Click Clean Up to see the list of targets in a confirmation dialog. If it includes Danger items, you must check the consent box before Clean Now is enabled.
4. When it's done, a summary shows the space freed, the change in free disk space, and any items that failed.

Installed Apps

The Installed Apps view removes apps you haven't used in a long time, along with their leftovers, and manages globally installed packages. The app scan uses only app information and this Mac's records; it doesn't use the network or AI.

App list

• Last used dates come from macOS launch records. If there's no record, the date is estimated from when the app's data was last modified (Estimated from app data).
• Size is the app itself plus its leftovers (settings, caches, data).
• The toolbar has an idle-time filter (Unused 90+ days, Unused 180+ days, Unused 1+ year), sorting (Largest first / Least recently used), Hide Apple apps, and search.
• Quit apps marked Running before removing them.

Removing apps and leftovers

1. Click an app to see its leftovers in the detail panel. Items matching the bundle ID or developer ID are certain leftovers; items that only share the name are marked Guessed.
2. Click Remove app and leftovers, then choose the removal method and the leftovers to remove. Guessed items and items shared with other apps are left out by default.
3. Apps and leftovers moved to the Trash can be restored from the Trash.

Leftovers from uninstalled apps

The Leftovers from uninstalled apps tab groups the settings, caches and containers that already-removed apps left in ~/Library, one row per app.

• Anything still owned by an installed app (including helpers inside apps), Spotlight, a Homebrew cask or a running process is not listed. When ownership is uncertain, the item stays hidden.
• Items modified in the last 30 days and items belonging to Apple or shared updaters are excluded.
• Only caches, web data and window state are selected by default; settings and containers must be picked by hand. Login items are shown but cannot be removed.
• Move to Trash re-checks each path right before moving it, and you can restore items from the Trash.
• If a size shows Size unknown · Full Disk Access required, allow Tidemark via Open Full Disk Access settings.
• Press Dismiss to hide an app whose data you want to keep; Restore ignored groups at the bottom shows it again.

Admin removal vault

When you remove an app owned by the system (root), such as one installed from a .pkg or downloaded from the App Store, macOS asks for an administrator password.

• These apps are moved to /Library/Application Support/Tidemark Trash instead of the Trash.
• When the vault has items, a notice appears above the list. Space is freed only after you click Empty vault.
• Until you empty it, you can restore items by taking them out in Finder (administrator password required).

Global packages

The Global packages tab in the toolbar gathers what you installed with Homebrew, npm, pnpm, yarn, and bun globals, pipx, uv tool, and cargo install, plus the npx cache.

• Check for updates checks for new versions of Homebrew, npm, and pnpm packages. It uses the network, including brew update, but changes nothing.
• Turn on Updates only to show only packages with updates.
• Upgrade (one package) or Upgrade all runs each package manager's official command in the built-in terminal, so you can see the progress and enter passwords yourself. Major versions may change.
• Removing a package also runs the manager's official command (brew uninstall, npm uninstall -g, and so on). Homebrew may refuse to remove a package installed as a Dependency of another package.
• The npx cache holds packages that npx downloaded when running them. Even if you move it to the Trash, npx downloads them again the next time you run it.

Disk Map

Disk Map shows which folders take up space as rectangles sized in proportion to their size (a treemap).

1. Click Analyze home folder or Analyze entire disk (/). The home folder can take a few minutes.
2. Click a folder's rectangle to go into it. Click the path at the top (breadcrumbs) to go back to a parent folder.
3. The list on the right shows the current folder's subfolders and files by size. You can open them in a terminal or Ask AI.

• A dashed yellow border marks folders that appear in Cleanup.
• Cloud-synced folders such as iCloud and other volumes are skipped so files aren't downloaded, and the skipped items are listed separately.
• Folders under 1 MB are grouped together. Analysis results are saved; click Reanalyze to recalculate.

Large Files

In Disk Map → Large Files, choose large files, old downloads, or duplicate downloads and click Scan. Choose a minimum size of 100 MB, 250 MB, 500 MB, 1 GB, or 5 GB, or an age of 30, 90, 180, or 365 days. Old downloads are top-level items in ~/Downloads; folders also use the newest modification inside them. Search, sorting, and cancellation are available. Duplicate files of at least 1 MB are confirmed by size, the first 64 KB, and full SHA-256 hashes.

Personal files start unselected. Only duplicate copies are selected, leaving the oldest file as a possible original. Review the count, total size, and list before moving items to Trash; file metadata is checked again immediately before the move. Library, music data, bundles, links, other volumes, and cloud placeholders are skipped, as are folders that cannot be fully checked. Results stay in memory. If access is denied, allow Tidemark under System Settings → Privacy & Security → Files and Folders and scan again.

AI Tools

View AI tools’ disk usage, redownloadable caches, running AI processes’ CPU and memory, and supported GPU utilization. Expand a tool to see cache, model, and user-data paths and sizes; Show in Finder opens the location. User data is never labeled as cache. This screen is read-only and cannot delete files or stop processes.

On first opening the tab, saved measurements appear immediately; automatic measurement runs only when no history exists. Use Measure again or Cancel as needed. Processes refresh about every 3 seconds while the tab is visible and can be paused. CPU uses a per-core scale and may exceed 100%; RSS memory may understate actual usage. Shared data can make per-model totals exceed physical disk usage. GPU information is hidden when unavailable.

Servers

Lists listening TCP ports by process. Use Refresh, search by port or name, or filter to network-exposed ports. This Mac only means loopback; Open to the network means the server binds to an address other devices may reach, independently of firewall permissions. Common port uses are hints, not proof of the running program.

• Expand the command line and parent chain before choosing Stop. A confirmation appears, and changed start time, executable, or user cancels the action. Tidemark sends SIGTERM and waits up to five seconds. If still running, force stop with SIGKILL requires a separate confirmation and may lose unsaved work.
• Tidemark and its ancestors, other users, macOS components, Docker, and managed services cannot be stopped directly. Missing safety information also hides the stop button.
• Turn off AirPlay Receiver in System Settings › General › AirDrop & Handoff. Stop Docker containers using the displayed docker stop <name>. For Homebrew services, the button prepares brew services stop <formula> in the built-in terminal; press Enter to run it.
• launchd services may restart; stop them in their service settings. For an Ollama.app child, quit Ollama from the menu bar. A development watcher parent can also be selected in the confirmation, but child-only is the default and stopping the parent may affect other work.

Ask AI

You can ask an AI agent CLI you already have installed about what you're looking at. AI can't delete anything; it only makes suggestions. Supported agents: Claude Code (claude), Codex (codex), Gemini CLI (gemini), Cursor CLI (cursor-agent), OpenCode (opencode).

How to ask

1. Click the sparkle icon at the right end of the header, Ask AI in the detail panel, or select items and click Ask AI in the bottom bar.
2. Choose an agent and write your question. You can also click a suggested question for the current view (for example, "Which program created this folder?") to fill it in.
3. Click Start in Terminal to run the agent in the built-in terminal. Information about the current view and selected items is passed along. If you change the view or selection during the conversation, the agent answers based on the latest state.

AI answers in Tidemark's display language. The agent runs as a CLI on your computer, so sign-in and billing follow each CLI's settings.

AI review badges

When AI reviews an item, the result is shown in the list and the detail panel.

The AI review card in the detail panel also shows the reasoning, what could go wrong if you clean it, and how to restore it. It's only AI's opinion, so decide for yourself whether to clean.

AI cleanup suggestions

• When AI suggests cleaning, a notice like AI suggested cleaning N items appears at the top of the window. Your selection doesn't change on its own.
• Click Review to load the suggested items into the confirmation dialog. You must check a box confirming you've reviewed the reasons yourself before you can clean.
• AI can be misled by text inside scanned files, so check the items yourself. If you don't need the suggestion, click Dismiss.

Terminal and shortcuts

A terminal is built in at the bottom of the window, so you can inspect items directly or run AI agents and package upgrades.

• Open and close it with the terminal icon in the header. Terminal in the detail panel opens a new terminal in that item's folder.
• + in the tab bar opens a new terminal in the same folder, and × on a tab ends that shell.
• Drag the top edge of the terminal to resize it, and double-click it to return to the default height.

On Windows and Linux, use Ctrl instead of ⌘. The zoom level and terminal height are saved and kept on the next launch.

Settings

Open it with the gear icon in the header. Changes apply right away and are kept on the next launch.

Menu bar and automatic rescanning

• Show in menu bar is off by default. When enabled, closing the window keeps Tidemark running. The menu shows free space, the last scan, and reclaimable space, with Open Tidemark, Scan now, and Quit actions. The Dock icon stays visible.
• Launch at login is off by default and requires a signed app on macOS 13 or later. Its status comes from macOS; allow it in System Settings if approval is required. A login launch hides the window only when menu bar mode is enabled.
• Automatically rescan cleanup candidates defaults to Manual, with 6 hours, daily, and weekly options. Scans run only while the app is running and idle, on AC power. Unknown power status skips the scan. Scanning never deletes files or sends notifications.

Language

• When you change the language, the window redraws immediately. Scan warnings and check descriptions that were already generated appear in the new language starting with the next scan.
• System follows the system language at launch. On macOS, this is the first preferred language in System Settings › General › Language & Region.

AI agents

• Tidemark only checks whether the executable exists and whether --version runs. Click Check again to recheck.
• If it isn't found on your PATH, enter the executable in the path field yourself (for example, /opt/homebrew/bin/claude) and click Apply.
• For sign-in or model setting issues, use Run in Terminal to launch the CLI directly and check.

Sponsoring

You can support Tidemark's development with Sponsor at the bottom of the Settings window.

App updates

Automatic checks are on by default. At launch, once 24 hours have passed, Tidemark requests only the version file from GitHub; you can also choose Check now. Files download only after you choose Update. After signature, notarization, and checksum checks, choose Install and restart; restarting is disabled while cleanup is running. If the app location or verification prevents automatic installation, choose Open release page to download it yourself. Your user data is preserved.

Safeguards

Tidemark shows what will be deleted before deleting it, and in the cases below it either refuses to delete or asks you to confirm again.

CLI usage

The same engine is also available as the terminal command tidemark. Without --yes, clean only shows the plan (dry run) and deletes nothing.

Install (from the repository): cargo install --path crates/cli

# Scan only (deletes nothing)
tidemark scan

# Show the cleanup plan for Safe items (dry run)
tidemark clean --max-risk safe

# Move node_modules of projects unused for more than 90 days to the Trash
tidemark clean --rule project:node_modules --unused-days 90 --trash --yes

# Actually clean a single rule
tidemark clean --rule npm-cache --yes

The output language follows the OS language. You can change it like TIDEMARK_LANG=en tidemark scan (ko, en, ja, zh). Use tidemark rules to see rule IDs.

Custom cleanup rules

To add caches that the built-in rules don't cover, or to turn off built-in rules, create rules.toml. On macOS it goes in ~/Library/Application Support/tidemark/rules.toml (on other OSes, <config_dir>/tidemark/rules.toml).

• The format is the same as the built-in rules file (crates/infra/rules/default.toml).
• Using the same id overrides a built-in rule, and disabled = true turns a built-in rule off.
• Rescan after making changes for them to take effect. Names and descriptions in custom rules aren't translated; they're shown exactly as written.

# Add a new rule
[[rules]]
id = "my-tool-cache"
name = "My Tool cache"
category = "package_cache"
risk = "safe"
description = "Files downloaded by my-tool."
restore = "Downloaded again on the next run."
paths = { macos = ["~/Library/Caches/my-tool"], linux = ["~/.cache/my-tool"] }
mode = "contents"

# Turn off a built-in rule (id, name, category, and risk are always required)
[[rules]]
id = "yarn-cache"
name = "Yarn cache"
category = "package_cache"
risk = "safe"
disabled = true

Data locations and troubleshooting

All of Tidemark's data is stored only on your computer. On macOS, it's in ~/Library/Application Support/tidemark/.

If a storage-clear folder from the old name (Storage Clear) exists, it's moved to tidemark automatically on first launch.

FAQ

I cleaned up, but free space didn't increase.

• If you cleaned with Move to Trash turned on, you need to empty the Trash. For apps removed with administrator privileges, click Empty vault.
• Files shared with other locations through hard links, such as the pnpm store, don't free space when deleted. They're marked Shared hard links in the list.
• If there are local Time Machine snapshots, the free space macOS shows may increase later.

Ask AI can't find the agent.

At launch, Tidemark takes the PATH from your login shell to find claude and codex. If it still can't find them, set the executable path yourself in Settings.

I changed the language, but some text still appears in the old language.

Scan warnings, pre-check descriptions, and git status notes are saved in the language used at scan time. Rescan to switch them to the new language.

Scan results don't match reality.

Last scan results · N days ago in the status line at the top means saved results are being shown. Rescan before cleaning for accurate results.

On first open, it won't launch because of an "unidentified developer".

This build isn't notarized by Apple yet. Control-click the app in Finder and choose Open. After you allow it once, it opens normally from then on.