How to Uninstall Ponytail from Claude Code: Complete Removal Guide

Run the scripts/uninstall.js Node script before removing the plugin to delete the mode flag, config file, and status bar entry from Claude Code's settings.json.

Ponytail is a Claude Code plugin that stores configuration and state files outside its installation directory. A complete uninstall requires more than the standard plugin removal command—you must also clean up external artifacts that persist after the source files are deleted.

Why Standard Uninstallation Leaves Residual Files

When you run the standard uninstall command (pi uninstall ponytail or the equivalent UI action), Claude Code deletes only the plugin's source directory. According to the Ponytail source code, this leaves three artifacts behind:

• The mode flag file (.ponytail-active) in the Claude Code directory
• The user configuration file (config.json) located at ~/.config/ponytail/config.json
• A status line entry inside Claude Code's settings.json if you enabled the Ponytail status bar

These files are created via hooks in hooks/ponytail-config.js and are not removed by the host's plugin manager because they reside outside the plugin directory.

Step-by-Step Uninstallation Process

To completely uninstall Ponytail from Claude Code, you must execute the cleanup steps in the correct order.

Step 1: Execute the Cleanup Script Before Plugin Removal

The scripts/uninstall.js file contains the logic to remove external state, but because it is part of the plugin itself, you must run it before uninstalling the plugin (or execute it from a separate clone of the repository).

Navigate to the Ponytail directory and run:

node scripts/uninstall.js

This Node.js script (identified by the shebang #!/usr/bin/env node) performs three critical actions:

1. Deletes the mode flag file using removeIfExists(path.join(getClaudeDir(), '.ponytail-active'), 'mode flag')
2. Deletes the configuration file using removeIfExists(getConfigPath(), 'config file')
3. Parses Claude Code's settings.json via getClaudeDir() and removes the statusLine entry if its command property contains ponytail-statusline

If the statusLine.command contains other commands besides Ponytail's, the script preserves those and removes only the Ponytail segment.

Step 2: Remove the Plugin via Claude Code

After the cleanup script completes, uninstall the plugin using Claude Code's standard command:

pi uninstall ponytail

Alternatively, use the Claude Code UI to remove the plugin. At this point, no residual files remain.

What the Uninstall Script Does Internally

The scripts/uninstall.js file relies on helper functions defined in hooks/ponytail-config.js to locate files:

• getClaudeDir() resolves the Claude Code configuration directory
• getConfigPath() returns the absolute path to ~/.config/ponytail/config.json

The script uses a removeIfExists utility to safely delete files without throwing errors if they are already missing. When processing settings.json, the script performs defensive parsing to handle malformed JSON gracefully, warning users when manual intervention is required.

Manual Cleanup (If You Already Uninstalled)

If you already ran pi uninstall ponytail and deleted the source files, you must manually remove the residual state:

1. Delete ~/.config/ponytail/config.json (and the directory if empty)
2. Delete .ponytail-active from your Claude Code working directory
3. Edit Claude Code's settings.json to remove any statusLine entry containing ponytail-statusline

Summary

• Run node scripts/uninstall.js before uninstalling the plugin to ensure the script can execute while the files still exist
• The script removes the mode flag (.ponytail-active), user config (~/.config/ponytail/config.json), and sanitizes settings.json
• Helper functions in hooks/ponytail-config.js provide the file paths used by the uninstaller
• Standard pi uninstall ponytail only removes source files and leaves external state intact
• If you already uninstalled, manually delete the three artifact locations listed above

Frequently Asked Questions

What files does Ponytail create outside its installation directory?

Ponytail creates three external artifacts: the mode flag file (.ponytail-active) in the Claude Code directory, a user configuration file at ~/.config/ponytail/config.json, and optionally a statusLine entry in Claude Code's settings.json if you enabled the status bar integration.

Can I run the uninstall script after removing the plugin files?

No. Because scripts/uninstall.js resides within the plugin directory, running pi uninstall ponytail first deletes the script itself. If you already uninstalled, you must either clone the repository separately to access the script, or manually delete the residual files listed in the cleanup locations.

Does the uninstall script affect other Claude Code settings?

The script specifically targets only the Ponytail-related segment of the statusLine.command property. If your settings.json contains other status line commands, the script preserves them and removes only the ponytail-statusline portion. It handles missing or malformed settings.json files gracefully with warnings rather than crashes.

What should I do if the uninstall script reports a malformed settings.json?

If scripts/uninstall.js warns you about a malformed settings.json, you must manually edit the file. Locate your Claude Code settings directory (found via getClaudeDir()), open settings.json in a text editor, and remove any statusLine object where the command property contains ponytail-statusline. Validate the JSON syntax before saving to prevent Claude Code startup errors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}