How to Uninstall Ponytail: Complete Removal Guide

Uninstalling Ponytail requires a two-stage process: first run the scripts/uninstall.js cleanup script to remove external state files, then use your host's package manager to delete the plugin directory.

Ponytail is a plugin for AI coding agents like Grok and Claude (Pi) that modifies editor settings and maintains state files outside its installation directory. Because it writes to locations such as ~/.claude/settings.json and creates persistent configuration flags, completely uninstalling Ponytail requires specific steps to ensure no residual data remains on your system.

Step 1: Execute the Cleanup Script

Before removing the plugin files, you must run the cleanup script located at scripts/uninstall.js. This script is deliberately idempotent—it silently ignores missing files and safely removes only Ponytail-specific entries without affecting other configurations.

The script performs the following actions:

• Removes the mode flag file (.ponytail-active) that tracks whether the plugin is active
• Deletes the config file (config.json) containing Ponytail settings
• Removes the statusLine entry from Claude's settings.json (located at ~/.claude/settings.json)
• Uses helper functions getConfigPath() and getClaudeDir() from hooks/ponytail-config.js to locate these files correctly

Execute the script from the plugin directory:

node scripts/uninstall.js

The script only touches the portions of settings.json that belong to Ponytail, leaving any other status-line commands or custom configurations untouched.

Step 2: Remove the Plugin from Your Host

After the cleanup script completes, use your specific host's package manager to uninstall the plugin. This step deletes the ponytail directory from the host's plugin folder.

Important: You must run this command after the cleanup script because scripts/uninstall.js lives inside the plugin directory and would be deleted otherwise.

Choose the appropriate command for your AI agent host:

• Grok: grok plugin uninstall ponytail
• Pi (Claude): pi uninstall ponytail

Examples:

# For Grok users

grok plugin uninstall ponytail

# For Claude/Pi users

pi uninstall ponytail

Step 3: Optional Manual Cleanup

In rare cases where ~/.claude/settings.json is malformed or corrupted, the uninstall script cannot safely edit the file and will print a warning with the exact path. If this occurs, manually open ~/.claude/settings.json and remove the Ponytail entry from the statusLine configuration.

This situation only arises when the JSON structure is invalid; otherwise, the script handles removal automatically.

Complete Uninstall Workflow

Here is the complete sequence for fully removing Ponytail from your system:

# 1. Clean up external state files (must run first)

node scripts/uninstall.js

# 2. Remove the plugin from your host (choose one)

grok plugin uninstall ponytail   # for Grok

# OR

pi uninstall ponytail            # for Claude-based agents

Key Files in the Uninstall Process

The following source files handle the uninstallation logic:

File	Role	Key Components
scripts/uninstall.js	Performs external state cleanup	Removes .ponytail-active, config.json, and settings.json entries
hooks/ponytail-config.js	Path resolution utilities	Provides getConfigPath() and getClaudeDir() functions
README.md	Documentation	Lines 313-317 describe the required order of operations
tests/uninstall.test.js	Verification	Test suite ensuring the script works correctly

Summary

• Always run node scripts/uninstall.js first to remove files outside the plugin directory, including the mode flag and Claude settings modifications.
• Use host-specific commands second (grok plugin uninstall ponytail or pi uninstall ponytail) to delete the plugin files themselves.
• The cleanup script is safe to run multiple times and will not affect non-Ponytail configurations.
• Manual intervention is only required if ~/.claude/settings.json is corrupted.

Frequently Asked Questions

What happens if I uninstall the plugin before running the cleanup script?

If you run grok plugin uninstall ponytail or pi uninstall ponytail first, you will delete the scripts/uninstall.js file while leaving residual configuration files (.ponytail-active, config.json, and entries in settings.json) on your system. You would then need to manually locate and delete these files.

What external files does Ponytail create that require cleanup?

According to the source code in scripts/uninstall.js, Ponytail creates three types of external state: the .ponytail-active mode flag, a config.json configuration file, and modifications to Claude's settings.json (specifically the statusLine entry). These exist outside the plugin directory and persist after the host uninstall command runs.

Is the uninstall script safe to run if files are already missing?

Yes. The script is designed to be idempotent—it checks for file existence before attempting deletion and silently continues if files are already removed. It also uses precise JSON manipulation to remove only Ponytail-specific entries from settings.json without altering other settings.

Do I need to restart my AI agent after uninstalling Ponytail?

While not explicitly required by the source code, restarting your AI agent host (Grok or Claude) ensures that any cached references to Ponytail's status line or configuration are fully cleared from memory. This guarantees a complete removal of the plugin's functionality.

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