From 58b0643a596ea1570a80fb1c01b11f1dc28b55c4 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Sun, 5 Apr 2026 22:53:43 -0700
Subject: [PATCH] docs: add uninstall instructions to README (#812)

Community PR #812 by @0531Kim. Adds two uninstall paths: the gstack-uninstall
script (handles everything) and manual removal steps for when the repo isn't
cloned. Includes CLAUDE.md cleanup note and Playwright cache guidance.

Co-Authored-By: 0531Kim <0531Kim@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/README.md b/README.md
index da2f0cf5..6e25ea39 100644
--- a/README.md
+++ b/README.md
@@ -265,6 +265,59 @@ gstack skills have voice-friendly trigger phrases. Say what you want naturally 
 "run a security check", "test the website", "do an engineering review" — and the
 right skill activates. You don't need to remember slash command names or acronyms.
 
+## Uninstall
+
+### Option 1: Run the uninstall script
+
+If gstack is installed on your machine:
+
+```bash
+~/.claude/skills/gstack/bin/gstack-uninstall
+```
+
+This handles skills, symlinks, global state (`~/.gstack/`), project-local state, browse daemons, and temp files. Use `--keep-state` to preserve config and analytics. Use `--force` to skip confirmation.
+
+### Option 2: Manual removal (no local repo)
+
+If you don't have the repo cloned (e.g. you installed via a Claude Code paste and later deleted the clone):
+
+```bash
+# 1. Stop browse daemons
+pkill -f "gstack.*browse" 2>/dev/null || true
+
+# 2. Remove per-skill symlinks pointing into gstack/
+find ~/.claude/skills -maxdepth 1 -type l 2>/dev/null | while read -r link; do
+  case "$(readlink "$link" 2>/dev/null)" in gstack/*|*/gstack/*) rm -f "$link" ;; esac
+done
+
+# 3. Remove gstack
+rm -rf ~/.claude/skills/gstack
+
+# 4. Remove global state
+rm -rf ~/.gstack
+
+# 5. Remove integrations (skip any you never installed)
+rm -rf ~/.codex/skills/gstack* 2>/dev/null
+rm -rf ~/.factory/skills/gstack* 2>/dev/null
+rm -rf ~/.kiro/skills/gstack* 2>/dev/null
+rm -rf ~/.openclaw/skills/gstack* 2>/dev/null
+
+# 6. Remove temp files
+rm -f /tmp/gstack-* 2>/dev/null
+
+# 7. Per-project cleanup (run from each project root)
+rm -rf .gstack .gstack-worktrees .claude/skills/gstack 2>/dev/null
+rm -rf .agents/skills/gstack* .factory/skills/gstack* 2>/dev/null
+```
+
+### Clean up CLAUDE.md
+
+The uninstall script does not edit CLAUDE.md. In each project where gstack was added, remove the `## gstack` and `## Skill routing` sections.
+
+### Playwright
+
+`~/Library/Caches/ms-playwright/` (macOS) is left in place because other tools may share it. Remove it if nothing else needs it.
+
 ---
 
 Free, MIT licensed, open source. No premium tier, no waitlist.