High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: add Chrome processes guide for macOS Activity Monitor
Mario5c1b84afd6bb
diff --git a/docs/chrome-processes.md b/docs/chrome-processes.mdnew file mode 100644index 00000000..8bc28d25--- /dev/null+++ b/docs/chrome-processes.md@@ -0,0 +1,92 @@+# Chrome Processes & Activity Monitor++Pinchtab launches its own Chrome instance. This doc explains how to identify Pinchtab's Chrome processes vs your personal Chrome, and what to do if things go wrong.++## How Pinchtab Uses Chrome++When Pinchtab starts, it spawns a Chrome process tree:++| Process | Role |+|---------|------|+| **Google Chrome** | Main browser process (parent) |+| **Google Chrome Helper** (gpu) | GPU rendering |+| **Google Chrome Helper** (network) | Network requests |+| **Google Chrome Helper** (storage) | Cookies, localStorage, etc. |+| **Google Chrome Helper (Renderer)** | One per tab/extension |++A typical Pinchtab instance creates **6-10 processes** depending on the number of open tabs.++## Identifying Pinchtab's Chrome++Pinchtab's Chrome is launched with a custom `--user-data-dir` flag pointing to the Pinchtab profile directory. Your personal Chrome uses `~/Library/Application Support/Google/Chrome` instead.++### From the terminal++```bash+# List Pinchtab's Chrome processes+ps ax | grep "user-data-dir=.*pinchtab" | grep -v grep++# List your personal Chrome processes (no --user-data-dir flag)+ps ax | grep "Google Chrome" | grep -v "user-data-dir" | grep -v grep+```++### From Activity Monitor++1. Open **Activity Monitor** (Spotlight → "Activity Monitor")+2. Search for **"Google Chrome"** in the search bar+3. Select a Chrome process → click the **ⓘ** (info) button in the toolbar+4. Go to the **Open Files and Ports** tab+5. Look for paths containing your Pinchtab state directory:+ - **Pinchtab Chrome**: references like `~/.pinchtab/chrome-profile/` or your custom `BRIDGE_STATE_DIR`+ - **Your Chrome**: references like `~/Library/Application Support/Google/Chrome/`++Alternatively, double-click any Chrome process → **Sample** or **Open Files** to inspect it.++### Quick check: is it headless?++Pinchtab's Chrome (in headless mode) won't appear in the Dock or have a visible window. If you see Chrome in Activity Monitor but not in the Dock, it's likely Pinchtab's.++## Normal Behavior++- Pinchtab Chrome processes appear when Pinchtab is running and disappear on graceful shutdown (SIGTERM/SIGINT)+- More tabs = more Renderer processes+- Memory usage: ~100-300MB base + ~50-150MB per tab depending on page complexity++## Orphaned Processes++If Pinchtab is force-killed (`kill -9`) or crashes, Chrome processes may be left behind. These are **orphaned processes** — they consume memory but do nothing useful.++### Automatic cleanup++Pinchtab automatically detects and kills orphaned Chrome processes on startup. You'll see this in the logs:++```+WARN killed orphaned Chrome processes count=8 profileDir=/path/to/profile+```++### Manual cleanup++If you need to clean up manually:++```bash+# Find orphaned Pinchtab Chrome processes+ps ax | grep "user-data-dir=.*pinchtab" | grep -v grep++# Kill them (graceful)+ps ax | grep "user-data-dir=.*pinchtab" | grep -v grep | awk '{print $1}' | xargs kill++# Or kill by specific profile path+pkill -f "user-data-dir=/Users/you/.pinchtab/chrome-profile"+```++In Activity Monitor, you can right-click any orphaned process → **Quit** (or **Force Quit**).++### How to tell if Chrome is orphaned++- Pinchtab is not running (`curl localhost:9867/health` fails)+- But Chrome processes with `--user-data-dir=<pinchtab-path>` still exist+- These are safe to kill++## Docker++Inside Docker containers, Chrome runs as `chromium-browser` under the `pinchtab` user. The container handles process lifecycle — when the container stops, all processes inside are cleaned up automatically. Orphan issues only apply to native (non-Docker) installations.