# How to Uninstall Ponytail from Claude Code: Complete Removal Guide

> Learn how to uninstall Ponytail from Claude Code. Follow our guide to remove the plugin completely by running the uninstall script and cleaning up settings.json.

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

---

**Run the [`scripts/uninstall.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/config.json)) located at `~/.config/ponytail/config.json`
- A **status line entry** inside Claude Code's [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/settings.json) if you enabled the Ponytail status bar

These files are created via hooks in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```bash
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`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```bash
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`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) file relies on helper functions defined in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/settings.json)
- Helper functions in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/uninstall.js) warns you about a malformed [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/settings.json), you must manually edit the file. Locate your Claude Code settings directory (found via `getClaudeDir()`), open [`settings.json`](https://github.com/DietrichGebert/ponytail/blob/main/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.