diff --git a/README.md b/README.md
index 61933ec..9fba2ef 100644
--- a/README.md
+++ b/README.md
@@ -210,6 +210,17 @@ VS Code with the Codex extension reads `AGENTS.md`, which this repo ships, so it
 
 Which files map to which agent: [Agent portability](docs/agent-portability.md).
 
+### Uninstall
+
+| Host | Command |
+|------|---------|
+| Claude Code | `/plugin remove ponytail` |
+| Codex | `codex plugin remove ponytail` |
+| Pi agent | `pi uninstall ponytail` |
+| Cursor / Windsurf / Cline / etc. | Delete the copied rule file |
+
+These remove the plugin's own files. They leave behind a small amount of state ponytail writes outside the plugin folder: the mode flag, `~/.config/ponytail/config.json`, and (if you accepted the setup nudge) a `statusLine` entry in `~/.claude/settings.json`. Run `node scripts/uninstall.js` (from this repo, or wherever it was installed) to clean those up too. It only removes the statusLine entry if it points at ponytail's own script, so a statusline you set up yourself is left untouched.
+
 ## Commands
 
 | Command | What it does |
diff --git a/scripts/uninstall.js b/scripts/uninstall.js
new file mode 100644
index 0000000..f070d39
--- /dev/null
+++ b/scripts/uninstall.js
@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// ponytail — removes state ponytail wrote outside the plugin's own files:
+// the mode flag, the config file, and the statusLine entry it added to
+// settings.json. Plugin files themselves are removed by each host's own
+// uninstall command (see README); this only cleans up what those commands
+// can't see.
+
+const fs = require('fs');
+const path = require('path');
+const { getConfigPath, getClaudeDir } = require('../hooks/ponytail-config');
+
+function removeIfExists(filePath, label) {
+  try {
+    fs.unlinkSync(filePath);
+    console.log(`Removed ${label}: ${filePath}`);
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+}
+
+removeIfExists(path.join(getClaudeDir(), '.ponytail-active'), 'mode flag');
+removeIfExists(getConfigPath(), 'config file');
+
+const settingsPath = path.join(getClaudeDir(), 'settings.json');
+try {
+  const raw = fs.readFileSync(settingsPath, 'utf8').replace(/^\uFEFF/, '');
+  const settings = JSON.parse(raw);
+  const cmd = settings.statusLine && settings.statusLine.command;
+  if (typeof cmd === 'string' && cmd.includes('ponytail-statusline')) {
+    delete settings.statusLine;
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+    console.log(`Removed ponytail statusLine entry from ${settingsPath}`);
+  }
+} catch (e) {
+  if (e.code !== 'ENOENT') throw e;
+}
\ No newline at end of file
diff --git a/tests/uninstall.test.js b/tests/uninstall.test.js
new file mode 100644
index 0000000..8cd4607
--- /dev/null
+++ b/tests/uninstall.test.js
@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const root = path.join(__dirname, '..');
+
+function runUninstall(env) {
+  return spawnSync(process.execPath, [path.join(root, 'scripts', 'uninstall.js')], {
+    env: { ...process.env, ...env },
+    encoding: 'utf8',
+  });
+}
+
+delete process.env.CLAUDE_CONFIG_DIR;
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'ponytail-uninstall-'));
+process.on('exit', () => fs.rmSync(temp, { recursive: true, force: true }));
+
+const home = path.join(temp, 'home');
+const claudeDir = path.join(home, '.claude');
+fs.mkdirSync(claudeDir, { recursive: true });
+
+const flagPath = path.join(claudeDir, '.ponytail-active');
+fs.writeFileSync(flagPath, 'full');
+
+const configDir = path.join(temp, 'config-home', 'ponytail');
+fs.mkdirSync(configDir, { recursive: true });
+const configPath = path.join(configDir, 'config.json');
+fs.writeFileSync(configPath, JSON.stringify({ defaultMode: 'ultra' }));
+
+const settingsPath = path.join(claudeDir, 'settings.json');
+fs.writeFileSync(settingsPath, JSON.stringify({
+  statusLine: { type: 'command', command: 'bash /some/path/ponytail-statusline.sh' },
+}));
+
+const env = {
+  HOME: home,
+  USERPROFILE: home,
+  XDG_CONFIG_HOME: path.join(temp, 'config-home'),
+};
+
+let result = runUninstall(env);
+assert.equal(result.status, 0, result.stderr);
+assert.equal(fs.existsSync(flagPath), false, 'mode flag must be removed');
+assert.equal(fs.existsSync(configPath), false, 'config file must be removed');
+
+const settingsAfter = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+assert.equal(
+  settingsAfter.statusLine,
+  undefined,
+  'ponytail statusLine entry must be removed',
+);
+
+// A user's own, unrelated statusLine must survive untouched.
+fs.writeFileSync(settingsPath, JSON.stringify({
+  statusLine: { type: 'command', command: 'bash ~/my-custom-statusline.sh' },
+}));
+
+result = runUninstall(env);
+assert.equal(result.status, 0, result.stderr);
+const settingsAfter2 = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+assert.equal(
+  settingsAfter2.statusLine.command,
+  'bash ~/my-custom-statusline.sh',
+  "a user's own statusLine must not be touched",
+);
+
+// Running on an already-clean machine must not throw.
+result = runUninstall({ HOME: path.join(temp, 'home-empty'), USERPROFILE: path.join(temp, 'home-empty') });
+assert.equal(result.status, 0, result.stderr);
+
+console.log('uninstall script checks passed');
\ No newline at end of file