# How to Uninstall Ponytail: Complete Removal Guide

> Learn how to uninstall Ponytail completely with this guide. Follow two simple steps: run the cleanup script and use your package manager to remove the plugin directory.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: how-to-guide
- Published: 2026-09-09

---

**Uninstalling Ponytail requires a two-stage process: first run the [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/config.json)) containing Ponytail settings
- Removes the **statusLine** entry from Claude's [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/settings.json) (located at `~/.claude/settings.json`)
- Uses helper functions `getConfigPath()` and `getClaudeDir()` from [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) to locate these files correctly

Execute the script from the plugin directory:

```bash
node scripts/uninstall.js

```

The script only touches the portions of [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```bash

# 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:

```bash

# 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`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) | Performs external state cleanup | Removes `.ponytail-active`, [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json), and [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/settings.json) entries |
| [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) | Path resolution utilities | Provides `getConfigPath()` and `getClaudeDir()` functions |
| [`README.md`](https://github.com/DietrichGebert/ponytail/blob/main/README.md) | Documentation | Lines 313-317 describe the required order of operations |
| [`tests/uninstall.test.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) file while leaving residual configuration files (`.ponytail-active`, [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json), and entries in [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js), Ponytail creates three types of external state: the `.ponytail-active` mode flag, a [`config.json`](https://github.com/DietrichGebert/ponytail/blob/main/config.json) configuration file, and modifications to Claude's [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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.