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

> Uninstall Ponytail completely from other hosts. This guide details removing mode flags, config files, and status-line entries for a clean state.

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

---

**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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/config.json)) – Stores custom defaults like `PONYTAIL_DEFAULT_MODE`, `quietStartup`, and `hideStatus`
- **Status-line entry** – The segment in Claude’s [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```bash
node scripts/uninstall.js

```

The script outputs confirmation of removed items, such as:

```text
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:

```bash

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

```bash

# 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`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) file itself will be deleted, preventing you from running the cleanup routine. The script requires access to [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) and [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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.