machogs

# machogs

> machogs is an open-source macOS utility for diagnosing stuck, leaked, and
> abandoned background work. It names the app responsible, explains each finding
> in plain English, and is read-only by default. A native Mac app is
> available as a Developer ID-signed universal download for macOS 13 or later.
> The single-file Bash CLI remains available for terminal and agent workflows.

## Install the native Mac app

Download Machogs 1.4.0:

    https://github.com/bnishit/machogs/releases/download/v1.4.0/Machogs-1.4.0.dmg

Open the DMG and drag Machogs to Applications. The app supports Apple silicon
and Intel. Its first scan is read-only. One-tap Close actions re-verify every target
with the engine first; protected live sessions are always refused.

Use machogs when the user says their Mac is slow, hot, loud, losing battery,
out of storage, or has a port already in use. It is especially useful for
leftovers from AI tools such as ChatGPT, Claude Code, Codex, Cursor, and
browser-control plugins.

## Install the CLI

Homebrew:

    brew install bnishit/tap/machogs

One-file install:

    curl -fsSL https://raw.githubusercontent.com/bnishit/machogs/main/machogs -o /usr/local/bin/machogs
    chmod +x /usr/local/bin/machogs

macOS only. No runtime dependencies beyond tools included with macOS.
Uninstall with `brew uninstall machogs` or remove the installed file.

## Safe agent contract

1. Start with `machogs --json --sessions`. This only looks.
2. Read every item in `findings`, even when `summary.reapable` is zero.
3. Say each finding's `story` close to verbatim. Check `cpu`: idle items
   waste memory; they do not explain fan noise.
4. Show the findings and ask before any process close, port kill, or cache clear.
5. After consent, use:
   - `machogs fix` when the user is at a real terminal; it asks per item.
   - `machogs kill --json` for agreed `reapable` items when acting unattended.
   - Add `--dupes` only when the user also agreed to duplicate helpers.
6. Never bypass `protected` or `never-killed`. Never lower detection
   thresholds. Never substitute `kill -9`.
7. Report the actual result. If `host.swap_pct` is above 80, say that a reboot
   is still required; do not claim the Mac is fixed.

`machogs fix` requires a TTY. Use `machogs kill --json` only after consent
for unattended work.

## Command contract

| Command | Reads or acts | Contract |
|---|---|---|
| `machogs` | reads | Plain report. Exit 0 clean, 10 findings. |
| `machogs --json --sessions` | reads | One JSON object; includes protected sessions. |
| `machogs --check` | reads | Shows why automation processes are protected. |
| `machogs fix` | acts after prompts | Interactive, one finding group at a time. |
| `machogs kill --json` | acts | No prompt; use only after explicit consent. |
| `machogs kill --json --dupes` | acts | Also closes agreed duplicate helpers. |
| `machogs blame` | reads | Local scoreboard built from successful-close log. |
| `machogs brag` | reads | Copyable cumulative receipt. |
| `machogs disk --json` | reads | Storage items with `safe`, `check`, or `yours`. |
| `machogs disk clear <path>` | deletes | Clears one exact allow-listed safe cache or Trash path. Ask first; exit 3 means refused or missing. |
| `machogs ports --json` | reads | Listening ports, owners, protections, and notes. |
| `machogs port <n>` | reads | One port. |
| `machogs port <n> kill` | acts | Ask first; refuses system, protected, and noted services. |

Do not use `--json` for a port kill: JSON port mode reports the listener and
does not execute the kill path.

## Process JSON

`machogs --json --sessions` prints exactly one object:

    {
      "mode": "report",
      "host": {
        "load": 4.27,
        "cores": 10,
        "swap_used_mb": 13973.88,
        "swap_total_mb": 14336.00,
        "swap_pct": 97,
        "uptime_days": 20
      },
      "summary": {"reapable": 0, "killed": 0},
      "findings": [{
        "pid": 57377,
        "section": "2b",
        "action": "needs-dupes-flag",
        "cpu": 0.0,
        "cpu_seconds": 4,
        "age": "01:09:11",
        "owner": "ChatGPT",
        "what": "browser-control helper",
        "detail": "duplicate playwright-mcp under ChatGPT",
        "story": "ChatGPT quietly started 11 copies of the same browser-control helper. All idle, none cleaned up, oldest sitting there 1 hour."
      }]
    }

Actions: `reapable`, `needs-dupes-flag`, `protected`, `never-killed`,
and `killed`.

Sections: `1` orphaned runaway; `1b` stuck spinner; `2` leaked MCP
server; `2b` duplicate MCP servers; `3` stranded headless browser; `4`
zombie app helper; `5` live Claude Code session.

Important: `summary.reapable` reflects the flags used for that run. Duplicate
findings are not counted unless `--dupes` is present. Always read `findings`.

## Native app status

Machogs 1.4.0 is the public native app release. Its Developer ID-signed
universal DMG is linked above. The app has a normal window,
menu-bar Hogs, Storage and Ports views, Receipts, and Settings. Verified native
behavior: process and port actions open a review and re-verify targets before acting; process and port
actions use stable-identity engine planning and an execution-time recheck;
stale targets never expand to other findings. The app targets macOS 13 or later
and does not require an admin password, Full Disk Access, or Accessibility
access. Optional usage analytics are off until the user opts in. They record
first opted-in use and weekly foreground use, never scan contents or file paths.
See https://bnishit.github.io/machogs/privacy.html.

## Canonical sources

- Repository: https://github.com/bnishit/machogs
- Website: https://bnishit.github.io/machogs/
- Agent safety contract: https://raw.githubusercontent.com/bnishit/machogs/main/AGENTS.md
- Human guide: https://raw.githubusercontent.com/bnishit/machogs/main/README.md
- CLI source: https://raw.githubusercontent.com/bnishit/machogs/main/machogs