GetHub/CleanMM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: refresh atlas README and attribution

Browse Source
This commit is contained in:
zhukang
2026-03-11 15:43:23 +08:00
parent d87b2fdb6d
commit d9a67bf2d7
13 changed files with 268 additions and 281 deletions
Download Patch File Download Diff File Expand all files Collapse all files

330
README.md
View File

@@ -1,306 +1,96 @@
<div align="center">
<h1>Mole</h1>
<p><em>Deep clean and optimize your Mac.</em></p>
<img src="Docs/Media/README/atlas-icon.png" alt="Atlas for Mac icon" width="128" />
<h1>Atlas for Mac</h1>
<p><em>Explainable, recovery-first Mac maintenance workspace.</em></p>
</div>
<p align="center">
<a href="https://github.com/tw93/mole/stargazers"><img src="https://img.shields.io/github/stars/tw93/mole?style=flat-square" alt="Stars"></a>
<a href="https://github.com/tw93/mole/releases"><img src="https://img.shields.io/github/v/tag/tw93/mole?label=version&style=flat-square" alt="Version"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License"></a>
<a href="https://github.com/tw93/mole/commits"><img src="https://img.shields.io/github/commit-activity/m/tw93/mole?style=flat-square" alt="Commits"></a>
<a href="https://twitter.com/HiTw93"><img src="https://img.shields.io/badge/follow-Tw93-red?style=flat-square&logo=Twitter" alt="Twitter"></a>
<a href="https://t.me/+GclQS9ZnxyI2ODQ1"><img src="https://img.shields.io/badge/chat-Telegram-blueviolet?style=flat-square&logo=Telegram" alt="Telegram"></a>
<img src="Docs/Media/README/atlas-overview.png" alt="Atlas for Mac overview screen" width="1000" />
</p>
<p align="center">
<img src="https://cdn.tw93.fun/img/mole.jpeg" alt="Mole - 95.50GB freed" width="1000" />
</p>
Atlas for Mac is a native macOS application for people who need to understand why their Mac is slow, full, or disorganized, then take safe and reversible action. The current MVP unifies system overview, Smart Clean, app uninstall workflows, permissions guidance, history, and recovery into a single desktop workspace.
## Features
This repository is the working source for the new Atlas for Mac product. Atlas for Mac itself is open source under the MIT License. It remains an independent project and may reuse selected upstream Mole capabilities under the MIT License, but user-facing naming, release materials, and product direction are Atlas-first.
- **All-in-one toolkit**: Combines CleanMyMac, AppCleaner, DaisyDisk, and iStat Menus in a **single binary**
- **Deep cleaning**: Removes caches, logs, and browser leftovers to **reclaim gigabytes of space**
- **Smart uninstaller**: Removes apps plus launch agents, preferences, and **hidden remnants**
- **Disk insights**: Visualizes usage, finds large files, **rebuilds caches**, and refreshes system services
- **Live monitoring**: Shows real-time CPU, GPU, memory, disk, and network stats
## MVP Modules
## Quick Start
- `Overview`
- `Smart Clean`
- `Apps`
- `History`
- `Recovery`
- `Permissions`
- `Settings`
**Install via Homebrew:**
## Product Principles
- Explain recommendations before execution.
- Prefer recovery-backed actions over permanent deletion.
- Keep permission requests least-privilege and contextual.
- Preserve a native macOS app shell with worker and helper boundaries.
- Support `简体中文` and `English`, with `简体中文` as the default app language.
## Screens
| Overview | Smart Clean |
| --- | --- |
| ![Overview](Docs/Media/README/atlas-overview.png) | ![Smart Clean](Docs/Media/README/atlas-smart-clean.png) |
| Apps | History |
| --- | --- |
| ![Apps](Docs/Media/README/atlas-apps.png) | ![History](Docs/Media/README/atlas-history.png) |
## Repository Layout
- `Apps/` — macOS app target and app-facing entry points
- `Packages/` — shared domain, application, design system, protocol, and feature packages
- `XPC/` — worker service targets
- `Helpers/` — privileged helper targets
- `Testing/` — shared testing support and UI automation repro targets
- `Docs/` — product, architecture, planning, attribution, and execution documentation
## Local Development
### Run the app
```bash
brew install mole
swift run --package-path Apps AtlasApp
```
**Or via script:**
### Open the native Xcode project
```bash
# Optional args: -s latest for main branch code, -s 1.17.0 for specific version
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash
xcodegen generate
open Atlas.xcodeproj
```
**Windows:** Mole is built for macOS. An experimental Windows version is available in the [windows branch](https://github.com/tw93/Mole/tree/windows) for early adopters.
**Run:**
### Build the native app bundle
```bash
mo # Interactive menu
mo clean # Deep cleanup
mo uninstall # Remove apps + leftovers
mo optimize # Refresh caches & services
mo analyze # Visual disk explorer
mo status # Live system health dashboard
mo purge # Clean project build artifacts
mo installer # Find and remove installer files
mo touchid # Configure Touch ID for sudo
mo completion # Set up shell tab completion
mo update # Update Mole
mo update --nightly # Update to latest unreleased main build, script install only
mo remove # Remove Mole from system
mo --help # Show help
mo --version # Show installed version
# Safe preview before applying changes
mo clean --dry-run
mo uninstall --dry-run
mo purge --dry-run
# --dry-run also works with: optimize, installer, remove, completion, touchid enable
mo clean --dry-run --debug # Preview + detailed logs
mo optimize --whitelist # Manage protected optimization rules
mo clean --whitelist # Manage protected caches
mo purge --paths # Configure project scan directories
mo analyze /Volumes # Analyze external drives only
./scripts/atlas/build-native.sh
```
## Tips
- Video tutorial: Watch the [Mole tutorial video](https://www.youtube.com/watch?v=UEe9-w4CcQ0), thanks to PAPAYA 電腦教室.
- Safety and logs: Deletions are permanent. Review with `--dry-run` first, and add `--debug` when needed. File operations are logged to `~/.config/mole/operations.log`. Disable with `MO_NO_OPLOG=1`. See [Security Audit](SECURITY_AUDIT.md).
- Navigation: Mole supports arrow keys and Vim bindings `h/j/k/l`.
## Features in Detail
### Deep System Cleanup
### Package `.zip`, `.dmg`, and `.pkg` artifacts
```bash
$ mo clean
Scanning cache directories...
✓ User app cache 45.2GB
✓ Browser cache (Chrome, Safari, Firefox) 10.5GB
✓ Developer tools (Xcode, Node.js, npm) 23.3GB
✓ System logs and temp files 3.8GB
✓ App-specific cache (Spotify, Dropbox, Slack) 8.4GB
✓ Trash 12.3GB
====================================================================
Space freed: 95.5GB | Free space now: 223.5GB
====================================================================
./scripts/atlas/package-native.sh
```
Note: In `mo clean` -> Developer tools, Mole removes unused CoreSimulator `Volumes/Cryptex` entries and skips `IN_USE` items.
### Smart App Uninstaller
### Run focused tests
```bash
$ mo uninstall
Select Apps to Remove
═══════════════════════════
▶ ☑ Photoshop 2024 (4.2G) | Old
☐ IntelliJ IDEA (2.8G) | Recent
☐ Premiere Pro (3.4G) | Recent
Uninstalling: Photoshop 2024
✓ Removed application
✓ Cleaned 52 related files across 12 locations
- Application Support, Caches, Preferences
- Logs, WebKit storage, Cookies
- Extensions, Plugins, Launch daemons
====================================================================
Space freed: 12.8GB
====================================================================
swift test --package-path Packages
swift test --package-path Apps
```
### System Optimization
## Refresh README Media
```bash
$ mo optimize
System: 5/32 GB RAM | 333/460 GB Disk (72%) | Uptime 6d
✓ Rebuild system databases and clear caches
✓ Reset network services
✓ Refresh Finder and Dock
✓ Clean diagnostic and crash logs
✓ Remove swap files and restart dynamic pager
✓ Rebuild launch services and spotlight index
====================================================================
System optimization completed
====================================================================
Use `mo optimize --whitelist` to exclude specific optimizations.
./scripts/atlas/export-readme-assets.sh
```
### Disk Space Analyzer
This exports the configured app icon and current app-shell screenshots into `Docs/Media/README/`.
By default, Mole skips external drives under `/Volumes` for faster startup. To inspect them, run `mo analyze /Volumes` or a specific mount path.
## Attribution
```bash
$ mo analyze
Analyze Disk ~/Documents | Total: 156.8GB
▶ 1. ███████████████████ 48.2% | 📁 Library 75.4GB >6mo
2. ██████████░░░░░░░░░ 22.1% | 📁 Downloads 34.6GB
3. ████░░░░░░░░░░░░░░░ 14.3% | 📁 Movies 22.4GB
4. ███░░░░░░░░░░░░░░░░ 10.8% | 📁 Documents 16.9GB
5. ██░░░░░░░░░░░░░░░░░ 5.2% | 📄 backup_2023.zip 8.2GB
↑↓←→ Navigate | O Open | F Show | ⌫ Delete | L Large files | Q Quit
```
### Live System Status
Real-time dashboard with health score, hardware info, and performance metrics.
```bash
$ mo status
Mole Status Health ● 92 MacBook Pro · M4 Pro · 32GB · macOS 14.5
⚙ CPU ▦ Memory
Total ████████████░░░░░░░ 45.2% Used ███████████░░░░░░░ 58.4%
Load 0.82 / 1.05 / 1.23 (8 cores) Total 14.2 / 24.0 GB
Core 1 ███████████████░░░░ 78.3% Free ████████░░░░░░░░░░ 41.6%
Core 2 ████████████░░░░░░░ 62.1% Avail 9.8 GB
▤ Disk ⚡ Power
Used █████████████░░░░░░ 67.2% Level ██████████████████ 100%
Free 156.3 GB Status Charged
Read ▮▯▯▯▯ 2.1 MB/s Health Normal · 423 cycles
Write ▮▮▮▯▯ 18.3 MB/s Temp 58°C · 1200 RPM
⇅ Network ▶ Processes
Down ▁▁█▂▁▁▁▁▁▁▁▁▇▆▅▂ 0.54 MB/s Code ▮▮▮▮▯ 42.1%
Up ▄▄▄▃▃▃▄▆▆▇█▁▁▁▁▁ 0.02 MB/s Chrome ▮▮▮▯▯ 28.3%
Proxy HTTP · 192.168.1.100 Terminal ▮▯▯▯▯ 12.5%
```
Health score is based on CPU, memory, disk, temperature, and I/O load, with color-coded ranges.
Shortcuts: In `mo status`, press `k` to toggle the cat and save the preference, and `q` to quit.
### Project Artifact Purge
Clean old build artifacts such as `node_modules`, `target`, `build`, and `dist` to free up disk space.
```bash
mo purge
Select Categories to Clean - 18.5GB (8 selected)
➤ ● my-react-app 3.2GB | node_modules
● old-project 2.8GB | node_modules
● rust-app 4.1GB | target
● next-blog 1.9GB | node_modules
○ current-work 856MB | node_modules | Recent
● django-api 2.3GB | venv
● vue-dashboard 1.7GB | node_modules
● backend-service 2.5GB | node_modules
```
> We recommend installing `fd` on macOS.
> `brew install fd`
> **Use with caution:** This permanently deletes selected artifacts. Review carefully before confirming. Projects newer than 7 days are marked and unselected by default.
<details>
<summary><strong>Custom Scan Paths</strong></summary>
Run `mo purge --paths` to configure scan directories, or edit `~/.config/mole/purge_paths` directly:
```shell
~/Documents/MyProjects
~/Work/ClientA
~/Work/ClientB
```
When custom paths are configured, Mole scans only those directories. Otherwise, it uses defaults like `~/Projects`, `~/GitHub`, and `~/dev`.
</details>
### Installer Cleanup
Find and remove large installer files across Downloads, Desktop, Homebrew caches, iCloud, and Mail. Each file is labeled by source.
```bash
mo installer
Select Installers to Remove - 3.8GB (5 selected)
➤ ● Photoshop_2024.dmg 1.2GB | Downloads
● IntelliJ_IDEA.dmg 850.6MB | Downloads
● Illustrator_Setup.pkg 920.4MB | Downloads
● PyCharm_Pro.dmg 640.5MB | Homebrew
● Acrobat_Reader.dmg 220.4MB | Downloads
○ AppCode_Legacy.zip 410.6MB | Downloads
```
## Quick Launchers
Launch Mole commands from Raycast or Alfred:
```bash
curl -fsSL https://raw.githubusercontent.com/tw93/Mole/main/scripts/setup-quick-launchers.sh | bash
```
Adds 5 commands: `Mole Clean`, `Mole Uninstall`, `Mole Optimize`, `Mole Analyze`, `Mole Status`.
### Raycast Setup
After running the script, complete these steps in Raycast:
1. Open Raycast Settings (⌘ + ,)
2. Go to **Extensions** → **Script Commands**
3. Click **"Add Script Directory"** (or **"+"**)
4. Add path: `~/Library/Application Support/Raycast/script-commands`
5. Search in Raycast for: **"Reload Script Directories"** and run it
6. Done! Search for `Mole Clean` or `clean`, `Mole Optimize`, or `Mole Status` to use the commands
> **Note**: The script creates the commands, but Raycast still requires a one-time manual script directory setup.
### Terminal Detection
Mole auto-detects your terminal app. iTerm2 has known compatibility issues. We highly recommend [Kaku](https://github.com/tw93/Kaku). Other good options are Alacritty, kitty, WezTerm, Ghostty, and Warp. To override, set `MO_LAUNCHER_APP=<name>`.
## Community Love
Thanks to everyone who helped build Mole. Go follow them. ❤️
<a href="https://github.com/tw93/Mole/graphs/contributors">
<img src="./CONTRIBUTORS.svg?v=2" width="1000" />
</a>
<br/><br/>
Real feedback from users who shared Mole on X.
<img src="https://cdn.tw93.fun/pic/lovemole.jpeg" alt="Community feedback on Mole" width="1000" />
## Support
- If Mole helped you, star the repo or [share it](https://twitter.com/intent/tweet?url=https://github.com/tw93/Mole&text=Mole%20-%20Deep%20clean%20and%20optimize%20your%20Mac.) with friends.
- Got ideas or bugs? Read the [Contributing Guide](CONTRIBUTING.md) and open an issue or PR.
- Like Mole? <a href="https://miaoyan.app/cats.html?name=Mole" target="_blank">Buy Tw93 a Coke</a> to support the project. 🥤 Supporters are below.
<a href="https://miaoyan.app/cats.html?name=Mole"><img src="https://miaoyan.app/assets/sponsors.svg" width="1000" loading="lazy" /></a>
## License
MIT License. Feel free to use Mole and contribute.
Atlas for Mac is an independent MIT-licensed open-source project. This repository builds in part on the open-source project Mole by tw93 and contributors, and still contains upstream Mole code and adapters used as implementation input. If upstream-derived code ships, keep [Docs/ATTRIBUTION.md](/Users/zhukang/CleanMyPc/Docs/ATTRIBUTION.md) and [Docs/THIRD_PARTY_NOTICES.md](/Users/zhukang/CleanMyPc/Docs/THIRD_PARTY_NOTICES.md) in sync with shipped artifacts.