{"id":49306870,"url":"https://github.com/kin0kaze23/pulse","last_synced_at":"2026-04-26T10:01:06.818Z","repository":{"id":353396398,"uuid":"1216863419","full_name":"kin0kaze23/pulse","owner":"kin0kaze23","description":"The safer, more developer-specific cleanup and machine audit tool for macOS","archived":false,"fork":false,"pushed_at":"2026-04-23T17:38:32.000Z","size":17301,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T19:27:31.237Z","etag":null,"topics":["cleanup","cli","developer-tools","homebrew","macos","nodejs","open-source","raycast","swift","xcode"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kin0kaze23.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-21T09:59:47.000Z","updated_at":"2026-04-23T17:38:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kin0kaze23/pulse","commit_stats":null,"previous_names":["kin0kaze23/pulse"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/kin0kaze23/pulse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kin0kaze23%2Fpulse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kin0kaze23%2Fpulse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kin0kaze23%2Fpulse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kin0kaze23%2Fpulse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kin0kaze23","download_url":"https://codeload.github.com/kin0kaze23/pulse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kin0kaze23%2Fpulse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32292958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cleanup","cli","developer-tools","homebrew","macos","nodejs","open-source","raycast","swift","xcode"],"created_at":"2026-04-26T10:00:45.659Z","updated_at":"2026-04-26T10:01:06.807Z","avatar_url":"https://github.com/kin0kaze23.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pulse\n\n\u003e Safe cleanup and machine audit for macOS developers\n\n[![CI](https://github.com/kin0kaze23/pulse/actions/workflows/ci.yml/badge.svg)](https://github.com/kin0kaze23/pulse/actions/workflows/ci.yml)\n[![Release](https://github.com/kin0kaze23/pulse/actions/workflows/release-cli.yml/badge.svg)](https://github.com/kin0kaze23/pulse/actions/workflows/release-cli.yml)\n![macOS](https://img.shields.io/badge/macOS-14.0+-black?logo=apple)\n![Swift](https://img.shields.io/badge/Swift-6.0-orange?logo=swift)\n![License](https://img.shields.io/badge/License-MIT-blue)\n\nPulse helps macOS developers **safely reclaim disk space** from developer junk and system bloat, and **audit their machine** for stale tooling, orphaned configs, and broken symlinks.\n\nUnlike broad \"Mac cleaner\" tools, Pulse is **narrow, transparent, and automation-first**. Every operation is preview-first, uses typed actions, and produces stable JSON for scripting.\n\n\u003e **Alpha / pre-release**\n\u003e Pulse is currently in controlled external alpha. Review `--dry-run` output before applying cleanup, and make sure you have a current backup the first time you use destructive commands.\n\n---\n\n## Quick Start\n\n### Install\n\n```bash\nbrew tap kin0kaze23/pulse\nbrew install pulse\n```\n\nOr install via script:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/kin0kaze23/pulse/main/scripts/install.sh | bash\n```\n\n### First Run\n\n```bash\npulse           # Open the interactive command dashboard\npulse analyze   # Scan for reclaimable space\npulse scan      # Friendly alias for analyze\npulse artifacts # Find build artifacts in your projects\npulse audit     # Check dev environment health\npulse audit index-bloat  # Find repos slowing AI IDE indexing\npulse audit agent-data   # Review Claude/Cursor data retention\npulse audit models       # Review Ollama / LM Studio model storage\npulse doctor    # Verify your setup\n```\n\n### The 5 commands most users need\n\n```bash\npulse         # open the dashboard\npulse doctor  # verify setup\npulse analyze # see reclaimable space\npulse clean   # guided cleanup flow\npulse audit   # check AI workstation issues\n```\n\n### Recommended First-Time Flow\n\n```bash\npulse doctor\npulse analyze\npulse clean\n```\n\nIn a normal terminal, `pulse clean` shows a guided preview and lets you:\n\n- press **Enter** to clean recommended items (or choose a profile if everything needs review)\n- press **p** to choose a profile\n- press **d** to deep clean everything shown\n- press **q** to cancel\n\nThen, if the preview looks right:\n\n```bash\npulse clean --profile xcode --apply\n```\n\n---\n\n## Commands\n\n| Command | Description | JSON |\n|---------|-------------|------|\n| `pulse analyze` | Scan developer and AI-workstation caches (Xcode, Homebrew, Node, Python, Bun, Rust, Claude, Cursor, installers) | ✅ |\n| `pulse scan` | Friendly alias for `pulse analyze` | ✅ |\n| `pulse artifacts` | Scan project build artifacts (node_modules, .build, target, venv, etc.) | ✅ |\n| `pulse audit` | Scan dev environment (stale simulators, orphaned taps, dead symlinks, old toolchains) | ✅ |\n| `pulse audit index-bloat` | Audit repos that slow Cursor / VS Code indexing | ✅ |\n| `pulse audit agent-data` | Audit Claude/Cursor data retention and cache sprawl | ✅ |\n| `pulse audit models` | Audit Ollama / LM Studio model storage and duplication risk | ✅ |\n| `pulse clean` | Safe default preview for all cleanup profiles | ✅ |\n| `pulse cleanup` | Friendly alias for `pulse clean` | ✅ |\n| `pulse clean --dry-run` | Preview what would be cleaned | ✅ |\n| `pulse clean --profile \u003cname\u003e --apply` | Execute cleanup | ✅ |\n| `pulse clean --profile \u003cname\u003e --apply --yes` | Execute cleanup (CI/CD, no prompt) | ✅ |\n| `pulse doctor` | Verify installation and environment | ✅ |\n| `pulse completion \u003cshell\u003e` | Generate shell completion scripts | — |\n\n### Auto JSON Detection\n\nWhen output is piped (not a TTY), Pulse automatically switches to JSON:\n\n```bash\npulse doctor | jq '.hasFailures'    # false\npulse analyze | jq '.totalSizeMB'   # 2150.5\npulse audit | jq '.criticalCount'   # 0\n```\n\n### Cleanup Profiles\n\n| Profile | What it cleans | Method |\n|---------|---------------|--------|\n| `xcode` | DerivedData, Archives, DeviceSupport, Simulators | File deletion |\n| `homebrew` | Download cache, old formulae/casks | `brew cleanup` |\n| `node` | npm cache, Yarn cache, pnpm store | File deletion |\n| `python` | pip, Poetry, and uv caches | File deletion |\n| `bun` | Bun install cache | File deletion |\n| `rust` | Cargo registry and git caches | File deletion |\n| `claude` | Claude Code logs, caches, transcripts, session artifacts | File deletion |\n| `cursor` | Cursor caches, logs, extension caches, workspace storage | File deletion |\n| `installers` | Old `.dmg`, `.pkg`, `.zip`, `.tar.gz` installers in Downloads/Desktop | File deletion |\n\n### Recommended user flow\n\n```mermaid\nflowchart TD\n    A[Install Pulse] --\u003e B[pulse doctor]\n    B --\u003e C[pulse analyze]\n    C --\u003e D[pulse clean]\n    D --\u003e E[pulse audit]\n    E --\u003e F[pulse audit index-bloat]\n    E --\u003e G[pulse audit agent-data]\n    E --\u003e H[pulse audit models]\n```\n\n### Artifact Types (16 supported)\n\n| Artifact | Tool | Typical Size |\n|----------|------|-------------|\n| `node_modules` | npm/yarn/pnpm | 100MB – 5GB |\n| `.build` | SwiftPM | 50MB – 2GB |\n| `target` | Cargo/Rust | 100MB – 3GB |\n| `dist` | Vite/Webpack/Rollup | 10MB – 500MB |\n| `venv` / `.venv` | Python venv | 50MB – 2GB |\n| `__pycache__` | Python | 5MB – 200MB |\n| `.dart_tool` | Dart/Flutter | 20MB – 500MB |\n| `Pods` | CocoaPods | 100MB – 3GB |\n| `.next` | Next.js | 10MB – 500MB |\n| `.nuxt` | Nuxt.js | 10MB – 500MB |\n| `.parcel-cache` | Parcel | 5MB – 200MB |\n| `elm-stuff` | Elm | 5MB – 100MB |\n| `go-cache` | Go modules | 50MB – 500MB |\n| `bun-cache` | Bun | 20MB – 200MB |\n\n### What Pulse Will NOT Touch\n\n- **Project-local files**: `node_modules` in your active projects is never touched by `pulse clean`\n- **System-critical paths**: `/System`, `/usr`, `/bin`, `/sbin` are protected\n- **User data**: `~/Documents`, `~/Desktop`, `~/Downloads` are protected\n- **App bundles**: `.app` files are never deleted\n- **Docker, browser caches, system logs**: Deliberately excluded — not our scope\n\n---\n\n## Safety Model\n\nPulse is designed for **trust over breadth**:\n\n1. **Preview-first**: Dry-run is the default. See exactly what will be deleted before it happens.\n2. **Confirmation required**: `--apply` requires typing \"yes\" (or use `--yes` for CI).\n3. **Trash-first by default**: Files go to Trash, not permanent deletion.\n4. **Protected paths**: System paths, user data, and app bundles are blocked at the code level.\n5. **Typed actions**: No string-based routing — every cleanup action is a typed enum.\n6. **TOCTOU protection**: Paths are re-validated immediately before deletion to prevent race conditions.\n7. **Symlink guards**: Broken or redirected symlinks are detected and skipped.\n8. **Stable JSON schemas**: Every command documents its schema version for reliable scripting.\n\n---\n\n## Configuration\n\nPulse uses `~/.config/pulse/config.json` with safe defaults:\n\n```json\n{\n  \"artifactScanPaths\": [\"~/Developer\", \"~/GitHub\", \"~/Projects\"],\n  \"artifactMinAgeDays\": 7,\n  \"artifactMinSizeMB\": 100,\n  \"excludedPaths\": []\n}\n```\n\nAll fields are optional — defaults are used if the file doesn't exist.\n\n---\n\n## Architecture\n\n```\nPulseCore        → Pure Swift engine (no SwiftUI, no AppKit, no singletons)\nPulseCLI         → Thin CLI over PulseCore (executable)\nPulseApp         → SwiftUI menu bar app (depends on PulseCore)\n```\n\nEvery command outputs stable JSON with `schemaVersion` for reliable automation:\n\n```json\n{\n  \"schemaVersion\": \"1.0.0\",\n  \"command\": \"analyze\",\n  \"timestamp\": \"2026-04-23T09:00:00Z\",\n  \"totalSizeMB\": 2150.5,\n  \"itemCount\": 4,\n  \"items\": [...]\n}\n```\n\n---\n\n## PulseApp (macOS Menu Bar)\n\nPulse also includes a native SwiftUI menu bar app with real-time monitoring, health scoring, and process management. See [PulseApp](PulseApp/) for details.\n\n---\n\n## Development\n\n```bash\nswift build          # Build everything\nswift test           # Run all tests\nswift run pulse      # Run CLI\n```\n\n---\n\n## License\n\nMIT. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkin0kaze23%2Fpulse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkin0kaze23%2Fpulse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkin0kaze23%2Fpulse/lists"}