How to Uninstall Ponytail from Other Hosts: Complete State Cleanup Guide

Run node scripts/uninstall.js before executing host-specific uninstall commands to completely remove Ponytail’s mode flags, configuration files, and status-line entries from Claude’s settings.

When you need to uninstall Ponytail from other hosts like Grok or Pi, the standard plugin removal commands only delete the plugin folder while leaving behind critical state files that can cause conflicts in future installations. This guide explains how to use Ponytail’s dedicated uninstall script located in scripts/uninstall.js to eliminate all traces of the plugin from your system, including the hidden mode flags and configuration data stored outside the plugin directory.

Why Host-Specific Uninstallers Are Incomplete

Host-specific uninstall commands such as grok plugin uninstall ponytail or pi uninstall ponytail remove only the plugin files themselves. However, according to the Ponytail source code, the tool stores three distinct pieces of state outside the host-specific plugin directories that persist after standard uninstallation:

• Mode flag (.ponytail-active) – Tracks whether Ponytail is active for the current session
• Configuration file (config.json) – Stores custom defaults like PONYTAIL_DEFAULT_MODE, quietStartup, and hideStatus
• Status-line entry – The segment in Claude’s settings.json that executes ponytail-statusline

These residual files can interfere with fresh installations or cause stale status-line references in Claude’s interface.

The Three Components of Residual State

Understanding where Ponytail stores its state is essential for complete removal. The hooks/ponytail-config.js file provides the helper functions getClaudeDir() and getConfigPath() that resolve these locations across platforms:

State Component	File Path	Purpose
Mode flag	~/.claude/.ponytail-active	Signals active/inactive status for the current session
Configuration	~/.config/ponytail/config.json	User preferences and default behaviors
Status-line config	~/.claude/settings.json	The statusLine.command entry invoking Ponytail’s status script

How the Uninstall Script Works

The scripts/uninstall.js file is designed to be idempotent – it safely skips missing files and only modifies the status-line entry if it exactly matches Ponytail’s script. The script performs three sequential operations:

1. Removes the mode flag by calling getClaudeDir() and deleting .ponytail-active
2. Deletes the configuration file using getConfigPath() to locate ~/.config/ponytail/config.json
3. Edits settings.json – Reads the Claude settings file, strips only the statusLine.command segment containing "ponytail-statusline" while preserving other status-line commands, then writes the cleaned JSON back to disk

Step-by-Step: Uninstalling Ponytail from Hosts

Method 1: Using the Provided Uninstall Script (Recommended)

Execute the cleanup script from the repository root before running any host-specific uninstall commands:

node scripts/uninstall.js

The script outputs confirmation of removed items, such as:

Removed mode flag: /home/user/.claude/.ponytail-active
Removed config: /home/user/.config/ponytail/config.json
Removed status-line entry from settings.json

Because the script is idempotent, you can run it safely even if some files are already missing. It will only modify ~/.claude/settings.json if the status-line command exactly matches Ponytail’s script path.

Method 2: Manual Cleanup

If you prefer not to use the provided script, execute these commands manually using Node.js to resolve the correct paths:

# Remove the mode flag

rm -f "$(node -e "console.log(require('./hooks/ponytail-config').getClaudeDir() + '/.ponytail-active')")"

# Delete the configuration file

rm -f "$(node -e "console.log(require('./hooks/ponytail-config').getConfigPath())")"

# Remove Ponytail's entry from Claude's settings

sed -i '/ponytail-statusline/d' ~/.claude/settings.json

Method 3: Host-Specific Uninstall Commands

After running the cleanup script, use the appropriate command for your host:

# For Grok Build

grok plugin uninstall ponytail

# For Pi agent

pi uninstall ponytail

Critical Execution Order

Always run node scripts/uninstall.js before executing the host-specific uninstall command. If you remove the plugin folder first using grok plugin uninstall or pi uninstall, the scripts/uninstall.js file itself will be deleted, preventing you from running the cleanup routine. The script requires access to hooks/ponytail-config.js to resolve platform-specific paths via getClaudeDir() and getConfigPath().

Summary

• Run the cleanup first: Execute node scripts/uninstall.js before host-specific uninstall commands to ensure the script remains available
• Three locations cleaned: The script removes ~/.claude/.ponytail-active, ~/.config/ponytail/config.json, and edits ~/.claude/settings.json
• Safe and idempotent: The script silently skips missing files and only modifies exact matches in the settings file
• Preserve other configurations: The uninstall process specifically targets Ponytail entries, leaving other Claude settings and status-line commands intact

Frequently Asked Questions

What happens if I run the host uninstall command before the cleanup script?

If you execute grok plugin uninstall ponytail or pi uninstall ponytail first, the entire plugin directory—including scripts/uninstall.js and hooks/ponytail-config.js—is removed from your system. You would then need to manually delete the mode flag at ~/.claude/.ponytail-active, remove ~/.config/ponytail/config.json, and edit ~/.claude/settings.json to strip the status-line entry, using the manual cleanup commands provided above.

Is the uninstall script safe to run multiple times?

Yes. The scripts/uninstall.js file is designed to be idempotent. It checks for file existence before deletion and only modifies ~/.claude/settings.json if the exact string "ponytail-statusline" appears in the statusLine.command value. Running it repeatedly produces no errors and makes no changes if the cleanup is already complete.

Where does Ponytail store its configuration data?

Ponytail stores configuration in two primary locations resolved by functions in hooks/ponytail-config.js: the mode flag at ~/.claude/.ponytail-active (or the directory returned by getClaudeDir()), and the user configuration at ~/.config/ponytail/config.json (or the XDG/AppData location returned by getConfigPath()). These paths adapt to your operating system’s standards.

Do I need to manually edit Claude's settings.json if I use the script?

No. The scripts/uninstall.js file automatically handles modifications to ~/.claude/settings.json. It parses the JSON structure, identifies only the segment containing "ponytail-statusline" in the statusLine.command field, removes that specific entry while preserving any other status-line commands you may have configured, and writes the sanitized file back to disk.

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